Umbraco User's Guide

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