Umbraco User′s Guide

Nik Wahlberg is the founder of Scandia Consulting, a full-service consultancy specializing in custom web application development. He is a Level 2 Certified Umbraco Professional. Paul Sterling is a member of the Umbraco Core Team and the creator of the Umbraco Store. He is also the founder of the Commerce for Umbraco open source project.

INTRODUCTION xxi PART I: CREATING YOUR FIRST SITE WITH UMBRACO CHAPTER 1: INSTALLING FOR THE FIRST TIME 3 Installing Umbraco 3 Installing Umbraco using the Microsoft Web Platform Installer 4 Installing Umbraco Manually 12 Tips for Installing Umbraco in Special Environments 18 Debugging in a Development Environment 18 Security Settings in a Production Environment 19 Other Installation Scenarios 19 Upgrading Umbraco 19 Performing a Patch Upgrade 19 Performing a Version Upgrade 21 Utilizing Umbraco Starter Kits 21 Installing a Starter Kit 22 Simple Starter Kit 23 Blog Starter Kit 24 Personal Starter Kit 24 Business Starter Kit 24 Extending the Starter Kits 24 Applying and Manipulating Umbraco Skins 25 Customizing a Skin 26 Modifying a Simple Umbraco Skin 27 Finding and Installing Umbraco Modules 29 Take Home Points 30 CHAPTER 2: THE UMBRACO APPROACH 31 Separating Content and Structure 32 Understanding the Umbraco Backoffi ce Structure 32 Creating a User with Restricted Access 33 Umbraco Content Tree 35 Umbraco Building Blocks 37 Users 42 Functions and Properties 42 User Types 44 Setting Up a New Dictionary Label 44 Permissions 45 Setting Up a User for Access to Multiple Start Nodes 46 Media 47 Settings 49 Developer 50 Members 50 Creating a Member Group 51 Creating a Member Type 52 Translation 52 Take Home Points 53 CHAPTER 3: DOCUMENT TYPES 55 The Data Model 56 Flexible Content Structure 57 Creating a Document Type 57 Restricting the Type of Content 62 Using Parent Document Types 64 Working with Document Types Outside of Umbraco 67 Exporting a Document Type 67 Importing a Document Type 68 Exporting Document Types as Plain Old CLR Objects 68 Using Document Type Properties 70 Built-in Properties 70 Properties with Special Meaning 71 Take Home Points 72 CHAPTER 4: TEMPLATES, MARKUP, AND MASTER PAGES 73 Building Website Structure using Templates 74 How Templates Build Layout and Structure 74 Creating Templates With Umbraco 76 Defining Markup 78 Creating Markup Using the Umbraco UI 78 Creating the Master Base Template 79 Creating the Textpage Template 80 Populating the Placeholder for the Textpage.Master File 81 Using Special Umbraco Tags 82 Applying the Template 85 Nesting and Inheritance with ASP.NET Master Pages 86 Umbraco and Your Markup 88 You Get What You Put In A Good Thing 88 Using AltTemplate 89 Changing the Document Type using AltTemplate 89 The No Template Eff ect 92 Styles and Scripts 94 Defining Your Styles 94 Layout and Organization 94 Handling Images 99 Styles and the Rich Text Editor 99 Using Scripts 102 Take Home Points 103 CHAPTER 5: USING MACROS 105 Introduction to Umbraco Macros 105 Macro Parameters 108 Rendering Macros In Your Site 110 XSLT Powered Macros 111 About XSLT 111 Using the Built-in XSLT Templates 112 Creating an XSLT Macro 116 Using XSLT Extensions to Make Macros Richer 118 Going Further with XSLT 121 Output an Image from the Media Library 121 Grouping Output by Date 124 .NET User Controls 128 Support for the .NET DLR 129 IronPython 129 Listing Pages from Current Page 129 Subpages from Changeable Source 130 IronRuby 130 User Generated Forms Using Umbraco Contour 131 Take Home Points 135 CHAPTER 6: LANGUAGES AND DICTIONARIES 137 Languages 137 Changing the Default Language 138 Adding and Updating Language Files 139 Changing the Backoffi ce UI Language 147 Dictionaries 148 The Umbraco Approach 148 Adding a Language 149 Working with the Dictionary 150 Take Home Points 152 CHAPTER 7: MULTIPLE SITES, HOSTNAMES, AND LOCALIZATION 153 Setting Up Multiple Sites 154 Working with Hostnames 156 Translation Workflow 159 Take Home Points 164 PART II: CONTENT PRODUCTION CHAPTER 8: CREATING CONTENT 167 Content Management Best Practices 167 Creating a Structure 168 Organizing Templates for Reuse 171 Understanding the Rich Text Editor 174 Take Home Points 179 CHAPTER 9: ADDING FUNCTIONALITY 181 Using the Umbraco Tags 181 Generating Website Navigation Menus 184 Providing the Latest News, Events, and Posts 187 Using Examine to Search Content 188 Take Home Points 193 CHAPTER 10: PACKAGES WHATEVER YOU CAN IMAGINE 195 Understanding Packages 195 Using Community Packages 197 Our.umbraco.org/projects 197 CodePlex.com 198 Understanding the Package Repository 199 Using Commercial Packages 199 Creating Your Own Packages 200 Take Home Points 205 CHAPTER 11: USING XSLT 207 Using XSLT for Published Content 208 Understanding XPath 210 Working with Media 212 Looking at Some XSLT Examples 215 List All Content 217 Counting, Looping, and Conditional Statements 219 Take Home Points 222 CHAPTER 12: WORKING WITH .NET CONTROLS 223 Creating a Macro 224 .NET Samples 224 List Subpages from Current Page 225 Rendering Nodes in a Grid Control 228 Creating a Page Programmatically 230 Creating a Custom Data Type 235 Sending Email with a Contact Form 239 Passing Data to .NET Through Macro Parameters 241 Creating a Login Macro 244 Using .NET from XSLT via XSLT Extensions 246 The Umbraco Event Model 249 Event Hooks 249 Event Examples 255 LINQ to Umbraco 256 Getting Started with LINQ to Umbraco 257 Extending LINQ to Umbraco 258 Take Home Points 258 CHAPTER 13: DEPLOYING TO A PRODUCTION INSTALLATION 261 Planning Considerations 261 Using the Packager 263 Database Synchronizing 266 Using Courier 266 Take Home Points 268 CHAPTER 14: TROUBLESHOOTING 269 Installation Troubleshooting 269 Are File Permissions Set Correctly? 270 Is Umbraco Confi gured in a Virtual Directory? 271 Does the IIS Application Pool .NET Runtime Version Match the Umbraco.NET Runtime Version? 271 Are All the Files Present? 271 Database-Related Installation Issues 272 Shared Hosting Considerations 273 Error Handling and Logging 273 The Umbraco Error Log 274 The Windows Event Log 275 A Note about XSLT and Errors 276 Moved and Missing Web Pages 276 404 Pages 276 Page Redirects 277 Using umbracoRedirect 277 Using umbracoInternalRedirectId 278 Take Home Points 278 CHAPTER 15: SAMPLE APPLICATION: CLASSIFIED ADS 279 What to Configure for this Example 279 Assumptions to Make for this Example 280 Visual Studio Features 281 The Umbraco Installation Components 281 Document Types 282 Templates 282 Macros 284 Event Hooks 287 Putting It All Together 288 Take Home Points 289 PART IV: APPENDIXES APPENDIX A: UPGRADING AN EXISTING INSTALLATION 293 Overall Steps to Upgrade 293 Backing Up Your Files and Database 295 Checking Package Compatibility 295 Copying the Right Files 296 Testing and Troubleshooting 296 APPENDIX B: SETTING UP YOUR VISUAL STUDIO ENVIRONMENT 299 Setting Up the Umbraco Folder Structure 299 Setting Up the Build Events 301 Referencing the Umbraco Libraries 303 APPENDIX C: RESOURCES 305 Source and Installation Files 305 Community 305 Umbraco Headquarters 306 APPENDIX D: DATA TYPE DEFINITIONS 307 The Data Type s Purpose 307 Definition of Built-in Data Types 308 Approved Color 309 Checkbox List 310 Content Picker 310 Date Picker with Time 311 Date Picker 311 Dropdown Multiple 311 Dropdown 312 Image Cropper 312 Macro Container 314 Media Picker 315 Member Picker 315 Radiobox 315 Related Links 315 Richtext Editor 316 Simple Editor 317 Tags 317 Textbox Multiple 318 Textstring 318 True/False 318 Ultimate Picker 318 Upload 319 Configuring a Data Type to Your Needs 319 INDEX 321