Kentico 9

1. Developing websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1 Website development basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2 Choosing the right development model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 Defining website content structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.3.1 Page types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3.1.1 Creating page types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.1.2 Creating content only page types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.3.1.3 Creating container page types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191.3.1.4 Advanced content modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.3.1.5 Configuring page types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.3.1.5.1 Changing page type icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.3.1.5.2 Creating alternative forms for page types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.3.1.5.3 Specifying the URL pattern for content only pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.3.1.5.4 Extending the page type listing filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251.3.1.5.5 Limiting the pages users can create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261.3.1.5.6 Reference - Page type properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

1.3.2 Custom tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.3.2.1 Creating custom tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.3.2.2 Editing custom tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.3.2.3 Managing custom table data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371.3.2.4 Creating alternative editing forms for custom tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391.3.2.5 Setting custom table permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

1.4 Preparing your environment for team development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411.4.1 Setting up continuous integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

1.4.1.1 Continuous integration repository structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481.4.1.2 Object types supported by continuous integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501.4.1.3 Restoring continuous integration files to the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541.4.1.4 Using continuous integration with Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

1.4.2 Working with object locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571.4.3 Editing object code externally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

1.5 Developing websites using the Portal engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611.5.1 Creating portal engine page templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631.5.2 Editing page layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651.5.3 Using and configuring web parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711.5.4 Creating portal engine master pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781.5.5 Inheriting portal engine page content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791.5.6 Working with layout web parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891.5.7 Using web part containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

1.6 Developing websites using ASPX templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971.6.1 Creating master pages for ASPX templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991.6.2 Creating ASPX page templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011.6.3 Adding portal engine functionality to ASPX page templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051.6.4 Using both ASPX and portal templates on a single site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071.6.5 Exporting portal engine templates as ASPX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

1.7 Developing sites using ASP.NET MVC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091.7.1 Creating MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

1.7.1.1 Installing Kentico integration packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111.7.2 Creating content repositories for MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111.7.3 Defining content structure on MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1121.7.4 Developing MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

1.7.4.1 Retrieving content on MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131.7.4.2 Working with page attachments in MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151.7.4.3 Generating classes for Kentico objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181.7.4.4 Displaying shared content in MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201.7.4.5 Providing friendly URLs on MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

1.7.4.5.1 Avoiding duplicate URLs on MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241.7.4.6 Providing smart search on MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241.7.4.7 Adding preview mode support for MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241.7.4.8 Localizing data on MVC sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261.7.4.9 Handling 404 Not Found globally in MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1271.7.4.10 Processing scheduled tasks when developing MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291.7.4.11 Testing MVC controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

1.7.5 Improving performance of MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311.7.6 Deploying MVC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

1.8 Using ASP.NET Web API with Kentico . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351.9 Managing page templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371.10 Loading and displaying data on websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

1.10.1 Loading page data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411.10.1.1 Writing page path expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

1.10.2 Building website navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1451.10.3 Loading data using custom queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521.10.4 Displaying data from custom tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551.10.5 Writing transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

1.10.5.1 Creating transformations for pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1601.10.5.2 Using hierarchical transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661.10.5.3 Writing transformations for custom tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721.10.5.4 Using transformations in macro expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

1.10.5.5 Displaying context menus in transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781.10.5.6 Reference - Transformation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

1.10.6 Filtering and paging data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971.10.7 Displaying data - advanced scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

1.10.7.1 Creating wizards on websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021.10.7.2 Setting up syndication feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

1.10.7.2.1 Syndication transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061.10.7.2.2 Usage example - CMS RSS feed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2071.10.7.2.3 Usage example - RSS feed + Data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081.10.7.2.4 Usage example - RSS repeater + Data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2091.10.7.2.5 Usage example - External RSS feed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111.10.7.2.6 Syndication web parts and widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

1.10.7.3 Displaying related pages using named relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2131.10.7.4 Displaying image galleries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2161.10.7.5 Displaying maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

1.10.7.5.1 Displaying static maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191.10.7.5.2 Displaying dynamic maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

1.11 Designing websites using CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221.11.1 Combining stylesheets from multiple sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2271.11.2 Using printer friendly CSS styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281.11.3 Creating printable versions of pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281.11.4 Creating skins using ASP.NET themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301.11.5 Adding CSS to page components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

1.12 Previewing design changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2341.13 Developing websites for mobile devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

1.13.1 Configuring mobile development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2361.13.2 Creating device profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2371.13.3 Resizing images for devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2381.13.4 Creating page layouts for devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2381.13.5 Mapping shared mobile layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2401.13.6 Creating mobile pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2411.13.7 Creating separate website sections for mobile devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2451.13.8 Device macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

1.14 Preparing widgets for users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2471.14.1 Creating widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481.14.2 Setting up widget zones on pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2531.14.3 Configuring permissions for widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

1.15 Validating website code and accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2561.15.1 Validating HTML code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2571.15.2 Validating CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2571.15.3 Validating links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2571.15.4 Validating accesibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

1.16 Managing JavaScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2591.17 Troubleshooting websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

1.17.1 Viewing system information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2601.17.2 Working with the system event log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611.17.3 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Developing websites

Basics

An overview of the development process as we see it. What are page templates and what is the role of the content editors?

Development models (Portal engine, ASPX or MVC?)

Kentico offers several ways to build websites. If you are not sure which development model to follow, learn about their advantages anddisadvantages.

Website data structure

Before you begin developing websites, familiarize yourself with the system's data structure. Learn how pages and files are organized,and about and .page types custom tables

Developing websites using the portal engine

Design websites directly in your browser with minimal coding.

Developing websites using ASPX page templates

Register ASPX web forms as templates in the system and use them to create pages.

Developing sites using ASP.NET MVC

ASP.NET MVC is a powerful tool for building dynamic websites.

Loading and displaying data on websites

Learn how to display various types of data on your website's pages. Use components to load the required data and convert it into aviewable format using .Transformations

Troubleshooting websites

Learn where to view system information and the event log, and how to debug websites.

Designing websites using CSS

Adjust the appearance and design of your websites using CSS. Manage your CSS files directly in Kentico, or use your CSS filesgenerated by your favorite automation tools.

Preparing widgets

Create components that content editors and other types of users can add onto pages.

Development for mobile devices

Design your web pages to be easily viewable on mobile devices. for tablets, smartphones, or other devices, Create device profiles prepa and .re unique page layouts for different profiles develop mobile web pages

1. 2.

3. 4.

             

                            

Website development basicsThe following figure shows the typical website development process in Kentico, and how the roles are split between developers and contenteditors:

The developers analyze client requirements.The developers prepare the site structure (site map) and the overall web design. Designers can use external toolswireframingduring this process.The developers create for every type of page required on the site (home page, solutions, products, news, etc.).page templatesThe content editors create new pages — they enter text and images into the page templates defined by the developers.

What is a page template?

Page templates define the structure, design and core functionality of pages.

The website can re-use a single template for any number of pages.Content editors can enter different content for all pages based on the same template.Templates allow editors to focus just on the content of pages, without the needing to take care of the page's layout and formatting.Templates help keep the design consistent throughout the whole website.

Team development

Configure your environment to support development in a collaborating team.

 

There are three different that you can use to create page templates in Kentico.development models 

Choosing the right development modelKentico provides three basic development models. You can choose the model that best suits your needs:

Portal Engine - allows you to build websites in a using components called web parts. Only requiresbrowser-based interfaceprogramming in Visual Studio when creating custom components.

ASPX Templates - can be chosen by ASP.NET developers who prefer to create websites using standard ASP.NET architecture andstandard development tools, such as . This model requires you to be familiar with ASP.NET web form developmentVisual Studioand have at least basic programming knowledge of C# or VB.NET.

MVC - allows developers to create websites using the Model-View-Controller architectural pattern (based on the ASP.NET MVCframework). Working with this model requires knowledge of programming and ASP.NET MVC.

If required, the and models can be combined on a single website. For example, you can place pages usingPortal Engine ASPX TemplatesASPX templates onto a portal engine website, and even insert custom ASPX pages implementing your own applications. On the other hand,you can create ASPX page templates with areas that can be edited through the portal engine.

  Portal Engine ASPX Templates MVC

How you work You build the website and designpages using a browser-basedinterface.

No programming knowledge isrequired for common tasks.

You build ASPX pages (web forms)that are used to display content fromKentico .

At least basic programmingknowledge of ASP.NET and eitherC# or VB.NET is required.

You implement models, controllersand views for rendering pagesrendering content retrieved from theKentico database.

Requires knowledge of MVCarchitecture, ASP.NET and C# orVB.NET.

How you assemble pages You use built-in or custom web partsthat you place into customizablepage layouts (HTML code withplaceholder zones for web parts).

You use built-in or custom ASP.NETserver controls and place them ontothe ASPX pages. These arestandard web forms that are part ofthe web project, so you can alsowork with code behind files.

It is also possible to place web partson the page templates if the requiredserver control is not available.

The appearance of the content youdisplay is defined completelythrough MVC views, which arecomposed of HTML and inline code.

The content structure in Kentico isrepresented by content only pages,which do not have page templatesas they serve as content repositoriesonly.

Master pages and visualinheritance

Subpages can nest within anyancestor pages. You can break thenesting on any level.

Page templates may inherit contentfrom a master page, which worksjust like a standard ASP.NET masterpage (.master file).

Pages do not inherit content fromtheir parents in the website contenthierarchy.

Visual representation is handled bythe MVC application completely.

Custom code integration andextensibility

You can create your own usercontrols (ASCX files) or web parts(ASCX files with a portal engineinterface) if you need to integratecustom functionality.

Any custom controls or code can beadded to the web parts placed onthe website.

You build standard ASPX pageswith code behind files, which meansyou can place any custom controlsand code onto the page.

You prepare the content of the MVCviews and the functionality of thecontroller and model classes inVisual Studio, so have full controlover customization.

Advantages Easier and faster way to buildwebsites.ASP.NET programmingknowledge is not required forcommon tasks.You can build the wholewebsite very quickly, using onlya web browser.

Standard ASP.NETarchitecture.You can use your favoritedevelopment tools, such asVisual Studio.

Model-View-Controllerarchitecture.The option of using the vRazoriew engineDevelopment via standard tools(Visual Studio).

Disadvantages Proprietary architecture anddevelopment process.

Requires ASP.NETprogramming knowledge.The design of the web pagescannot be fully managed viathe browserbasedadministration interface.

Development tasks requireknowledge of ASP.NET MVCand programming.The design of the web pagescannot be managed via thebrowserbased administrationinterface.

 

Defining website content structureOn this page, you can learn how to best store and organize data in Kentico.

Deciding how you're going to store content in your project

Kentico recommends storing data that you use on your website in the following ways:

As - a hierarchical structure in the content tree of the application.pages Pages ?When should you use pages to store content

In - suitable for storing large amounts of data in a flat structure. module classes?When should you use module classes to store content

on module classes.More informationIn custom tables - 

?When should you use custom tables to store content on custom tables. More information

In - suitable for storing media libraries large files, not exclusively of media character, such as videos, high resolution images orpackaged files.

?When should you use media libraries to store content on media libraries.More information

 

When should I use pages to store content?

Use pages as a content storage when you need:

Hierarchical structure - for example, when storing news articles or products:Store

CoffeesCoffee product 1Coffee product 2...

BrewersAccessoriesGrindersE-booksother store sections

Workflow - you require to use for your content. Module classes and media libraries don't support workflow.workflowItem-level permissions - you require to configure access permissions on individual content item level. Pages allow you to configure

for this purpose.access control listsMultilingual content - pages allow you to store content in and manage its translations.different languages

Pages are stored in the content tree. The content tree defines the navigation and site map of the website:

Limitations of using pages for storing content

We recommend limiting the number of pages in the content tree to 500 000 to preserve performance.The limit depends largely on how the system is used and configured. If you mainly use the system for operations, suchread as displaying the content on the Live site, the system will be able to handle more pages. Having multiple editors make veryfrequent changes to content in the administration interface is, on the other hand, more demanding on the system'sresources.

We recommend that each item (page) in the content tree have at most 1000 direct child pages. This is something we recommendtaking into consideration from the very beginning of your development process. See setting up content tree structure for a large

.number of pages

The same limitations apply to the number of linked pages and pages in different cultures.When displaying data on the live site, we recommend to display content tree sections that contain 100configuring listing web parts000 descendant pages (pages in all levels) at most.The 'Alias path' for each item in the content tree cannot exceed 450 characters in length. Each item in the tree has an alias pathconsisting of all of the items leading to the item in the content tree. For example the alias path leading to a product can be /Store/Cof

for a product called The alias path value of the field is stored in the databasefee/Nicaragua-Dipilto Nicaragua Diplito. CMS_Treetable's 'NodeAliasPath' field, which is set to 450 characters.

Note: The limitations largely depend on the of the system.overall configuration

Setting up content tree structure for a large number of pages

When you plan on storing and creating a large number of pages, consider structuring the content tree into smaller segments. This can helpyou avoid reaching the recommended limit of 1000 child pages under a single page. For example, articles can be structured based on theday they were created on. 

Articles2015

March1

Article1Article2...

23...31

April1...30

May  

If you plan on creating an even larger amount of content, you can structure the content tree even further. 

Articles2015

March1

MorningArticle1Article2...

AfternoonArticle3Article4

EveningArticle 5Article 6

23...31

AprilMay

The 'Alias path' for each item in the content tree cannot exceed 450 characters in length. See limitations of using pages for storing content.

Note: while this helps you structure content so that you don't exceed the recommended 1000 child pages limitation, the total number ofpages in the system will increase. Consider the number of pages in the system as well.recommended maximum

Structured pages

While all items in the content tree of the Pages application are pages, there are two types of pages that you can distinguish. There are pagesthat are set to display content and they are displayed as menu items by default (this can be also customized). Examples of these are the /Ho

, , on the sample This behavior is enabled by editing individual Page types in the Page typesme /Products /Services Corporate site. application and enabling the option.Behave as Page (menu item)

The second type of pages are , which contain structured data that is then displayed by pages that behave as menu items.Structured pages

Resolving performance issues caused by storing a large number of pagesSee for information on how to resolve issues with website performance. One approach forOptimizing website performancereducing the amount of pages stored in the content tree is .setting up archival for outdated pages

Examples of these are the news items under the section of the sample Corporate Site./News

Pages that are set to behave as menu items usually contain unstructured content in the form of editable regions that can be edited on the Pa tab. Structured pages contain structured and typed data stored in page type-specific database tables and edited on the tab.ge Form

You will typically use when you need to display a , such as list of news, list of products, etc.structured pages list of items

Types of content stored in pages

There are two types of content stored within pages:

content stored in editable regions on the pagecontent stored in page fields 

The following table compares both approaches:

  Editable regions on the page Form tab

Content structure Simple content structure, only text-basedcontent.

Complex content structures, typed data,such as text, date-time, numbers, etc.

Validation Only basic validation rules for minimum andmaximum length.

Complex validation rules, including regularexpressions and custom form controls withcustom validation code.

Display The content is displayed in the context ofthe page providing truly WYSIWYG editing.

The content is displayed by controls or webparts using ASCX or XSLT transformations.

Storage The content is stored in a single XMLdocument in the page properties.

The content is stored in a separatedatabase table. Each field has its owncolumn. The data can be easily modifiedusing SQL queries or API.

Examples of use Home page, contact page.

 

Generally: pages with simply structured orunstructured, text-only content.

 

The editable regions are usually used onlyin connection with pages of type Page

.(menu item)

News, product specification, event details,job opening, anything that requires different,more complex fields for its content.

 

Generally: pages with structured contentwhere you need to separate content fromdesign and keep the content in its originaldata type.

 

The form-based content is usually used inconnection with pages of type , News Produ

etc.ct, Article,

When should I use module classes to store content?

Custom allow you to store large amounts of content without the hierarchy provided by the . Use module classes whenmodule classes pagesyou need:

Access to the data via the UI, but without the need to represent the data in a hierarchical structure in the content tree.Need to store large amounts of data in a flat structure using the standard data types (int, string, ...) and one-to-many data (radiobuttons, drop-down lists).You don't necessarily need to display the data on the live site. This is possible, but custom module classes don't have built in listingweb parts for displaying the content on the live site the way custom tables do.You don't require versioning for you data.You don't need to store the same content in different languages.

Scenario

One specific scenario in which you can utilize module classes as a content storage is for page archival. That is, storing outdated pages thatyou don't need to display on the live site anymore. You are still able to access the page data but you don't have to clutter the content treewith unnecessary items. 

Limitations of using module classes for storing content

There are several things to consider when deciding if you should be using pages to store your content. Use pages when you need:

Data cannot be easily displayed on the live site.You cannot store multilingual content. Data can be translated using localization macros only.Unlike pages, data in module classes cannot make use of workflow.

When should I use custom tables to store content?

Custom tables allow you to store large amounts of content without the hierarchy provided by the pages. Use module classes when you need:

Access to the data via the UI, but without the need to represent the data in a hierarchical structure in the content tree.Need to store large amounts of data in a flat structure using the standard data types (int, string, ...) and one-to-many data (radiobuttons, drop-down lists).You want to display the data on the live site. Kentico comes with built-in web parts that allow you to display custom table data on thelive site.You don't need to store binary stream data.You don't require versioning for you data.You don't need to store the same content in different languages.

Pages vs. module classes and custom tables

  Pages Module classes Custom tables

Can hold traditional data types (int,float, ...)

Can hold binary stream data (files)

Can hold one-to-many data (radiobuttons, drop-down lists)

Data can be formatted usingtransformations

Can be used as an E-commerceproduct

Can be displayed by 'Listings' webparts

Can be displayed by 'Navigation'web parts

Workflow

Versioning

Multilingual content *

Hierarchical data structure

Each record has its own URL **

Data can be accessed using API

Importable / Exportable

Performance

Recommended for large data setswhen using flat data structure

Number of database tables thatstore the data

3+ 1 1

Recommended for large binary data

Binary data can be stored in filesystem

*You can translate data using localization macros only.

**You can access custom table records via listing web parts and query string URL parameters.

When should I use media libraries to store content?

Media libraries are designed to store large files — not exclusively of media character — such as videos, high-res images or packaged files.You can access media library files without overhead as there is no need to query the database to access them.

Pages vs. media libraries

  Pages Media libraries

Recommended for large binary data

Direct access to the data without queryingdatabase

Number of database tables that store thedata

3+ 2

Binary data can be stored in file system

 

Page typesEach page in Kentico is of a specific type – a page type. Each page consists of:

fields (data structure)editing form layouttransformations (design)queries

and other . properties Page types allow you to define custom website structure and store content (data) separately from design.

Creating custom page types

There are three 'types' of page types that you can create in Kentico:

Standard page types - use these to create template-based pages that form the structure of the site. Standard page types hold datain fields that you can fully customize.Content only page types - suitable for pages whose only task is to hold content, such as individual news articles.on MVC sitesContent only pages aren't based on and don’t contain presentation properties and tabs. This allows content editorspage templatesto use the pages without unnecessary distractions.Container page types - suitable for storing queries and transformations. Container page types don't contain any custom fields asthey are created without a  .coupled data table

Configuring page types

Page types are fully customizable – you can add, modify and delete any custom fields. You can also create additional versions of editingforms for individual page types, which you can then use in different situations.

See configuring page types for more information.

1. 2.

1.

2.

1. 2. 3. 4.

 

Creating page typesThis page describes how you can create page types. You can create new page types in the application.Page types

There are three 'types' of page types that you can create in Kentico:

Standard page types - use these to create template-based pages that form the structure of the site. Standard page types hold datain fields that you can fully customize.Content only page types - suitable for pages whose only task is to hold content, such as individual news articles.on MVC sitesContent only pages aren't based on and don’t contain presentation properties and tabs. This allows content editorspage templatesto use the pages without unnecessary distractions.Container page types - suitable for storing queries and transformations. Container page types don't contain any custom fields asthey are created without a  .coupled data table

Creating standard page types

Open the application.Page typesClick . A wizard opens.New page type New page type

Step 1

Fill in the values:Page type display name - the system displays this name to users in the administration interfaceNamespace: namespace distinguishes your page types from the default system types that use the namespace. cms Forexample, you can use your site name as the namespace.Name - page type identifier appended to its namespace

Click .Next

Step 2

Enter a for the database table that stores the page type data.Table nameEnter a for the table.Primary key name(Optional) Select if you want the page to to .Inherit fields from page type(Optional) Enable . Content only page type

Suitable for pages whose only task is to hold content, such as individual news articles. The pageson MVC sitesdon’t contain presentation properties and tabs. This allows content editors to use the pages without unnecessarydistractions. Note that you cannot convert 'Content only' page type to a standard page type later.

4.

5.

1. 2.

Click .Next

The wizard creates the database table.

Step 3

Now, you need to define fields of the page type (columns of the table). To define a page type field:

Click .New fieldFor each field, enter the values, click Save and repeat the procedure until you have defined all the listed fields.

Example of setting up fields for a Computer page type...

Field name: ComputerNameData type: TextSize: 200Required: yes (checked)Field caption: Computer nameForm control: Text box

Field name: ComputerProcessorTypeData type: TextSize: 200Field caption: Processor typeForm control: Drop-down listEditing control settings -> Data source: select and enter the following items into the text area, oneList of optionsper line:

The page is only a container without custom fieldsUse the second option 'The page is only a container without custom fields' if you want to create a page type that doesn'tcontain any custom fields (Container page type). That is, a page page without a  . Container page typescoupled data tableare suitable for storing queries and that are shared by multiple page types.transformations

2.

3.

1.

Athlon;AthlonPentium XEON;Pentium XEONPentium Core 2 Duo;Pentium Core 2 Duo

Field name: ComputerRamSizeData type: Integer numberField caption: RAM (MB)Form control: Text box

Field name: ComputerHDDSizeData type: Integer numberField caption: HDD (GB)Form control: Text box

Field name: ComputerImageData type: FileField caption: ImageForm control: Upload file

Click .Next

Step 4

Choose the field that will be used as the name for pages of this type. Pages of this type will use the value of the field in sitenavigation and in the Page application's content tree. Only fields are available in the drop-down list.Required 'text'

You can also define system fields that will be displayed when editing pages of this type on the tab. You can do this using the Form drop-down list when creating a new field. Select and you can then choose from the following two groups ofField type Page field

system fields:

Page fields - offers system fields of pages.Node fields - offers system fields of content tree nodes.

Page or node system fields will then be offered in the drop-down list. If you leave the Field name Display field in the editing check-box turned on, the field will be visible on the page's tab.form Form

1.

2.

1. 2.

3.

 Click .Next

Step 5

Select the page types that will be supported as parents for pages of this type in the application's content tree.Page

Click and sAdd page types elect a specific page type.Click . OK

 Click .Next

1. 2. 3.

4.

Step 6

Assign the page type to all websites on which you want to use it.

Click . Add sitesCheck the appropriate websites in the selection dialog.Click .OK

 Click .Next

Step 7

The wizard has finished the configuration of the new page type.

Click . You have created a new page type.Finish  

 

Creating content only page typesContent only page types are suitable for pages whose only task is to hold content, such as individual news articles. on MVC sites Unlike

Unlike custom tables, you can still use them to create a hierarchicalstandard page types, they don't have a representation on the website.data structure that supports workflow and versioning. Content only pages:

Aren't based on .page templatesDon’t contain presentation properties and tabs. This allows content editors to use the pages without unnecessary distractions.Don't have a presentation URL by default. You can to allow content editors to display content only pages inspecifying a URL patternthe preview mode and .on the live site via the administration UI

Now, you may want to:

Create transformations for the page type - to define how the page type's content is rendered on your pages.Create alternative forms for the page type - to create alternative editing forms for the page type.Extend the page type's listing filter – editors use page listing to in the applperform multiple page (batch) operations Pages ication.Limit the pages users can create – this way you can control where on the site users create new pages.

How content in page types is stored

The new page type has its own database table for its specific fields. Each page is stored in three tables: CMS_TREE (treestructure), CMS_Document (page properties, metadata and content defined on the Page tab) and the custom table - for example, CUSTOM_Computer.

The system automatically ensures all operations are performed correctly on these tables. The advantage of this storage is that it isvery fast and you can easily write standard SQL SELECT queries to retrieve data from the Microsoft SQL Server database.

1. 2.

1.

2.

1. 2. 3. 4.

5.

1. 2. 3.

Creating content only page types

Open the application.Page types Click . A wizard opens.New page type New page type

Step 1

Fill in the values:Page type display name - the system displays this name to users in the administration interfaceNamespace: namespace distinguishes your page types from the default system types that use the namespace. Forcmsexample, you can use your site name as the namespace.Name - page type identifier appended to its namespace

Click .Next 

Step 2

Enter a for the database table that stores the page type data.Table nameEnter a for the table.Primary key name(Optional) Select if you want the page to to .Inherit fields from page typeEnable . Content only page type

Click .Next

The wizard creates the database table.

Step 3

Click to define individual New field fields of the page type (columns of the table).For each field, enter the values, click   and repeat the procedure until you have defined all the listed fields.SaveClick .Next

You can also define system fields that will be displayed when editing pages of this type on the tab. You can do this using the Form

1.

2.

1. 2. 3.

1. 2. 3. 4.

Step 4

Choose the field that will be used as the name for pages of this type. Pages of this type will use the value of the field in sitenavigation and in the application's content tree. Only  'text' fields are available in the drop-down list.Page Required

 Click .Next

Step 5

Select the page types that will be supported as parents for pages of this type in the application's content tree.Page

Click and select a specific page type.Add page types Click .  OKClick .Next

Step 6

Assign the page type to all websites on which you want to use it.

Click . Add sitesCheck the appropriate websites in the selection dialog.Click . OKClick .Next

Step 7

The wizard has finished the configuration of the new page type. 

Click . You have created a new page type. Finish

drop-down list when creating a new field. Select and you can then choose from the following two groups ofField type Page fieldsystem fields:

Page fields - offers system fields of pages.Node fields - offers system fields of content tree nodes.

Page or node system fields will then be offered in the drop-down list. If you leave the Field name Display field in the editing check-box turned on, the field will be visible on the page's tab.form Form

Now, you may want to:

Specify URL pattern for content only pages - to allow content editors to display content only pages on the live site and inthe preview mode.Create transformations for the page type - to define how the page type's content is rendered on your pages.Create alternative forms for the page type - to create alternative editing forms for the page type.Extend the page type's listing filter – editors use page listing to in the applperform multiple page (batch) operations Pages ication.Limit the pages users can create – this way you can control where on the site users create new pages.

How content in page types is stored

The new page type has its own database table for its specific fields. Each page is stored in three tables: (treeCMS_TREEstructure), (page properties, metadata and content defined on the Page tab) and the custom table - for example, CMS_Document

1. 2.

1.

2.

1.

2.

 

Creating container page typesContainer page types are suitable for storing queries and transformations. Container page types don't contain any custom fields as they arecreated without a  .coupled data table

Due to their limited functionality, container page types do not have the Alternative forms, Fields, Layout, and Search fields tabs.

Creating container page types

Open the application.Page typesClick . A wizard opens.New page type New page type

Step 1

Fill in the values:Page type display name - the system displays this name to users in the administration interfaceNamespace: namespace distinguishes your page types from the default system types that use the namespace. Forcmsexample, you can use your site name as the namespace.Name - page type identifier appended to its namespace

Click .Next 

Step 2

Select the option.The page is only a container without custom fields

 

CUSTOM_Article.

The system automatically ensures all operations are performed correctly on these tables. The advantage of this storage is that it isvery fast and you can easily write standard SQL SELECT queries to retrieve data from the Microsoft SQL Server database.

2.

1. 2. 3.

1. 2. 3. 4.

1. 2.

3.

4. 5.

Click .Next

Step 3

Select the page types that will be supported as parents for pages of this type in the application's content tree.Page

Click and select a specific page type.Add page types Click .  OKClick .Next

Step 4

Assign the page type to all websites on which you want to use it.

Click . Add sitesCheck the appropriate websites in the selection dialog.Click . OKClick .Next

Step 5

The wizard has finished the configuration of the new page type.

Click . You have created a new page type. Finish

 

Advanced content modelingYou can use Kentico's page types to build an advanced content model. This allows editors to work with shared content (reusecontent onlypages) when modeling pages. Individual pages also support , and .workflow localization page-level permissions

Kentico allows you to define a field on individual page types. Using the field, you can let content editors know that you expectPages Pagesthem to reuse different pages when modeling an individual page.

For example, you can create an page type that consists of standard fields: , , and In addition to that, the article willArticle Header Text Image. consist of an page and an page. Both and are just pages that editors can use to create theInteresting fact Author Interesting fact Author content of this page.

Setting up content for modeling with related pages

To allow editors to reuse pages, add the form control to a page type:Pages

In the application, a page type.Page types Edit On the tab, add :Fields New field

Data type - PagesForm control - Pages 

Use the , and fields to inform content editors how you intend them to use the field.Field caption Field description Explanation textFor example:

Field caption - Interesting Fact and Author 

(Optional) a . This allows you to specify the section of the site from which editors are able to select pages. Select Starting pathSave.

Editors can now to reuse content on the tab.use this advanced content modeling technique Form

Developers can display the content on the live site:

By via generated code. For example in  .accessing the data MVC viewsUsing . The Relationship name is in the Page type (field name) format.listing web parts

   

Now, you may want to:

Create transformations the page type will store - to be shared by other page types.Create custom queries to store in the page type

This approach serves mainly for modeling content by editors. If you need to create named, two-sided page relationships betweenpages, use .standard page relationships

Modeling content by adding different pages in the Pages field is not a versioned operation. Changing the model of a page under aworkflow immediately reflects the changes on the published version of the page. The individual pages that editors add using thePages can still be affected by a .workflow

1.

2. 3.

4.

Configuring page typesYou can edit page type properties in the application, on the tab of a particular page type. The following topics describePage types General  some of the common page type configuration scenarios:

 

Changing page type iconsKentico allows you to upload your own icons and associate them with page types. You can also use a font icon class as a page typerepresentation.. This can be useful if you create custom page types or if you want particular page types to be more easily recognizable in vari

. For example, when users want to create a new page type.ous parts of the system  

To change a page type icon:

Open the Page types application.

Edit ( ) the page type.On the tab, youGeneral  choose between two types of images: 

Image - upload a standard image file

Font icon class - enter the name of a CSS class that defines a font icon

Save the changes.

You have changed a page type icon.

Where does the system use page type icons?

Users can see the smaller page type icons in, for example, the content tree of the application.Pages

Users can see the larger page type icons in, for example, the webpage dialog on the and tabs:Insert link Content -> Tiles Thumbnails

Note:

Page type icon files must be in the .PNG format.The system automatically converts the image you upload to the appropriate size. However, werecommend at least 16x16 pixels for the small icon and 48x48 pixels for the large icon.  

1.

2. 3. 4. 5.

6.

1. 2.

a.

b.

 

Creating alternative forms for page typesAlternative forms allow you to create additional versions of editing forms for page types, which you can then use in different situations. See C

for more information.reating alternative forms

In , you can learn about special code names of alternative forms. If you create anCode names of automatically used alternative formsalternative form with one of these names, the system uses the form automatically for a specific purpose.

Example - Creating a custom Page type insert form

The following example demonstrates how to create an alternative form for the page type and use it to customize the editing formNewsdisplayed when creating news articles.

Adding an alternative form

Create an alternative form for the page type:News

Open the application.Page types

Edit ( ) the page type.News Switch to the tab. Alternative formsClick  .Create new formSet the names of the form to the following:

Display name: News creationCode name: (this is the used for creating new items)insert automatic alternative form code name

Click .Save

The system creates a new alternative form. 

Configuring the alternative form

After you create an alternative form, you can change its fields using the .field editor

Switch to the tab.FieldsModify the fields as you desire. For example:

Select the field.NewsTitle

See for another practical example of using alternative forms with page types.Extending the page type listing filter

2.

b. c. d.

e. f.

g. h. i. j.

Type into the field's setting.The title of the news article... Editing control settings -> Watermark -> TextClick  .SaveSelect the field.NewsReleaseDate

Click ( ) next to the field's .Edit value Default valueEnter the into the dialog and click .{% DateTime.Now %} macro OKClick  .SaveSelect the field.NewsTeaserClear the check box.Display field in the editing formClick  .Save

The alternative form is ready to be used. If you open the application and create a new page, you can see the modificationsPages Newsmade in the alternative form:

The field displays the entered watermark textNews titleThe field automatically contains the current date and timeRelease DateThe field is no longer visible (it is only available when editing existing News pages)Teaser

1. 2. 3. 4.

5.

1. 2.

If you edit an existing News page on the tab, the original default editing form is used.Form

 

Specifying the URL pattern for content only pagesContent only page types don't have a presentation URL by default. This means that content editors cannot access content only pages in the

mode or when opening them on the live site via the administration UI. Content editors also aren't able to create page links using the Preview If you want your content only pages to support this functionality, you need to specify the property of their page type.text editor. URL pattern

Specify the property when:

Using a standalone which handles the presentation of your content only pages.MVC applicationUsing the portal engine and make use of content only page types.

You will usually only want to specify the property for pages with a separate presentation. For example, pages that provide information that isonly used when aggregated on a different page may not need to have their own specified. Examples of these pages could beURL patternindividual branches/offices/cafes of a company that you use on an aggregate page that displays all the branches/offices/cafes in one place.

Specifying the URL pattern property

(Optional) the site's .If you run your live site on a different domain, specify Presentation URLOpen the application.Page typesEdit a content only page type.Fill in the under which you want the page to be accessible from the administration UI. You can use iURL pattern macro expressionsn the pattern to access the . For example:page and node data

/{% DocumentCulture %}/Articles/{% NodeAlias %}

Resolves into URL ' for a page in the 'en-US' culture with 'On Roasts'.Roasts'http://www.example.com/en-US/Articles/On- Node alias

Click . Save

Editors can now access the pages of this type from the administration UI using the button. They can also insert links to the pagesLive site using the .text editor

The system may add a parameter to the resulting URL when displaying pages. For example, the parameter is added to the URLviewmodewhen you open a page on live site via the administration UI. The resulting URL may then look like this:

Roasts?viewmode=0http://www.example.com/en-US/Articles/On-

 

Adding support for preview mode

After you set the URL pattern for your content only page types, the system can automatically generate preview URLs for the given pages.You can use the preview mode in two ways within the application:Pages

Switch to mode using the main view mode selector.PreviewGenerate preview links for pages in , which you can then send to other users. See: Properties -> General -> Preview URL Sendinglinks to unpublished pages

The preview URLs that the system generates for content only pages can be very long (they contain information about the virtual context ofthe page and validation hashes). We recommend increasing the maximum allowed URL length for the application used to present thecontent.

Edit the web.config of the application.Set the attribute of the element in the section (512 should be a large enough value):maxUrlLength httpRuntime system.web

Another example of the usage of page type alternative forms is in the web part used by the feContribution list User contributionsature. In this web part, you can define pages that visitors are allowed to create on the live site.

The macro allows you to retrieve a page alias that you can use to create more SEO-friendly URLs.{% NodeAlias %}

Note: We do not recommend using query string parameters in URL patterns. The system removes any parameters whengenerating URLs for pages based on the pattern.Preview

Note:

Preview mode is not supported if you are using content only page types in combination with the portal engine and standard pages.You can instead use the preview of the pages that load and display the given content.

When developing an application that handles the presentation of content only pages (for example a ,standalone MVC application)you need to manually ensure that the preview mode displays the latest versions of pages. For more information, see Adding

.preview mode support for MVC sites

2.

3.

1.

2. 3. 4. 5.

a. b.

6.

<system.web>... <httpRuntime targetFramework="4.5" relaxedUrlToFileSystemMapping="true"requestValidationMode="2.0" maxUrlLength="512" />...</system.web>

Add a element to the  and set the attribute to the same value:requestLimits sectionsystem.webServer maxUrl

<system.webServer> ... <security> <requestFiltering> <requestLimits maxUrl="512" /> </requestFiltering> </security></system.webServer>

The application can now correctly process the preview URLs generated by the system. 

Extending the page type listing filterTo extend the possibilities of listing a certain page type, you can customize the filter that is used in the mode . Editors use the pageListing listing filter to in the and on perform multiple page (batch) operations Pages application Live site.

To extend the page type listing filter, in which you specify the fields that are then available in the filter.create an alternative form

Creating an alternative form to extend the page type listing filter

The following example shows how you can create an alternative form that extends an existing page type by a field.Location

Open the application.Page types

Edit ( ) the page type for which you want to customize the filter.Switch to the tab. Alternative formsCreate new form.Fill in the details as follows:

Display name - FilterCode name - Filter

The alternative form needs to have as its Code name to work as a filter in page listing.Filter

6.

7. a.

b.

i. ii.

Save the alternative form.The alternative form inherits all the fields from the parent (original) form by default. You can either:

Add new fields that you want to display in the page listing filter.— or — Deactivate the fields that you don't want to use in the page listing filter.

To deactivate the fields:

Switch to the .Fields tabFor each field that you don't want to use in the page listing form filter, turn the fielDisplay field in the editing formd off and the changes.Save

Now, whenever a user lists the page type for which you created the Filter alternative form, the system displays the customized filter.

 

Limiting the pages users can createThis topic explains how you can make creating new pages more intuitive for editors on your site. You can also use the same functionality tocontrol which pages are created in certain sections of the site and under certain page types in general. There are two complementary wayshow you can achieve this:

Allowed page types - define which page types users can place under the current page type. This is a general setting that doesn'ttake into account the path that users place the page types under.Page type scopes - define which page types users can use when creating new pages under specified paths. You can use scopes todistinguish certain sections of the website and restrict the pages that users can create in them.

Allowing users to place certain pages under a page type

You can control which page types users can create under a specific page type. Do that by adding allowed types to a page type. For example,you may want to allow users to only create page types under page types. This rule then appliesFile (CMS.File) Folder (CMS.Folder)

Note that custom layout in the alternative forms that are used to extend the page type listing filter.isn't applied

1.

2. 3. 4. 5. 6.

everywhere on the site.

Defining allowed child page types

Open the application. Page types

Edit ( ) the page type under which you want to specify allowed page types.Switch to the tab.Allowed typesUnder , click . A dialog opens.Allowed child page types Add page types Select page typesTurn the check-box on next to the page types that you want to add to the allowed child page types.Confirm by clicking .OK

You have added allowed child page types.

  

Specifying which pages users can create under certain paths

You can use page type scopes to narrow the number of page types that users can use when they create new pages under specified paths.This makes creating new pages more intuitive, especially if you have many page types in the system. For example, on the sample Corporatesite, you may want users to only create page types under the /Products/Books/ path.E-Book (CMS.Ebook)

In this section, you can learn about:

Defining allowed child page typesCreating page type scopesManaging page type scopes

When you add an , the system also automatically adds an to the child page thatallowed child page type allowed parent page typeyou are allowing.

1. 2. 3. 4. 5. 6.

a.

b.

a.

b.

a.

b.

c.

7.

Creating a new page under a page type scope

Creating page type scopes

Open the Page types application.Switch to . ScopesIn the drop-down list, select the site under which you want to create a new page type scope.Site Click on  .New scopeSpecify the path the scope applies to in the field. You can type the path in or use the button.This scope covers SelectSpecify the rest of the parameters.

Click for a description of the available options:

General – specify the scope coverage:

This scope covers – use the button to specify the path to which you want the page type scope to apply. YouSelectcan also type the path in the field directly.Apply to the whole section – enable if you want the scope to apply to all child pages under the specified path as well.

Page types – specify the page types the scope allows users to create:

Allow all page types – turn the check-box on if you want the scope to allow users to create all page types under thespecified path.Allow only the following page types – enable the check-box and to specify which page types usersAdd page typescan create under the specified path.

Advanced – specify additional options. These options are also limited to the page types you select in the Page types section.

Allow creating a linked page – turn the check-box on to allow users to create a linked page when creating a newpage.Allow creating A/B test variant – turn the check-box on to allow users to create an  A/B testing variant when creatinga new page.Condition – fill in a condition that further specifies when the scope is applied. For example, you can have two scopescover the same path, and the more restrictive of the scopes then apply to users who do not have the Globaladministrator . Scopes with a condition are evaluated before scopes without a condition.privilege level

Save the page type scope.

You have now created a new page type scope.

1. 2. 3.

4. 5. 6. 7. 8. 9.

Managing page type scopes

In this section, you can learn about:

Limiting multiple page types to a specific scope – Use to add multiple page types to a single page type scope.Limiting a page type to multiple scopes – Use to add a page type to multiple different page type scopes.Removing multiple page types from a scope – Use to remove multiple page types from a single page type scope.Removing a page type from multiple scopes – Use to remove a single page type from multiple page types at once.

Limiting multiple page types to a specific scope

Use this method if you want to assign multiple page types to a single page type scope. To assign a page type to multiple different page typesscopes, use .this method

Open the Page types application.Switch to . ScopesIn the drop-down list, select the site under which you want to add page types to an existing page type scope.Site

Edit ( ) the page type scope.Enable the check-box.Allow only the following page types Click on . The dialog opens.Add page types Select page typesTurn the check-box on next to the page types that you want to add.Confirm by clicking .OKSave the page type scope.

You have assigned page types to a page type scope.

Limiting a page type to multiple scopes

1.

2. 3. 4. 5. 6.

1. 2. 3.

4. 5.

6. 7. 8.

1.

2. 3. 4. 5. 6.

1.

2. 3.

Use this method if you want to assign a page type to multiple different page types scopes. To assign multiple page types to a single pagetype scope, use .this method

Open the Page types application.

Edit ( ) the page type to which you want to assign page type scopes.Switch to the tab.ScopesClick on . The dialog opens.Add to scopes Select scopesTurn the check-box on next to the page type scopes that you want to assign to the page type.Confirm by clicking .OK

You have assigned page type scopes to a page type.

Removing multiple page types from a scope

Use this method if you want to remove multiple page types from a single page type scope. To remove multiple page type scopes from a pagetype, use .this method

Open the Page types application.Switch to . ScopesIn the drop-down list, select the site under which you want to remove page types from an existing page type scope.Site

Edit ( ) the page type scope.Turn the check-box on next to the page types that you want to remove.

Click on . Remove selectedConfirm by clicking .OKSave the page type scope.

You have removed page types from a page type scope.

Removing a page type from multiple scopes

Use this method if you want to remove a page type from multiple page type scopes at once. To remove multiple page types from a singlepage type scope, use .this method

Open the Page types application.

Edit ( ) the page type from which you want to remove page type scopes.Switch to the tab.ScopesTurn the check-box on next to the page type scopes that you want to remove from the page type.Click on .Remove selectedConfirm by clicking .OK

You have removed page type scopes from a page type.

Viewing which pages are users allowed to create under a specific page type

To list the pages users are allowed to create under a page type:

Open the Page types application.

Edit ( ) the page type under which you want to view which pages are users allowed to create.Switch to the tab.Allowed childs

You have listed the page types users can create under a specific page type.

If you want to remove all page types from the page type scope at once, click on ( ) and choose  .... Remove all

1. 2. 3.

4.

Viewing which pages are users allowed to create under a specific path

To list the pages that users are allowed to create under a page type scope:

Open the Pages types application.Switch to . ScopesIn the drop-down list, select the site under which you want to view which pages are users allowed to create under a specificSitepath.

Edit ( ) the page type scope(s) covering the path.

You have viewed the pages that users are allowed to create under a specific path.

Note that some page type scopes can cover not only their specified paths, but all their child pages as well. This is indicated by an enabled A option.pply to the whole section

Viewing under which paths are users allowed to create a page

1.

2. 3. 4.

You can view under which paths users are allowed to create a certain page type. To do that, list the page type scopes the page type isassigned to:

Open the Page types application.

Edit ( ) the page type for which you want to list the page type scopes.Switch to the tab.Scopes In the drop-down list, select the site under which you want to list the page type scopes.Site

You have listed the page type scopes to which a page type is assigned.

 

Reference - Page type properties

General

Display name The name of the page type displayed in the administration andcontent editing interface.

Code name Sets a namespace prefix and unique name that serves as anidentifier for the page type, for example in selectors or the API.

Table name Displays the name of the database table used to store coupled datafor pages of this type, i.e. the content of its specific fields.

Inherit fields from pages type If a page type is selected and saved, the definitions of its fields willbe loaded and added to the current page type. These fields can beviewed and modified on the Fields tab.

Page type icon Allows you to that will be used to represent theupload custom iconspage type in various parts of the system.

Include in module package Allows you to assign the page type to a custom module (onlymodules that are in development mode are available). The systemthen includes the page type in that you createinstallation packagesfor the selected module in the application.Modules

If you select a module, you cannot specify on which the pageSitestype is available. The page type automatically uses the site bindingsof the given module, which you can edit in the application.Modules

New page settings

New page URL of the page that will be used when creating new pages of thistype.

Show template selection Indicates if users will be required to select a page template whencreating a new page of this type.

Root page template category May be used to limit the page template options available for pagesof this type to a specific sub-section of the template catalog. Whencreating new pages of the given type, users can only choose fromthe templates located under the specified category or in its childcategories.

Default page template Sets the page template used by default when the page is created. Ifno page template is specified, new pages inherit the template oftheir parent by default.

Due to their limited functionality, page types do not have the tabs.container Alternative forms, Fields, Layout, and Search fields

Editing pages settings(specify if you do not wish to use the system's default editing pages)

Editing page URL of the editing page that will be used when the page isdisplayed in editing mode via the Page tab.

Editing form URL of the editing page that will be used when the page isdisplayed in editing mode on the Form tab.

Preview page URL of the page that will be used when the page is displayed inpreview mode.

List page URL of the editing page that will be used when the page isdisplayed in list mode.

Advanced settings

Use publish from/publish to Indicates if the Publish from/to fields should be offered on the Formtab for pages of this type. These may be used to schedule the pagerepresented by the page to be published on the live site on aspecific date and time, or shown only during a limited time interval.

Behaves as Page (menu item) type Indicates if the page type behaves similar to the default Page (menu page type:item)

The default view mode for pages of this type is the Page tab.Pages of this type do not inherit the parent page's pagetemplate by default.Viewer web parts placed on pages automatically display childpages if their Path property is empty.Custom content is rendered on pages of this type if the<head>header content is defined in page template properties ->Header tab.

Related pagesCreating page types

 

Custom tablesCustom tables allow you to create your own tables in the system database. You can manage the data in custom tables without usingMicrosoft SQL Server Management Studio or any other database management tool. You will find this useful especially when you need tostore a large number of items in a flat data structure. Standard Kentico pages are not as efficient as custom tables for storing items in a flatstructure. Refer to for more information on the advantages of using custom tables over Pages.Storing data effectively

To learn how to display data from custom tables on the live website, see:

Displaying data from custom tablesWriting transformations for custom tables

Data stored in the tables can be searched through using . You can also . These forms canSmart search create alternative forms for the tablesbe used instead of the default forms for creating or editing custom tables in the administration interface, as described in Code names of

.automatically used alternative forms

You can use custom tables to store the data of custom-developed modules. Developers can handle custom tables and their data via the cust.om table API

   

Creating custom tablesThere are two applications related to custom tables in Kentico:

Custom table object typeIf you need to specify the type of the records in a custom table, use the following naming convention:

CustomTableItem.<code name>

For example, a custom table with code name has records of type:CustomTable.Users

CustomTableItem.CustomTable.Users

1. 2.

1.

2.

1. 2.

Custom tables application allows you to create new custom tables, given you are the site's global administrator. You can also viewand manipulate data in existing tables using this interface.Custom table data application allows you to view and manipulate data in existing custom tables only.

Note that you can create new custom tables using the wizard in the application only. There is currently no simple way ofCustom tablescreating custom tables using the API. This is due to the need to create related objects and settings — these tasks are handled by the wizard. 

Creating a custom table

Follow the example to create a new custom table using the .New custom table wizard

Starting the New custom table wizard

Open the application.Custom tables Click . A starts.New custom table New custom table wizard

Step 1

Enter the following details:Custom table display name: People

display name is used in Kentico user interface.Namespace: customtableName: people

Name is used in website code — always preceded by a Namespace, which allows you to have different tables ofthe same name in different contexts.

Click .Next

Step 2

Specify the details of the database table that the custom table uses.

Choose Create a new database table.Leave the value customtable_People in the Database table name field.

Click here for information about the available options...

Create a new database table - choose this option to create a brand new table in the system's database.Database table name - the actual name of the table in the system database. A name in the <cod<namespace>e name>_ format is pre-filled automatically.Primary key name - primary key column name, pre-filled with the value.ItemID

 

Use an existing database table - choose this option if you already have a physical table in the system database andwant to register it in the system.

Database table name - the actual name of the table in the system database. The drop-down list offers onlydatabase tables which are not part of the default Kentico database schema and are not yet registered for anyobject.

2.

3. 4.

1.

2.

3.

4.

5.

Primary key name - primary key column name. The original table's primary key column is used automatically.Note that this column needs to be an identity column as well.

The following check-boxes allow you to choose the default fields that you want to include in the custom table:

Include ItemGUID field - globally unique ID of the particular custom table data record. Note that this field is mandatoryif you want to  to a different instance of Kentico.stage the table's dataInclude ItemCreatedBy field - user name of the user who created the item.Include ItemCreatedWhen field - date and time of when the item was created.Include ItemModifiedBy field - user name of the user who last modified the item.Include ItemModifiedWhen field - date and time of last modification.Include ItemOrder field - order of the item when table content list is displayed. The lower number, the earlier positionin the list.

Make sure all the checkboxes are enabled.Click .Next 

Step 3

Third step contains a . The field editor lets you define the columns in the database table.field editor

Create the following fields to follow this example:

Create a field using the button with the following properties:New fieldField name: FirstNameData type: TextSize: 100Required: Yes (check the box)Field caption: First nameForm control: Text box

Click Save. Create a second field using with the following properties:New field

Field name: LastNameData type: TextSize: 100Required: Yes (check the box)Field caption: Last nameForm control: Text box

Click Save. Create a third field using New field with the following properties:

Field name: DateOfBirthData type: DateRequired: No (leave the box unchecked)Field caption: Date of birth

5.

6.

7.

1. 2. 3.

1.

2.

Form control: CalendarEditing control settings -> Edit time: NoEditing control settings -> Show 'Now' link: No

Click Save. Click .Next

Step 4

Select for which sites you want to make the custom table available

Click Add sites. A dialog box opens.Choose Corporate Site (or any site that you want to add the custom table to).Click Next.

Step 5

The last step gives you an overview of the tasks executed by the wizard.

the wizard. The system redirects you to the tab of the custom table that you created.Finish General 

Editing custom tablesThis topic shows how you can edit existing custom tables. If you want to learn more about creating custom tables first, refer to Creating

.custom tables  

For information on managing the data in custom tables, refer to .Managing custom table data

Editing existing custom tables

Open the Custom tables application.

Edit ( ) the custom table that you want to manage.

2.

3.

1.

2. 3. 4.

 Save the changes.

The interface is divided into the following tabs:

General - this is where you can modify the display and code names of the custom table, as well as define URLs of custom pagesthat you can then use instead of the default pages for adding, editing, viewing and listing of data items stored in the tableFields - on this tab, you can find the field editor that can be used to manage fields (columns) of the tableLayout - this tab allows you to create a custom form layout that will be used for adding and editing data itemsTransformations - this is where transformations for the custom table can be created and managedQueries - database queries for manipulation with data in the table can be created and managed on this tabSites - on this tab, you can define websites for which the custom table will be availableAlternative forms - alternative forms for adding and editing custom table data can be created on this tab; more info can be found in Code names of automatically used alternative formsSearch fields - on this tab, you can define how data stored in the custom table will be indexed by the Smart search moduleData - allows you to manage the data in the custom table. The same functionality is provided by the application.Custom table data Versions - on this tab, you can view and manage the versions of the custom table.

 

Managing custom table dataAs a content editor, you can manage data stored in custom tables in the application.Custom table data

As an administrator, you can access the same interface in Custom tables application, on the tab of a particular custom table.Data

Adding data into custom tables

The following example uses the custom table created according to the instructions in . The procedure is thePeople Creating custom tablessame for any other custom table (except for the fields, which always depend on individual tables).

Open the application.Custom table data

Click ( ) next to the table.Edit PeopleClick .New itemFill in the custom table's editing form.

4.

5. 6.

1.

2. 3. 4.

5.

6.

Click  to store the data into the custom table.Save Click and create at least two more records.Create another

Viewing data in custom tables

The following example uses the custom table created according to the instructions in . The procedure is thePeople Creating custom tablessame for any other custom table (except for the fields, which always depend on individual tables).

Open the application.Custom table data

Click ( ) next to the table. The system displays the list of entries in the custom table.Edit PeopleClick  . The system displays the dialog box.Select displayed fields Select displayed fieldsTurn the check-boxes on for the fields that you want to display.

Click . You can now see the modified view of the entries.Save & Close

Click ( ) next to any of the data records. The system displays a dialog with detailed information about the entry.View

6.

1.

2.

 

 

Creating alternative editing forms for custom tablesThe alternative forms allow you to create alternative representations of existing forms, which you can then use in different situations. You canfind more information in . In , you can learn about special codeCreating alternative forms Code names of automatically used alternative formsnames of alternative forms. If you create an alternative form with one of these names, it will be used automatically in the given situation.

The following example demonstrates how to create an alternative form for the custom table created according to the instructions in People C. You can apply the same procedure to any other custom table.reating custom tables

Adding the alternative form

Imagine, you want to collect data from the site visitors into this custom table, but you do not need their date of birth. For this purpose, you cancreate an alternative form, where you will disable the field.DateOfBirth

Open the application.Custom tables

Tip: You can create a custom filter for the custom table's data using alternative forms. See Displaying filters using alternative forms.

2. 3. 4. 5.

6.

1. 2. 3.

4.

1. 2. 3.

4. 5. 6.

7.

Edit ( ) the custom table.PeopleSwitch to the tab. Alternative formsClick  .Create new formType a for the form.Display name

Click  .Save

The system creates a new alternative form for the custom table. 

Configuring the alternative form fields

After you create an alternative form, you can change its fields using the .field editor

Switch to the tab. FieldsSelect the field.DateOfBirthDisable the option.Display attribute in the editing form

Click  .Save

You have configured the fields of the alternative form.

Displaying the alternative form on the live site

Now you can display this custom table on the website using the alternative form. You can use the web part.Custom table form

Open the application.Pages Switch to the tab.DesignPlace the web part on a page.Custom table form— or — Use the example web part on .Corporate site -> Examples -> Custom tables -> Custom table formConfigure the web part.Click next to the Alternative form name.Select

The alternative form takes precedence over the selected custom table.Choose the class and alternative form in the displayed dialog box and click .Select

Instead of hiding the field, you can experiment with different settings of the field. Try changing the Form control type or theField caption, or try changing the Editing control settings. This way, you can configure the alternative form as you wish.

7.

8.

1. 2. 3. 4.

1. 2. 3. 4.

Click .Save & Close

The alternative form appears on the page (without the field). Users can submit the form to add new records to the custom table.DateOfBirth

 

Setting custom table permissionsBy modifying permissions, you can control which users and roles can read, create, modify and delete custom table data. You can configurethe permissions of custom tables on two levels — globally for all custom tables belonging to the current site and separately for eachparticular custom table.

Note that this example uses the sample and the roles that are on the site by default. Learn more about roles in Corporate site Role.management

Configuring permissions for all custom tables assigned to a certain site

Open the application.Permissions In the drop-down list, select .Site Corporate siteIn the first drop-down list choose , and in the second.Permissions for Module Custom tablesGrant the permission to the role.Read CMS Basic users

You have assigned the role the permission to custom table data on the CMS Basic users read Corporate site.

Configuring permissions for specific custom tables

Open the application.Permissions In the drop-down list, select .Site Corporate siteIn the first drop-down list choose , and the specific custom table in the second.Permissions for Custom tableGrant the permission to the role.Read CMS Community administrators

You have assigned the role the permission to custom table data on the CMS Community administrators read Corporate site. 

1.

2.

3.

Preparing your environment for team developmentKentico provides the following features that help users collaborate when developing websites:

 

Setting up continuous integrationKentico provides a solution that allows you to serialize the data of objects from the database into XML files on the filecontinuous integrationsystem. You can then add the files to a (for example or ) and use them to synchronizesource control system Team Foundation Server Gitdatabase data between team members. The system ensures that the XML data of matching objects is always identical and consistent(including element and attribute order), even when serialized on different instances of Kentico.

The system stores the XML files containing the serialized data of objects in the project's folder. For detailsCMS\App_Data\CIRepositoryabout the folder and file structure, see .Continuous integration repository structure

The continuous integration solution is usable in the following environment:

Multiple development instances, each with its own project files and database– AND –A central source control system that provides change management and version control for files

To start developing sites using the continuous integration solution:

Set up your development environment and continuous integration according to the instructions in the following sections:Preparing the development environmentFiltering object types

Establish a process for transferring objects back into the database from the XML files. See CIRepository Restoring continuous.integration files to the database

Begin development. We strongly recommend following the best practices described in Using continuous integration with Visual

Continuous integration

Enables development in the following environment:

Multiple development instances, each with its own database– AND –A central source control system for managing files

Allows developers to serialize the data of objects from the database into XML files on the file system. The files can then be added to asource control system and used to synchronize database data between team members along with standard project files.

Object locking

Usable in the following environments:

Multiple development instances with a shared database– OR –Single instance used by multiple developers

When working with a shared database, collisions can occur if multiple people edit the same object at the same time. To avoid overwritingof work, developers can lock objects for editing (check out) and unlock them (check in) after finishing. When an object is checked out,other developers cannot modify it. Locking is available for most objects with editable code, such as or CSS stylesheets web part

.containers

Note: We strongly recommend setting up for any collaborative environment with a shared database. Webweb farm synchronizationfarms ensure that all instances are always up-to-date by synchronizing cached content and settings.

External editing of code

Many objects used for website development in Kentico contain code (for example , or ).CSS stylesheets Page layouts TransformationsThe system allows you to store the code within the project's file system in addition to the database and synchronize the changes. Youcan then edit the code in external editors and manage it using a source control system.

Note: This feature only manages code. Other object data and settings remain only in the database and are represented in the fileNOTsystem.

If you need to work with the continuous integration files in a different location, use one of the approaches described in Storing the.continuous integration files in a custom location

3.

1. 2. 3. 4.

1.

. The page primarily focuses on using Visual Studio in combination with a or sourceStudio Team Foundation Version Control Gitcontrol repository, but many of the recommendations also apply generally to any source control system.

  

Usage and relationship with other features

Continuous integration is designed to allow synchronization and version control of database data (through an externalduring developmentsource control system).

The solution is NOT intended for deployment of content to instances outside of your development environment.

For deployment of content, you can use the following options:

Set up one of the instances in your continuous integration environment as a source server for StagingExport and import packages

Additionally, we do not recommend using continuous integration together with the other team development and versioning features inKentico:

Object lockingObject versioning (including the and )Recycle bin for objects PagesExternal editing of code (and )Deployment mode for virtual objectsPage workflow

Continuous integration always works with the main version of each object in the database. Older or deleted versions of objects andnon-published versions of pages are ignored. For example:

If you use the feature, continuous integration ignores all versions of objects except for the latest. If you roll back anobject versioningobject to an older version, the object is updated in the folder.CIRepositoryIf you delete an object or page to the recycle bin, continuous integration fully removes the corresponding XML file. If you restore theobject, an XML file is added as if a completely new object were created.If you edit an object's code externally (e.g. the code of a CSS stylesheet), changes are ignored by continuous integration until yousynchronize the code back into the database. You can still synchronize the code without the continuous integration solution byincluding the external file in your source control.

Limitations

Continuous integration currently has the following limitations:

Not all object types in the system are supported. See for a complete list.Object types supported by continuous integration

Continuous integration only tracks object changes made through the Kentico administration interface or API. Changes made directlyin the database or by external tools that modify the database are not tracked. After making such changes, you need to manuallyserialize all objects in the application to synchronize the database with the file system repository. ForContinuous integrationexample, continuous integration does not track roles imported by the external utility.AD import

You reliably use continuous integration in environments where the folder is located on a (cannot CIRepository shared file systemmultiple Kentico instances with separate databases connected to the same file system repository). Common examples of shared filesystems are external storage providers, such as or .Azure storage Amazon S3

Preparing the development environment

Before you can use the continuous integration solution, you need to set up Kentico instances for your development team.

Start by preparing an initial instance:

Either a new instance of Kentico or select an existing instance as a starting point.installEnable continuous integration on the given instance (see for details).Enabling continuous integrationCreate a backup of the instance's database.Add the Kentico solution to your source control (adding only the folder may lead to problems and is notentire CIRepositoryrecommended).

To add development instances into your environment, perform the following steps for each instance:

Connect to the source control from the development machine and load the latest version of the solution files onto the local filesystem.

Decide how to handle source control for the project's file. Each development machine needs to have aweb.configconnection string to a different database, but you may want to synchronize other parts of the web.config.

Continuous integration has a and should never be enabled on production sites.negative impact on site performance

See fhttps://weblog.west-wind.com/posts/2013/Feb/27/Sql-Connection-Strings-in-Config-Files-vs-Source-Controlor possible solutions.

1.

2. a. b. c.

3. 4.

1.

2.

1. 2. 3. 4. 5.

1. 2.

If you use IIS to run your development sites, register the project as an application in IIS:Open .Internet Information Services (IIS) ManagerAdd a new application under your IIS web site and map the to the project's folder.Physical path CMSCreate a new application pool for the application (or use an existing application pool).

Create (restore) a copy of the initial database on your SQL server.Connect the instance to the new copy of the database (set the appropriate connection string in the project's web.config).

After you complete the process, all development machines will contain their own Kentico project files connected to a separate copy of thedatabase. You can start using your source control system to synchronize project files between the instances. The continuous integrationsolution serializes database data onto the file system and you can include it in your source control, just like any other files.

If you need to add further instances later (after development with continuous integration starts), use the same process. However, you need tomake sure the database is synchronized with the rest of the development environment. Use one of the following approaches:

Maintain a central database connected to the mainline source control and always create an up-to-date backup for new developers.– OR –Use the original database backup and then get the latest data:

Restore the current object status from the continuous integration repository into the database. See Restoring continuous.integration files to the database

Manually transfer changes made to the data of object types not supported by continuous integration (maintaindocumentation of such changes). You can use the feature.export and import

Enabling continuous integration

To configure a Kentico instance to use the continuous integration solution, perform the following steps:

Open the application in the Kentico administration interface.Continuous integrationSelect the checkbox.Enable continuous integrationClick .SaveClick .Serialize all objectsWait until the serialization process finishes.

The project's  folder now contains XML files storing the serialized data of all supported objects from theCMS\App_Data\CIRepositorydatabase. The system also tracks create, update and delete operations for the given objects and automatically transfers the changes to theserialized data on the file system.

Configuring instances to synchronize macros

To ensure that work correctly when synchronizing objects using the continuous integration solution, all developmentmacro expressionsinstances must use the same hash salt value.

If your development instances do not all start with the same web.config file, you need to set a matching value for the keCMSHashStringSalty in the section on all instances. The best option is the hash salt used by the starting instance that you used to create your initialappSettingsdatabase backup. You can use any string as the value, but the salt should be random and at least 16 characters long. For example,a randomly generated is a strong salt:GUID

<add key="CMSHashStringSalt" value="e68b9ad6-a461-4707-8e3e-ece73f03dd02" />

The salt value is used as part of the input for the hash function that creates the security signatures of macros. Having the same hash saltvalue on all instances is necessary to ensure that macro signatures are valid when transferring data between instances.

The best option is to set the hash salt value before you start development. Changing the salt causes all current hash values to becomeinvalid. To fix existing macro expressions in the system after changing the hash salt, you need to re-sign the macros. See Working with

for more information.macro signatures

Filtering object types

The continuous integration solution allows you to exclude specific types of objects if you do not wish to synchronize all supported types. Toconfigure the system to ignore certain object types within continuous integration:

Edit the file in the root of the folder.repository.config CMS\App_Data\CIRepositoryAdd elements into one of the following sections of the config file:<ObjectType>

<IncludedObjectTypes> - defines a of object types. If you specify one or more object types, continuous integrationwhitelistonly processes objects of the given type. No restrictions apply if the whitelist is empty.

The process described above ensures that objects have identical GUID values (globally unique identifiers) across your entiredevelopment environment. If you perform a separate database installation for each development instance, you will need tomanually resolve a large number of when synchronizing data through the continuous integration solution.GUID conflicts

2.

3.

4. 5.

a. b.

<ExcludedObjectTypes> - defines a of object types. Continuous integration processes all included object typesblacklistexcept for the listed types.

Set the values of individual elements to the names of object types that support continuous integration. ObjectType

Save the file.repository.configRun complete serialization for all objects to bring your folder into the required state:CIRepository

Open the application in the Kentico administration interface.Continuous integrationClick .Serialize all objects

Excluding an object type in the file affects all processes related to continuous integration:repository.config

Serializing of all objects onto the file systemAutomatic tracking of create, update and delete operations for the given objects and transferring of the changes to the serializeddataRestoring of objects from the file system into the database

By default, the list contains the object type. Settings may contain sensitive data – only remove the<ExcludedObjectTypes> cms.settingskeyexclusion if you agree to make all setting values available within the file system used by your application and any connected source controlsystems.

repository.config examples:

<?xml version="1.0" encoding="utf-16"?><RepositoryConfiguration xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <!-- Continuous integration includes all supported objects except for emailtemplates. --> <IncludedObjectTypes> </IncludedObjectTypes> <ExcludedObjectTypes> <ObjectType>cms.emailtemplate</ObjectType> </ExcludedObjectTypes></RepositoryConfiguration>

Tip: To find the values, see or check the names of theObjectType Object types supported by continuous integrationcorresponding folders in the folder.CIRepository

Excluding child and binding object types

The system uses the following rules to automatically exclude child and binding object types:

Child object types follow the configuration of their parent object type. For example if you exclude page types, then queries,transformations and alternative forms of page types are also excluded.Binding object types are excluded if all object types within the given relationship are excluded.

The whitelist only allows you to specify the main object types.<IncludedObjectTypes>

In the blacklist, you can exclude both the main object types and specific binding or child object types.<ExcludedObjectTypes>

Important: To maintain consistency, always use the same settings across your entire development environment.repository.configWhenever you make any changes, use your source control system to synchronize the file along with the other content of theconfig

folder. When a developer loads a new version of from the source control, the new settings startCIRepository repository.configapplying after or a manual restart of the application.restoring objects into the database

1.

2. 3.

a. b.

<?xml version="1.0" encoding="utf-16"?><RepositoryConfiguration xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <!-- Continuous integration only includes web parts and web part categories. Webpart layouts are excluded. --> <IncludedObjectTypes> <ObjectType>cms.webpart</ObjectType> <ObjectType>cms.webpartcategory</ObjectType> </IncludedObjectTypes> <ExcludedObjectTypes> <ObjectType>cms.webpartlayout</ObjectType> </ExcludedObjectTypes></RepositoryConfiguration>

Upgrading projects that use continuous integration

If you need to apply a to an instance that has continuous integration enabled, use the following procedure:hotfix or upgrade

Restore objects from the continuous integration repository to your database.

Apply the hotfix or upgrade.Run complete serialization for all objects to recreate the content of the folder:CIRepository

Open the application in the Kentico administration interface.Continuous integrationClick .Serialize all objects

This approach ensures that your folder contains all object changes made by the hotfix or upgrade and that the serializationCIRepositoryprocess itself runs according to the new version.

For hotfixes, you need to apply the update separately for each development instance. Do NOT load project file changes from your sourcecontrol on instances where the hotfix is not applied yet.

For major upgrades, it may be more efficient to upgrade only one instance and then set up your environment again according to the processdescribed in .Preparing the development environment

Storing the continuous integration files in a custom location

After you set up and enable continuous integration, the system serializes database data into XML and stores the results on the file system.

By default, the files are created in the Kentico project's folder. If your development environment requires aCMS\App_Data\CIRepositorydifferent location for the continuous integration files, you can use one of the following approaches:

Create a file system junction point– OR –Use a custom Kentico storage provider

Creating a junction point

By defining a file system , you can redirect the folder to a different location.Junction point CIRepository

You can skip the restore if you are sure that your database is synchronized with the current status of your folCIRepositoryder.

Important

We recommend keeping the default folder within the folder of the Kentico web project and having theCIRepository App_Dataentire Kentico solution included within your source control. This setup allows you to easily synchronize all types of related projectfiles together with the database data tracked by the continuous integration solution.

If you do decide to change the location, do NOT use the new folder as the root of your source control repository.CIRepositoryAlways add it as a subfolder under a different root folder. The continuous integration solution within deletes all folders CIReposito

when storing all objects. If the folder is the root of your source control repository, you may encounter errors or other problemsrywhen using source control systems that utilize custom folders in the root.

Limitation: The target location must be on a local drive or volume (network locations cannot be used).

1. a. b.

2. 3.

1. 2. 3.

If you have already enabled continuous integration and serialized objects, you need to:(Optional) Back up your and the data files in .repository.config CIRepositoryDelete the folder in your Kentico project (it is not possible to create a junction point for an existing folder).CIRepository

Create the target folder where you wish to store the continuous integration files.Open the Windows command prompt and run the command:mklink /J

mklink /J <CIRepository folder path> <target folder path>

For example:mklink /J C:\inetpub\wwwroot\Kentico\CMS\App_Data\CIRepositoryC:\ExternalSourceControl\CIRepository

When serializing object data to the file system, the Kentico continuous integration solution now creates the files in the specified target folder.You can add the target folder into your source control system.

Using a custom storage provider

You can use a to change the path of the folder. The target location can be a local drive, or any networkcustom storage provider CIRepositorylocation for which the application has sufficient permissions.

To register a storage provider, you need to run custom code during the initialization of the application. You can do this by creating a custom, or via the partial class in the Kentico project's folder. For example, the following steps demonstratemodule CMSModuleLoader App_Code

how to change the path by adding a class in CIRepository App_Code:

Open the Kentico web project in Visual Studio (using the or file).WebSite.sln WebApp.slnCreate a new class in the folder (or  on web application projects).App_Code CMSApp_AppCode -> Old_App_CodeUse the following code for the class:

using CMS.IO;using CMS.Base;

[CICustomStorage]public partial class CMSModuleLoader{ private class CICustomStorageAttribute : CMSLoaderAttribute { /// <summary> /// The system executes the Init method of CMSModuleLoader attributes whenthe application starts. /// </summary> public override void Init() { // Maps the 'App_Data/CIRepository' folder in the Kentico project to acustom location // The 'UseLocalFileSystemForPath' method internally creates a customStorageProvider instance, // and maps the specified Kentico directory (first parameter) to adifferent location based on a root path (second parameter) StorageHelper.UseLocalFileSystemForPath("~/App_Data/CIRepository",@"C:\ExternalSourceControl"); } }}

When serializing object data to the file system, the Kentico continuous integration solution now uses the folder located underCIRepository

Limitations:

The target location always includes the full folder structure, starting from a specified root~/App_Data/CIRepositorydirectory.After you define the custom storage provider, the folder can no longer be accessed within the originalCIRepositorylocation (unlike when using a junction point).

the mapped root folder. You can add the folder into your source control system. 

Continuous integration repository structureWhen using the , the system serializes database data into XML and stores the results on the file system in thecontinuous integration solutionproject's folder.CMS\App_Data\CIRepository

The files are further organized within the following folder structure:

Site level folders - the top level separates objects based on their relationships with sites: for global objects, @global <site code for individual sites (stores site-related objects, such as roles or ad-hoc page templates)name>

Object type folders - the next level contains folders for specific types of objects, based on (see object type names Object to learn more).types supported by continuous integration

Object files - individual XML files are named according to the of the corresponding object. Objectcode nametypes without code names use the value of a non-unique field, followed by a unique hash. Object types without anyeasily readable identifying fields use their GUID value for the file name.

Binding data files - binding data is not stored in separate files for individual binding records, but combined for eachmain object in the relationship. The binding XML data contains an identifier of the main object (parent) in therelationship, and then identifiers of all objects that have the given relationship with the main object, along with anyother data stored by the binding. The binding files are named after the main object in format: <objectname>@<unique hash>

Parent object folders - object types that belong under a parent type (such as the transformations of a page type)use an additional level of subfolders – objects are separated into folders named according to the parent object informat: . For object types that have multiple possible parent types, the<parent object name>@<unique hash>folder name also contains a prefix (for example, transformations can belong under page<parent object type>_types or custom tables).

Separated field files - certain types of objects store the values of specific data fields in separate files (placed nextto the main XML file). For example, the binary data of metafile objects is stored in separate files. The separated filesuse names in format and have an appropriate extension.<object name>#<separated field identifier>

 

Example - CIRepository structure

Note: The example does not include all .object types supported by continuous integration

Long names and forbidden characters

Very long folder and file names automatically replace the middle of the name with characters, preceded and followed by a limited..number of characters from the start and end of the name. To ensure the uniqueness of the name, an symbol followed by a@fixed-length hash value is appended.

For example: longcustomwpprefix..webpartcodenameend@fe6fd25d3e.xml

If an object name contains characters that are not allowed in file names (for example slashes or backslashes), the given charactersare removed and the same unique hash is appended.

CMS\App_Data\CIRepository@global

cms.alternativeformcms.news@8a478af656

filter.xmlcms.documenttype

cms.news.xmlcms.emailtemplate

blog.newcommentnotification.xmlcms.metafile

articles@7baacb97a4articlesthumbnail.png@ead1667b00#file.pngarticlesthumbnail.png@ead1667b00.xml

cms.pagetemplatearticles.xml

cms.pagetemplatesitearticles@7baacb97a4.xml

cms.transformationcms.news@8a478af656

newslist.xmlcms.webpart

repeater.xmllogonform.xml

cms.webpartcategorydocumentviewers.xml

Storage structure for specific object types

Pages

The system uses three object types to store the definitions and settings of . As a result, the files containing the serialized page dataPagesuse a more complex structure than standard objects. The structure reflects how pages are .stored in the database

Each page is serialized in a site-specific folder and contains:cms.document

A file format describing the node data. This data determines where the page is stored in thein the <nodealiaspath>@<hash>.xml content tree. The data is shared by all language versions of the page.A folder in the format containing:<nodealiaspath>@<hash>#<culturecode>

A file, containing language-specific data. Also contains the content of and  .document.xml editable regions editor widgetsA file, containing the data stored in the fields of individual  .fields.xml page types

Note: Other page-related object types, such as and , are stored seperately in the Page attachments Page-level permissions (ACLs) CIReposi folder.tory

For example, a page with the " " culture code on the site would be serialized into the"Coffee Beverages Explained" en-us dancinggoat following XML files:

Forms

The system uses multiple object types to store the definitions and settings of . As a result, the files containing the serialized data ofFormsforms use a more complex structure than standard objects.

Each form is serialized into the following files:

A global item.cms.formclassA site-specific item.cms.formAny alternative forms under the main form are serialized as child objects of the global item.cms.formclassBindings between forms and roles (determine which user roles are allowed to manage the form and its data in the application)Formsare site-specific, and the main object in the relationship is the form's item.cms.form

Note: The continuous integration solution does NOT serialize the data records stored by individual forms.

For example, a form on the site with the  code name, a  alternative form and role bindings woulddancinggoat "UserFeedback" "VIPFeedback"be serialized into the following XML files:

cms.webpartlayoutlogonform@9c9772813a

ecommercelogon.xmldancinggoat

cms.documenttypescopearticles@e0c9de07c4.xml

cms.emailtemplateblog.newcommentnotification.xml

cms.pagetemplate3f0209c2-c0b9-47de-a855-0ca34e586b77.xml

cms.pagetemplatescopedancinggoat-landingpage@5db220236b

home@6be8e032f6.xmlcms.role

contenteditor.xmlcms.userrole

contenteditor@f6aafc4899.xml

CMS\App_Data\CIRepositorydancinggoat

cms.attachmentarticles_coffee-be..es-explained_en-us@b93096c0b8

coffee-beverages-explained-1080px.jpg@33fb4ffda2#file.jpgcoffee-beverages-explained-1080px.jpg@33fb4ffda2.xml

cms.documentarticles_coffee-beverages-explained@e50cf58d9e.xmlarticles_coffee-beverages-explained@e50cf58d9e#en-us

document.xmlfields.xml

CMS\App_Data\CIRepository@global

cms.alternativeformbizform.userfeedback@09642c63d0

vipfeedback.xml

 

Object types supported by continuous integrationContinuous integration supports the following types of Kentico objects:

General

Object type CI folder name Notes

Alternative forms cms.alternativeform Child object type with the following possibleparent types: , , Custom tables Forms Pagetypes 

Countries cms.country Supported child objects:

States (cms.state)

CSS stylesheets cms.cssstylesheet  

Custom tables cms.customtable Only includes the definitions and settings ofcustom tables, not the data records storedwithin the tables.

Supported child objects:

Alternative forms ( )cms.alternativeformTransformations (cms.transformation)Queries ( )cms.query

Email templates cms.emailtemplate  

Forms cms.formcms.formclass

Only includes form definitions and settings,not the data records stored by individualforms.

The system uses multiple object types tostore the definitions and settings of forms.See the section in Forms Continuous

for moreintegration repository structureinformation.

Supported child objects:

Alternative forms ( )cms.alternativeform

Form controls cms.formusercontrol  

Meta files cms.metafile Includes files related to other objects. Forexample thumbnail images of page types oremail template attachments.

Page layouts (shared) cms.layout  

Page template categories cms.pagetemplatecategory  

Page template scopes cms.pagetemplatescope Child object type of objects. Page template

Page templates cms.pagetemplate Supported child objects:

Page template scopes (cms.pagetempl)atescope

MVT combinations (om.mvtcombination)MVT variants ( ) om.mvtvariantPersonalization variants (om.personaliz

)ationvariant

Page type scopes cms.documenttypescope  

cms.formclassbizform.userfeedback.xml

dancinggoatcms.form

userfeedback.xmlcms.formrole

userfeedback@b8da61c184.xml

Page types cms.documenttype Supported child objects:

Alternative forms ( )cms.alternativeformTransformations (cms.transformation)Queries ( )cms.query

Queries cms.query Child object type with the following possibleparent types: ,  Custom tables Page types

Roles cms.role  

Settings cms.settingskey Settings are supported by continuousintegration, but in the excluded by default r

. Settings may containepository.config filesensitive data – only remove the exclusion ifyou agree to make all setting valuesavailable within the file system used by yourapplication and any connected sourcecontrol systems.

States cms.state Child object type of objects. Country

Transformations cms.transformation Child object type with the following possibleparent types: ,  Custom tables Page types

Web part categories cms.webpartcategory  

Web part containers cms.webpartcontainer  

Web part layouts cms.webpartlayout Child object type of objects. Web part

Web parts cms.webpart Supported child objects:

Web part layouts ( )cms.webpartlayout

Widget categories cms.widgetcategory  

Widgets __________________________

cms.widget  

 

Page content

Object type CI folder name Notes

ACL items cms.aclitem Child object type of Page-level permissionobjects. (ACL)

Attachments cms.attachment Child object type of objects. Page

Categories cms.category Only includes global and site categories.User categories are not supported.

Page-level permissions (ACLs) cms.acl Supported child objects:

ACL items ( )cms.aclitem

Unsupported development objects

The following object types commonly used during development are currently NOT supported by continuous integration:

Custom modules - to synchronize module database objects across your development environment, use the export and feature. To leave the modules open for editing after import, disable the option whenimport Seal the selected modules

selecting modules in the export wizard.Resource strings - create and edit resource strings within files in the Kentico project. Use your source control systemresxto synchronize the files between developers.

Pages cms.document Only supported when not using , asworkflowcontinuous integration is designed for useduring the project's development phase.

The system uses multiple files to store pagedata. See the section in Pages Continuous

for moreintegration repository structureinformation.

Supported child objects:

Attachments ( )cms.attachment

Page relationship types cms.relationshipname  

Page tags and tag groups__________________________

cms.taggroup Tag groups are represented as a separateobject type (cms.taggroup). Tags are storedwithin the data of individual Page(cms.document) objects.

On-line marketing

Object type CI folder name Notes

Activity types om.activitytype  

Automation actions ma.automationaction  

Email campaign templates newsletter.emailtemplate  

MVT combinations om.mvtcombination Child object type of objects. Page template

MVT variants om.mvtvariant Child object type of objects. Page template

Personalization variants __________________________

om.personalizationvariant Child object type of objects. Page template

E-commerce

Object type CI folder name Notes

Carriers ecommerce.carrier  

Currencies ecommerce.currency  

Departments ecommerce.department  

Exchange tables ecommerce.exchangetable  

Manufacturers ecommerce.manufacturer  

Order statuses ecommerce.orderstatus  

Payment options ecommerce.paymentoption  

1. 2.

1. 2.

3.

Unsupported page permission scenario

Continuous integration does not support scenarios where different are applied to the same pagepage-level permissions (ACLs)from different sources and then synchronized.

Developer A

Sets permissions for a user or a role on a page.Pushes the changes to the source control system.

Developer B

Sets permissions for the user or role on the page.different same sameDownloads the latest version from the source control. No collisions occur, because the ACL items are represented bydifferent files.

from the file system to the database. Both ACL item files are processed, but only one is kept in theRestores objectsdatabase, depending on the order in which they are processed.

Product internal statuses ecommerce.internalstatus  

Product option categories ecommerce.optioncategory Supported child objects:

Product options(ecommerce.skuoption)

Product options ecommerce.skuoption Child object type of Product option objects.category

Product public statuses ecommerce.publicstatus  

Product files ecommerce.skufile Child object type of objects.Product

Product variants ecommerce.skuvariant Child object type of objects.Product

Products ecommerce.sku Supported child objects:

Product files ( )ecommerce.skufileProduct variants (ecommerce.skuvarian

) t

Shipping costs ecommerce.shippingcost Child object type of objectShipping options.

Shipping options ecommerce.shippingoption Supported child objects:

Shipping costs (ecommerce.shippingco)st

Suppliers ecommerce.supplier  

Tax classes __________________________

ecommerce.taxclass  

Binding object types

In addition to the standard object types, continuous integration also supports most related bindings (i.e. objects representing relationshipsbetween the supported objects and other objects). For example, the binding objects that store how page templates or page types areassigned to sites.

Binding CI folder name Main object type (parent) Related object type

Allowed child page types cms.allowedchildclass Page type Page type

Applications assigned to the defaultdashboard of roles

cms.roleapplication Role UI element

Categories assigned to pages cms.documentcategory Page Category

Countries of tax classes ecommerce.taxclasscountry Tax class Country

States of tax classes ecommerce.taxclassstate Tax class State

Device profile layouts of pagetemplates

cms.templatedevicelayout Page template Device profilePage layout (optional)

Exchange rates ecommerce.exchangerate Exchange table Currency

Managers (users) of departments ecommerce.userdepartment User Department

Mapped page layouts of deviceprofiles

cms.deviceprofilelayout Device profile Page layout (source)Page layout (target)

Page relationships cms.relationship Page PagePage relationship type

Pages with fields containing otherpages(see )Advanced content modeling

cms.adhocrelationship Page PagePage relationship type

Payment options of shipping options ecommerce.paymentshipping Shipping option Payment option

Permissions assigned to roles cms.rolepermission Role Permission

Product bundles ecommerce.bundle Product Product

Product options allowed for products ecommerce.skuallowedoption Product Product option

Product options of product variants ecommerce.variantoption Product variant Product option

Product option categories ofproducts

ecommerce.skuoptioncategory Product Product option category

Roles assigned to forms cms.formrole Form Role

Roles assigned to widgets cms.widgetrole Role WidgetPermission

Roles in memberships cms.membershiprole Membership Role

Scopes assigned to page types cms.documenttypescopeclass Page type scope Page type

Sites of CSS stylesheets cms.cssstylesheetsite CSS stylesheet Site

Sites of data classes cms.classsite Page typeCustom table

Site

Sites of page templates cms.pagetemplatesite Page template Site

Sites of page relationship types cms.relationshipnamesite Page relationship type Site

Sites of web part containers cms.webpartcontainersite Web part container Site

Tax classes of departments ecommerce.departmenttaxclass Department Tax class

Tax classes of products ecommerce.skutaxclass Product Tax class

Tax classes of shipping options ecommerce.shippingoptiontaxclass Shipping option Tax class

UI elements allowed for roles (UIpersonalization)

cms.roleuielement Role UI element

Users in roles cms.userrole Role User

 

Restoring continuous integration files to the databaseWhen using , you can get changes from other developers or your source control system by loading XML files into your continuous integration

folder. You then need to transfer the corresponding object changes to the database of your Kentico instance. Kentico providesCIRepositorya command line utility that deserializes the files and saves the object data back into the database.

Navigate to the folder of your Kentico project and run from the command line with the parameter.CMS\bin ContinuousIntegration.exe -r

ContinuousIntegration.exe -r

The utility deserializes the objects stored in the project's folder and creates, overwrites or removes corresponding data in theCIRepositorydatabase (specified by the connection string in the given project's web.config file).

To ensure that the restore process works correctly, you need to .stop your Kentico application before running the restore processOtherwise you may encounter the following problems:

Deadlocks or data inconsistencies if the system attempts to write to the folder while data is being restored from the filesCIRepositoryOutdated content in the application's cache if you restore without restarting (can cause inconsistencies in the Kentico administrationinterface or the website's content)

Note: If you are using a web application project and always rebuild your solution after loading files from the source control, the applicationstops and starts automatically.

We recommend setting up a process that runs the restore operation, stops/starts your application and performs any other required actions.For example, you can prepare a script.PowerShell

Warning

The restore operation any in the database that do not exist as files in the continuous integration deletes supported objectsrepository. Before you run the restore process, make sure the folder contains the required state of your object data.CIRepository

To avoid loss of local data, you need to maintain the file system repository as a full image of your database – serialize all objects tothe file system at the start of development and leave continuous integration enabled. You then need to merge the file content of the

folder when loading data from another team member or the central source control.CIRepository

# Parameter that specifies the path of your Kentico web project folder (i.e. theCMS subfolder)param ( [Parameter(Mandatory=$true)] [string]$Path)

# Creates an 'App_Offline.htm' file to stop the website"<html><head></head><body>Continuous integration restore inprogress...</body></html>" > "$Path\App_Offline.htm"

# Runs the continuous integration restore utility& "$Path\bin\ContinuousIntegration.exe" -r

# Removes the 'App_Offline.htm' file to bring the site back onlineRemove-Item "$Path\App_Offline.htm"

The script above is only a basic example that demonstrates the general concept. We recommend that you adjust the script to perform allfunctions required by your environment. The attached  file contains a more complete script that also stops and starts KenticoRestore-CI.ps1external services.

 

Using continuous integration with Visual StudioThis page contains best practices and tips for developing projects in Visual Studio in combination with a orTeam Foundation Version Control

source control repository and the Kentico solution. Many of the recommendations also apply generally when usingGit continuous integrationcontinuous integration with any type of source control system.

For detailed instructions and additional information, please refer to the following resources:

Use Team Foundation Version ControlUse Visual Studio with Git

Setting up workspaces

When using a repository, developers need to set up their Kentico project and folder within a Team Foundation Version Control CIRepository workspace. Server workspaces are not supported.Local

See the article for more information about the workspace location types.Decide between using a local or a server workspace

Creating and deleting objects

When you add a new object or delete an existing one in Kentico, the system creates or removes the corresponding XML files. You may needto perform additional actions to correctly track such changes, depending on the type of your source control repository:

Team Foundation Version Control - by default, changes that create new files or delete existing ones appear in the list of Excluded in the . You need to view the detected or operations and the changeschanges Visual Studio Team Explorer Add Delete Promote

before you can check them in to the source control.

Git - when viewing files representing new objects appear in the section (delete operations are trackedChanges, Untracked Filesautomatically). You need to the files before you can and them to a shared repository.Add Commit Push

  

Changing object identifiers

Identifiers are values that the continuous integration solution uses to determine the names and locations of files representing objects in the CI folder:Repository

In most cases, objects use their as the identifier.code name

Basic PowerShell example

Custom restore solutions

Alternatively, you can use the Kentico API to implement a custom solution for restoring objects from the file system repository. See .Restoring objects from the file system

1. 2.

Object types that do not have a suitable code name use other values (a notable example are pages, which use their as thealias pathprimary identifier).Identifiers may also include values of related objects, such as the code name of the parent object, the name of the related site, etc.

Avoid making changes to object identifiers if possible, particularly for objects that have a large number of child objects or affect the identity ofother objects (such as sites). This also includes operations that change the identifier indirectly, for example moving a child object under adifferent parent.

When an object's identifier changes, the continuous integration solution the file representing the object in the file system and createsdeletesa new one based on the new identifier. This causes a in the source control and makes it difficult to mergeloss of the file's version historychanges made to the same object by other developers.

Checking in changes

When checking in (committing) changes to your source control, we strongly recommend including detected file changes in the all CIRepositor folder. It may not be obvious which files correspond to specific changes made in the Kentico administration interface. Certain objects arey

represented by multiple files and changes may also affect related objects or relationships between objects.

To learn more about how objects are represented in the folder, see the following pages:CIRepository

Continuous integration repository structureObject types supported by continuous integration

Getting new versions of the repository content

Whenever you load a different version of any files in the folder from your source control, you need to:CIRepository

Merge any files that conflict with your instance's local versions. See also: Resolving object conflictsRestore the objects into your database.

The restore operation ensures that your instance's database is consistent with the file system repository. If you continue working on theinstance without performing the restore operation, changes to local data may overwrite the new versions of the files that you loaded from thesource control.

Resolving object conflicts

You may encounter object conflicts when getting or checking in files. Conflicts happen if your local folder and the opposingCIRepositoryfolder contain a file with the same name, but different content. File names are based on unique identifiers of objects (in most cases theobject's code name).

For more information about the identifiers of files, see the section and CIRepository Changing object identifiers Continuous integration page.repository structure

Planned conflicts can occur if you need to create across your entire development environment. For example, multiplethe same objectdevelopers may create a web part category with the same name when starting development of custom web parts. Even if the objects havecompletely identical values for all configurable properties, a conflict will occur during synchronization, because the object's GUID (globallyunique identifier) value is different for each developer.

The best solution is to have one developer create the object and check in the resulting XML files to the central source control. Otherdevelopers then load the XML files from the source control and to their local database. This approach completely avoidsrestore the objectobject conflicts and file merging.

If you cannot avoid an object conflict and need to merge XML files, always use the GUID value that is already checked in to the sourcecontrol and replace your local GUID. Do NOT push your local GUID values to the source control – this could cause conflicts for all otherdevelopers in your environment.

Unplanned conflicts occur if developers unintentionally create of the same type with matching identifiers (typically codedifferent objectsnames) and then synchronize through the source control. In such cases, you need to contact the developer who checked in the conflictingXML file and one of you must delete and recreate the object with a different identifier (or rename the identifier values). We stronglyrecommend changing the local object that is not checked in to the source control yet, which prevents potential conflicts for other developers.

Undoing changes

We do not recommend using the Visual Studio action for changes that create new files. Undoing changes may lead to inconsistenciesUndo

Note:

The XML elements and attributes used in the content of files are . Make sure you preserveCIRepository case sensitivethe letter case if you edit the XML content when merging files.

If you change an object's GUID during conflict resolution and then to your database, you may need torestore the objectmanually fix broken references on your local development instance. For example, object and page fields that allowuploading of files store the GUID of the selected metafile or attachment object.

1. 2. 3. 4.

between the state of the file system repository and the database. You can instead delete the given object in the Kentico interface, which alsomakes the corresponding changes in the file system.

If you undo a delete or modify operation and revert an XML file to its previous state, you then need to torestore the objects into the databasereverse the object changes in Kentico.

Working with web application projects

For Kentico projects installed as a web application, the folder and its file content does not need to be included in the App_Data/CIRepository project.CMSApp

 

Working with object lockingObject locking provides a way to prevent conflicts and overwriting of changes when developing websites in a multi-user environment.Overwriting can occur when multiple users work on a single instance of Kentico or when multiple development instances are connected to ashared database. Locking ensures that only a single user (or multiple people signed in under the same user account) can modify a specificobject at a time. Users can lock objects for editing (check out) and unlock them (check in) after finishing.

The following table lists the objects types that support object locking. The column shows the locations within the KenticoEditing interfaceadministration interface where you can edit objects of the given type.

Object type Editing interface

Alternative forms Page types -> Edit a page type -> Alternative formsCustom tables -> Edit a custom table -> Alternative formsModules -> Edit a module -> Classes -> Edit a class ->Alternative formsForms -> Edit a form -> Alternative forms

CSS stylesheets CSS stylesheetsPages -> Edit mode -> Properties -> General -> Edit a CSSstylesheetother interfaces containing the stylesheet selector

Email templates Email templates

Page layouts Page layoutsPages -> Edit mode -> Design -> Edit layout

Page templates Page templates -> select a template -> LayoutPages -> Edit mode -> Designother interfaces that allow editing of page templates

Transformations Page types -> Edit a page type -> TransformationsCustom tables -> Edit a custom table -> TransformationsWeb part configuration dialogs of web parts with transformationproperties

Web part containers Web part containersWeb part configuration dialogs

Web part layouts Web parts -> select a web part -> LayoutPages -> Edit mode -> Design -> Configure a web part ->Layout

 

  

Enabling object locking

Object locking is disabled by default. To enable the feature:

Open the application.SettingsSelect the category.Versioning & Synchronization -> Object versioningEnable .Use check-in/check-out for objectsClick .Save

The setting applies globally and cannot be changed for individual sites.

Tip: If your environment consists of multiple development instances with a shared database, we strongly recommend setting up we. Web farms ensure that all instances are always up-to-date by synchronizing cached content and settings.b farm synchronization

1. 2.

Editing objects with locking

With locking enabled, you cannot edit objects directly. If nobody else is currently editing a given object, click to enable editing andCheck outlock the object.

Once you have an object checked out, you can make any required changes.

Click to save changes and update the system (other users can view your changes).SaveClicking has the following effect:Undo checkout

if is ON: cancels the checkout and discards all changes made to the object (even changes confirmed viaobject versioningthe button). Unlocks the object for other users.Saveif object versioning is OFF: discards changes made to the object since the last and unlocks the object for other users.Save  

Click to save changes and unlock the object for other users. Check in

You can have any number of objects checked out and there is no time limit.

If another user has an object checked out, the object is read-only. You cannot make any changes or check out the object yourself.

Typical scenarios

You want to edit an object:

Open the object's editing interface (for example ( ) ).CSS stylesheets -> Edit Corporate Site

Global administrators can undo the checkout of any object

Users with the can perform on any checked out object in the system.Global administrator privilege level Undo checkout

Object versioning with locking

Every time you click or , the system creates a new version of the object according to the rules described in Save Check in Using. You can view the versions on the object's tab.object versioning Versions

If you click , the versions created by the action are discarded. The last version before the checkout is thenUndo checkout Saveset as the current version.

2.

3.

4.

1.

2. 3.

1. 2.

Click .Check outThe object is locked for other users. Only you can edit an object.

Edit the object.You can save your work using the button.Save

Click .Check inThe system confirms your modifications and unlocks the object.

You want to create a new object:

Click in the given section of the administration interface.New <object>The system displays the new object's dialog with only the button available.Save

Type in the object's name and all the required details.Click .Save

The system saves your new object.The status of the new object depends on the Settings -> Versioning & Synchronization -> Object versioning -> Keep

setting.new objects checked out

You need to edit an object, that is currently checked out by another user:

You have several options:

wait until the user checks the object back in. You may need to refresh the page to see if the object is checked-in.contact the user (you can use the built-in application).Messagesask a global administrator to perform .Undo checkout

Viewing checked-out objects

To view a list of all objects that you have checked-out:

Open the application.Checked-out items Select the tab.Objects

 

Editing object code externallyKentico provides a way to store the code of virtual objects in the file system in addition to the database. Having code files on a local diskallows you to edit code in external editors or manage it using a source control system.

To store object code in the file system, open the application and select the tab. The options in the sSystem Virtual objects Source controlection allow you to select which objects are stored in the file system:

Option Requires compilation

Alternative form layouts Yes (for ASCX layouts)

Form layouts Yes (for ASCX layouts)

Page layouts Yes (for ASCX layouts)

Page template layouts Yes (for ASCX layouts)

Transformations Yes (for ASCX transformations)

Web part layouts Yes

CSS stylesheets No

Web part containers No

To store object code in the file system, select the boxes next to the required object types and click . The file areApply changessaved in the folder.~/CMSVirtualFiles

Note: This feature only manages code. Other object data and settings remain only in the database and are represented in theNOTfile system. The provides a more complete solution if you wish to synchronize development objectscontinuous integration solutionusing a source control system.

To move object code back into the database, uncheck the corresponding boxes and click . Checked objects stay inApply changesthe file system and unchecked objects are moved back into the database.Click to copy the code from the files on the disk into the matching objects in the database.Synchronize changes to database

When using source control mode, you can still edit the code of objects through the Kentico administration interface. If you edit an object, thesystem displays the code from the corresponding file. Saving the code in the UI writes the data into both the file system and the database.

Using source control on web application projects

Source control in Deployment mode

If is , you cannot configure the source control options for objects that require compilation (only for Web partDeployment mode ONcontainers and CSS stylesheets).

Limitations

Do not while using source control mode. Before you start the hotfix procedure, return files to the database.apply hotfixesYou can re-enable source control mode once the hotfix is applied.

The feature has limited support for synchronizing object code when using source control mode:StagingOn servers, staging tasks are generated only if you edit code in the Kentico UI or after you synchronizesourcechanges from files into the database.On servers, source control mode must be if you wish to use incoming staging tasks to updatetarget disabledobject code.

1. 2. 3. 4.

When you enable source control on installations, the system cannot automatically integrate the created files into the Visualweb applicationStudio project. If you wish to edit the code of objects directly within your web application project, perform the following steps:

Open the project in Visual Studio.Click at the top of the Solution Explorer.Show all filesRight-click the folder and select .CMSVirtualFiles Include in ProjectBuild the project.CMSApp

You can now edit the code files of objects in Visual Studio inside the folder. In source control mode, the system generates CMSVirtualFiles a files without code behind files, so you do not need to convert the files into the web application format.scx

 

Developing websites using the Portal engineThe Kentico Portal engine allows you to create dynamic web pages without any programming. With the Portal engine, you do not need to useVisual Studio or any other web development tool. Instead, you create reusable page templates directly in your web browser.

Every page on a Kentico website, with the exception of pages based on page types, is based on a . Pagecontent only page templatetemplates consist of a layout and instances of web parts. The system stores portal engine page templates in the database.

The structure of each page template is determined by its , which you can either define through full ASCX markup or standardpage layoutHTML code. The code allows you to set up any layout that you require for your pages. Portal engine page layouts need to contain specialmarkup tags that define — areas where developers place web parts. Each web part zone can contain any number of webweb part zonespart instances.

Web parts (called "servlet", "portlet" or "module" in other solutions) are components that display some type of content or provide backgroundfunctionality. From a technical point of view, web parts are standard with a predefined portal engine interface.ASP.NET user controls

The following figures show the components of a sample page — the page layout, web part zones and web parts on the page template, andthe output in various view modes.

The page layout of the template

The following image shows the layout code of a page template that defines three sections: top, left and right. Each section contains a CMSW tag representing a web part zone.ebPartZone

The page template on the Design tab

The following shows a template that uses the sample page layout on the tab of the application. The template consists of threeDesign Pagesweb part zones: , and . The web part zones contain individual instances of web parts.zoneTop zoneLeft zoneRight

The page in editing mode

When viewing a page that uses the sample template on the tab of the application, editors can enter text and other content intoPage Pagesthe editable text region in the top section. Non-editable web parts (such as lists of news and products) appear as fixed content.

The page on the live site

On the live site, the page displays content according to the template's layout and web parts.

1. 2.

3. 4. 5. 6.

Creating portal engine page templatesThere are two types of page templates:portal engine

Ad-hoc - templates bound to one specific page. The system automatically deletes ad-hoc templates if their page is removed.Re-usable - named templates that can be shared by any number of pages, even across multiple websites in the system.

 

Creating new pages with ad-hoc templates

The most direct way to build pages using the portal engine is through ad-hoc templates:

Open the application.PagesSelect a parent page for the new page.

Click ( ) and choose the page type.New Page (menu item) Type a name into the  field.Page nameChoose the option.Create a blank pageClick .Save

The system adds the new page to the content tree. You can now work with the template on the page's tab. The new page uses anDesignempty ad-hoc page template with a single web part zone.

The section with a green header designates the area defined by the page template.The area with a yellow header inside the template is a web part zone, where you can place web parts.

Page terminology

The main purpose of page templates is to build the design of , i.e. pages that focus on presentation rather than holding data.PagesPages are that have the following properties enabled on the tab:page types General

Show template selectionBehaves as Page (menu item) type

By default, use the page type to create pages.Page (menu item)

Pages that are not configured to behave as Page (menu item) type also use page templates, but typically their templateinheritfrom a parent page.

1. 2. 3.

4.

5.

1. 2.

Build the structure and content of the template by and .editing the page layout adding web parts

Creating re-usable page templates

Re-usable templates allow you to:

Prepare templates that content editors can select when creating pagesShare the same page template across multiple pages

To create a re-usable template:

Create a new page with an and implement the required template design.ad-hoc templateIn the application, open the page's tab.Pages Properties -> TemplateClick .Save as new template

The dialog opens.Save as new page template

Fill in the following values:

Template display name - type a name for the re-usable template.Template category - select a category for the template.Assign to the current page - if checked, the system automatically assigns the new template to the selected page insteadof the original template.

Click .Save & Close

You can now assign the new page template when creating pages:

Choose the option in the template selection dialog.Use existing page templateSelect the template (find the template in the category tree or search for the name).

a. b.

Tip

You can also save ad-hoc templates as re-usable directly on the tab:Design

Right-click the page template header.Select in the menu.Save as new template

1. 2. 3.

Modifying re-usable templates

When you edit the or of a re-usable page template, the changes affect all pages that use the given template. Iflayout web part configurationyou need to modify the template only for one specific page:

Select the page with the required re-usable template in the application.PagesOpen the tab.Properties -> TemplateClick .Clone template as ad-hoc

The system creates a new ad-hoc page template and assigns it to the page.

You can now edit the template without affecting pages that use the original template.

 

Editing page layoutsThe structure of every is determined by a . Page layouts consist of and thatportal page template page layout layout code web part zonesspecify regions where designers can place . Page layouts allow you to define the basic .web parts layout and design of your website

There are two general types of page layouts:

1. 2.

Tip

You can also clone re-usable templates as ad-hoc on the tab:Design

Right-click the page template header.Select in the menu.Clone template as ad-hoc

Note

Keep in mind that the new template is now ad-hoc. If you delete the associated page at a later point, the system also removes thepage template.

If you want to use the modified template on other pages, you can save it as a named template by clicking oSave as new templaten the tab.Properties -> Template

1. 2. 3. 4.

5.

Custom - used only by one specific page template.Shared - stored as separate objects that you can assign to any number of page templates. Modifying a shared layout affects alltemplates that use it.

Editing layouts

To edit the layout of a page:

Open the application.PagesSelect the page in the content tree.Switch to the tab.DesignRight-click the green template header and click in the menu.Edit layout

Modify the layout code as required.Note: when removing web part zones from a layout, make sure you remove all the web parts in the zone first.

5.

The selector allows you to choose between two types of layout code:Layout type

Layout type Description

ASCX__________

This type of layout code supports both HTML and ASP.NETmarkup, i.e. the same syntax that you would use to edit a standardweb form or user control, including inline code and embeddedcontrols.

You can web part zones as control tags:Insert

<cms:CMSWebPartZone ZoneID="zoneA"runat="server" />

The value must be unique for every web part zone withinZoneIDthe given layout.

Important: For security reasons, ASCX layouts may onlybe edited by users who have the code Edit ASCX permis

for the module. Only users with the Globalsion Designadministrator can assign this permission.privilege level

HTML_____________

The system processes the layout code as basic HTML. ASP.NETmarkup, such as controls or inline code, is not supported.

HTML layouts do not require compilation, which brings the followingbenefits:

Faster initial load time than ASCX layoutsYou can create and modify HTML layouts even inenvironments where compilation of virtual objects is notpossible, for example on websitesprecompiled

Insert web part zones into HTML layouts through the followingexpressions:

{^ WebPartZone|(id)zoneA ^}

The value of the parameter must be unique for every web partidzone within the given layout.

If you need to insert dynamic values into HTML layouts, use Kentico.macro expressions

Removing web part zones from page layouts

 

Example - Layout code

Page layouts are composed of standard HTML elements, which means . Youyou have full control over how the system renders the pagecan choose between table and CSSbased layouts.

The following sample page layout uses a table to define a two-column structure:

<table> <tr> <td> <cms:CMSWebPartZone ZoneID="zoneA" runat="server" /> </td> <td> <cms:CMSWebPartZone ZoneID="zoneB" runat="server" /> </td> </tr></table>

The following layout code defines the same two-column structure, but using DIV elements and CSS styles:

<div style="width: 100%;"> <div style="width: 50%; float: left;"> <cms:CMSWebPartZone ID="zoneA" runat="server" /> </div> <div style="width: 50%; float: right;"> <cms:CMSWebPartZone ID="zoneB" runat="server" /> </div></div>

Previewing layouts

You can preview page layouts by clicking Preview in the header of their editing dialog. You can then write the layout codeside-by-side with a preview of how the changes affect the live site version of the page.

See also: Previewing design changes

Removing layouts

1. 2. 3.

Adding CSS styles to layouts

Page layouts allow you to directly define any CSS classes used within the layout code.

Requirement: Enable the setting in .Allow CSS from components Settings -> System -> Performance

Click below the page layout's code. The editor appears.Add CSS styles CSS stylesEnter the definitions of the required CSS classes.Click .Save

All pages that use the layout automatically load the specified styles (in addition to the website or pagespecific stylesheet).

See also: Adding CSS to page components

Creating conditional layouts

When editing the code of ASCX page layouts, you can elements. This allows you to create flexible layouts thatInsert Conditional layoutdisplay content based on certain criteria. The page layout renders the content between the tags only if the conditionsCMSConditionalLayoutspecified by the properties are fulfilled.

For example:

<div class="padding">

<cms:CMSConditionalLayout runat="server" id="goldLayout" GroupName="Roles"VisibleForRoles="GoldPartners"> <cms:CMSWebPartZone runat="server" ZoneID="zGold" /> </cms:CMSConditionalLayout>

<cms:CMSConditionalLayout runat="server" id="silverLayout" GroupName="Roles"VisibleForRoles="SilverPartners"> <cms:CMSWebPartZone runat="server" ZoneID="zSilver" /> </cms:CMSConditionalLayout>

<cms:CMSConditionalLayout runat="server" id="defaultLayout" GroupName="Roles" > <cms:CMSWebPartZone runat="server" ZoneID="zDefault" /> </cms:CMSConditionalLayout>

</div>

You can configure the following properties for conditional layouts:

Property Description

GroupName Allows you to group conditional layout elements together. Whenmultiple conditional layouts use the same group name, the pageonly displays the first one (from the top of the code) that has itsvisibility condition fulfilled.

VisibleForDocumentTypes Adds a visibility condition that checks if the current page is of aspecific page type. Enter the value as a list of codepage typenames separated by semicolons.

For example: VisibleForDocumentTypes="CMS.MenuItem;CMS.News"

VisibleForRoles Adds a visibility condition that checks if the user viewing the pagebelongs to specific . Enter the value as a list of role coderolesnames separated by semicolons.

For example: VisibleForRoles="MarketingManager;ChatSupportEngineers"

Note that users with the 'Global administrator' Privilege level bypassthe condition and will always see the first layout.

This sample layout displays one of three possible web part zones based on the roles of the user viewing the page. Gold partnerssee the content of the zone, Silver partners see the zone and all other users see . zGold zSilver zDefault

VisibleForDeviceProfiles Adds a visibility condition that checks if the user viewing the pagematches a specific device profile. Enter the value as a list of device

names separated by semicolons.profile

For example: VisibleForDeviceProfiles="iPad;iPhone"

VisibleForDomains Adds a visibility condition that checks if the site is being accessedunder a specific . Enter the value as a list of domaindomain namenames separated by semicolons.

ActiveInDesignMode If set to , the conditional layout also evaluates its visibilitytruecondition in mode.Design

Note: This may prevent you from working with web part zonesinside the conditional layout.

False by default.

Creating pages with shared layouts

When creating a new page, you can select the option and choose from a number of predefined pageCreate a blank page with layoutlayouts.

If you leave the option at the bottom of the selection dialog checked, the system creates a customCopy this layout to my page templatecopy of the layout specifically for the page template. Otherwise the template uses the shared layout directly. If you disable the option andthen modify the layout code, the changes affect all pages with templates that use the shared page layout. Leave the option enabled unlessyou wish to create pages with a shared layout that can be edited in one place.

Managing shared page layouts

You can manage the pre-defined (shared) page layouts in the application. When editing a layout on the tab, you canPage layouts Generalmodify its code and also configure the following properties:

1. 2.

Property Description

Display name Name of the layout displayed in the page layout list.

Code name A unique name that serves as an identifier for the page layout (e.g.in the API).

Description Allows you to enter an optional text description of the page layout.

Thumbnail Upload field for the layout preview image. Users see this image inthe page layout selection dialog when creating new blank pages.

Is convertible If enabled, you can use to assign replacementautomatic mappinglayouts that the system loads for specific instead ofdevice profilesthe current layout.

Number of zones Indicates how many web part zones the layout uses. The number ofzones helps users find appropriate matches when mapping layoutsfor .device profiles

The system automatically counts the number of zones in the layoutcode, but you can manually override the value (for example in thecase of conditional layouts or layouts that load web part zonesdynamically).

On the tab, you can check which templates currently use the given layout. Templates with a custom page layout are notPage templatesincluded here, even if they were created as a copy based on the currently edited shared layout.

Using layout web parts

You can alternatively define the layout of page templates by adding special web parts designed for this purpose — .Layout web parts

This approach allows you to set up the structure of page templates and add web part zones without writing or editing the page layout code.Simply create a page containing a single zone, add a layout web part, and then configure the required layout via the web part's propertiesdialog or even directly on the tab.Design 

Using and configuring web partsYou can use web parts on both and . However, with ASPX page templates, you lose theportal page templates ASPX templatesbrowserbased interface — the web parts need to be added and configured in Visual Studio as standard user controls.

This page describes how to work with web parts when editing page templates through the portal engine.

Open the application and select your website.PagesSelect any page in the content tree and switch to the tab (in mode).Design Edit

The Design tab allows you to view the structure of the page's template and manage the template's web parts.

Only users who have ( for the module) can use web parts.design permissions Design web site Design

 

  

Adding web parts

Impacts of modifying page templates

The system applies all web part modifications immediately and reflects the changes on the live site. Page templates are notconnected to the page's . However, you can use to keep track of the changes made to a template,workflow object versioningincluding its web part content (and roll back to previous versions if necessary).

When you edit the web parts on a re-usable page template that is shared by several pages, the changes affect all of the pages. Ifyou only wish to modify the design for one of the pages, you need to as an ad-hoc template or save it as a newclone the templatepage template.

1.

2.

1. 2.

From the web part toolbar

The most direct way to add a new web part to the template is provided by the , which appears on the right side of the web part toolbar Designtab:

Find the required web part in the toolbar's list — you can use two approaches:Type the name of the web part or its part into the search box. The toolbar searches for both individual web parts and entirecategories.Select a web part category at the top of the toolbar.

Drag the web part from the toolbar and drop it into the desired location in one of the template's web part zones.

Using zone actions

If you do not wish to use the toolbar, you can add new web parts into specific zones:

Right-click the header of the required zone, or click the zone's menu icon ( ).Click in the menu.Add new web part

The dialog opens, which contains a catalog of all available web parts. Locate specific web parts by browsing through theSelect web partcategory tree or using the search. Click to confirm your selection.Select

Configuring web parts

When you add a new web part instance into a zone, using either the toolbar or the zone action buttons, the dialogWeb part propertiesopens. Here you can set up the behavior of the web part by entering values into its properties.

1. 2.

3.

NoteWeb parts can skip the initial configuration dialog when users add new instances. To enable this behavior for a web part:

Open the application.Web partsSelect the web part in the tree catalog.

To open the configuration dialog for existing web part instances, double-click the web part's header on the tab or open the web part'sDesign

menu ( ) and select . You can also edit properties for entire by double-clicking their header.Configure Web part zones

3. 4.

Check on the tab.Skip initial configuration GeneralClick .Save

Macros in web part properties

All web part properties support . Macros allow you to insert dynamic values instead of constants. The systemmacro expressionsevaluates macros at run-time, so the web parts can work based on context-dependent values.

For web part properties that do not have text values (such as checkboxes), insert macro expressions by clicking ( )Edit valuenext to the given property. This opens a dialog where you can write the required macro.

See for additional details.Adding macro values into web part properties

Loading values from the properties of other web parts

Macro expressions allow you to connect the functionality or content of multiple web parts. By adding the following macros intoproperties, you can set up web parts that automatically adjust their behavior based on the configuration of other web parts orzones.

Note: The connected web parts or zones must be placed on the same page template.

{% WebPart.GetValue("WebPartControlID","PropertyFieldName") %} - gets the value of a web part's property. Toidentify the property, fill in the of the source web part and the of the given property. YouWeb part control ID Field namecan find the field names of properties by editing web parts on the tab in the application.Properties Web parts

1. 2. 3.

1. 2. 3.

Moving web parts

To relocate a web part to different positions or to other zones, drag the web part's header to the desired location.

Alternatively:

Right-click the web part's header.Hover over .Move toSelect one of the options to move the web part up/down in the current zone, or to one of the other zones on the template.

To move all web parts in a specific zone:

Right-click the header of the zone.Hover over .Move web parts toSelect the target web part zone.

Copying web parts

Copying allows you to duplicate web parts and paste them into any web part zone, including the on the sametemplates of other pages website.

You can copy:

Individual web parts - right-click the web part's header, click CopyAll web parts in a zone - right-click the header of the zone, click Copy all

The system saves the web parts and their configuration into an internal component clipboard. To paste the copied web parts into a zone,choose the target location:

At the end of the zone - right-click the header of the zone, click PasteDirectly below a specific web part - right-click the given web part's header, click Paste

You can paste the web parts any number of times. Copying different web parts (or ) overwrites the clipboard content. Every user inwidgetsthe system has their own separate clipboard.

: To get the value of a property of the current web part, use only: Tip {% PropertyFieldName %}

{% WebPartZone.GetValue("ZoneId","PropertyColumnName") %} - gets the value of a zone's property. To identify theproperty, fill in the of the web part zone and the column name of the given property. You can find the IDs of zonesZoneIDin the template's code, and the column names of zone properties in the XML files in Page layout ~\App_Data\CMSModule

.s\PortalEngine\Properties\WebPartZone

When the system displays the page, the macros resolve into the values of the specified properties.

Copy limitations

When copying web parts, the system does NOT carry over:

The content of editable web parts ( , ). Editable content is unique for every page.Editable text Editable imageMultivariate testing and variants. When you copy a web part with variants, the system onlyContent personalizationtransfers the original web part.

1. 2. 3. 4.

Removing web parts

To remove existing web part instances from the page template:

Right-click the header of a specific web part and select .RemoveTo remove all web parts in a zone, right-click the zone header and select .Remove all web parts

Finding where specific web parts or widgets are used

You can see which objects use a specific web part or a widget. The objects are:

Web parts

Page templatesWeb parts - for inheriting web partsWidgets - for inheriting widgetsMVT variantsPersonalization variants

Widgets

Page templatesPages (editor widgets)Group pages (group widgets)Last version of page - on pages that are under a workflowMVT variantsPersonalization variantsDashboardsUser widget personalized pages

To find specific web part or widget usage

Open the (or ) application.Web parts WidgetsSelect a specific web part (or widget).Switch to the tab.Usage Here, you can see listed the objects that use the web part.You can find out which pages use a specific page template on the Pages tab of a specific page template in the Page templates application.

Configuring web parts via on-site editing

Users with can use to configure the properties of web parts directly while browsing the website.design permissions on-site editing

Content placed inside the child zones of . You need to copy the web parts of individual child zoneslayout web partsmanually through additional operations.Copy all web parts

1. 2.

3.

1. 2. 3. 4.

Open the website in on-side editing mode.Highlight web parts by moving the mouse over the corresponding part of the page.

The page encloses highlighted web parts in a dotted outline, with an additional box displaying the web part's title.

Click ( ) next to the web part title.Configure

The web part properties dialog opens just like when configuring web parts on the tab of the Pages application.Design

To view the entire web part structure of a page, enable the action on the on-site editing toolbar. This highlights all web parts placedHighlighton the given page.

Editing hidden web parts

Some web parts may not have any visible output at the time when you are viewing the page. For example, pages only display paging webparts if the connected listing contains a sufficiently large number of items.

You cannot find such web parts directly on the page in on-site editing mode. However, you can still access their properties by clicking Hidde

on the toolbar and configuring ( ) the appropriate item in the drop-down.n

Resolving web part errors

In rare cases, web part errors may prevent the tab of a page from working correctly. For example due to invalid configuration of aDesignweb part or when testing custom web parts.

You can fix the page by manually editing the web part XML source of the page template:

Open the application.Page templatesEdit the given page's template.Open the tab.Web parts

Note

Because of and , the content displayed by a page on the live website may often be loaded from severalmaster pages page nestingdifferent page templates.

On-site editing mode does not differentiate between templates, so you can configure any web parts displayed on the current page,even those that actually belong to ancestor pages.

Note: The list only includes web parts that have the potential to affect the appearance of the page. Instances of invisibleHiddenweb parts that only perform background functionality need to be configured in the administration interface through the applicPagesation.

4.

5.

Remove the source of the error by editing the XML data.You can modify the values of properties for all web parts on the template.You can remove web parts from the template by deleting entire elements.<web part>

Click .Save 

Creating portal engine master pagesMaster pages allow you to share content across all pages on the website without having to add it separately to every . By usingpage templatemaster pages, you can manage repeated elements, such as the site logo, main navigation menu, and footer content in a single location.

The following figure shows two pages that are nested inside the same master page. The system combines the content of individual pagesand the master page, and displays the result as a single page.

Websites can have multiple master pages:

The root page of the content tree is a master page.alwaysYou can create additional master pages within the structure of your website by assigning to pages.master page templates

To designate a page template as a master page, enable the option on the tab of the .Master page General page template editing interface

 

Editing master pages

You can edit the and of master pages on the tab, like with any other pages.web parts page layout Design

Adjusting the HTML output of master pages

All master pages have the tab available in the application. Here you can define sections of the master page's HTMLMaster page Pagescode. The system also adds the code to all pages that are nested within the master page.

DOCTYPE - insert any code that you need to place at the beginning of the page's HTML source, typically the page's DOCTYPEdefinition.HEAD - allows you to add HTML code inside the element of the master page and all nested descendant pages.<head>BODY - here you can add custom attributes to the page's element.<body>

Master page layout - the area between the tags displays the of the master page template. To modify the layout<body> layout codecode, click in the tab header.Edit layout

 

ImportantMaster pages do automatically ensure content inheritance. They are only a tool that helps organize your website and cannotmake it easier to set up page nesting. Portal engine pages can inherit content even without master pages.

See to learn how to implement the actual inheritance.Inheriting portal engine page content

Page placeholder requirement

Master pages must always contain the web part. The page placeholder specifies where child pages are nestedPage placeholderinside the master page.

Note: The code on the master page tab outside of the editable sections is only informative and may not be identical to the actualcode rendered for pages.

1. 2. 3. 4.

Inheriting portal engine page contentInheritance allows you to maintain a consistent design throughout the website and manage content shared by multiple pages in a singlelocation. Portal engine pages can use two different types of content inheritance:

Page nesting inside ancestor pagesInheriting the entire page template from the parent page (shared templates)

Using page nesting

Nested pages display their own content inside other pages. You can nest pages within ancestor pages in the content tree.

Nesting allows you to organize your website's content tree in the following way:

Pages that provide shared content on the upper levelsIndividual content pages stored as subpages

 

Creating pages that support nesting

To allow subpages to nest within a page:

Open the application.PagesSelect the page in the content tree.Open the tab.DesignAdd the web part.Page placeholder

The page placeholder specifies the position of nested pages within the content. When displaying the nested pages, the system loadseverything around the page placeholder as fixed content.

What are ancestor pages?

Ancestors include all pages under which a given page is stored, from the root of the site's content tree down to the page's directparent.

For example, the page has the following ancestors:/Company/Offices/London Office

Website root page/Company/Company/Offices

Note: The following steps are required for all pages serving as , but you can also set up nesting for any other pages.master pages

1. 2. 3.

Setting default content for page placeholders

By default, the placeholder does not display anything on the page where it is placed. You can configure the placeholder to show one of thewebsite's as default content:re-usable page templates

Configure the page placeholder web part (double-click).Select a template in the property.Default page templateClick .OK

The page displays the selected template inside the area occupied by the page placeholder. Nested pages ignore the placeholder's defaulttemplate and display their own content instead.

1. 2. 3. 4.

a. b. c.

Configuring pages to nest within ancestors

Open the application.PagesSelect the subpage page in the content tree.Open the tab.Properties -> TemplateChoose one of the following options for the page:Page nesting

Page nesting type Description

Use page template settings_________________________

The page nesting settings are determined by the configurationof the . This option allows you to manage thepage's templatesettings for pages with shared templates.

To modify the page template's nesting settings:

Click .Edit template propertiesSet the options on the tab.Page nesting GeneralClick .Save

None The page behaves as a standalone page without any nesting.

Only the nearest master page The page nests only within the website's . If yourmaster pagewebsite uses multiple master pages, the page nests within theclosest master page in the content tree hierarchy.

Specific ancestor pages Allows you to enable or disable nesting within any ancestorpages (regardless of the master page structure). Specific pagesare represented by the checkboxes below.

The and properties force the placeholder to always display the default templateUse template on all subpages Page to displayor a specific page. Such placeholders cannot be used for standard page nesting — all nested subpages display the specifiedcontent instead of their own.

Tip: You can use page nesting on any number of levels. Nested pages can also contain their own page placeholders for displayingsubpages.

4.

5. Click .Save

When visitors view the nested page, the system loads the content of the selected ancestors and displays it around the content of the pageitself (according to the positions of the page placeholder web parts).

On the tab of nested pages, the editable template section appears inside the content of ancestor pages (in the position of the pageDesignplaceholder on the previous nesting level). You can edit the and of the nested page's template as usual. You cannot page layout web partsmodify the content from the ancestors where the page is nested.

Inheriting page header content for nested pages

Important

You can only edit the page template on the tab if all pages where the given page is nested contain a .Design Page placeholder

If you configure a subpage to "nest" inside a page without a page placeholder, the subpage only displays the content of the givenancestor and cannot be modified in any way.

1. 2. 3. 4. 5.

1. 2. 3. 4.

1. 2. 3. 4. 5.

You can add custom content to pages, such as links to external CSS or JavaScript files.<head>

In the application, open the page's tab.Pages Properties -> TemplateClick .Edit template propertiesSwitch to the tab.HeaderType in the required content.Click .Save

The system inserts the content into the element in the output code of all pages that use the given template.<head>

Nested pages can inherit the header content from their ancestors. The inheritance depends on the following options, which you can enable ordisable on the tab of each page template:Header

Allow descendant templates to inherit the headerInherit headers from the templates of ancestor pages

The header inheritance follows the page nesting settings — pages can only inherit head content from the ancestor pages where they arenested. Pages that do not use nesting cannot inherit head content.

Inheriting the page template of the parent page

One way to display content from parent pages is to inherit the entire . Pages with an inherited template are mostly identical topage templatethe parent, but you can modify them in the following ways:

Set different content inside the page's editable web parts ( and )Editable text Editable imageUse web parts that display different content based on the page's type and location in the content tree (path)Hide web parts on subpagesAdd web parts that appear only on particular page types

A typical scenario where you can use page template inheritance is a parent page of the Page (menu item) type with multiple child pages thataren't set to behave as Page (menu item) types. By inheriting the template, users can create the child pages without worrying about the pagedesign. You can use one of the page viewer web parts to dynamically display a list of these child pages on the parent page. Each child pagethen displays specific detailed information when viewed.

You can create  with an inherited template by choosing the option in the template selection dialog.new pages Use parent page templatePage types that automatically inherit the template of the parent page by default.aren't set to behave as Page (menu item) types

To configure an existing page to inherit the parent page's template:

In the application, select the page in the content tree.PagesOpen the tab.Properties -> TemplateSelect in the section.Inherit from parent TemplateClick .Save

The child page uses the same page template as the parent. to the page template's or Any changes that you make layout web part configuration affect both the parent page and all pages that inherit the template.

Hiding web parts on subpages

You can disable content inheritance for individual instances of web parts. This allows you to add web parts to pages without affecting thedesign of subpages that inherit content. Applies to both types of content inheritance — and pages with .page nesting inherited templates

In the application, open the tab of the page containing the web part.Pages DesignConfigure the web part (double-click).Expand the property category.VisibilityCheck .Hide on subpagesClick .OK

Users now cannot see the web part on sub-pages in the content tree.

Note: To render the custom content on pages, the given page template must also have the <head> Behaves as Page (menu property enabled.item) type

Tip: The page template inheritance can continue throughout the content tree — pages may inherit from parent pages that alreadyuse an inherited template ( ).Parent -> Child -> Descendants...

Example

You can find an example on the page on the sample Corporate site. The page hides the , , News Header text Description text News and web parts on child pages. As a result, the text sections are only visible on the list of news items — not onfilter Universal pager

the detail pages of individual news items, which inherit the page template from the parent News page.

1. 2. 3. 4. 5. 6.

Making web parts visible only for specific page types

You can configure web part instances to appear only on specific . This allows you to set up different content inheritance fortypes of pagesdifferent page types (applies to both and pages with ). You can also use this feature for pages that simplypage nesting inherited templatesshare page templates, without any kind of inheritance.

In the application, open the tab of the page containing the web part.Pages DesignConfigure the web part (double-click).Expand the property category.VisibilityClick next to the property.Select Show for page typesChoose the allowed page types.Click in both dialogs.OK

The web part is now only visible when viewing pages of the selected types.

Sample inheritance scenario

The following example shows how the system processes a request for a nested product page: /Products/Notebooks/Dell-XPS-15z

This sample scenario demonstrates content inheritance through both page nesting ( web parts) and page template sharing.Page placeholderThe portal engine loads the templates in the following order:

1. / (root)

Website master template

2. /Products

Products page template

Example

You can find an example on the page on the sample Corporate site. The page displays/Community/Blogs/Andrew-Jones-Blogthe , and web parts only on and pages. The web parts areHeader text Description text Blogs filter CMS.Blog CMS.BlogMonthhidden when viewing individual pages, which inherit the template.CMS.BlogPost

3. /Products/Notebooks

Laptops page template

4. /Products/Notebooks/Dell-XPS-15z

- inherits the page template from the parent page.Laptops page template

1. 2. 3.

4. 5.

  

Working with layout web partsLayout web parts allow you to define and modify the structure of without the need to edit the code of pageportal engine page templateslayouts. Each layout web part contains one or more child zones that are arranged in a specific way. You can configure the layouts just likestandard web parts using properties, or even directly on the tab of the application.Design Pages

To create a page with a web part-based layout:

Open the application.PagesCreate a new page.Select in the template selection dialog.Create a blank page

This creates a page with no layout and a single web part zone.On the tab, add and configure the required layout web parts.DesignFill in the page's content into the zones defined by the layout web parts.

In addition to defining flexible web part zones, some layout web parts also provide special functionality, such as:

Collapsible page sectionsZones with a fixed positionGraphical interfaces that allow users to select which zone's content the page displays

Note

A page viewer web part (e.g. ) automatically displays the detail of the selected product instead of the product list.Repeater

See Loading and displaying data on websites for more information.

Adding layouts as widgets

Layouts can also be added to pages as . This gives editors or other users without design permissions additional flexibilitywidgetswhen it comes to arranging page content. The zones generated by layout widgets automatically match the type of the parent zone.

Users can place layout widgets onto their to help organize the content. When adding content into a layout on awidget dashboardsdashboard page, you need to drag new widgets from their default location to the appropriate zone generated by the layout (it is not

 

Editing the content of layout web parts

To add or edit the content of the zones generated by layout web parts, view the given page on the tab of the application. YouDesign Pagescan manage the zones inside the layout like any other standard web part zones and add the required web parts.

All default layout web parts have the property. If enabled, the tab provides additional zone management actionsAllow design mode Designfor the layout. You can dynamically resize individual layout zones by dragging the green lines on the borders. Layouts composed of multiplezones also allow designers to directly add or remove the sections that form the layout (columns, tabs etc.).

Once you add and configure the layout web part and all of its child web parts, the page displays the entered content on the live site using thespecified structure.

Available layout web parts

Kentico provides the following layout web parts by default. You can find them in the web part category.Layouts

Layout web part Description

Accordion layout_________________

Provides a layout divided into multiple panes that can be expandedor collapsed.

Each pane defines a separate web part zone.Users can click on the pane headers to select which pane thepage displays.

Collapsible panel Generates a web part zone inside a panel that users can expand orcollapse.

Columns layout Provides a CSSbased column layout for content. Each columndefines a separate web part zone.

Rows layout Provides a row layout for content. Each row contains a separateweb part zone.

Table layout Provides a table layout for content. Each cell in the table defines aseparate web part zone.

possible to add widgets into specific dashboard zones directly).

1. 2. 3. 4. 5.

Tabs layout Creates an AJAX tab layout.

You can add content for each tab through a separate web partzone.Users can click on the tabs to select which content the pagedisplays.

Web part zone Adds a single web part zone to the page that you can use to groupmultiple web parts or assign additional formatting.

You can configure the zone to display its content at a fixed locationon the screen that moves along with page scrolling.

Zones with effect Provides a list of elements that define separate web part zones.

You can apply additional JavaScript effects (e.g. using jQuery) tothe content displayed by the zones. You need to specify the scriptsused to generate the effects through the web part's properties.

Wizard layout Provides a layout divided into multiple steps.

The wizard displays one step at a time and allows users tonavigate through them in consecutive order.The content of each step is defined in its own web part zone.The layout may generate two additional zones as a header andfooter for the wizard. You can add the header content and thebuttons used to move between steps through the Wizard

and web parts.header Wizard buttons

Preparing layouts with default content

Layouts with default content allow designers to quickly add reusable groups of functionality composed of multiple web parts. To set up thedefault content, create specialized versions of existing layout web parts:

Open the application.Web partsCreate an inherited web part based on a layout web part.Open the tab.Default contentClick .Configure default contentConfigure the layout and add child web parts just like when editing pages on the tab.Design

When you add instances of the inherited layout web part on the tab of pages, the system automatically inserts the default contentDesigninto the layout's zones. The default content overrides the standard default values of the .web part's properties 

Using web part containersKentico allows you to create containers that serve as "boxes" for instances of on pages. Containers consist of HTML content thatweb partssurrounds the enclosed web part. The functionality of containers is similar to the and web part properties, butContent before Content afterwith the following advantages:

Containers are re-usable for any number of web part instancesContainers are separate objects in the system, so you can them to other instances of Kenticoexport and import

The structure of a web part, its content before/after sections and container is as follows:

Tip: If you cannot achieve the desired layout using the built-in web parts, you can create new layout web parts or customizeexisting ones to fulfill your requirements.

See: Developing layout web parts

Note: The web part only uses the default content if you leave the property enabled on the tab.Skip initial configuration General

Managing web part containers

You can manage web part containers in the application.Web part containers

Click to create web part containers.New container

To manage existing containers, use the following basic actions:

  - opens the container's editing interface.Edit

 Delete

 

Writing container content

When editing or creating web part containers, define the content inside the editor. Enter the HTML code that the containerHTML codeplaces around the web part. The position of the actual web part content within the code is represented by a placeholder, so you can add bothopening and closing elements.

Tip: In addition to web parts, you can also assign containers to and entire web part zones.widgets

1. 2. 3.

You can add macro expressions that dynamically load the values of the enclosed web part's properties. Insert the expressions in format:

{% PropertyName %}

For example, the following expression loads the value of the web part's property:Web part container title

{% ContainerTitle %}

Defining CSS styles for containers

There are two locations where you can define CSS classes used within the code of the web part container:

(Recommended) In the main site stylesheet - all CSS classes are stored in one file, but exporting the container to a site that usesa different stylesheet is more difficult.In the property of the containerCSS styles - the system stores the styles separately for every container. This requires anadditional resource request on pages where the container is used, but allows the system to automatically export containers with theirCSS classes (including ).Staging

To add CSS styles directly into containers:

Click below the editor.Add CSS styles HTML codeDefine the required CSS classes.Click .Save

The system dynamically loads the specified styles on any pages where the given container is used.

Previewing changes

In the case of existing web part containers that are already placed somewhere on the website, you can use the modePreviewwhen editing. This allows you to inspect the live site appearance of the container directly while working with its code.

See also: Previewing design changes

When you place a container with styles defined in the property onto a page, the system adds a stylesheet request linkCSS stylesto the page's element, for example:<head>

1. 2. 3. 4.

5.

Assigning containers to components

To enclose a web part, widget or zone into a container:

Open the application.PagesEdit the page containing the component (on the or tab).Design PageConfigure the component.Select a container through the property.Web part container

(Optional) Configure the additional web part container properties:

Property name Description

<link href="/Kentico/CMSPages/GetCSS.aspx?_containers=1;14" type="text/css" rel="stylesheet"/>

The value of the URL parameter is dependent on the containers used on the page. The value contains the _containers ContainerIs of the given containers.D

If your system uses , the request is generated in the following format instead:CSS minification

<link href="/Kentico/CMSPages/GetResource.ashx?_containers=1;14" type="text/css" rel="stylesheet"/>

Storing files related to web part containers

If your web part container code requires any additional files, such as images used by the classes defined in the propertCSS stylesy, you need to store them in the folder, so they can be~/App_Themes/Components/Containers/<container code name>exported/imported along with the container. You can manage the content of this folder directly in the applicatWeb part containersion by editing the given container and switching the tab.Theme

If the the container's CSS classes are defined in the site stylesheet, store the accompanying files in the ~/App_Themes/<stylesheet folder.code name>

Tip: You can access the container editing interface directly from the dialog:Web part properties

Click to create a container.NewClick to modify the HTML code of the currently selected container.Edit

5.

1. 2. 3. 4.

Container title Sets a title for the container. You need to add the title into thecode of the container through the macro.{%ContainerTitle%}

Container CSS class Name of a CSS class applied to the container. You need to usethe macro as the value of an{%ContainerCSSClass%}element's attribute in the code of the container.Class

Container custom content Custom content that you can use to parameterize the container.Applied only if the macro is{%ContainerCustomContent%}used in the code of the container.

Hide container on subpages If enabled, the container does not appear on pages that tinherithe component from an ancestor page. For example, this allowsyou to add a container only for the .master page

Example - Creating a web part container

The following example demonstrates how to define a new web part container:

Open the application.Web part containersClick .New containerType into the field.Blue box Display nameCopy the following into the editor:HTML code

<table width="100%" class="BlueTable" cellpadding="5" cellspacing="0"> <tr valign="top"> <td class="BlueTitle"> {%ContainerTitle%} </td> </tr> <tr valign="top"> <td> </td> </tr></table>

Working with the web part placeholder

The "" character in the code above determines the position of the web part placeholder when you paste the code into the field.HTML code

If you ever need to set a container's HTML code using the API or in the database, you do not have to worry about theplaceholder character. The system stores the content before and after the placeholder in two fields: ContainerTextBeforeand .ContainerTextAfter

4.

5. Click and define the CSS classes used in the code:Add CSS stylesNote that styles are added directly to the container for the purpose of this example. The recommended approach for your websites isto define CSS classes for your web part containers in .site stylesheets

5.

6. 7. 8. 9.

10.

.BlueTable{ border: 1px solid #4a62e4;}

.BlueTitle{ background-color:#4a62e4; font-weight:bold; color:white}

Click .SaveSwitch to the tab and click to assign the new container to the websites where you wish to use it.Sites Add sitesOpen the application and edit any page on the tab.Pages DesignConfigure any web part (double-click) and set its properties according to the following:

Web part container: Blue boxContainer title: My web part with a container

Click .OK

If you view the page in mode, the web part is surrounded by a blue border with the specified title.Preview 

Developing websites using ASPX templatesASPX page templates in Kentico are standard ASP.NET web forms. When you register ASPX templates in the system, users can create

based on the templates and fill in content.pages

When developing ASPX page templates, you can:

Use standard ASP.NET controls, as well as the default controls and web parts provided by KenticoFreely modify the code of the pages

What do ASPX page templates consist of?

The content of page templates is a combination of static HTML code and ASP.NET server controls (or user controls) that render dynamiccontent. You can also use code behind (using either VB.NET or C#) to modify page behavior and add custom functionality.

The following figure illustrates how Kentico combines ASPX page templates with the content of individual pages to display the final result:

How does the system process ASPX page templates?

When a user requests a page, such as , the system internally calls the page template assigned to the given page with the ~/Company.aspx a URL parameter. The parameter specifies what content (which page from the content tree) the page template displays to the user.liasPath

Kentico controls or web parts placed on the page template process the parameter in the URL, and render the appropriate contentaliasPathautomatically.

On the front-end, Kentico in format which are more user-friendly and better for generates URLs <domain>/Company.aspx, search engine.optimization

 

Creating master pages for ASPX templatesYou can use standard ASP.NET together with ASPX page templates. This is a powerful concept that allows you to sharemaster pagescontent across all pages without having to add it separately to every page template. For example, you can create master pages containingheader and footer sections with a logo, navigation menu, search box etc.

Define master pages in files with the extension..masterYou can assign one master page to every ASPX page.Master pages must always contain one or more controls:ContentPlaceHolder

<asp:ContentPlaceHolder ID="plcMain" runat="server"></asp:ContentPlaceHolder>

 

Preparing master pages for ASPX templates

The following code sample shows the markup of a basic master page.

The control specifies where child pages display their content inside the master page.ContentPlaceHolder

Tip: It is recommended to store master pages in the folder together with your ASPX page template files. ThisCMSTemplatesallows the system to export master pages along with your website when you it to another instance of Kentico.deploy

1.

<%@ Master Language="C#" AutoEventWireup="true" CodeFile="Custom.master.cs"Inherits="CMSTemplates_CorporateSite_Custom" %>

<%=DocType%>

<html xmlns="http://www.w3.org/1999/xhtml" <%=XmlNamespace%>><head id="Head1" runat="server"> <title id="Title1" runat="server">My site</title> <asp:literal runat="server" id="ltlTags" enableviewstate="false" /></head>

<body class="<%=BodyClass%>" <%=BodyParameters%>> <form id="form1" runat="server"> <asp:PlaceHolder runat="server" ID="plcManagers"> <ajaxToolkit:ToolkitScriptManager ID="manScript" runat="server"EnableViewState="false" ScriptMode="Release" /> <cms:CMSPortalManager ID="CMSPortalManager1" runat="server"EnableViewState="false" /> </asp:PlaceHolder>

<cms:CMSListMenu ID="CMSListMenu1" runat="server" />

<asp:ContentPlaceHolder ID="ContentPlaceHolder1" runat="server"> </asp:ContentPlaceHolder> </form></body></html>

All ASPX page templates require the following manager controls, so it is a good practice to add them onto your website's master page:

Control name Description

ajaxToolkit:ToolkitScriptManager Allows pages to use AJAX components. If required, the CMSPortal automatically loads the , but addingManager ToolkitScriptManager

the control directly reduces overhead.

CMSPortalManager Ensures the transferring of content between the database andeditable regions. Also provides the management functionalityneeded for .portal engine zones

The CMSPortalManager must be placed inside a standard Plac control.eHolder

Writing the master page code behind

You need to modify the code behind file of your master pages according to the following steps:

Important

If you installed the Kentico project as a web application, you need to rename the attribute on the first line to CodeFile Cod for the code example to be functional.ebehind

The attribute's value must match the name of the master page's code behind file.CodeFile/CodebehindSet the value of the attribute according to the location and name of the master page file.Inherits

Note: If your master page contains the CMSPageManag control, remove it and add the inser CMSPortalManager

tead. The is an older equivalent,CMSPageManagerwhich is obsolete and only available for the purposes ofbackwards compatibility.

The control is one of the options that you can use to generate a menu for .CMSListMenu website navigation

1.

2.

3.

1. 2. 3. 4.

5.

6. 7. 8.

9.

Add a reference to the namespace:CMS.UIControls

using CMS.UIControls;

Change the class definition to match the following (the name of the class may be different):

public partial class CMSTemplates_CorporateSite_Custom : TemplateMasterPage

Add the following code into the master page's code behind class:

protected override void CreateChildControls(){ base.CreateChildControls(); PageManager = CMSPortalManager1;}

protected override void OnPreRender(EventArgs e){ base.OnPreRender(e); this.ltlTags.Text = this.HeaderTags;}

This code ensures that ASPX templates using the given master page support all required functionality. 

Creating ASPX page templatesUse the following steps to create :ASPX page templates

Open your Kentico web project in Visual Studio.Create a new web form ( file)..aspx(Optional) Select a .master pageDevelop the content of the page template.

Add any required HTML or controls into the template's markup.You can execute custom code in the web form's code behind.

Edit the web form's code behind and make the class inherit from .CMS.UIControls.TemplatePage

public partial class CMSTemplates_CorporateSite_HomeASPX : TemplatePage

Log in to the Kentico administration interface and open the application.Page templatesCreate a .New templateSet the following values on the template's tab:General

Template type - ASPX pageFile name - enter the path of the aspx file that implements the template

Switch to the tab and add all websites where you wish to use the template.Sites

Users can now based on the template.create pages

Master pages of ASPX templates must always inherit from the class.TemplateMasterPage

Adjust the value of the property according to the ID of the control placed on the masterPageManager CMSPortalManagerpage.

Inheriting from allows you to use the web form as a page template in Kentico.TemplatePage

1. 2. 3.

4. 5. 6. 7.

1. 2.

3. 4.

5.

  

Example - Building an ASPX template

The following example demonstrates how to create a new ASPX page template. The sample template allows users to add pages with twoeditable regions.

Creating the web form

Open your web project in Visual Studio (using the or file).WebSite.sln WebApp.slnRight-click the folder in the Solution Explorer and select .CMSTemplates/CorporateSite Add -> Add New ItemCreate a new and enable .Web Form Select master page

Or if you are using a web application project.Web Form with Master Page Name the file TwoColumnTemplate.aspxClick . The dialog opens.Add Select a Master PageChoose the folder and select the default file.CMSTemplates/CorporateSite Root.masterClick .OK

Writing the ASPX code

Open the view of the new web form.Source Add the following code inside the element:<asp:Content>

<table> <tr> <td style="width: 50%"> <cms:CMSEditableRegion ID="txtLeft" runat="server" DialogHeight="400"RegionType="HtmlEditor" RegionTitle="Left column" /> </td> <td style="width: 50%"> <cms:CMSEditableRegion ID="txtText" runat="server" DialogHeight="400"RegionType="HtmlEditor" RegionTitle="Right column" /> </td> </tr></table>

Edit the web form's code behind file (TwoColumnTemplate.aspx.cs).Add a reference to the namespace:CMS.UIControls

using CMS.UIControls;

Modify the class declaration so that the web form inherits from :TemplatePage

Adding Kentico Controls to your Visual Studio Toolbox

Before you start developing ASPX page templates, it is recommended to .add the Kentico Controls to your Visual Studio ToolboxThis allows you to draganddrop the controls onto the ASPX pages.

Note: This example uses a table layout. If you prefer a CSS-based layout, replace the surrounding HTML code with <div>elements. You have full control over the content.

The control allows you to use standard ASP.NET master pages. When the system renders the<asp:Content>page, it loads the content of the control into the assigned master page (as defined in the file).Root.masterThe control defines an editable region that the page displays as an HTML editor in theCMSEditableRegionKentico administration interface on the tab of the application. On the live site, the control renders the Page Pagescontent entered into the editor.

5.

6.

1. 2. 3. 4. 5. 6.

7. 8. 9.

10.

1. 2.

3. 4. 5. 6.

public partial class CMSTemplates_CorporateSite_TwoColumnTemplate :TemplatePage

Save the web form's files.

Registering the web form as a page template

Now you need to register the web form as a page template in Kentico.

Log in to the administration interface and open the application.Page templatesSelect the category.Corporate Site/ExamplesClick  .New templateType into the field.Two column template Template display nameClick .SaveSet the following values on the tab:General

Template type: ASPX pageFile name: ~/CMSTemplates/CorporateSite/TwoColumnTemplate.aspx

Click .SaveSwitch to the tab.SitesClick .Add sitesChoose the sites where you wish to use the page template and click .Select

Creating a page based on the template

Content editors can now use the page template to create pages.

Open the application.PagesSelect (the root of the content tree).Corporate Site

Click ( ) above the tree.NewChoose the page type.Page (menu item)Type as the and choose the option.About Us Page name Use existing page templateSelect the category and the page template.Corporate Site/Examples Two column template

6.

7. Click to create the new page.Save

On the tab, you can see the page and its editable regions.Page

You can now type in text into the regions and click to store the content of the page.Save 

Adding portal engine functionality to ASPX page templatesWhen developing or maintaining websites built on , one of the drawbacks is that you need to manually modify the codeASPX page templatesof pages whenever you wish to change the design. You can add flexibility to ASPX templates by defining areas that are editable directlythrough the browser in the application, just like when using the . These areas allow you to add Pages Portal engine development model Web

or onto ASPX page templates.parts Widgets

Add the following elements to the code of your page templates to integrate portal engine areas:

 <cms:CMSPagePlaceholder ID="plcZones" runat="server"> <LayoutTemplate>

...

<cms:CMSWebPartZone ID="zoneCenter" runat="server" />

...

</LayoutTemplate></cms:CMSPagePlaceholder>

The control creates an area on the page that behaves like a portal engine page template. You can placeCMSPagePlaceholdermultiple controls onto a single page.CMSPagePlaceholderThe content of the element defines the layout of the area. You can specify a table structure or a CSS-based<LayoutTemplate>layout applies through HTML elements (<div>, <span>, etc.).The layout may contain multiple controls, which represent fully functional portal engine zones. You can configureCMSWebPartZoneevery zone to serve as either a standard web part zone or any type of widget zone. Users can manage these zones when editingpages based on the page template on the tab of the application. When web part or widget content is added to aDesign Pageszone, information about it is stored in the database along with the respective page template object, not in the actual code of theASPX page.

When registering ASPX page templates with portal engine functionality in the application, you need to set the Page templates Template

CMSPortalManager control required

The control must be present on ASPX templates that contain portal engine functionality. The typical solutionCMSPortalManageris to provide the control through the of your templates.master page

1.

to . This enables the tab when editing pages based on the template in the application.type ASPX + Portal page Design Pages

  

Example

The following example demonstrates how to create an ASPX page template with zones that users can design via the portal engine:

Build a new page template according to the example on the page.Creating ASPX page templates

When writing the template's ASPX code, place the following inside the element: <asp:Content>

<cms:CMSPagePlaceholder ID="plcZones" runat="server"> <LayoutTemplate> <table style="width:100%"> <tr> <td style="width: 50%"> <cms:CMSWebPartZone ID="zoneLeft" runat="server" /> </td> <td style="width: 50%"> <cms:CMSWebPartZone ID="zoneRight" runat="server" /> </td> </tr> </table> </LayoutTemplate></cms:CMSPagePlaceholder>

This code defines two editable web part zones in a basic two column table layout.

1.

2. 3.

4. 5. 6.

7.

8.

9. 10.

When registering the template in the application, set the to .Page templates Template type ASPX + Portal page

Open the application and a page to the content tree using the new page template.Pages add Page (Menu item)Switch to the tab of the new page. You can see two web part zones on the page.Design

Expand the menu ( ) of the zone and click  .zoneLeft ConfigureSwitch the property from to .Widget zone type None Customization by page editorClick .Save & Close

The zone now serves as a widget zone for page editors.

Add a web part to , for example .zoneRight Editable text

Open the tab.PageHere you can manage the editor widget zone on the left and enter content into the editable text region displayed by the webpart on the right.

Open the menu of the editor zone ( ) and click to place some widgets onto the page.Add new widgetSave the page.

The example demonstrates how to use web parts or widgets to build the design of pages based on ASPX page templates. This approachcombines the standard architecture and development process of ASPX templates with the flexibility and userfriendliness of the portal engine. 

Using both ASPX and portal templates on a single siteIt is possible to combine and on the same website.ASPX page templates portal engine page templates

Sharing a master page on hybrid websites

If you have a website built using the portal engine development model, the master page and all other pages use portal engine page

1.

2.

3.

4.

5.

1.

2. 3. 4. 5. 6.

templates. Unfortunately, you cannot "insert" ASPX pages directly into the portal engine master page.

However, you can use the following workaround:

Create a copy of your portal engine master template as an ( file) and assign it to your ASPX templates.ASPX master page .masterThis scenario works, but the drawback is that you now need to manage the master page in two locations.

Take all content (HTML and controls) that you have above the web part on the portal master page and place itPage placeholderinto a new user control named .Header.ascx

Take all content from below the Page placeholder and place it into a user control named .Footer.ascx

Delete the content of your portal engine master page and replace it with the following web parts:

User control - set the property to load User control virtual path Header.ascxPage placeholderUser control - set the property to load User control virtual path Footer.ascx

Remove the content from your ASPX master page and replace it with the following controls:

The user controlHeader.ascxThe controlContentPlaceHolderThe user controlFooter.ascx

You can now manage the header and footer in a single place for both the portal engine and ASPX master page.

 

Exporting portal engine templates as ASPXThe system provides a way to export existing as ASPX templates.portal engine page templates

Edit your application's web.config file and add the key to the section:CMSShowTemplateASPXTab <appSettings>

<add key="CMSShowTemplateASPXTab" value="true"/>

Log in to the Kentico administration interfaceOpen the application. Page templatesSelect the required portal engine template in the tree.Open the tab.ASPX codeSelect the export type:

Template using master page

Note: When you create a website with both ASPX template and portal engine pages, you cannot use between thepage nestingtwo different types of pages.

6.

7. 8.

Master pageStandard page templatePage template code only (no code behind)

Choose a and fill in the .Site Template nameClick .Save to the disk

You can find the exported ASPX template in the web project's folder.~/CMSTemplates/<Site>/ 

Developing sites using ASP.NET MVCKentico supports website development using . The support is based on a separate MVC application while Kentico functionsASP.NET MVC 5as separate application that you use as a content platform.

Both Kentico and the MVC application access data from the same database and call API from Kentico libraries. Content synchronization, forexample of is handled by web farms. This approach allows you to separate the live site (MVC application) and thesmart search indexes, administration (Kentico).

This means that you use Kentico to store data and manage content (mostly via pages), and generate the entire design of the site using yourown MVC controllers and views.

Kentico's application is a repository for content consisting of content only pages. The content itself is entered and modeled by contentPageseditors based on a created by developers. Developers take care of how the content is displayed on the live site via the MVCcontent structureapplicaiton.

Requirements and limitations

You will need the following configuration for MVC projects:

Kentico 9.NET Framework version: .NET Framework 4.5 / 4.5.1.Visual Studio version: Visual Studio 2013 or higher (for MVC 5 support). You can also install ASP.NET and Web Tools 2013.1 for

for your VS 2012. Visual Studio 2012

License requirements

If you want to make use of , you will need an extra license with an extra web farm server that will be used for the MVC application.web farmsRequest a license through the or our if you need one extra server just for the MVC application.Kentico Client Portal support

To develop sites using ASP.NET MVC, see:

1. 2. 3.

4.

5.

Getting started with development using ASP.NET MVCCreating MVC applicationsCreating content repositories for MVC sitesDefining content structure on MVC sitesDeveloping MVC applicationsImproving performance of MVC applicationsDeploying MVC applications

   

Creating MVC applicationsKentico provides ASP.NET MVC support based on a separate MVC application. The application takes care of the presentation and is

Both applications access the same database as the Kentico application and contentseparated from the Kentico administration. synchronization can be handled by web farms.

You can also and host the MVC application together with the Kentico application on Microsoft Azure.deploy

To create an MVC application

Create an empty ASP.NET MVC project and select the MVC template. the integration package in your MVC application project. Install Kentico.Web.Mvc  

In the MVC project's main web.config file: Add a connection string to your Kentico database (we recommend copying the exact connection string from the web.configfile of the related Kentico application project).

<connectionStrings> ... <add name="CMSConnectionString" connectionString="Persist SecurityInfo=False;database=Kentico;server=myserver;userid=username;password=mypassword;Current Language=English;ConnectionTimeout=120;" /></connectionStrings>

Ensure that the MVC application generates hashes using the same salt value as the Kentico application (for example for ma or page preview links). Copy the value of the key from the web.config ofcro signatures CMSHashStringSalt appSettings

the Kentico project into the same key in the MVC project's web.config.

<appSettings> <add key="CMSHashStringSalt"value="e68b9ad6-a461-4707-8e3e-ece73f03dd02" /> ...</appSettings>

In the MVC application's file, add a reference to and add the following line in the Global.asax Kentico.Web.Mvc Application_Start method:

using Kentico.Web.Mvc;... protected void Application_Start(){ ...

// Enable and configure the selected Kentico ASP.NET MVC integrationfeatures ApplicationConfig.RegisterFeatures(ApplicationBuilder.Current);}

To be able to work with the , add the assembly attribute in the MVC project's generated page type classes AssemblyDiscoverable A file.ssemblyInfo.cs

5.

1. 2. 3.

using CMS;...[assembly: AssemblyDiscoverable]

You can now continue to .develop the MVC application   

Installing Kentico integration packagesKentico allows you to download integration ( ) packages to help you with your site development. There are two types of NuGetNuGetpackages that you can integrate into your projects:

MVC integration packageGeneral integration packages

Installing Kentico integration packages

Visual Studio -> Nuget Package Manager -> Manage Nuget Packages for Solution...Search for Kentico.Install the necessary packages.

Kentico.Web.Mvc integration package

The main purpose of the is to help you start developing your with as few manual integration packageKentico.Web.Mvc MVC applicationssteps as possible. The package contains the necessary items to make your MVC application work with the Kentico application.

The package contains: Kentico.Web.Mvc integration

API for working with Kentico objects.The integration package.Kentico.LibrariesThe integration package.Kentico.LanguagePack.EnglishPreview feature Data annotation localizationGlobal Not Found feature

General integration packages

Kentico.Libraries integration package

NuGet package containing all the Kentico assemblies that you need for working with Kentico in an external application.

: Always use the package with the same version as the version of your Kentico application. For example, if you'reImportant Kentico.Librariesusing Kentico 9.0.1, you need to use the 9.0.1 version of the Kentico.Libraries package as well. See how you can to yourapply a hotfixKentico installation.

Kentico.LanguagePack.English integration package

NuGet package containing files required for the English localization of Kentico. Individual Kentico features depend on the localization files.

Kentico.Search integration package

NuGet package containing improved API for working with .smart search

Kentico.Newsletters integration package

NuGet package containing improved API for working with .email marketing   

Creating content repositories for MVC sitesWe recommend starting from the . The Blank MVC site servers as a template for sites that use an MVC applicationBlank MVC site templatefor their presentation. The site is mainly intended as a repository of content only pages that are managed by content editors.

The site allows content editors to create pages of in the content tree.content only page types

Site Settings

1. 2.

3.

Note that many of the configured in the Settings application are not reflected on MVC sites, as the site serves mainly as asite settingscontent repository and the presentation is handled by the MVC application.

Running MVC sites on the same domain as Kentico

If you want to run Kentico on the same domain, you need to run the MVC application in a different virtual folder.

Running MVC sites on a different domain

If you want to run your MVC site on a different domain (different to the one you run the Kentico application on), you need to specify a URLleading to the site's domain.

Open Kentico and your site in the application.Edit Sites On the tab, type the URL leading to the site's domain into the property. For example: General Presentation URL http://www.mysite.com

. Save

Links on the live site will now be resolved with the domain you entered. that Kentico cannot guarantee that links used (clicked on)Note directly on the or tab of the Kentico's application will resolve correctly when using this property. Page Design Pages   

Defining content structure on MVC sitesThe content displayed on MVC sites is represented by . Ideally, developers (or administrators) set up a page structure andcontent only pageslimit where content editors create pages. Content editors then create and content.model

Defining content structure

The structure of pages in Kentico doesn't represent how the content is displayed on the live site. Developers fully control how content isdisplayed.

 Set up the page structure to take performance limitations into consideration. Each item (page) in the content tree shouldn't exceed 1000direct child pages.

We recommend structuring pages in Kentico so that each page type has its own section, for example: 

Root  Articles

Article pageArticle page...

Store

Product page

Product page

...

...

Only are supported on MVC sites.content only pages

You can set up Kentico pages for advanced content modeling.

Limiting where content editors can create pages

You can use the following to limit where content editors can create particular content only pages.

Allowed page type restrictions - by defining which page types content editors can place under the current page type.Page scope restrictions - by specifying which page types content editors can use when creating new pages under specified paths.

   

Developing MVC applicationsOnce you and perform the initial setup, you can start developing its functionality.create an MVC application

Generating classes for Kentico objects

 

                             

Retrieving content on MVC sitesThe following section describes how you can retrieve Kentico data in your MVC application. Generally, we recommend using generated codewhen retrieving page, custom table, and form table from Kentico.

Generate code files that allow you to work with and retrieve Kentico objects. You can generate code files for ,   Page types Custom tablesand  .Forms

MVC Code examples

See examples on how you can work with pages in your MVC application.

Providing smart search on MVC sites

Make sure  indexes stay up to date so that you can provide search functionality on your MVC site.smart search

Adding preview mode support for MVC sites

Allow your content editors to display the latest version of pages before they are published.

Displaying shared content in MVC applications

Display modeled by content editors.reusable content

Working with page attachments in MVC applications

Display and work with on your MVC site.page attachments

Localizing data on MVC sites

Localize resource strings stored in Kentico as well as validation results and model properties.

Handling 404 Not Found globally in MVC applications

Return a '404 Not Found' page when no controller or controller actions is found or when an action returns .HttpNotFoundResult

Processing scheduled tasks when developing MVC applications

Make sure in the Kentico application are processed in regular intervals.tasks scheduled

Testing MVC controllers

Provide tests for the logic implemented in your MVC controllers.

Retrieving pages

We recommend using when working with pages.generated code

The following example uses a generated page type. We recommend using the generated providers when retrievingDancingGoat.Articleindividual page types.

// Get articles using the generated provider.var articles = ArticleProvider.GetArticles() .OnSite("MySite") .Culture("en-US") .Path("/Articles/", PathTypeEnum.Children);

// Get the published version of a a single article using the generated provider.Article article = ArticleProvider.GetArticle(nodeID, "en-US", "MySite");

By default, the generated code returns published version of pages. If you need to retrieve the latest edited version of a page, use:

// Get the latest version of a single article using the generated provider.Article article = ArticleProvider.GetArticle(nodeID, "en-US","MySite").LatestVersion().Published(false);

 

Working with retrieved page data

You can access the data of a retrieved page using the method. There are two types of page data that you can access:TreeNode.GetValue()

Form data - the data that is editable on a page's tabForm Metadata - data like the and page title page keywords

Accessing page form data

The fields available on a page's Form tab are specific to its Page type. You can see the fields that each page type uses:

In .Pages types (application) -> edit page type -> Fields tabIn the database table.CONTENT_<document_type>

We recommend accessing the specific fields of a specific page in the following way as code completion will provide you the relevant fieldsthat you can use:

// Retrieves the pageNews news = NewsProvider.GetNews(nodeID, "MySite", "en-US");

// Accesses the 'Title' fieldvar title = news.Fields.Title;

// Accesses the 'Text' fieldvar title = news.Fields.Text;

Accessing page metadata

Page metadata are stored the same way as Form data (in the TreeNode object), but aren't provided in the classes. This meansgeneratedthat you need to use the method to access page metadata.GetValue

All the metadata fields you can access are defined in the table.CMS_Document database

// Retrieves the pageNews page = NewsProvider.GetNews(nodeID, "MySite", "en-US");

// Accesses the 'DocumentPageTitle' metadata fieldpage.GetValue("DocumentPageTitle");

// Accesses the 'DocumentPageKeywords' metadata fieldpage.GetValue("DocumentPageKeywords");

Retrieving page attachments

For information on retrieving page attachments, see .Working with page attachments in MVC applications

Retrieving custom table data

The following example requires the class for the custom table included in the solution.generated SampleTable

// Get all custom table itemsInfoDataSet<SampleTableItem> items =CustomTableItemProvider.GetItems<SampleTableItem>().TypedResult;

// Get a single custom table itemSampleTableItem item = CustomTableItemProvider.GetItem<SampleTableItem>(1);

Retrieving form data

The following example requires the class for the form included in the solution.generated ContactUs

// Get all form itemsInfoDataSet<ContactUsItem> items =BizFormItemProvider.GetItems<ContactUsItem>().TypedResult;

// Get a single form itemContactUsItem item = BizFormItemProvider.GetItem<ContactUsItem>(1);

 

Working with page attachments in MVC applicationsAttachments represent data, for example images, stored in fields. Attachments are stored in the following of page typepage type data typesfields:

Attachments - allows you to store multiple attachments in a single page type field.File - allows you to store a single page attachment in a page type field. 

Kentico provides a standard API for working with attachments within the Kentico application. For working with attachments in MVCapplications, Kentico provides a different API. The API is part of the code that you can for individual page types.generate

The API for working with attachments in MVC applications gives you more control than the standard API would when creating URLs for pageattachments. You can create strongly typed views and the provided method for creating page attachment URLs is independent on Kentico'ssettings. That is, the resulting URL is always in the same format and Kentico's image resizing settings aren't applied.

Example of working with page attachments using generated page type code

1. 2.

// Retrieve an article.Article article = ArticleProvider.GetArticle(nodeID, "en-US", "MySite"); // Work with a single attachment in the retrieved article's 'Teaser' field.var teaserImageWidth = article.Fields.Teaser.ImageWidth;

...

// Iterate over attachments in the article's 'Images' field.foreach (var image in article.Fields.Images){ var imageMimeType = image.MimeType; ...}

Prerequisites when storing attachments on the file system

You to perform the following configuration if your MVC application has do not need web farms configured or is running on Microsoft Azure.

If your Kentico application is configured to , you need to set up your MVC application to work with the pagestore files on the file systemattachment files within the Kentico project folder.

Map the attachment directory to a storage provider. You can do that by creating a new instance in the hStorageProvider Application_Startandler within the MVC application's file.Global.asax.cs

: The following example assumes that the Kentico application is running in the Note C:\intepub\wwwroot\Kentico\CMS folder, uses the defaultfile storage location and the code name of the site is mvcsite.

using CMS.IO; public class MvcApplication : System.Web.HttpApplication{ protected void Application_Start() { // Creates a new StorageProvider instances var provider = new StorageProvider { // Specifies the root directory of the related Kentico project CustomRootPath = @"C:\intepub\wwwroot\Kentico\CMS" };

// Maps the directory that stores attachment files // The MVC application now shares the attachment directory with the relatedKentico project StorageHelper.MapStoragePath("~/mvcsite/files", provider); }

...}

Creating page attachment URLs

of your MVC application.Perform the initial set upIn the MVC project's ' file, add the following namespace. The namespace contains methods that you can use toViews/web.config'create links to page attachments:

2.

3.

4.

5.

<namespaces> ... <add namespace="Kentico.Web.Mvc"/></namespaces>

 Use the method to retrieve page attachment URLs.Url.Kentico().Attachment()

<img alt="Article @article.Fields.Teaser"src="@Url.Kentico().Attachment(article.Fields.Teaser">

The result is a relative URL in the following format:

~<domain>/getattachment/<file GUID>/<filename>

See also:Attachment versioningConstraining the returned attachment size for image attachmentsPrompting users for action when accessing attachments

 

Because the returned URLs are relative, the MVC site needs to run on the same domain as the site configured in Kentico. Another solution issetting up a leading to the MVC site.domain alias

Note: the system processes the file names and replaces all special characters with a '-' (hyphen). All characters that aren't , (latin0-9 a-zsmall letter a to latin small letter z), ' ' (full stop) or ' ' (underscore) are replaced.. _

Attachment versioning

The Url.Kentico().Attachment() method always returns the attachment that is attached to the version of the page you are currently workingwith. For example, using the method on pages retrieved using the providers always retrieves theUrl.Kentico().Attachment() generated codeattachment belonging to the published version of the page (the providers work with published versions of pages). 

Constraining the returned attachment size for image attachments

You can further parametrize the Url.Kentico().Attachment method to retrieve attachments of specific size:

Specify the maximum height of the retrieved image. This constraint retains the original aspect ratio.

<img alt="Article @article.Fields.Teaser"src="@Url.Kentico().Attachment(article.Fields.Teaser, SizeConstraint.Height(200))">

Specify the maximum width of the retrieved image. This constraint retains the original aspect ratio.

<img alt="Article @article.Fields.Teaser"src="@Url.Kentico().Attachment(article.Fields.Teaser, SizeConstraint.Width(200))">

Specify both the maximum width and height of the retrieved image. This constraint doesn't retain the original aspect ratio.

<img alt="Article @article.Fields.Teaser"src="@Url.Kentico().Attachment(article.Fields.Teaser, SizeConstraint.Size(400,1200))">

Specify the maximum width and height that the retrieved image cannot exceed. This constraint retains the original aspect ratio and theresized image is never made larger than the original.

1. 2. 3.

4. 5.

6. 7.

1. 2.

<img alt="Article @article.Fields.Teaser"src="@Url.Kentico().Attachment(article.Fields.Teaser,SizeConstraint.MaxWidthOrHeight(400))">

Prompting users for action when accessing attachments

You can specify whether the web browser will prompt users to perform an action, such as saving the file to a disk, when accessingattachments.

@{ var urlOptions = new AttachmentUrlOptions { AttachmentContentDisposition = true }; } <img alt="Article @article.Fields.Teaser"src="@Url.Kentico().Attachment(article.Fields.Teaser, SizeConstraint.Size(1280,800), urlOptions))">

 

Generating classes for Kentico objectsThis page describes how to use code generators to prepare an wrapper classes for working with specific object types ( , Page types Custom

and ).tables Forms

Code generators are available for the following objects, in their respective applications:

Page types - allow you to generate a class with the page type's fields as properties and a provider to retrieve the individual pages.Generate code for individual page types on the tab of the specific types.Code Generate code for all site page types on the tab of the application.Code Page types  

Custom tables - allow you to generate a class with the custom table's fields as properties.Generate code for individual custom tables on the tab of the specific custom tables.Code  

Forms - class with the form's fields as properties. generate allow you toGenerate code for individual forms on the tab of the specific forms.Code

Code generators allow you to create classes for working specific objects types (Page types, Custom tables, Forms) in the API.

Working with page type code generators

The page type code generators allow you to generate both properties and providers for your custom page types. The generated properties You can use the providers represent the page type fields. to work with published or latest versions of a specific page type.

Generating code for a specific page type

Create a custom .Page typeNavigate to the page type's tab.Code (Optional) Select a different . Based on your scenario, you can include the files in:default folder to place the code files in

A folder in your MVC applicationLibrariesOther location

Save code.If you want to use the code files in a separate library or external application , allow the system to detect the generated classes in a

custom assembly. Add the 'AssemblyDiscoverable' assembly attribute in the library/application project's file:AssemblyInfo.cs

using CMS;...[assembly: AssemblyDiscoverable] 

Use the generated properties in your code.Build your solution.

 

Generating code for all site page types

Navigate to the tab of the application.Code Page types

2. 3.

4. 5.

6.

7. 8.

Select a .Site(Optional) Select a different default folder to place the code files in. Based on your scenario, you can include the files in:

A folder in your MVC applicationLibrariesOther location

(Optional) If you want to generate code for , enable .container page types Include container page typesSave code.Note that the generated class names are not guaranteed to be unique. The system can in certain cases (usually when alsogenerating code for container page types) generate multiple classes with the same name. In that case, you need to rename theclasses manually. If you want to use the code files in a separate library or external application, allow the system to detect the generated classes in acustom assembly. Add the 'AssemblyDiscoverable' assembly attribute in the library/application project's file:AssemblyInfo.cs

using CMS;...[assembly: AssemblyDiscoverable] 

Use the generated properties in your code.Build your solution.

Customizing generated classes

We do as they contain object properties only.not recommended modifying the generated classes

The classes are generated as This means that you can extend them in a separate code file. Using this approach, you willpartial classes. avoid having to merge custom changes made to the generated code. You would have to do this every time the object's properties changedand you'd have to generate the class again.

Example of customizing generated classes

public partial class Article : TreeNode{ ...

public class ArticleFields {   ...  /// <summary> /// Article name. /// </summary> [DatabaseField] public string Title { get { return ValidationHelper.GetString(GetValue("ArticleTitle"), ""); } set { Article.SetValue("ArticleTitle", value); }   } ... } ...}

Articles.generated.cs - generated class

1. 2.

3.

/// <summary>/// Custom article page type class./// </summary>public partial class Article : TreeNode{ /// <summary> /// Load this object with sample data. /// </summary> public void LoadSampleData() { Title = "Sample article title"; Summary = "Sample article summary"; Text = "Sample article text"; }}

 

Displaying shared content in MVC applicationsYou can display the added by in your MVC application's views. The shared content, created by addingreusable content content editorspages in the form control is accessible via a field that's part of the for individual page typesPages , code generated .

To display reused content in your MVC application

 of your MVC application.Perform the initial set upReference the page types that you want to access in your view using the directive:@model

@using CMS.DocumentEngine.Types;@model Article...

Access the individual related pages stored in the view. that by default, the pages are accessed in the same order in which they are .Note added by content editors on the Form tab

// Create a list of individual pages stored in the 'Pages' page type fieldnamed 'ContentItems'@{ var pages = Model.Fields.ContentItems.ToList(); }

@if (pages.Any()){ ... // Iterate over each of the pages of a specific type in the same order inwhich they are added on the Form tab @foreach (var article in pages.OfType<Article>()) { ... // Display the image stored in the page's 'Teaser' field <img src="@Url.Kentico().Attachment(article.Fields.Teaser)class="article-tile-image" /> ... }}

 

Articles.cs - extending the generated class

   

Providing friendly URLs on MVC sitesContent only pages in Kentico give over a part of a page URL, called . This part of a URL that identifies acontent editors control page aliaspage using human-readable keywords.

One of the motivations for using page aliases is to improve the site's . That is, you can use page aliases to provide content with moreSEOSEO-friendly identifiers in URLs.

Kentico automatically predefines a page alias for every content only page. Internally, page alias is the of the content only pageNodeAliasand you can retrieve a page alias using the macro expression. Each content only page can only have one unique page alias.{%NodeAlias%}

Identifying pages based on a page alias

Since page aliases in content only pages are controlled by content editors, they can change. Also, page aliases are only guaranteed to beunique in the current sub-tree (under the current parent page). For example, only pages stored directly in the section will have a/Articlesunique page alias. However, if one page is stored under and another page is stored under , they can both have/Articles/March /Articles/Maythe same page alias. This is why you may not want to use page aliases as the only identifier when displaying pages.

The for identifying pages that use page aliases is to use URLs that consist of and . This isrecommended practice NodeID Page aliasmainly to ensure SEO in case the page alias of pages changes on the live site.

Typically, a page alias will be part of a macro expression that makes up a in content only page types. For example, a URLURL patternpattern can be specified like this . Where accesses the page alias./Articles/{%NodeID%}/{%NodeAlias%} {%NodeAlias%}

Identifying multilingual content when using page aliases

Page aliases remain the same for pages in different cultures. To be able to distinguish pages in different cultures, you can, for examplecreate a new page type field that will be used as the page alias. 

Retrieving content only pages based on a page alias

When using page aliases without to create page URLs, you need to make sure that page alias is always unique. You can, to aNodeIDcertain degree, ensure this uniqueness by limiting the way content editors can create new pages:

Allowed page type restrictions - by defining which page types users can place under the current page type.Page scope restrictions - by specifying which page types users can use when creating new pages under specified paths. 

To retrieve pages that use both and a page alias, use the following method. The method is available in .NodeID generated page type code

public static DocumentQuery<Article> GetArticle(int nodeId, string cultureName,string siteName){ returnGetArticles().OnSite(siteName).Culture(cultureName).WhereEquals("NodeID", nodeId);}

To retrieve pages that use page alias ( ) only:NodeAlias

public static DocumentQuery<Article> GetArticles(string pageAlias){ returnGetArticles().OnSite(siteName).Culture(cultureName).WhereEquals("NodeAlias",pageAlias).TopN(1);}

You can also use the whole in the URL. URLs built with contain the whole path leading to the page. ForNodeAliasPath NodeAliasPathexample for an article named . This approach is useful if you store pages in a more structured content/Articles/March/On-Roasts On Roaststree. The method is available in generated page type code. You will also need to map a route with a URL pattern for the .NodeAliasPath

Note that  is limited to 50 characters in length. This means that the resulting URL may be truncated.NodeAliasPath

See our MVC Demo site for a showcase of using this approach to display an article containing content added via the field.Pages

1.

2.

3.

public static DocumentQuery<Article> GetArticle(string nodeAliasPath, stringcultureName, string siteName){ return GetArticles().OnSite(siteName).Culture(cultureName).Path(nodeAliasPath);}

Configuring MVC application to display pages based on a page alias

The following example shows how you can configure your MVC application to display articles that have a URL based on a page alias withoutusing a . Note that the examples build on our , which uses patterns like repositories to retrieve content and otherNodeID MVC Demo siteimplementation specifics.

In your application's RouteConfig.cs file, create a route for accessing articles without a .NodeID

public class RouteConfig { public static void RegisterRoutes(RouteCollection routes) { ... route = routes.MapRoute( name: "ArticleByPageAlias", url: "{culture}/Articles/{pageAlias}", defaults: new { culture = defaultCulture.Name, controller = "Articles",action = "ShowByPageAlias" } ); ... }};

Add a controller action for retrieving articles based on a page alias.

public class ArticlesController : Controller{... // GET: Articles/{pageAlias} public ActionResult ShowByPageAlias(string pageAlias) { var article = mArticleRepository.GetArticle(pageAlias); if (article == null) { return HttpNotFound(); } return View("Show", article); }...}

Create a method for generating article URLs based on a page alias without a .NodeID

3.

4.

5.

public static class UrlHelperExtensions{... /// <summary> /// Generates a fully qualified URL to the action method handling the detailof given article. /// </summary> /// <param name="urlHelper">Url helper</param> /// <param name="article">Article object to generate URL for.</param> public static string ForArticleByPageAlias(this UrlHelper urlHelper, Articlearticle) { return urlHelper.Action("ShowByPageAlias", "Articles", new { pageAlias = article.NodeAlias }); }...}

Retrieve articles based on a page alias. For example in repositories.

public interface IArticleRepository{... /// <summary> /// Returns the article with the specified page alias. /// </summary> /// <param name="pageAlias">The article page alias.</param> /// <returns>The article with the specified page alias, if found; otherwise,null.</returns> Article GetArticle(string pageAlias);...}

public class KenticoArticleRepository : IArticleRepository{... /// <summary> /// Returns the article with the specified page alias. /// </summary> /// <param name="pageAlias">The article page alias.</param> /// <returns>The article with the specified page alias, if found; otherwise,null.</returns> public Article GetArticle(string pageAlias) { return ArticleProvider.GetArticles() .OnSite(mSiteName) .Culture(mCultureName) .WhereEquals("NodeAlias", pageAlias) .LatestVersion(mLatestVersionEnabled) .Published(!mLatestVersionEnabled); }...}

Work with article URLs in Views based on a page alias.

5.

1. 2. 3.

<a href="@Url.ForArticleByPageAlias(article)">@article.Fields.Title </a>

 

Avoiding duplicate URLs on MVC sitesContent only pages are identified by a that usually contains a . As page aliases are guaranteed to be unique only onURL pattern page aliasthe same sub-section level, there are situations in which different content can end up having the same URL. You can use one of the followingapproaches to prevent conflicts in content URLs:

Recommended approach

Allow multiple pages with the same page alias and add another identifier into the URL. For example, a . See how you can NodeID uniquely.identify URLs pages when using page aliases

Alternative approaches

Disallow multiple pages with the same page alias. For example, you can use each individual type of in onecontent only pagessection of the content tree only. If you need to use a content only page type in a different section of the content tree, use a differentcontent only page type instead. To enforce these restrictions, you can use and/or .allowed page types page type scopes

Allow multiple pages with the same page alias and handle duplicate page aliases in the MVC application. Make sure content editorsknow of the potential limitations of this approach.

   

Providing smart search on MVC sitesIf you want to provide smart search on your MVC sites, you need to ensure that   indexes stay up to date. By default, searchsmart searchindexes on MVC applications are updated automatically (when   are enabled).web farms  

That is, no additional configuration is necessary. If you want to process the tasks in a regular interval (by a scheduler), you need to use the S, as the standard way of scheduling tasks is not available in MVC applications.cheduler Windows service

   

Adding preview mode support for MVC sitesPreview mode in Kentico provides a way to view the latest version of pages before they are published (for example when using ). IfWorkflowyou wish to use preview mode in an MVC application that handles the presentation of the website's pages, you need to implement therequired functionality in the application's code.

Before you can use preview URLs, you need to (in Kentico administration) for your content only page types. Thespecify the URL patternURL pattern is then used to create URLs to the Kentico content presented by an external application. Preview URL for pages are generated:

When using the main mode in the application.Preview PagesWhen generating preview links for pages in . See: Pages -> Properties -> General -> Preview URL Sending links to unpublishedpages

The preview URLs the system generates for content only pages consist of additional information, such as language version and a hash forvalidating the URL. The Kentico in your MVC application validates and processes the preview URL. The package thenintegration packageremoves the additional information to leave only the original presentation URL based on the URL pattern. The original presentation URL thengoes through the standard routing process.

You need to manually ensure that your MVC application displays the in preview mode.latest versions of pages

Enabling preview mode in MVC applications

Preview mode support is provided in the . To enable preview support in your MVC application:Kentico.Web.Mvc integration package

Specify a URL pattern for content only pages.  the integration package in your MVC application project. Install Kentico.Web.Mvc

In the MVC application's file, add the following line in the Global.asax Application_Start method:

3.

4.

5.

6.

protected void Application_Start(){ ...

// Enable and configure the selected Kentico ASP.NET MVC integrationfeatures ApplicationConfig.RegisterFeatures(ApplicationBuilder.Current);}

Make sure the feature is enabled in the MVC application's ApplicationConfig.cs file:

public static void RegisterFeatures(ApplicationBuilder builder){ ... builder.UsePreview(); ...}

Checking whether preview mode is enabled for requests

Use the following code to check whether preview mode is enabled for a request:

using Kentico.Web.Mvc;

...

bool previewEnabled =System.Web.HttpContext.Current.Kentico().Preview().Enabled;

The location where you need to check the request context for preview mode depends on the implementation of your MVCapplication. For example, directly in the code of your controllers or when registering repositories that make use of your generatedproviders.

Loading latest versions of pages

Ensure that your code loads the versions of pages instead of the versions. For more information about retrievinglatest publishedpage data, see . For example:Generating classes for Kentico objects

Same-origin policy and preview modeBy default, the MVC application sends a header that enables the . The disasame-origin policy Kentico integration packagebles the policy for preview URLs. This allows you to preview content handled by the MVC application. With the policyenabled, the preview mode in Kentico administration would display a blank page instead of the previewed content.

Tip: If the that you use for your content only pages does not include a variable for the page culture (forURL patternexample if you use a different mechanism to pass the requested culture), you can get the culture from the context of thepreview request:

using Kentico.Web.Mvc;

...

string cultureName =System.Web.HttpContext.Current.Kentico().Preview().CultureName;

6.

7.

// Uses DocumentQuery to load article pages, getting the latest versionsinstead of the published versionsvar articles = ArticleProvider.GetArticles() .LatestVersion(true) .Published(false) .OnSite("mvcsite") .Culture("en-us") .OrderByDescending("DocumentPublishFrom");

If you use for your pages, you need to disable it for preview mode. This ensures that caching works correctly fordata cachingstandard requests, but is not used for the different content displayed in preview mode.

Preview mode should now work correctly for the Kentico application that you use to manage your website's content.

   

Localizing data on MVC sites

Localizing site content

We recommend localizing individual strings displayed on the site via the . You can then create an alias for the Localization application CMS.H class and use the method to work with the strings in your code:elpers.ResHelper GetString()

@using Resources = CMS.Helpers.ResHelper;...<h2>@Resources.GetString("SiteName.OurProducts")</h2>

@using Resources = CMS.Helpers.ResHelper;...@{ ViewBag.Title = Resources.GetString("SiteName.OurProducts");}

 

Localizing validation results and model properties

The default approach to validating the data model of MVC applications is to decorate the model and its properties with attributes from the System.ComponentModel.DataAnnotations namespace. You use the attributes to define common validation patterns, such as range checking,string length and required fields.

The provides a feature that allows you to use localized as errorKentico.Web.Mvc integration package Kentico resource string keysmessages in data annotation attributes. The strings are localized The based on the current culture context of the current visitor. Kentico.Lang

(installed with the integration package) contains a file with the resource stringsuages.English integration package Kentico.Web.Mvc .resx used in the English localization of Kentico. Aside from that, you can also use the standard resource strings stored in the database.

The feature supports localization of the following data annotation attributes:

DisplayDisplayNameDataTypeMaxLengthMinLengthRange

Preview mode and controller output caching

If you use caching of controller output in your MVC application ( attributes), the iOutputCache Kentico integration packagen your MVC application automatically ensures that the output cache is not used for page requests in preview mode.

See our  for an advanced example of an MVC application that uses preview mode.MVC Demo site

1. 2.

3.

RegularExpressionRequiredStringLength

Enabling data annotation localization in MVC applications

the integration package in your MVC application project. Install Kentico.Web.MvcIn the MVC application's file, add the following line in the Global.asax Application_Start method:

protected void Application_Start(){ ...

// Enable and configure the selected Kentico ASP.NET MVC integrationfeatures ApplicationConfig.RegisterFeatures(ApplicationBuilder.Current);}

Make sure the feature is enabled in the MVC application's ApplicationConfig.cs file:

public static void RegisterFeatures(ApplicationBuilder builder){ ... builder.UseDataAnnotationsLocalization(); ...}

Once the feature is enabled, the validation results and display names of model properties are localized using Kentico localization services.

public class MessageModel{... [Required(ErrorMessage = "General.RequiresMessage")] [Display(Name = "General.Message")] [DataType(DataType.MultilineText)] [MaxLength(500, ErrorMessage = "General.MaxlengthExceeded")] public string MessageText { get; set; }...}

Note: The individual error messages are processed by the method and support composite formatting. That is, the System.String.Formatstrings themselves can contain format items that are specific to each validation attribute and represent their parameters. For example, the mi

for the or the and for the .nimum length MinLenghtAttribute minimum maximum RangeAttribute 

Handling 404 Not Found globally in MVC applicationsThe Kentico.Web.Mvc comes with a feature that allows you to return the same '404 Not Found' page in the MVCintegration packageapplication in the following scenarios:

A suitable controller is not foundA suitable controller action is not foundA controller action returns HttpNotFoundResult' (usually returned by calling the controller's 'HttpNotFound''System.Web.Mvc.method)

Prerequisites:

For this feature to work, the element in the section of your <modules> <system.webServer> MVC project's main web.config file needs to attribute set to . The attribute is automatically added by installing the Kentico.Web.Mvc have the runAllManagedModulesForAllRequests true i

.ntegration package

1. 2.

3.

4. 5.

1.

2.

<system.webServer>... <modules runAllManagedModulesForAllRequests="true"></modules> ...</system.webSever> 

Enabling the global Not Found handler in MVC applications

the integration package in your MVC application project. Install Kentico.Web.MvcIn the MVC application's file, add the following line in the Global.asax Application_Start method:

protected void Application_Start(){ ...

// Enable and configure the selected Kentico ASP.NET MVC integrationfeatures ApplicationConfig.RegisterFeatures(ApplicationBuilder.Current);}

Make sure the feature is enabled in the MVC application's ApplicationConfig.cs file:

public static void RegisterFeatures(ApplicationBuilder builder){ ... builder.UseNotFoundHandler(); ...}

In your MVC application's project, create a ' ' view under the path.NotFound.cshtml 'Views\Shared'Implement the view.

Now, whenever a request for a page that doesn't match any controller or controller action is made, the system returns the pNotFound.cshtml age. The system also returns the page whenever a controller action returns the System.Web.Mvc. class (for example,HttpNotFoundResultwhen calling the method).System.Web.Mvc.Controller.HttpNotFound

 

Handling requests not matched by any route

You can also return the 'NotFound.cshtml' view in other cases in which the MVC application responds with a 'Not Found' status. To cover ascenario when a request is made, you need to implement a catch-all route in the RouteConfig.cs file.that doesn't match any configured route

Create a new catch-all route in the MVC application's RouteConfig.cs file. Make sure the route is the last route that you register inthe file:

public static void RegisterRoutes(RouteCollection routes){ ... routes.MapRoute( name: "NotFound", url: "{*url}", defaults: new { controller = "HttpErrors", action = "NotFound" } ); }

Create a controller and action for the catch-all route.

2.

1. 2.

1. 2. 3. 4.

5. 6. 7. 8.

public class HttpErrorsController : Controller{  public ActionResult NotFound() { Response.StatusCode = 404; Response.TrySkipIisCustomErrors = true;

return View(); }}

The system returns the NotFound.cshtml page whenever a request for an undefined route is made on the MVC site. 

Processing scheduled tasks when developing MVC applicationsWhen using a separate MVC application together with a Kentico application, you need to ensure that on the Kenticoscheduled tasksapplication get processed in regular intervals. As the Kentico application itself won't usually receive traffic from site visitors, you either need tokeep the application alive in a different way or process the tasks independently on the Kentico application's worker process.

You can use one of the following approaches for processing scheduled tasks when developing MVC applications:

Automatic scheduler mode - recommended approach. Requires that the Kentico application's worker process remains alive.Scheduler Windows service - independent of the Kentico application's worker process.

Automatic scheduler mode

Configure the Kentico application to use .Automatic scheduler modeSet the setting of your IIS application pool to 0. Otherwise, the application pool worker process shuts downIdle Time-out (minutes)after a period of inactivity. As the Kentico application does not receive traffic from visitors, the worker process would shut down if noone used the Kentico administration for a certain period of time and scheduled tasks would not get executed.

If you don't want to set the Idle setting to 0, you can keep the worker process alive by sending requestsTime-out (minutes)to the Kentico application within the set interval.

Scheduler Windows service 

You can also use the if you want to process scheduled tasks independently on the Kentico application.Scheduler Windows service

Processing scheduled tasks on MVC sites in regular intervals

To guarantee that smart search tasks are processed in regular intervals even if the Kentico application isn't running, set up processing of the Execute search tasks scheduled task using the Windows scheduler service.

Example: Processing smart search tasks on MVC sites in regular intervals

You need to duplicate the scheduled task, which the system contains by default, but isn't runnable by an externalExecute search tasksscheduler:

Install the Scheduler Windows service.Go to (application) and enable .Settings -> System -> Scheduler Use external serviceOpen the application and click .Scheduled tasks New taskSet the following properties of the new task:

Assembly name - CMS.SchedulerClass - CMS.Scheduler.SearchTaskExecutorPeriod - set the desired time interval. For example, the original 'Execute search tasks' scheduled task, available in thesystem by default, uses a 4 hour interval.Use external service - enabled

Click . SaveEdit the original scheduled task.  Execute search tasksDisable the option.Task enabledClick . Save

The system now processes search tasks generated by both the MVC and Kentico application using the Windows scheduler service.

Note:

The Windows scheduler service requires the Kentico EMS license.Tasks that are processed by the Windows service cannot resolve macros dependent on application context, such as: {%ApplicationPath %}.

1.

2.

3.

   

Testing MVC controllersYou can test the logic of your MVC controllers that work with content items, such as articles or products, info objects as well as any otherobjects. This is done by providing fake representations of these objects. Using this approach, you can create the necessary objects withoutaccessing the database.

The recommended approach for providing fake objects is to use repositories (adapters) that, for content items, make use of generated classe Repositories provide the following advantages over using directly in controllers:s. document query

Your tests will work regardless of the used methods. This is important as not all document query methods are supported whencreating fake objects.Repositories only need to contain the methods the application really needs. This allows you to make changes to the implementationin a much smaller scale than if you were using document query.

We also recommend writing individual controllers to use dependency injection and retrieve their dependencies via their constructors. Thisapproach allows you to create classes with clearly defined responsibilities, which are, in turn, easier to test.

You can also use containers such as (or similar container implementations) to simplify the process of creating controllers and theirAutofacdependencies, as well as handling the life cycle of the dependencies.

Providing content items in controller tests

This is an example showing how the ArticleController controller and ArticleControllerTests are implemented in a similar way as on the sampleMVC Demo site. The controller displays a list of articles and their detail. Note that the sample implementation is dependent on externallibraries, such as , , and .Autofac TestStack.FluentMVCTesting NSubstitute

Create a repository that provides access to content items using their . The repository only needs to contain thegenerated providersmethods required by the application, not the data layer.

public interface IArticleRepository{ IEnumerable<Article> GetArticles(int count = 0); Article GetArticle(int nodeID);}

public sealed class ArticleRepository : IArticleRepository... public Article GetArticle(int nodeID) { return ArticleProvider.GetArticle(nodeID, mCultureName, mSiteName); }...

Register the repository in the container configuration. For example, the Kentico MVC Demo site configures the container in theapplication's Global.asax.cs file. 

builder.Register<ArticleRepository>().As<IArticleRepository>();

Use container and any other dependencies in the controller constructor.

See our for a reference on how to implement tests for your controllers.MVC Demo site

3.

4.

5.

6.

public class ArticlesController : Controller{ private readonly IArticleRepository mArticleRepository;

public ArticlesController(IArticleRepository repository) { mArticleRepository = repository; }...

The controller contains a method that returns a view based on article's NodeID or a new instance of the class ifHttpNotFoundResult the article doesn't exist.

// GET: Articles/Show/{id}public ActionResult Show(int id = 0){ var article = mArticleRepository.GetArticle(id); if (article == null) { return HttpNotFoundResult(); } return View(article);}

Set up the controller test and create the controller with the required dependencies. The following example uses the testingNUnitframework.

[SetUp]public void SetUp(){ // Allow creating of articles without accessing the database. Fake().DocumentType<Article>(Article.CLASS_NAME); // Mock a repository and set a return value. var article = TreeNode.New<Article>().With(a => a.DocumentName = "Test"); var repository = Substitute.For<IArticleRepository>(); repository.GetArticle(1).Returns(article);

mController = new ArticlesController(repository);}

Create individual test cases for the controller.

[Test]public void Show_WithoutExistingArticle_ReturnsHttpNotFoundStatusCode(){ mController.WithCallTo(c => c.Show(2)) .ShouldGiveHttpStatus(HttpStatusCode.NotFound);}

   

Improving performance of MVC applications

Configuring web farms on MVC applications

1. 2.

If you want to on your MVC site and don't run your application on , you need to configure your Kenticouse caching Microsoft Azureapplication and the MVC application as .servers in a web farm

License limitations: this scenario requires a license with an extra web farm server that will be used for the MVC application. Request alicense through the or our if you need one extra server just for the MVC application.Kentico Client Portal support

Perform all steps required to set up your .MVC applicationConfigure (in the administration interface of the Kentico application).automatic web farm mode

The MVC application works as a web farm server, because it uses the same database as the Kentico application and performs operationsthrough the Kentico API.

The web farm ensures that the MVC application invalidates cache according to content or setting changes made in the Kentico applicationand vice versa. You can now use in the MVC application.caching of data and output

 

Caching in MVC applications

You can cache the data and output of controller actions in your MVC application.

Prerequisite: for caching in your MVC application to work correctly, your Kentico and MVC applications need to be configured as a web farm.

Specifically, you can cache the following:

Data you retrieve to display on individual web pages.Output of controller actions.

Caching data in MVC applications

We recommend using caching of data, especially for data that is frequently accessed (queried from the database). For example, you maywant to cache individual pages, forms and any other data that you retrieve from the Kentico database and display on the site.

For pages, custom table data or forms, you can handle the caching in individual repositories that make use of the .generated providersAnother approach would be using and decorating the individual repositories—see our  for a reference on how to useAOP MVC Demo sitethis approach.

Use the method to cache data in your code.CacheHelper.Cache

Examples

Note: the examples use minimal cache dependencies – the cache is cleared whenever an article is modified, deleted, or when a new articleis created.

To ensure consistency of the viewed data, you should always generate cache keys with all the parameters that you use to retrieve the data.So that, for example, after switching to a different culture, visitors don't see the displayed articles in the previously selected culture.

See for more information on how to configure cache dependencies for your scenarios.Setting cache dependencies

Example: Caching the data of multiple articles

1. 2.

Adding web farm servers to scale performance

If you wish to use a web farm to scale the site's performance, you can add further instances of the MVC application. Werecommend using the following process:

Develop and test the site in a web farm with two servers (one MVC application, one Kentico application).Deploy any number of additional instances of the same MVC application. Each instance must connect to the same Kenticodatabase.

The automatic web farm mode automatically registers the new instances as web farm servers and ensures correct synchronization(among all instances of the MVC application and the Kentico application).

If you need to scale the performance of the Kentico administration interface used to manage the site content and settings, you canalso run multiple instances of the Kentico application in the web farm. In this scenario, use the standard approach for configuring

. You need to use one of the servers as the "primary" Kentico instance (for example for holding files shared by theweb farm serversentire web farm, such as ).smart search indexes

Note: The above scenarios require a license that supports the additional number of web farm servers.

public sealed class ArticleRepository : IArticleRepository... public override IEnumerable<Article> GetArticles(int count = 0) { ...

Func<IEnumerable<Article>> provideData = () => ArticleProvider.GetArticles() .OnSite(mSiteName) .Culture(mCultureName) .TopN(count) .OrderByDescending("DocumentPublishFrom") .TypedResult; // Ensures that the result of the query is saved, notthe query itself.   var cacheSettings = new CacheSettings(10, "myapp|data|articles", mSiteName,mCultureName, count) { GetCacheDependency = () => { // Create cache dependencies. This example makes the cache clear data once anyarticle is modified in Kentico. var dependencyCacheKey = String.Format("nodes|mvcsite|{0}|all",Article.CLASS_NAME.ToLowerInvariant()); return CacheHelper.GetCacheDependency(dependencyCacheKey); } }; return CacheHelper.Cache(provideData, settings); }...

Example: Caching the data of a single article

public sealed class ArticleRepository : IArticleRepository... public override Article GetArticle(int nodeID) { ... Func<Article> provideData = () => ArticleProvider.GetArticle(nodeID,mCultureName, mSiteName).FirstObject; var cacheSettings = new CacheSettings(10, "myapp|data|article", nodeID,mCultureName, mSiteName) { GetCacheDependency = () => { // Create cache dependencies. This example makes the cache clear data once anyarticle is modified in Kentico. var dependencyCacheKey = String.Format("nodes|mvcsite|{0}|all",Article.CLASS_NAME.ToLowerInvariant()); return CacheHelper.GetCacheDependency(dependencyCacheKey); } }; return CacheHelper.Cache(provideData, settings); }...

Caching controller action output in MVC applications

1. 2. 3.

1. 2. 3.

You can cache the output of individual controller actions using ASP.NET output caching. This can significantly increase your websiteperformance. We recommend caching the output of all possible controller actions, especially on controllers that return often requested views.

Output cache also allows you to define cache dependencies to accommodate various scenarios with both static and dynamic content.

Use the attribute to mark the action methods you want cached and set the cache duration (in seconds).OutputCache

Use the HttpContext.Current.Response.AddCacheItemDependency() method to add dependencies in your individual controller actionmethods.

Controller actions can be called in situations in which the dummy cache items haven't yet been created. To account for that, ensure theexistence of the dummy cache item explicitly by calling .CacheHelper.EnsureDummyKey()

Using CMS.Helpers;... [OutputCache(Duration=600, VaryByParam="none")]public ActionResult Index(){ var articles = mArticleRepository.GetArticles();  // Set cache dependencies. This example makes the system clear the cache once anyarticle is modified in Kentico. var dependencyCacheKey = String.Format("nodes|mvcsite|{0}|all",Article.ClassName.ToLowerInvariant()); CacheHelper.EnsureDummyKey(dependencyCacheKey); HttpContext.Current.Response.AddCacheItemDependency(dependencyCacheKey);  return View(articles);}

Note: the example uses minimal cache dependencies – the cache is cleared when any of the articles the method works with is modified,deleted, or when a new article is created. See for more information on how to configure cache dependencies forSetting cache dependenciesyour scenarios. 

Deploying MVC applications

Using staging for the content of MVC applications

You can use to transfer page content and other objects between different instances of Kentico, even when using a separate Staging MVC for the presentation of the website.application

For MVC websites, every "instance" within the staging topology must consist of the following components:

The Kentico application used to store data and manage contentThe MVC application used to generate the design of the live website (or multiple MVC applications running in a web farm)One Kentico database shared by the applications

The steps required to set up the staging are the same as with standard Kentico projects. You need to between theconfigure the stagingKentico applications, which then provide the transfer of data between the databases of the given staging instances. The MVC applicationswithin individual staging instances use the data of the related Kentico application to present the website.

Running MVC applications on Microsoft Azure

You can run your MVC application, together with the Kentico application, on . You can make use of both or Microsoft Azure Azure Web Apps.Azure Cloud Services

Running MVC applications on Azure Web Apps

Perform the of your MVC application.initial set upDeploy both the Kentico application and MVC application .to Azure Web AppsEdit your and add a and for your MVC application.site domain alias presentation URL

Running MVC applications on Azure Cloud Services

Configure the Kentico application .to run Azure Cloud ServicesEdit your and add a and for your MVC application.site domain alias presentation URLPerform .additional configuration

1. 2.

3. 4. 5. 6.

a.

b.

7.

1.

2.

3. 4.

5.

Configuring the MVC application project to run on Azure Cloud Services

Perform the of your MVC application.initial set upAdd an project to your solution. Azure Cloud Service Visual Studio ->Add -> New project -> Azure Cloud Service -> Add

.ASP.NET WebRoleIn the window, click (do not choose a template).New ASP.NET Project Cancel In the WebRole project you just created, right-click .Roles -> Add -> Web Role Project in solutionSelect your project and click .MVC application OKModify the section of the following files:<WebRole> </WebRole>

ServiceDefinition.csdef - copy the whole  and <ConfigurationSettings> ... </ConfigurationSettings> <LocalResources sections from the same file in the CMS (Kentico) project.> ... </ >LocalResources

ServiceConfiguration.Cloud.cscfg - copy all the settings starting with in the CMS* <ConfigurationSettings> ... section from the same file in your CMS (Kentico) project.</ConfigurationSettings>

 Publish the project. Use the same Storage account that you are using for the Kentico application when publishing.

   

Using ASP.NET Web API with KenticoYou need to perform certain tasks to make work with Kentico. The steps vary based on the version of Web API that youASP.NET Web APIwant to use.

Note that Kentico uses ASP.NET Web API 1 for internal APIs. These are registered at the /cmsapi/ endpoint and aren't meant for public use.

Using ASP.NET Web API 1Using ASP.NET Web API 2

Using ASP.NET Web API 1

Add the following references to your custom project. Find the libraries in the folder of your Kentico solution:LibCMS.BaseCMS.CoreCMS.DataEngine

In your project's file, add: AssemblyInfo.cs

[assembly: CMS.AssemblyDiscoverable] Using NuGet Package Manager, install Microsoft.AspNet.WebApi into the project. This adds all the necessary libraries to the project.Make all the controllers you are placing in the class library inherit from the System.Web.Http.ApiController class.

using System.Web.Http;

namespace MyCompany.MySpace{ public class CustomWebAPIController : ApiController { public HttpResponseMessage Get(int id = 0) { // You can return a variety of things in Web API controlleractions. For more details, seehttp://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/action-results return Request.CreateResponse(HttpStatusCode.OK, new { Data ="test data", ID = id }); } }}

In your startup logic, register custom routes that do not conflict with Kentico's 'cmsapi' or any other page paths.

5.

6.

1. 2. 3.

4.

5. 6.

7.

protected override void OnInit(){ base.OnInit(); GlobalConfiguration.Configuration.Routes.MapHttpRoute("customapi","customapi/{controller}/{id}", new { id = RouteParameter.Optional });}

Rebuild the solution.If your custom project uses a different .NET version, you may need to manually add the Newtonsoft.Json library to the f/binolder.

You can now make calls on the custom route that you registered.

$http.get("http://myserver/customapi/CustomWebAPI", { id: 1}) .success(function (data) { alert(data); }) .error(function(error) { // handle the error });

 

  

Using ASP.NET Web API 2

Create a new library project in the Kentico solution. The project will contain your Api Controllers.Reference the class library project in the CMSApp project. Or in your website if you are using a website project.Add the following references to the class library's project. Find the libraries in the Lib folder of your Kentico solution:

CMS.BaseCMS.CoreCMS.DataEngine

 In your project's file, add: AssemblyInfo.cs

[assembly: CMS.AssemblyDiscoverable] Using NuGet Package Manager, install Microsoft.AspNet.WebApi into the project. This adds all the necessary libraries to the project.Make all the controllers you are placing in the class library inherit from the System.Web.Http.ApiController class.

using System.Web.Http; namespace MyCompany.MySpace{ public class CustomWebAPIController : ApiController { public HttpResponseMessage Get(int id = 0) { // You can return a variety of things in Web API controlleractions. For more details, seehttp://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/action-results return Request.CreateResponse(HttpStatusCode.OK, new { Data ="test data", ID = id }); } }}

In your , register custom routes that do not conflict with Kentico's 'cmsapi' or any other page paths.startup logic

7.

8.

9.

1. 2. 3.

1. 2.

protected override void OnInit(){ base.OnInit(); GlobalConfiguration.Configuration.Routes.MapHttpRoute("customapi","customapi/{controller}/{id}", new { id = RouteParameter.Optional });}

If your solution contains the CMSApp_MVC project, remove the project from the solution and delete all the files in the /Lib/MVCfolder follow the for your MVC development.or steps for using the CMSApp_MVC projectRebuild the solution.

If your custom project uses a different .NET version, you may need to manually add the Newtonsoft.Json library to the f/binolder.

You can now make calls on the custom route that you registered.

$http.get("http://myserver/customapi/CustomWebAPI", { id: 1}) .success(function (data) { alert(data); }) .error(function(error) { // handle the error });

 

Managing page templatesAll pages on Kentico websites are based on . Templates, with the exception of pages based on content only page types, page templatesdefine the basic structure and components of pages without the content added by editors.

To access the main management interface for all page templates in the system, open the application. The system organizesPage templatestemplates into categories. You can edit individual templates by selecting them in the category tree.

To edit the properties of the template assigned to a specific page in the application:Pages

Select the page in the content treeOpen the tab.Properties -> TemplatesClick .Edit template properties

OR

Open the page's tab.DesignRight-click the green template header and click .Edit template

When editing templates, you can set the following page template properties on the tab:General

Page template property Description

Template display name The name of the template displayed to users in the administrationinterface.

Template code name A unique identifier of the template.

Category Sets the category where the template is stored in the page templatecatalog.

Template description Here you can enter a description for the template. Users can seethis description when selecting page templates in the catalog (forexample when creating new pages).

Thumbnail Allows you to set the image that represents the template in thepage template selection catalog.

You can choose between two types of images:

Image - upload a standard image file (for example a png).Font icon class - enter the name of a CSS class that defines a

.font icon

Clone as ad-hoc for new pages Only available if the is .Template type Portal page

When a user creates a new page with a template that has thisoption enabled, the system automatically creates an ad-hoc copy ofthe template and assigns it to the page. This allows users toimmediately modify the design of the new page without affecting thedefault re-usable template.

Template type________________________

The following types of page templates are available:

Portal page - functions as a page template.portal engineASPX page - uses the developmentASPX page templatemodel. The content is based on a standard ASPX web form. Ifselected, you need to specify the path to the source file in the F

property.ile nameASPX + Portal page - works the same way as the ASPX pageoption, but also supports portal engine functionality —managing web parts or widgets in predefined zones on the Des

tab of the application.ign PagesDashboard page - provides a template for swidget dashboardections of the administration interface. This type of pagetemplate cannot be used for standard content tree pages.MVC - template for creating pages defined through an coMVCntroller and action. Only choose this option when using theobsolete CMSApp_MVC project to develop your MVC sites.You need to specify the controller and action via the Default

and properties. Pages based oncontroller Default actionMVC templates automatically use the live URL and view inediting mode (i.e. on the tab of the Pages application).PageUI page - functions as a template for pages ofportal enginethe Kentico administration interface. You cannot assign UIpage templates to normal website pages, only to .UI elements

Master template Only available if the is .Template type Portal page

Indicates if the pages that use the template are designated as Mast. Enabling this option also causes the template to beer pages

selectable as the root master page template in the New site wizard.

Page nesting Only available if the is .Template type Portal page

Determines how pages based on the template display their contentinside ancestor pages in the content tree.

All ancestor pages - nests within all ancestor pages in thecontent tree up to the nearest master page.None - behaves as a standalone page without any nesting.Only the nearest master page - nests only within thewebsite's master page. If the website uses multiple masterpages, the pages based on this template nest only within theclosest master page in the content tree hierarchy.Specific content tree levels - allows you to enable or disablenesting within specific levels of the content tree (representedby the checkboxes below). The actual nesting depends on thestructure of the website where the template is used.

See: Inheriting portal engine page content

File name Only available if the is or Template type ASPX page ASPX + Portal.page

Specifies the path to the file that serves as the page.aspxtemplate's source. You can either choose the using the buttoSelectn, or enter the path manually. The tilde character (~) represents theroot directory of the project folder, e.g. ~/CMSTemplates/CorporateSite/Blog.aspx

Default controller Only available if the is .Template type MVC

Sets the name of the controller class containing the MVC action thatthe system performs when pages using this template are accessed.

Do not type the suffix of the class name. For example, ifController the class is called , enter .NewsMVCController NewsMVC

The system first searches for the specified class in the CMS.Control namespace. If the class cannot belers.<current site code name>

found there, the namespace is searched.CMS.Controllers.Global

1. 2. 3.

4. 5.

6.

1. 2. 3. 4.

Default action Only available if the is .Template type MVC

Specifies the exact action defined within the controller class that thesystem performs when loading pages based on the template.

 

  

Limiting the use of page templates

When editing page templates in the application, you can:Page templates

Assign templates to specific websites on the tab. Users can only work with the template on the selected websites.SitesAdd further limitations through (by default, page templates can be used anywhere on the websites to which they aretemplate scopesassigned).

Scopes simplify the user experience by reducing the number of templates available for selection in specific parts of the website. To definescopes for a page template:

Open the tab of the template's editing interface.ScopesSelect .Template can be used only within the following scopesChoose the where the scope will apply.Site

You can only choose the sites to which the template is assigned.Global scopes are valid on all sites in the system.

Click .New template scopeSet the parameters of the scope:

Starting path - defines a sub-section of the website where the template can be used. Allows the exact page with theentered path and all of its descendants (subpages).Page type - allows the template only for pages of the selected .typeCulture - allows the template for page versions in the selected .culture (language)Levels - you can allow the template only for pages on specific levels in the content tree hierarchy.

Click .Save

You can add any number of scopes for each template. Users can select the template for pages that fulfill the requirements of ofat least onethe scopes.

Defining head content for templates

You can add custom head content for page templates, such as links to external CSS stylesheets or JavaScript files. 

Open the page template's editing interface.Switch to the tab.HeaderType in the required head content.Click .Save

The system inserts the content into the element in the output code of all pages that use the given template.<head>

For pages that use , the head content can also be inherited by subpages. The inheritance depends on the followingportal engine templatesoptions, which you can enable on the tab of each page template:Header

Allow descendant templates to inherit the header - if enabled, the head content of the template can be inherited by pages onlower levels in the content tree.Inherit headers from the templates of ancestor pages - indicates if pages based on the template are allowed to inherit headcontent from the templates of pages that are above them in the content tree.

Finding which pages use a given template

To view a list of all pages in the system that use a specific page template, open the tab of the template's editing interface.Pages

You can access individual pages in the list through the following actions:

Important: Template scopes are a security feature. After assigning a template to a page, users can move the page to anotlocation that is not allowed by the given template's scopes.

Note: The header inheritance works according to the settings of pages — pages can only inherit head content frompage nestingancestor pages where they are nested. This way, the system only adds the head content to pages that actually display the pagetemplate containing the header definition.

1. 2. 3.

1. 2. 3. 4. 5.

6.

 Edit page - opens the page in the mode of the application.Edit Pages

 Navigate to page - opens the page on the live site.

Editing the XML source of a template's web parts

The system stores the content and configuration of placed on page templates as XML data. If you cannot use the tab dueweb parts Designto an error caused by an incorrectly configured web part, you can fix the issue on the tab of the given page template's editingWeb partsinterface. The tab allows you to edit the XML source directly.

You can modify the values of properties for all web parts on the template.You can remove web parts from the template by deleting entire elements.<web part>

 

Loading and displaying data on websitesOnce you prepare the data structure of your website using and/or , add components ( or ASP.NETpage types custom tables web partscontrols) onto pages to load and display the content. The following steps outline the general process:

Use a to load the required datadata sourcePrepare to define how the data appears on the websitetransformationsPlace a component onto the page, which displays the items from the data source according to the assigned transformationslisting

Many listing components contain a built-in data source. For example, the provides a data source for loading Kentico pages. If youRepeaterwish to connect a separate data source to such web parts, the type must match the internal data source. So in the case of the Repeater webpart, you need to connect a .Pages data source

To display items from any type of data source, use the , or . The basic listing webBasic repeater Basic datalist Basic universal viewerparts do not load data on their own and you always need to connect a separate data source.

You can also add optional functionality to lists of data:

Filters - allow users on the live site to limit which data is displayed Paging - separates lists of data into multiple pages and provides navigation between the pages

For more information, see .Filtering and paging data

Example - Displaying blog posts (page data)

The following example shows how to display a list of blog posts using a web part. The Repeater combines both a page data sourceRepeaterand listing functionality. You can use the same approach whenever you need to display the content of your website's pages.

Note: The example works with data from the sample Corporate site.

Open the application.PagesUse the content tree to select the page where you want to display the data.Open the tab.DesignAdd the web part onto the page.RepeaterSet the web part's properties:

Path: /Community/Blogs/%Page types: CMS.BlogPostTransformation: CorporateSite.Transformations.BlogPosts

Save & Close.

The Repeater loads data from the blog post pages in the specified section of the website, and displays the information in the format definedby the transformation.

 

For more information, see:

Loading page dataWriting transformations

1. 2. 3. 4. 5.

6. 7.

8.

Example - Displaying user profiles (object data)

The following example demonstrates how to create a list of content editor user profiles. To display user data, you need to connect twoseparate web parts — a data source and a basic listing web part.

Open the application.PagesUse the content tree to select the page where you want to display the data.Open the tab.DesignAdd the web part onto the page.Users data sourceSet the following properties for the web part:

Web part control ID: EditorUserSourceWhere condition: UserIsEditor = 1

Click .OKAdd the web part onto the same page with the following properties:Basic repeater

Data source name: EditorUserSourceTransformation name: CorporateSite.Transformations.MembersList

Click .OK

The User data source loads all users who have the Editor (i.e. have access to the administration interface). The privilege level Web part and properties bind the data source to the Basic repeater, which displays the user data according to thecontrol ID Data source name

specified .transformation

 

Loading page dataThe system provides various types of predefined components ( or controls) that allow you to from the pagesweb parts load and display datain your website's content tree.

The most common examples include:

Pages data source, combined with a , or Basic repeater Basic datalist Basic universal viewerListing web parts with built-in page data sources ( , , , ...)Repeater Datalist GridComponents for displaying pages in a hierarchical structure ( , — see Universal page viewer Hierarchical viewer Using hierarchical

)transformations When configuring page data sources, fill in the property to specify which pages to load. See for details.Path Writing page path expressions

You can also use the properties to further limit which pages that data source retrieves:Content filter

Web part property Description Sample value

Page types___________________________

Determines which to load. Enterpage typesa list of page type code names, separatedby semicolons (;).

You can use the * wildcard as a substitutefor any sequence of characters. Forexample includes the page types Product.*

, , Product.Camera Product.CellPhone Produ etc.ct.Computer

If you leave the property empty, the datasource retrieves all page types.

Note: If you use an empty value to load allpage types, only the general data columnsfrom and the View_CMS_Tree_Joined COM

table (for product pages) are_SKUavailable in the retrieved data. The specificfields of individual (coupledpage typesdata) are not included. Keep this fact inmind when writing , WHEREtransformationsconditions, ORDER BY expressions, orotherwise using columns.

cms.menuitem;cms.article;cms.news

Category name Allows you to load only pages that belong tothe selected .categories

 

Combine with default culture Indicates if the data source loads the default for pages that are notlanguage version

available in the language selected by thecurrent user.

You can choose between and , orYes Nouse the website-level settings (Settings ->

).Content -> Combine with default culture

 

Culture code Determines which culture version of thespecified pages the data source loads.Leave the property empty to automaticallyuse the language selected by the currentuser.

en-us

Maximum nesting level Specifies the maximum number of contenttree sub-levels from which the data sourceloads content. The number is relative, i.e.counted from the beginning of the specifiedpage path.

The value -1 loads pages from allsub-levels.

 

ORDER BY expression Sets the value of the ORDER BY clause inthe SELECT statement used to retrieve thecontent.

: Users without the Administrator Note privile or the foge level Edit SQL code permission

r the module are only allowed toDesignwrite the following types of SQL syntax:

one or more column names (separatedby commas)the ASC and DESC keywords

ProductName ASC, ProductPrice DESC

Select only published Indicated whether the data source onlyloads published pages (based on workflow

).and content scheduling

 

Select top N pages Specifies the maximum amount of pages toload. If empty, the data source loads allpossible pages.

 

Site name Specifies the site from which the pages areloaded. If you leave the value empty, thedata source retrieves content from thecurrent website.

CorporateSite

WHERE condition Sets the value of the WHERE clause in theSELECT statement used to retrieve thecontent.

: Users without the Administrator Note privile or the foge level Edit SQL code permission

r the module are only allowed toDesignwrite the following types of SQL syntax:

column names, values and basicoperators: =, !=, >, <AND & OR operators, parenthesescolumn BETWEEN AND value valuecolumn LIKE valuecolumn IN (values)column IS NULLNOT keyword for the aboveexpressions (NOT BETWEEN, NOTLIKE, NOT IN, IS NOT NULL)

ProductPrice > 100 ANDProductColor='green'

Filter out duplicate pages If checked, the data source filters outduplicate links to the same page (see creati

for details).ng linked pages

 

Check permissions(System settings category)

Indicates whether the data source checksthe permissions of the users viewing thecontent. If enabled, only pages for which theuser has the permission are loadedRead(for secured pages).

 

 

Writing page path expressionsPath expressions allow you to select a set of pages from the content tree of Kentico websites. The expressions are based on the valias pathalues of pages. You can use two types of path values:

Exact paths of individual pagesExpressions containing special characters that specify multiple pages or relative paths

You need to use path expressions in the property of or controls that load data from pages (page data sources, page listingsPath web partswith built-in data sources, ).navigation components

Using wildcard characters (% and _)

The . Add the wildcard to the end of the path to select all pages under the specified% wildcard represents any number of characters section of the site.

Examples:

/ - only the root page/% - all pages/Products - only the pageProducts/Products/% - all child pages under the pageProducts

The _ . For example: wildcard represents a single character

/Product_ - selects pages , , etc./ProductA /Product1 Product2

Important

We recommend that you carefully consider the performance aspects of components that load data. Fill in the propertyColumnsand set up caching.

For more information, see:

Loading data efficientlyCaching the data of page components

Tip: You can also allow users to dynamically choose which data is displayed on the live site. See .Filtering and paging data

Escaping wildcards in paths

If you need to use the wildcards as standard characters inside path expressions, enclose the character inside brackets ([ ]). Forexample:

 

Using relative paths

You can use relative paths expressions to .select child pages or parent pages

Examples:

. - the current page's path

.. - the path of the current page's parent

./Product - page under the current pathProduct

../Product - page under the parent page of the current pathProduct

./% - all pages under the current path (or selection of the current page, see below)Leaving the Path value empty

../% - all pages under the parent page of the current path

Leaving the Path value empty

If you leave the path value empty, the behavior depends on the type of the component and other variables.

Navigation components

For (such as the web part), an empty value always sets the path to all pages (equivalent of /%).navigation components CSS list menu

Standard page data sources

General web parts and controls with page data sources perform one of the following actions if you leave the Path property empty:

Selection of the current page - the component loads and displays only the current page using the (ifSelected item transformationspecified).Loading of child pages - equivalent of . All specified for the data source still apply.<current alias path>/% filtering options

The behavior depends on the following conditions:

* Whether the listing component's property includes the current page's . : An empty valuePage types (ClassNames) page type Noteincludes all page types.** If the current page type has the flag enabled ( ).Behaves as Page (menu item) type Page types -> Edit the page type -> General

Page type match (*) Behaves as Page (menu item) type flag(**)

Empty path behavior

Selection of the current page

Loading of child pages

Loading of child pages

The data source does not load any data atall

Getting parts of the current path

You can use special expressions to .extract parts of the current page's path

{0} - the alias of the page on the first level of the current path{1} - the page alias of the current path's second level...

For example, if the page path is: /Company/Careers/USA-Branch/Development/QA-Engineer

{0} = Company{1} = Careers{3} = Development

Path examples:

/{0}/{1}/% - all pages under the second level of the current path/{0}/{1}/Details - page on the third level of the current pathDetails

/Special[_]Offers - selects the pageSpecial_Offers

For standard page data sources, the path expression works exactly the same way as an empty path value../%

1. 2.

 

Building website navigationNavigation is a necessary part of every website. The purpose of navigation is to:

Allow users to easily move between pagesProvide an overview of the website's content

Kentico stores pages in the website content tree. The basic principle of dynamic navigation is to load page data, such as page names andURL information, and use the data to generate links. The appearance of the links primarily depends on the website's CSS.

You can use the following default components to build your site's navigation:

Navigation web parts Navigation controls

On pages, build your navigation using the followingportal engineweb parts:

Repeater/Basic repeater (recommended for flat navigation)Hierarchical viewer (recommended for hierarchicalnavigation)CSS list menu (simple, but limited markup customizations)BreadcrumbsTab menuTree viewSite map

Use controls to create navigation on or insideASPX page templatescustom components:

CMSBreadCrumbsCMSListMenuBasicTabControlCMSTabControlCMSTreeViewCMSSiteMapCMSUniView

All navigation components contain a built-in data source for loading pages (except for the web part, and the Basic repeater BasicTabControlcontrol).

You can choose which pages to load by configuring standard properties, such as the or .page filtering , Page typesPath WHERE conditionUse the and properties to ensure that the navigation is accurate on the live site.Select only published Check permissions

Please be aware of the following behavior when working with navigation components:

Navigation components load and display data according to the .navigation properties of pages

If the property is empty, navigation components load all pages on the website (equivalent to /%).Path

If the property is empty, navigation components load and display only pages.The Page types CMS.MenuItem Breadcrumbs / component is an exception, and displays all page types by default.CMSBreadcrumbs

When writing expressions for navigation components that display pages in a tree structure, the root of the page tree (orORDER BYsub-tree) must be first in the resulting order. Always start your Order By clauses with the column, for example: NodeLevel NodeLevel, NodeOrder 

Navigation data sources load a default set of page columns (required to correctly display pages in menus). The proalways Columnsperty allows you to add extra columns if your menu needs data from a field that is not included in the defaults. To find a full list of thedefault navigation columns, use the SQL queries debugging tool and inspect the query performed by your navigation component.

 

Creating a flat menu using the Repeater web part

We recommend using the or web part for creating a flat website navigation. Unlike the web part,Repeater Basic repeater CSS List menuyou can fully control the HTML code generated for the individual menu elements in the transformation.

Note that compared to the web part, this approach requires additional configuration.CSS List menu

Place the web part Repeater on the page where you want the menu displayed.Configure the web part's properties:

HTML Envelope -> Content before:

 <ul class="CMSListMenuUL">

HTML Envelope -> Content after:

 </ul>

Note: If you attempt to extract a level that does not exist in the current page's path:

The expression returns an empty value.If there is a slash (/) after the expression, the system removes it when resolving the overall path.

2.

3. 4.

1.

2. 3.

4. 5.

Create a . The following example Text/XML transformation replicates the web part with the Transformation CSS List menu , , properties enabled:Display highlighted item as link Render CSS classes Render link title

<li class="{% if (IsCurrentDocument()) { return"CMSListMenuHighlightedLI" } else { return "CMSListMenuLI" } #%}"><a href="{% GetDocumentUrl() %}" class="{% if (IsCurrentDocument()) {return "CMSListMenuLinkHighlighted" } else { return "CMSListMenuLink" }#%}" title="{% HTMLEncode(DocumentName) %}">{% HTMLEncode(DocumentName)%}</a></li>

(Optional) Configure .additional propertiesSave & Close.

Creating a hierarchical menu using the Hierarchical viewer web part

We recommend using the web part for creating a hierarchical (multi-level) website navigation. Hierarchical viewer Unlike the CSS Listmenu web part, you can fully control the HTML code generated for the individual menu elements in the transformation.

The web part makes use of .Hierarchical viewer hierarchical transformations

Note that compared to the CSS List menu web part, this approach requires additional configuration.

In a container page type, create the transformations that you will need. This example will use a , , and transforHeader Foooter Item mations of the . We will place code in the transformations later.Text/XML typePlace the web part on the page where you want the menu displayed.Hierarchical viewer Configure the web part's properties:

In , select the Hierarchical transformations Header transformation.

 <ul class="CMSListMenuUL">

Create a new Footer transformation.

 </ul>

Create a new . The following example Text/XML transformation replicates the webItem Transformation CSS List menu part with the , , properties enabled. The Display highlighted item as link Render CSS classes Render link title {^

is a placeholder control that defines an entry point for nested transformations.SubLevelPlaceholder ^}

<li class="{% if (IsCurrentDocument()) { return"CMSListMenuHighlightedLI" } else { return "CMSListMenuLI" } #%}"> <a href="{% GetNavigationUrl() %}" class="{% if (IsCurrentDocument()){ return "CMSListMenuLinkHighlighted" } else { return "CMSListMenuLink"} #%}" title="{% HTMLEncode(DocumentName) %}">{%HTMLEncode(DocumentName) %}</a> {^SubLevelPlaceHolder^}</li>

(Optional) Configure .additional properties.Save & Close

Example - Creating a menu using the CSS List menu web part

The following example demonstrates how you can create a basic two-level menu using the web part.CSS List menu

Adding the menu web part

The CSS List Menu web part loads page data and renders links inside standard HTML lists (composed of and elements).<ul> <li>The links automatically lead to the appropriate page URLs and display the page names in the link text.

1. 2. 3. 4.

5. 6. 7.

8.

1. 2. 3. 4.

Open your website in the application.PagesCreate a new page.Open the new page's tab.Properties -> TemplateSelect in the section and click .None Page nesting Save

Disabling is not a required step for creating menus, but allows you to have a completely blank page for thepage nestingpurposes of the example.

Switch to the tab.DesignAdd the web partCSS List menu to the page.Configure the web part's properties:

Content filter -> Maximum nesting level: 2 (ensures that the menu only loads and displays the first two levels of thewebsite's content tree)HTML Envelope -> Content before: <div class="SimpleMenu">HTML Envelope -> Content after: </div>

Click .OK

The web part displays an unstyled list of page links. Pages on the second level in the site's content tree appear in sub-lists under the parentpages.

Defining CSS styles

Implement the design of the menu using . You can either assign a separate stylesheet to the page (shown in the example) orCSS stylesheetsuse the website's main stylesheet.

Open the page's tab.Properties -> GeneralUncheck the box next to the property.Inherit CSS stylesheetClick .NewType a for the stylesheet and enter the following :Display name CSS code

4.

5. 6. 7.

.SimpleMenu UL { Border: #c2c2c2 1px solid; Float: left; Font-size: 12px; Font-family: Arial; Background: #e2e2e2; Padding: 0px; Margin: 0px; List-style-type: none;}

/* Makes the first menu level horizontal */.SimpleMenu LI {  Float: left;}

.SimpleMenu A {  Padding: 3px;  Margin: 0px;  Display: block;  Width: 120px;  Color: black;  Text-decoration: none;}

/* Highlights menu items on mouse-over */.SimpleMenu A:hover {  Background: #808080;  Color: white;}

/* Hides the second menu level by default */.SimpleMenu UL UL {  Display: none;}

/* Displays the second level when hovering over an item on the first level */.SimpleMenu UL LI:hover UL { Display: block; Border-top: none; Width: 125px; Position: absolute; }

Click .SaveClose the dialog.CSS stylesheet propertiesSave the page to assign the new stylesheet.

You can now view the menu on the live site. The menu displays the first level horizontally, and the second level appears when hovering overmenu items with child pages.

1. 2. 3.

Setting navigation properties for pages

You can configure how individual pages behave and appear when displayed by menus or other navigation elements.

Open the application.PagesSelect the page in the content tree (in mode).EditSwitch to the tab.Properties -> Navigation

1. 2. 3.

4.

The navigation settings apply when Kentico navigation web parts and controls display the given page.

Basic properties

Property Description

Menu caption The name that navigation elements display for the page. If empty,the system uses the page name.

Show in navigation Indicates if navigation controls and web parts display the page.

Note: Navigation components display pages if all of the followingconditions are met:

The box is checked.Show in navigationThe page is .publishedThe type of the page matches the page types configured in thegiven navigation web part or control. By default, navigationcomponents only display pages.CMS.MenuItemIf you enable the property of the menuCheck permissionsweb part or control, users can only see pages that they areallowed to read.

Show in site map Indicates if the page is included n the website's .Google sitemap

Additionally, web parts and controls onlySite map CMSSiteMapdisplay pages that have this property enabled.

Menu actions

Property Description

Standard behavior Clicking the menu item opens the page as expected.

Inactive menu item Clicking the menu item doesn't cause any action — the item isdisabled.

You can also fill in the field, which allows you toRedirect to URLautomatically redirect users who access the page to a differentlocation (for example when users access the given page through anexternal link).

Javascript command The page runs the entered JavaScript command when users clickthe menu item.

Example: ; ;alert('hello') return false

Redirect to first child Redirects users to the page's first published child page (shown inparentheses).

Redirected pages are marked with the  icon in the content tree.

URL redirection Redirects users to the target location when they access the givenpage. Applies in all situations, not only when users click onnavigation elements.

Redirected pages are marked with the  icon in the content tree.

Example: or http://www.domain.com ~/products.aspx

Note: The navigation settings are not supported by standard listing components (for example if you display your navigation using a web part and transformations).Repeater

Adding macro expressions

You can use in the / and fields. Macros allow you tomacro expressions URL redirection Redirect to URL JavaScript commandinsert values of the given page, such as the alias path, node name. Use expressions in format .{% ColumnName %}

For example, entering:

~/products.aspx?show=brand&aliaspath={%NodeAliasPath%}

Into the field of the page redirects users to:URL redirection /MobileStore/Products/Android

Menu design

The menu item design properties are available in three alternatives:

Standard designMouse-over design - style used when users hover their mouse over the menu itemHighlighted design - style applied if the page represented by the menu item is selected by the user

These values override:

The settings of individual navigation web parts (controls) unless their ( ) property is Apply menu design ApplyMenuDesign disabled.The CSS styles defined in the page's .CSS stylesheet

Property Description

Menu item style Style definition of the menu item. Enter values like when writingCSS classes in stylesheets.

Sample value: color: orange; font-size: 140%

Menu item CSS class Assigns a CSS class from the page's CSS stylesheet.

Sample value: h1

Menu item left image Image displayed on the left of the menu item's caption.

Sample values:

http://www.domain.com/image.gif~/Images-(1)/icon.aspx

Menu item image Image displayed in menus instead of the item's caption. You canenter absolute URLs or relative paths.

Menu item right image Image displayed on the right of the menu item's caption.

Configuring additional properties when using listing web parts for navigation

When using the general web parts (Repeater, Basic repeater, Hierarchical viewer) to create a menu, you may want to use certain advancedproperties. The following is a list of the specific properties and instructions on how to replicate them:

Property Description  Where to replicate How to replicate 

Preserve the show in navigationflag

Makes sure only pages that havethe property setShow in navigation to true are displayed.

In the web part's WHERE condition

Configure the pShow in navigationroperty for each page in:

Pages -> Properties -> Navigation-> Show in navigation

DocumentMenuItemHideInNavigation = 0

Select the current page Adds a special CSS class to a pageif it's the current page.

In the web part's transformation {% if (IsCurrentDocument()) { return"item-current" } else { return "item" }#%}

Highlight the selected path Allows the menu to show the path tothe page you are currently viewing.

In the web part's transformation {% IsDocumentOnSelectedPath()%} 

Custom menu caption Allows you to use custom menucaptions for specific pages. Bydefault, the system uses the Pagename.

In the web part's transformation

Define the caption for each page in:

Pages -> Properties -> Navigation-> Menu caption 

{%HTMLEncode(String.IsNullOrEmpty(DocumentMenuCaption) ?DocumentName :DocumentMenuCaption) %}

 http://<domain>/products.aspx?show=brand&aliaspath=/MobileStore/Products/Android

Note: The system escapes all apostrophes in the source data to to avoid breaking JavaScript ( ' -> \' ).

Note: Some of the properties may not apply to all navigation web parts and controls.

1.

2.

Custom menu CSS class Allows you to use custom CSSclasses for specific pages.

In the web part's transformation

Define the custom CSS class foreach page in:

Pages -> Properties -> Navigation-> Menu item CSS class

{%HTMLEncode(DocumentMenuClass)#%}

Subitems check Allows you to return a customindicator if a page contains children.

In the web part's transformation {% if (NodeHasChildren) { return"has-children" } %}

Workflow: Use insteadNode.Count of if your pagesNodeHasChildrenuse workflow.

Item order the same as in Contenttree

Displays the pages in the menu inthe same order in which they appearin the Content tree.

In the web part's conditiORDER BY on

NodeLevel, NodeOrder, NodeName

Using CSS prefixes

CSS prefixes allow you to:

Specify different styles for any level of hierarchical menusPlace multiple menu web parts or controls of the same type on the same page and differentiate their CSS classes

You can work with CSS prefixes when using the web part (property name: ) or control (propertyCSS list menu CSS prefix CMSListMenuname: ).CSSPrefix

Example

The following example shows how to specify different styles for individual levels of a  control (or the CSS list menu web part):CMSListMenu

Fill in the property of the control or the web part with the following value: CSSPrefix MainMenu;SubMenu;OtherLevelsSemicolons separate individual levels of prefixes.Every prefix represents a lower level of the menu, starting from the main level (0).The last defined prefix also represents all remaining sub-levels.If you only wish to differentiate between CSS classes used by multiple menus on the same page, setting one prefix level issufficient.

Define the following CSS classes in the page's stylesheet:

/* Classes applied to the first level of the menu (level 0) */ .MainMenuCMSListMenuUL.MainMenuCMSListMenuLI.MainMenuCMSListMenuLink

/* Classes applied to the second level of the menu (level 1) */.SubMenuCMSListMenuUL.SubMenuCMSListMenuLI.SubMenuCMSListMenuLink

/* Classes applied to all underlying levels of the menu (level 2 and lowersub-levels) */ .OtherLevelsCMSListMenuUL.OtherLevelsCMSListMenuLI.OtherLevelsCMSListMenuLink

The web part/control applies the appropriate CSS classes when rendering the corresponding levels of the menu. 

Loading data using custom queries

Note: To use CSS prefixes with the , you need to enable the property.CSS list menu Render CSS classes

Set the names of the CSS classes according to the following format: <CSS prefix> + <Class used by the menucomponent>

1.

2.

3.

Queries allow you to load any type of data stored in the Kentico database, including:

PagesCustom table recordsGeneral system objects (classes) - both default (such as users, forums, newsletters, SKUs) and custom module classes

Using queries gives you full control over the data retrieval, but requires knowledge of SQL syntax and the Kentico database structure.

To display data loaded by a query on the website:

Add one of the query web parts or controls onto the page.

Query web parts Query controls

On pages, load and display query data usingportal enginededicated web parts:

Query data source (connected with a basic listing webpart)Grid with custom queryRepeater with custom queryDatalist with custom queryUniversal viewer with custom query

Use controls to display query data on orASPX page templatesinside custom components:

QueryDataGridQueryRepeaterQueryDataListQueryUniView

Select a predefined query through the property (or create a new query).Query name

Assign .transformations

The component loads data from the database using the selected query, and displays the results according to the specified transformation. 

Managing queries

You can create new queries or modify existing ones through the administration interface. The location depends on the type of data that youwish to load:

Page types - Page types -> Edit page type -> QueriesCustom tables - Custom tables -> Edit table -> QueriesData classes - Modules -> Edit module -> Classes -> Edit class -> Queries

The following properties are available when creating or editing queries:

Property Description

Query name Serves as the identifier of the query. Cannot contain spaces,periods or other special characters.

The full identifier of the query is in format: <parent object code>.<query name>name

Query type Determines whether the query is processed as a stored procedure.

Requires transaction If enabled, the system processes the query as a database.transaction

Query text Write the code of queries using standard syntax.Transact-SQL

Note: For queries that belong to module data classes (both the default Kentico modules and custom modules), you cannotuse the query selector. You need to manually type the full query name into the property in format: <class codename>.<query name>

Using properties to modify queries

Listing web parts and controls provide properties that set sections (clauses) of the query that loads the data. These properties allow users to

1. 2. 3. 4.

Overriding default system queries

The system uses automatically generated queries for basic operations. If necessary, you can override the defaults by creating newqueries with the following :Query name

select - loads a single recordselectall - loads all records from the table (with optional conditions)selectversions - loads recordspage versioninsert - adds a recordinsertidentity - adds a record with an explicitly set ID columnupdate - updates a single recordupdateall - updates multiple records in the table (based on conditions)delete - removes a single recorddeleteall - deletes records from the table (based on a where condition)searchtree - used by the to search the fields of individual page typesSQL search

Warning: Changing the default queries without considering all options may prevent the system from working correctly. Werecommend the following customization approach:

Create a new query with the required and click (leave the query text empty).Query name SaveClick above the editor to get the default code of the system query.Generate default queryExtend the query according to your custom requirements.Save the query.

1. 2. 3.

4.

adjust the data retrieval for individual instances of web parts or controls. To maintain this functionality for your custom queries, add thefollowing expressions into the query code:

SQL code expression Web part property Control property

##ORDERBY## ORDER BY expression OrderBy

##COLUMNS## Columns SelectedColumns

##TOPN## Select top N TopN

##WHERE## WHERE condition WhereCondition

For example, the following query selects page (menu item) pages:

SELECT ##TOPN## ##COLUMNS## FROM View_CONTENT_MenuItem_Joined WHERE (##WHERE##)ORDER BY ##ORDERBY##

When executing queries for web parts/controls, the system replaces the expressions with the values of the corresponding properties.

 

Displaying data from custom tablesThe system provides a set of web parts that allow you to display data from on the pages of your website.custom tables

Custom table web parts Description

Custom table data source A separate component that loads data stored in custom tables. Todisplay the data, you need to connect the data source to a Basic

, or web part.repeater Basic datalist Basic universal viewer

Custom table datagrid____________________________

Loads data from a custom table, and displays selected columns in atable. Contains a built-in custom table data source.

You can modify the design of the web part using standard ASP.NETskins.

Custom table repeaterCustom table datalistCustom table repeater with effect

Load data from a custom table, and display the records in a formatbased on . Contain a built-in custom table datatransformationssource.

See for more informationWriting transformations for custom tablesand examples.

Custom table form Allows users to manage the data of a custom table on the live site(add new data records or edit existing ones).

 

Displaying lists of items from custom tables

Open the application.PagesSelect the page where you want to display the data.Switch to the tab.Design

Dynamically inserting parameters into SQL clauses

You can insert values into SQL clause properties (such as the ) through . For example:Where condition macro expressions

{% CurrentAliasPath %} - alias path of the current page.{% CurrentDocumentCulture.CultureCode %} - the culture code of the language in which the current page is displayed.{% CurrentSiteID %} - SiteID value of the current site.

By default, the system protects the SQL properties of against SQL injection attacks, which may affect how macros areweb partsresolved. If the macro returns a string value that contains single quote characters ('), the system replaces them with two singlequotes (''). This may cause SQL syntax errors.

To disable single quote escaping for specific macro expressions, add the macro parameter and set its value tohandlesqlinjection :false

{% ... |(handlesqlinjection)false %}

Note: Disabling SQL protection may create security vulnerabilities if the macro resolves its value according to data that can bemodified by the website's users, such as in the case of QueryString macros.

4. 5. 6.

7.

1. 2. 3. 4. 5. 6. 7.

8.

Add one of the web parts that loads custom table data. The dialog opens.Web part propertiesChoose the that you want to display.Custom table  Assign a that defines the output format of individual custom table records (skip this step for the transformation Custom table

web part).datagrid

Click .OK

The web part loads the data from the custom table, and displays the information on the page. The appearance of the data depends on thetype of the web part and the assigned transformation.

Displaying details for selected custom table items 

In addition to creating lists of data, you can use the custom table web parts to display detailed views of individual custom table records. Detailviews are useful if the records in your table contain more information than you can display in a list. The web parts identify selected customtable items using a query string URL parameter.

The following steps describe how to extend a list of custom table data to allow users to select and view individual records:

Open the application.PagesSelect the page containing your custom table list.Configure (double-click) the web part that loads the custom table data.Enter a name for the selection URL parameter into the property (for example ).Selected item query string key name itemidType the of the (primary key) into the property.Field name custom table's identifier field Selected item database column nameSet the according to the data type of the table's identifier field ( , , or ).Selected item validation type number text GUIDEdit the custom table's and add a detail link into the content. The link's target is the same page, with the additionlist transformationof the selection query string parameter. Load the parameter's value from the table's identifier field. For example:

<a href='?itemid=<%# Eval("TableID") %>'>View details</a>

Create and assign a that defines the content of the detail view for custom table items.Selected item transformation

When a user views the custom table list and clicks the detail link for one of the items:

The page updates, with the selection parameter added to the URL's query string.The web part (data source) reads the parameter's value and loads the custom table record with a matching identifier.The web part (listing) displays the content of the for the given item (instead of the list).Selected item transformation

 

Writing transformationsTransformations are a crucial part of the process used to display pages and other data in Kentico. A transformation is a code template thatdetermines how listing web parts and controls render content. Data sources provide a collection of items containing raw data, andtransformations convert the data into appropriately formatted page output code (HTML).

The functionality of transformations is very similar to that of item templates used by standard ASP.NET list controls, such as the Repeater.The main difference is that the system stores transformations as virtual objects in the database, and you can easily reuse transformations fordifferent components.

Transformations are categorized under the objects whose data they display. You can manage transformations for:

Page types ( )Page types -> Edit a page type -> TransformationsContainer page types do not represent actual objects on the website, but only serve as containers for transformations. Usecontainer page types to store transformations that you want to share among multiple page types.

Custom tables ( )Custom tables -> Edit a table -> Transformations

To assign transformations to listing web parts or controls, use the available properties. Transformations are supported by allTransformation

: If you are using a separate , you need to set the transformation for the connected basicNote Custom table data sourcelisting web part.

Tip

You can use to convert the query string parameter in the selection URL into a more user friendly format. ForURL wildcardsexample:

<domain>/CustomTableList.aspx?itemID=10

to:

<domain>/CustomTableList/10.aspx

data listing web parts, as well as by that are designed to work with Kentico pages. The full name that identifies transformationslisting controlsis in format .<parent object code name>.<transformation name>

The Kentico sample sites include many transformations for all built-in page types.

Transformation types

You can use several different approaches when writing the code of transformations. The following transformation types are available:

Transformation type Description

ASCX______________________

The code of the transformation supports ASCX markup, i.e. thesame syntax that you would use to edit standard web forms or usercontrols. This includes:

Embedded controlsInline code (Kentico API, standard ASP.NET data bindingexpressions, special methods designed for use intransformations)

To access the fields of the transformed page or custom table, usedata binding expressions in format: <%# Eval("ColumnName") %>

Text/XML The system processes the code of transformations asText/XMLbasic HTML. ASCX markup (controls or inline code) does not work.You can use Kentico and methods to insertmacro expressionsdynamic values into the content.

To access the fields of the transformed page or custom table, useexpressions in format: {% ColumnName %}

Text transformations have the following advantages:

No compilation required. You can create and edit texttransformations even in environments where compilation ofvirtual objects is not possible, for example on webprecompiledsites.Text transformations do not allow users to execute inline code,so they cannot be used to compromise the security of thewebsite.

HTML Work the same way as transformations, but you edit theText/XMLcontent through the . The editor shows theWYSIWYG editorrendered output of the transformation's HTML code.

Using controls in transformationsYou can register and use user controls and inside transformations. See that done .servers controls Transformation examplesHowever, using web parts in transformations is not recommended for performance reasons.

Notes

For security reasons, only users who have the Edit code for the module mayASCX permission Design

edit the code of ASCX transformations. Thispermission can only be assigned by users with theGlobal administrator .privilege levelASCX transformations need to be compiled, so youcannot create or edit them on applicatioprecompiled ns.ASCX transformations do NOT support macro

.expressions

XSLT Use XSL elements to render the data. The code must be in validXML format.

When creating XSLT transformations for displaying pages, set the attribute of the element to .match <xsl:template> Table

<xsl:stylesheetxmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"><xsl:output method="xml"omit-xml-declaration="yes" />

<xsl:template match="Table">

...

</xsl:template>

</xsl:stylesheet>

jQuery Provide a way to define the jQuery templates used by:

The applicationChatIntegrated Strands recommendations

 

Transformation example

The following is the code of the ASCX transformation, which displays lists of products on theCorporateSite.Transformations.ProductListsample Corporate Site:

<%@ RegisterSrc="~/CMSModules/Ecommerce/Controls/ProductOptions/ShoppingCartItemSelector.ascx"TagName="CartItemSelector" TagPrefix="uc1" %><div class="ProductPreview"> <div class="ProductBox"> ##editbuttons## <div class="ProductImage"> <a href="<%# GetDocumentUrl() %>" style="display:block;"> <img src="<%# GetSKUImageUrl(200) %>" alt="<%# EvalText("SKUName", true) %>" /> </a> </div> <a href="<%# GetDocumentUrl() %>"> <span class="ProductTitle textContent"> <%# EvalText("SKUName", true) %> </span> </a> <div class="ProductFooter"> <div class="productPrice"><%# GetSKUFormattedPrice() %></div> <uc1:CartItemSelector id="cartItemSelector" runat="server" SKUID='<%#EvalInteger("SKUID") %>' SKUEnabled='<%# EvalBool("SKUEnabled") %>'AddToCartImageButton="~/App_Themes/CorporateSite/Images/btn_addToShoppingCart.png"/> </div> </div></div>

When assigned to a listing web part or control that has products (SKUs) in its data source, the output HTML code of individual productscontains values returned by the methods and data binding expressions, like in the following example (part of the code is omitted to save

ASCX transformation code

1. 2. 3.

space):

<div class="ProductPreview"> <div class="ProductBox"> <div class="ProductImage"> <a href="/8.0_4822.32562/Products/Smartphones/Apple-iPhone-4.aspx"style="display:block;"> <imgsrc="/8.0_4822.32562/getmetafile/9ee206cd-ff8b-4ae2-a218-a10f91801c55/iphone4_product.aspx?maxsidesize=200" alt="Apple iPhone 4 with inscription" /> </a> </div> <a href="/8.0_4822.32562/Products/Smartphones/Apple-iPhone-4.aspx"> <span class="ProductTitle textContent"> Apple iPhone 4 with inscription </span> </a> <div class="ProductFooter"> <div class="productPrice">$759.99</div> ... </div> </div>

The final output of the product on the website then looks like this:

Adding CSS styles to transformations

You can define the CSS classes used in transformation code either in the or individual pages, or add them directlystylesheets of the websiteto the transformation object (we only recommend this approach for testing purposes).

To add styles to transformations:

Edit the transformation on the tab. GeneralClick below the code editor. The field appears, where you can add any required CSS classes.Add CSS styles CSS stylesClick .Save

If the styles require any additional files (such as images), you can add them on the tab.Theme

For more information about page component CSS styles, see  .Adding CSS to page components

HTML output

1.

2. 3.

1. 2.

3. 4. 5. 6. 7.

1. 2. 3. 4. 5. 6.

 

Creating transformations for pagesThis page demonstrates how to write for a sample page type. See for instructions on how totransformations Computer Creating page typescreate page types.

Managing transformations

Open the application.Page types

Edit ( ) a page type.Open the tab.Transformations

This is the main management interface for the transformations of a given page type.

 

Example - Creating a transformation for a specific page type

This example uses a specific (Computers) page type. See Creating page types if you want to create a page type that uses the same fields.You can apply the information here to other page types as well.

 Creating default page type transformationPreparing the source pagesEditing transformations

Creating default page type transformation

Open the application. Page types Edit the page type. Computer

See how you can this example works with.create the page typeSwitch to the tabs. Transformations Click . New transformationEnter as transformation name.Preview Save.Create another transformation in the same way and name it .Default

Preparing the source pages

Before you can use the transformations, you first need to add some computer pages to the website.

Open the application, select the root of the website and click ( ).Pages NewSelect the page type.Page (menu item)Type in as the and select the template option.Computers Page name Create a blank pageClick to create the page.SaveSwitch to the tab of the new page and add a web part into .Design Datalist zoneASet the following property values for the web part:Datalist

Page types: ; you can choose the page type from a list by clicking the button.custom.computer SelectTransformation: ; to easily choose from a list of available transformations, click , choosecustom.computer.preview Select

Storing transformationsTypically, transformations are stored under the page type they are meant to display. However, there are situations in which youmay want to create more general transformations to share by different page types. You can a special create Container page typefor this purpose.

6.

7.

8.

9.

10.

11.

1. 2.

3.

the page type in the dialog and then click on the required transformation.ComputerSelected item transformation: custom.computer.default

Click to insert the web part.OKThe web part will display the data of computer pages on the page according to the specified transformations. For now, thepage is empty because there are no pages of the type on the website.custom.computer

Click ( ) with the page selected and choose the page type. New Computers ComputerThe page displays an editing form with the fields of the computer page type.

Enter the following values:

Computer name: Home PC DallasProcessor type: AMD FX 8-CoreRAM (MB): 16384HDD (GB): 4500Image: Upload an image from your local disk.

Click and enter the following values for the second computer page:Save and create another

Computer name: Office PC HoustonProcessor type: Intel Core i7RAM (MB): 8192HDD (GB): 4500Image: Upload another image.

Click .Save

Editing transformations

The way the pages display data is determined by its transformations. You can fully customize the data format by modifying theComputerscode of the transformations through the main interface in the application. The application also allows you to editPage types Pagestransformations, which is more convenient in many cases. As you will often want to make changes to transformations when you are actuallydisplaying the data. Let's see how you can do that now:

In the application, return to the mode and open the tab of the page.Pages Edit Design ComputersConfigure (double-click) the web part, scroll down to the property and click .Datalist Transformation Edit

The editing dialog of the opens. The web part uses this transformation transformationcustom.computer.Preview Datalistfor displaying data when listing computer entries.

Enter the following code:

3.

4. 5.

<div style="text-align:center;padding: 8px;margin: 4px;border: 1px solid#CCCCCC"> <h2> <a href="<%# GetDocumentUrl() %>"><%# Eval("ComputerName") %></a> </h2> <%# GetImage("ComputerImage", 120) %></div>

Click to apply the changes in the code.SaveClick to see how the transformation affects the page.Preview

This opens a split view that allows you to check the appearance of the web part directly while editing the transformationcode.

Because this is an type transformation, the code is similar to standard that you may already beASCX ItemTemplatesfamiliar with from using ASP.NET Repeater or controls. It combines HTML with ASP.NET commands and dataDataListbinding expressions. You may also use the built-in that simplify various tasks.transformation methods

Notice the code used to create the link to specific pages. It consists of a standard HTML link tag and inserts theappropriate URL and link text dynamically:

<a href="<%# GetDocumentUrl() %>"><%# Eval("ComputerName") %></a>

You can generate an image tag containing the file uploaded into the given page's field using the ComputerImage GetIma method. The sample code calls the method with a parameter that ensures automatic serverside resizing of the image'sge

longest side to 120 pixels:

<%# GetImage("ComputerImage", 120) %>

When writing ASCX transformations, you often need to specify the names of data fields as parameters of the dataEvalbinding expression or other methods, such as and in the example above. You can eitherComputerName ComputerImagetype the names manually, or press the key combination to access a list of available page fields andCTRL + SPACErelated objects.

By clicking an item in the list or by selecting it and pressing enter, you can insert the item to the current cursor position inthe code. The specific fields of the given page type are prioritized at the top.

5.

6.

7.

Close the dialog and click next to the transformation in the Edit transformation Edit custom.computer.default Selected item property.transformation

This transformation defines the output that the Datalist shows to users viewing the details of computer pages.

Enter the following code:

7.

8.

<h1><%# Eval("ComputerName") %></h1>

<table><tr><td>Processor:</td><td><%# Eval("ComputerProcessorType") %></td></tr>

<tr><td>RAM (MB):</td><td><%# Eval("ComputerMemorySize") %></td></tr>

<tr><td>HDD (GB): </td><td><%# Eval("ComputerStorageSize") %></td></tr>

<tr><td>Image:</td><td><%# GetImage("ComputerImage") %></td></tr></table>

Click .Save

The web part applies the when one of the displayed pages is the currently active page, e.g., when a visitorSelected item transformationclicks on the link in the titles of the computers on the page. To see how the detail view looks like for a specific computer page,Computers

enter into the path textbox on the preview bar and ( ) the page section./Computers/Home-PC-Dallas Refresh

If you close the configuration dialogs and view the page on the live website, you can see that both the list of computers and theComputersdetails pages of individual computer pages are rendered according to the new data format.

You have learned how to write transformations for displaying the content of structured pages. Other types of transformations may beASCXused in the same way, only with different transformation code syntax.

Note: If you wish to use transformations, you need to display the data through the or XSLT XSLT viewer Universal page viewerweb parts (or server control).CMSViewer

Transformations for multilingual websites

You may need to display different text in transformations based on the currently selected language. If you are using the built-in mul, you can achieve this by creating a separate transformation for each language, using the appropriate culture codetilingual support

as a suffix in the transformation name.

1. 2.

 

Using hierarchical transformationsThe system provides a special type of transformations that you can use to display pages (and other types of appropriately organized data) ina hierarchy. Hierarchical transformations can affect multiple page types and have different content for every level of the hierarchy (forexample levels of the page content tree).

Currently, hierarchical transformations are supported by the following web parts:

Hierarchical viewerUniversal viewerUniversal viewer with custom query

As well as the following Kentico controls:

UniViewBasicUniViewCMSUniViewQueryUniView

Hierarchical transformations are not directly defined by code. Instead, they serve as containers for a number of standard transformations,which are then applied to the appropriate parts of the source data. A hierarchical transformation can be composed of manysub-transformations that define the overall layout, and the format of the displayed items.

To manage hierarchical transformations, edit a in the application on the tab. We recommend storingpage type Page types Transformationstransformations that are not related to a specific Page type in 'container' page types.

 

Managing sub-transformations

When editing a hierarchical transformation in the application, you can , ( ) and ( ) sub-transformations.Page types Add Edit Delete

The purpose of each sub-transformation depends on its settings, which you can configure when adding the transformation or later via the Edi

( ) action.t

To add a sub-transformation:

Click .Add transformationConfigure the following properties:

Transformation type

Example:

English (default language) transformation code name: cms.news.detailFrench transformation code name: cms.news.detail_fr-fr

When a user switches the content culture to French, web parts and controls automatically load the French version of thetransformation.

The  ( ) action does not remove the given transformation from the system, only from the currently edited hierarchicalDeletetransformation.

2.

3.

Page typesLevelTransformation name

Click .Save

By adding transformations as components and configuring their fields, you can create complex hierarchical transformations suitable fordisplaying any kind of data.

Example

You can find an example of the web part using a hierarchical transformation on the Corporate Site sampleUniversal viewerwebsite in the section of the content tree.Examples -> Web Parts -> Listings and viewers -> Pages -> Universal viewer

1. 2. 3.

Selecting the transformation type

You can select a transformation type for each sub-transformation:

Transformation type Description

Item transformation Applied to all displayed items that are not covered by a specializedtransformation type (e.g. alternating items, first items etc.).

Alternating item transformation Applied to items that have an even position in the listing order.Every level in the hierarchy has its own separate alternation pattern.

First item transformation Applied to the first item on every level in the hierarchy. Only worksfor levels that contain more than one item.

Last item transformation Applied to the last item on every level. Only works for levels thatcontain more than one item.

Header transformation Rendered at the beginning of every level (before the first item onthe level). These transformations provide a convenient way tovisually separate or style individual levels.

Footer transformation Rendered at the end of every level (after the last item on the level).Can be used to close encapsulating elements from the .Header

Single item transformation Applied in cases where there is only one item on a level in thehierarchy.

Separator transformation Rendered between items on the same level. It is not placedbetween items on different hierarchy levels (i.e. between a parentitem and its child).

Current item transformation Applied to the currently selected item (i.e. the page that is beingviewed).

Limiting page types

You can choose which are affected by sub-transformations. Enter the code names of the required page types into the page types Page property. When adding multiple page types, separate them using semicolons, for example . Leaving the fieldtypes CMS.News;CMS.Article

empty applies the transformation to all page types.

Alternatively:

Click .SelectChoose page types by checking the boxes next to the items in the list.Click .Select

You must always specify a (or types) forPage typeCurrent item transformations.

1. 2. 3. 4.

If your hierarchical transformations contains multiple sub-transformations of different types, more than one transformation may beapplicable to a single item. In these cases, the hierarchical transformation applies only the transformation type with the highestpriority, according to the following order:

Current item (top priority)First/Last/Single itemAlternating itemItem

Transformations that are dedicated to specific page types have a greater priority than those set to include all types.The property has no effect for the , or transformation types.Page types Header Footer Separator

1. 2.

1.

Setting the hierarchy levels

The property determines which levels in the hierarchy use the sub-transformation. For example, enter to create a transformation forLevel 2items on the third level (the number of the first level in the hierarchy is ). The system always counts the levels from the start of the data0hierarchy that is being displayed. In the case of pages, level represents the first content tree level under the selected path, not the root of0the entire website.

If you leave checked, the transformation also affects all levels below the specified level. You can override theApply to sublevelstransformation by adding other transformations for specific sublevels (these transformations must have the same andTransformation typeaffect the same ). If your hierarchical transformation contains multiple overlapping transformations that , thePage types apply to sublevelslower levels have higher priority.

To apply a transformation on all levels in the hierarchy, set the to an empty value or 0, and leave checked.Level Apply to sublevels

Assigning the transformation

The value in the field specifies the actual transformation used for the purpose defined by the sub-transformation'sTransformation nameother properties. You can use an existing transformation or create a new one. Refer to to learn what options theWriting transformationssystem offers when creating or standard transformations.editing

If you wish to use an existing transformation, type the full name of the transformation.

Alternatively:

Click .SelectFind and click the required transformation in the dialog.Select transformation

Setting the location of sublevels in transformations

When editing the code of transformations that display hierarchical data, you can specify the position of sublevels by adding aitemplaceholder:

ASCX transformations:

<cms:SubLevelPlaceHolder runat="server" ID="plcSub" />

Text transformations:

{^SubLevelPlaceHolder^}

For items that have descendants in the hierarchy, the placeholder is replaced by the child level under the given item (including the headerand footer for the new level). If you do not add the sublevel placeholder, the system automatically renders child levels after the code of parentitems.

You can use the placeholder in any transformation applied to hierarchical data, not just within hierarchical transformations.

Displaying non-page data in a hierarchy

If you wish to use hierarchical transformations to display content, the source data must fulfill the following requirements:

The records must be connected through parentchild relationships.All records in the source data must contain a value determining their level in the hierarchy.The source data needs to be organized in a hierarchical format. You can ensure this by enabling the propertLoad hierarchical datay, which is available for all supported web parts and controls.

The most common example of suitable hierarchical data are pages in the Kentico content tree. You can use the Universal viewer with a web part (or control) to load and display other types of data from the database, as long as the data meets thecustom query QueryUniView

hierarchy requirements.

Open the application and select a page in the content tree.Pages

Note: The sublevel placeholder only works if the property of the viewer web part is set to .Hierarchical display mode Inner

Note

Paging is not possible when displaying hierarchical data, because the separation of data into pages breaks the hierarchy.If any parent records are missing from the source data (for example due to content filtering, WHERE conditions etc.), thedisconnected parts of the hierarchy are not displayed.

2. 3. 4. 5.

Switch to the tab and add the web part.Design Universal viewer with a custom queryAssign the required .Hierarchical transformationEnable the property.Load hierarchical dataSet the properties in the section:Hierarchical settings

Property Description

ID column Enter the name of the column in the source data that serves asa unique identifier for records. The web part uses the column toset up the parentchild relationships of the data.

ParentID Column Enter the name of the column in the source data that stores theunique identifiers of parent records. The system uses thecolumn to set up the parentchild relationships of the data. 

The value of the ParentID column cannot be for any itemsnullin the data source.

Level column Enter the name of the column that stores the hierarchy level ofrecords.

Selected item column Allows you to set up behavior for the displayed items thatreflects some type of selection made by users. Enter the nameof a column that serves as a unique identifier for records.

The web part identifies the selected item by comparing thevalue of the specified column with the value of the Selected

property.item value

Selected item value Insert a that dynamically retrieves themacro expressionselection value from the current context. The web part selectsthe record whose value in the matchesSelected item columnthe value returned by the macro.

5.

6.

1. 2. 3. 4. 5.

6.

1. 2. 3. 4. 5. 6.

Click .OK

The web part displays the source data using the selected hierarchical transformation.

 

Writing transformations for custom tablesWhen on your website, use to define the format of the output.displaying data from custom tables transformations

The scenario below shows examples of transformations applied to custom table data.

Setting up the custom table web part

Start by preparing a page that loads and renders data from the custom table:

Open the application.PagesSelect the page where you want to display the custom table data.Open the tab.DesignAdd the web part onto the page.Custom table repeaterSet the following properties for the web part:

Custom table: PeopleSelected item querystring key: itemidSelected item database column name: ItemIDSelected item validation type: Validation by numberHTML envelope -> Content before:

<table border="1" cellpadding="4" style="border-collapse:collapse">

HTML envelope -> Content after:

</table>

Click .OK

The web part does not display any data for now, because you have not assigned transformations. The properties add aHTML envelopetable element around the web part. The transformations created in the next sections will fill the content of the table.

 

Writing the list transformation

The purpose of list transformations is to display multiple items on the same page. The Custom table repeater applies the list transformation toevery record loaded from the specified custom table. In this example, the "list" is composed of table rows.

In the application, configure (double-click) the web part (on the tab).Pages Custom table repeater DesignClick next to the property. The dialog opens.New Transformation New transformationChange the to and select as the value.Class type Custom table People Custom tableType as the .ListItem Transformation nameChange the to .Transformation type Text / XMLCopy the following code into the transformation editor:

Note: To apply hierarchical transformations to completely external data or data sources customized through the API, you need touse the or controls.UniView BasicUniView

See: UniView - Displaying data using hierarchical transformations

Example prerequisites

To follow the example, you need to:

Create the custom table according to the instructions in People Creating custom tablesAdd data to the table as described in Managing custom table data

To learn more about setting up custom table web parts, see .Displaying data from custom tables

6.

7. 8.

1. 2. 3. 4. 5. 6.

7.

<tr> <td>{% ItemID %}</td> <td>{% FirstName %} {% LastName %}</td> <td><a href="?itemid={% ItemID %}">View information</a></td></tr> 

Click and close the dialog.SaveClick to confirm and close the dialog.OK Web part properties

The transformation defines a table row, which the repeater renders for every record in the custom table. If you view the page on thePeoplelive site, you can see the custom table's data.

Writing the detail transformation

To allow users to view more information about individual people from the custom table, you need to create a second transformation for thedetail view:

In the application, configure (double-click) the web part again.Pages Custom table repeaterClick next to the property. The dialog opens.New Selected item transformation New transformationChange the to and select as the value.Class type Custom table People Custom tableType as the .ItemDetails Transformation nameChange the to .Transformation type Text / XMLCopy the following code into the transformation editor:

<tr> <td><strong>First name</strong></td> <td style="width:250px;">{% FirstName %}</td></tr><tr> <td><strong>Last name</strong></td> <td>{% LastName %}</td></tr><tr> <td><strong>Date of birth</strong></td> <td>{% DateOfBirth.ToShortDateString() %}</td></tr><tr> <td><strong>ID</strong></td> <td>{% ItemID %}</td></tr><tr> <td><strong>Last modified</strong></td> <td>{% ItemModifiedWhen %}</td></tr><tr> <td><strong>Personal GUID</strong></td> <td>{% ItemGUID %}</td></tr><tr> <td colspan="2" style="text-align:center;"> <a href="{% CurrentDocument.RelativeURL %}">Back to list</a> </td></tr>

7. 8.

Save the transformation and close the dialog.Click to confirm and close the dialog.OK Web part properties

The Custom table repeater applies the detail transformations when a single record is selected via a URL parameter.

On the live site, you can now click the link next to individual people in the list. The table changes and displays the data ofView informationthe selected person.

 

Using transformations in macro expressionsYou can apply of the and type to pages and other objects retrieved via . Transformationstransformations Text/XML HTML macro expressionsin macro expressions allow you to display dynamically loaded data inside text and HTML content, where you cannot add listing web parts or

. Typical examples include:controls

Email templates that define the content of system emailsEmail campaign templates

You can also use transformations in all locations where macro resolving is supported.

To apply transformations to data inside macros, call the following macro method:

ApplyTransformation(String transformationName)

The parameter must match the full name of the transformation that you wish to use. An overload with three parameters is also possible,which allows you to place additional transformations before and after the displayed data:

ApplyTransformation(String transformationName, StringcontentBeforeTransformationName, String contentAfterTransformationName)

You can call the method for collections of objects that implement the interface, or for single instances of an object. When theIEnumerablesystem resolves such macro expressions, they return the objects of the given collection, formatted into the output code defined by thetransformation.

Tip - previewing transformations

When editing the code of transformations that are already assigned to a web part, you can . preview the output directly Click Previe in the dialog header. The editor opens a split view, where you can see how the content displayed by the web part changes whenw

you save the transformation code.

Security considerations

When you save a macro expression, the system automatically adds a security signature. The signature is used to check accesspermissions for the data collections loaded by the expression. Macro security depends on the user who entered and saved themacro expression, not on the user viewing the resolved result.

1.

2. 3. 4. 5. 6.

1.

2. 3.

4.

1. 2. 3.

4.

 

Examples - transformations in macro expressions

Preparing the environmentDisplaying the current userDisplaying pages from the content treeRetrieving and displaying site objects

Preparing the environment

Open the application and select the root of the website.Pages

Click ( ).NewSelect the page type.Page (menu item)Type as the and select the template option.Macros Page name Create a blank pageClick to create the page.SaveSwitch to the tab of the new page and an web part.Design add Editable text

You can now insert the macro expressions described below into the editable region on the page's tab. The system resolves the macrosPageon the live versions of the page.

Displaying the current user

First you need to create the transformation:

Open the application.Page types

Edit ( ) the page type and open the tab.Root TransformationsClick and enter the following data:New transformation

Transformation name: UsersInTextTransformation type: Text / XMLCode:

<div class="member"> <a href="{% GetMemberProfileUrl(UserName) %}"> {% GetUserAvatarImage(UserAvatarID, UserID, FullName, 52, 0, 0) %} </a><div class="memberInfo"><p> <h3> <a href="{% GetMemberProfileUrl(UserName) %}"> {% FullName %} </a> </h3></p></div></div>

Click .Save

Your transformation is now registered in the system. You can apply the transformation to user objects inside macro expressions:

Open the application.PagesEdit the previously created page on the tab.Macros PageEnter the following expression into the editable region.

{% CurrentUser.ApplyTransformation("CMS.Root.UsersInText") %}

Click .Save

As a result, the system does not resolve macro expressions if their author does not have permissions to access the requesteddata.

See also: Working with macro signatures

This scenario is intended primarily for demonstration purposes. The recommended way to display data on standard website pagesis using , which provide support for transformations.listing web parts or controls

1.

2. 3.

4.

1. 2. 3.

The macro expression above retrieves an object containing the data of the user currently viewing the page, which is then formatted accordingto the specified transformation. You can view the page on the live website to see how the macro is resolved.

Displaying pages from the content tree

First you need to create the transformation.

Open the application.Page types

Edit ( ) the page type and open the tab.Root TransformationsClick and enter the following data:New transformation

Transformation name: NewsInTextTransformation type: Text / XMLCode:

<div class="description"> <a class="header bold" href="{% GetDocumentUrl() %}"> {% NewsTitle %} </a> <p> {% NewsSummary %} <br /> </p></div>

Click .Save

Your transformation is now registered in the system. You can apply the transformation to collections of news pages inside macroexpressions:

Open the application.PagesEdit the previously created page on the tab.Macros PageEnter the following expression into the editable region.

{%Documents["/News"].Children.WithAllData.ApplyTransformation("CMS.Root.NewsInText") %}

In the expression above, the page under the path is selected from the collection. Through its prop/News Pages Childrenerty, the system then accesses a collection containing all child pages. Using the property ensures that theWithAllDataretrieved page objects include their coupled data, i.e. the specific fields defined for the given page type.

3.

4.

1.

2. 3.

4. 5. 6.

7. 8. 9.

     Click .Save

If you view the page on the live website, you can see how the macro is resolved.

Retrieving and displaying site objects

In this example, you first need to create three separate transformations.Text / XML

Open the application.Page types

Edit ( ) the page type and open the tab.Root TransformationsClick and enter the following data:New transformation

Transformation name: ProductTableHeaderTransformation type: Text / XMLCode:

<table border="2" cellpadding="3"> <tr> <td width="200"><b>Product name</b></td> <td width="100"><b>Price</b></td> </tr>

Click .SaveReload the page type's tab.TransformationsClick and enter data for the second transformation:New transformation

Transformation name: ProductTableRowTransformation type: Text / XMLCode:

<tr> <td>{% SKUName %}</td> <td>{% SKUPrice %}</td></tr>

Click .SaveReload the page type's tab again.TransformationsClick and enter data for the third transformation:New transformation

9.

10.

1. 2. 3.

4.

Transformation name: ProductTableFooterTransformation type: Text / XMLCode:

</table>

Click .Save

All three transformations are now registered in the system. You can apply the transformation to collections of SKU objects (products) insidemacro expressions:

Open the application.PagesEdit the previously created page on the tab.Macros PageEnter the following expression into the editable region.

{% SiteObjects.SKUs.Where("SKUDepartmentID =4").OrderBy("SKUPrice").ApplyTransformation ("CMS.Root.ProductTableRow","CMS.Root.ProductTableHeader", "CMS.Root.ProductTableFooter") %}

       Click .Save

The method is called with additional parameters to add the header and footer transformations before and after theApplyTransformationmain data items. This ensures that the transformations are combined to achieve the desired result:

 

Displaying context menus in transformationsWhen writing transformations for displaying or , you can enclose the transformation into a container control that provides aUsers Groupscontext menu triggered by right-clicking a user or group. You can see a live example of these context menus on the sample Community site:

Right-click one of the users listed in the section.MembersRight-click one of the groups listed in the section.Groups

The system retrieves product objects (SKUs) from the collection. The macro method is then used toSiteObjects Wherefilter the collection according to a standard SQL condition specified as the parameter. In this case, only products from theSmartphones department are loaded. The method sorts the objects according to the values in their fieOrderBy SKUPriceld.

You can apply the and methods to all types of collections, including pages.Where OrderBy

How is this achieved? If you view the transformation code in the or web parts (used for displaying users andUsers viewer Groups viewer groups), you can see that the transformation is enclosed inside a container control. 

Writing transformations for user context menus

To add the context menu to lists of users, enclose your transformation inside the control ( ucms:usermenucontainer edit the transformationsed by the component that displays the list of users):

<cms:usermenucontainer runat="server" ID="userMenuElem" MenuID="userContextMenu"Parameter='<%# Eval("UserID").ToString() %>' ContextMenuCssClass="UserContextMenu">

... transformation code ...

</cms:usermenucontainer>

Writing transformations for group context menus

To add the context menu to lists of groups, you need to enclose your transformation inside the control (cms:groupmenucontainer edit the used by the component that displays the list of groups):transformation

<cms:groupmenucontainer runat="server" ID="groupMenuElem" MenuID="groupContextMenu"Parameter='<%# Eval("GroupID").ToString() %>' ContextMenuCssClass="UserContextMenu">

... transformation code ...

</cms:groupmenucontainer>

Modifying the context menu design

The default controls used for context menus are stored in :<web project>\CMSAdminControls\ContextMenus

GroupContextMenu.ascxUserContextMenu.ascx

These two controls are used automatically for the Group or User context menus. If you want to modify the design of the context menus, editthe controls in Visual Studio.

You can also develop custom context menu controls. In this case, you need to add the parameter to the MenuControlPath cms:usermenuco or controls in the transformation and set its value to the path to your control:ntainer cms:groupmenucontainer

<cms:groupmenucontainer runat="server" ID="groupMenuElem" MenuID="groupContextMenu"Parameter='<%# Eval("GroupID").ToString() %>' ContextMenuCssClass="UserContextMenu"MenuControlPath="~\CMSAdminControls\ContextMenus\MyGroupContextMenu.ascx" >

... transformation code ...

</cms:groupmenucontainer>

 

Reference - Transformation methods

This reference provides information about the default methods specifically designed for use in :transformations

Data loadingBoolean operations

Note: You can only add controls into transformations of the type. The system does not render context menu controls in theASCXother transformation types.

URLs and page linksText manipulationImagesE-commerce

SKU priceSKU price formattingSKU propertiesURLsDiscounts

Membership and communityDate & timeSmart searchSyndication (RSS, Atom, XML)Microsoft SharePointPlaceholders for sublevels in hierarchical dataEditing buttons for pages displayed by listing web parts

 

  

Data loading

Method Parameters Description and examples

Eval string columnNamebool encode

Loads the value from the specified columnof the transformed object's data. Returns thevalue as an data type. Use only forobjectASCX transformations.

The optional boolean parameter specifieswhether the method HTML encodes theloaded value. When not specified, theencoding depends on the value of the CMS

web.config key (false byHTMLEncodeEvaldefault).

<%# Eval("NewsTitle") %><%# Eval("NewsTitle", true) %>

Eval<ReturnType> string columnName Loads the value from a column of thetransformed object's data, and returns it asan object of the specified type. Use only forASCX transformations.

<%# Eval<string>("NodeAliasPath") %>

EvalCDATA string columnName bool encapsulate

Loads the value from the specified columnof the transformed object's data andescapes all occurrences of the sequence]]>in the returned string.

Depending on the optional booleanparameter (true by default), the methodwraps the whole string in the <![CDATA["wr

enclosure.apped text"]]>

<%# EvalCDATA("NewsText") %><%# EvalCDATA("NewsText", true) %>

EvalJSString string columnName   Loads the value from the specified columnof the transformed object's data. Encodesthe returned text to be used in JavaScriptcode and encapsulates it into ' characters.

Notes

All transformation methods return values (unless otherwise specified).stringThe examples of methods below are formatted for transformations. For transformations, macro methodASCX Text / XMLequivalents with identical signatures are available for most transformation methods.

In addition to the listed method, transformations allow you to call any type of inline code, including ASP.NET systemASCXmethods, Kentico API or custom API.For transformations, you can also use general macro methods. See: Text / XML Reference - Macro methods

GetEditableValue string controlId____________________

Loads the content of an editable region onthe page. Specify the region using thecontrol ID (web part control ID).

<%# GetEditableValue("mainText") %>

GetNotEmpty object columnsOjb Returns the value of the first data columnthat is not empty or . The parameternullmust provide a list of column namesseparated by semicolons.

<%# GetNotEmpty("FullName;UserName")%>

GetColumnName string columnsbool allowEmptyColumn

Returns the value of the first column that ispresent in the data of the transformedobject. The parameter must provide a list ofcolumn names separated by semicolons.

By default, the method only returns columnsthat are not or empty. Set the optionalnullsecond parameter to to allow emptytruevalues.

Property Description and examples

DataItem Gets the currently transformed data item.

<%# DataItem %>

DataItemIndex Gets the data item index for the current transformation container.You have to use to get the index in theContainer.DataItemIndexcurrent binding context.

<%# DataItemIndex %>

DataItemCount Gets the total number of data items in the current transformationcontainer.

<%# DataItemCount %>

DataRowView Gets a of the transformed record's data. DataRowView

<%# DataRowView["UserName"] %>

DisplayIndex Gets the current position of the data item as displayed in a control.

<%# DisplayIndex %>

DocumentCustomData Gets the value of custom page data fields (culture specific). Use the["nodename"] notation to retrieve data stored in the specified nodeof the XML.

See also: Storing custom data for all page types

<%# DocumentCustomData["myproperty"] %>

EditableItems Gets the content of the specified editable region on the page.

<%# EditableItems["mainText"] %>

NodeCustomData Gets the value of custom page data fields (shared for all cultureversions). Use the ["nodename"] notation to retrieve data stored inthe specified node of the XML.

See also: Storing custom data for all page types

<%# NodeCustomData["myproperty"] %>

> Back to the list of transformation method categories

Boolean operations

Method Parameters Description and examples

If object valueobject trueResultobject falseResult

Returns a result according to the booleanvalue of the first parameter.

<%# If(Eval("IsSecuredNode"), "The pagerequires authentication", "The page ispublicly available") %>

IfCompare object valueobject comparableValueobject falseResultobject trueResult

Compares the values of the first and thesecond parameter.

If the parameters are different or areboth , the method returns the thirdnullparameter.If the parameters are equal, the fourthparameter is returned.

<%# IfCompare(1, 2, "The values aredifferent", "The values are equal") %>

IfEmpty object valueobject emptyResultobject nonEmptyResult____________________

Checks for emptiness of the value in the firstparameter.

If the first parameter is , the methodnullreturns the second parameter.If the first parameter is not , the thirdnullparameter is returned.

<%# IfEmpty(Eval("ProductPhoto"), "Noimage", GetImage("ProductPhoto")) %>

IfTrue object valueobject trueResult

Checks whether the first parameter containsa true boolean value.

If true, the method returns the secondparameter.If false, an empty string is returned.

IsFirst - Returns a value if the transformed datatrueitem is the first in the provided data.

<%# IsFirst() %>

IsLast - Returns a value if the transformed datatrueitem is the last in the provided data.

<%# IsLast() %>

IsCurrentDocument - Returns a value if the transformed pagetrueis equal to the page where thetransformation is being displayed.

<%# IsCurrentDocument() %>

IsDocumentOnSelectedPath - Returns a value if the transformed pagetrueis present on the of the pagealias pathwhere the transformation is being displayed(i.e. if the transformed page is an ancestorof the current page).

<%# IsDocumentOnSelectedPath() %>

> Back to the list of transformation method categories

URLs and page links

Method Parameters Description and examples

GetAbsoluteUrl string relativeUrlint siteIdobject siteNameObjstring domainName

Converts relative URLs to absolute URLs.You can specify the target domain name inthe absolute URL using either a site ID, sitecode name or explicitly.

If you leave all optional parameters empty,the method generates the absolute URLusing the domain of the current site.

<%# GetAbsoluteUrl("~/Home.aspx") %><%# GetAbsoluteUrl("~/Home.aspx",Eval<int>("NodeSiteID")) %>

GetAttachmentIcon object attachmentGuidColumn Returns the attachment file type iconaccording to the extension of the fileidentified by the given GUID column.

<%#GetAttachmentIcon("AttachmentGUID") %>

GetAttachmentUrl string attachmentFileNamestring nodeAliasPath

Returns the URL of the attachment filespecified by name in the first parameter,loaded from the page whose alias pathmatches the second parameter.

The method returns the same URL as the G method, but without loading theetFileUrl

whole page, which results in betterperformance.

<%#GetAttachmentUrl(Eval<string>("AttachmentName"), Eval<string>("NodeAliasPath")) %>

GetDocumentLink bool encodeName Returns a HTML link (<a> tag) that leads tothe transformed page. By default, themethod HTML encodes the page name inthe link title. Set the optional parameter tofalse to disable the encoding.

<%# GetDocumentLink() %><%# GetDocumentLink(false) %>

GetDocumentUrl object documentIdObj__________________________

Returns the URL of the specified page. Ifcalled without parameters, the methodreturns the URL of the transformed page.You can optionally specify the page using apage ID.

<%# GetDocumentUrl() %><%# GetDocumentUrl(Eval("DocumentID"))%>

GetDocumentUrl object nodeGuidColumnobject nodeAlias

Returns a of the specifiedpermanent URLpage (with the NodeGUID in the querystring).

<%# GetDocumentUrl(Eval("NodeGUID"),Eval("NodeAlias")) %>

GetFileIcon object fileExtension Returns the file type icon according to thespecified extension.

<%# GetFileIcon(Eval("FileExtension")) %>

GetFileUrl object attachmentFileNameobject attachmentDocumentId

Returns the URL of the attachment filespecified by name in the first parameter,loaded from the page whose ID matches thesecond parameter.

<%#GetFileUrl(Eval("AttachmentFileName"),Eval("AttachmentDocumentID")) %>

GetFileUrl object attachmentGuidstring fileName

Returns the URL of the attachment file,specified by an attachment GUID.

<%# GetFileUrl("ProductPhoto") %>

GetForumPostUrl object postIDPathobject fourmID

Returns the URL of the post specifiedforumby the path in the first parameter, from theforum specified by the identifier in thesecond parameter.

<%# GetForumPostUrl(Eval("PostIDPath"),Eval("ForumID")) %>

GetMediaFileUrl object fileGUIDobject fileName

Returns the URL of the specified .media fileThe media file is specified by the file GUIDin the first parameter and the file name inthe second parameter.

<%# GetMediaFileUrl(Eval("FileGUID"),Eval("FileName")) %>

GetMetaFileUrl object fileGUIDobject fileName

Returns the URL of the specified meta file.The file is specified by the file GUID in thefirst parameter and the file name in thesecond parameter.

GetNavigationUrl   Returns a resolved (absolute) URL of thepage that's currently being processed. The

The methodresulting URL is not encoded. reflects page navigation settings, such as U

., and RL redirection Redirect to first child

<%# GetNavigationUrl() %>

GetUrl object aliasPathobject urlPathobject siteName

Returns the URL of the page specified bythe in the first parameter or thealias pathURL path in the second parameter.

<%# GetUrl(Eval("NodeAliasPath"),Eval("DocumentUrlPath")) %><%# GetUrl(Eval("NodeAliasPath"),Eval("DocumentUrlPath"),Eval("SiteName")) %>

> Back to the list of transformation method categories

Text manipulation

Method Parameters Description and examples

EnsureMaximumLineLength object textObjint maxLength

Allows you to insert line breaks into longsequences of characters without whitespace(such as URLs). The method places the linebreak after the number of charactersspecified by the second parameter.

<%#EnsureMaximumLineLength("VeryLongStringWithoutAnyBlankSpaces", 21) %>

HTMLEncode string text Encodes HTML tags in the specified text.

<%# HTMLEncode("Sample text <br />") %>

LimitLength object textObjint maxLengthstring padStringbool wholeWords

Limits text to the length specified in thesecond parameter. The third parameter isthe trimming suffix, i.e. the string appendedto the end of shortened strings. The suffix isincluded in the maximum length. Forexample, if you use the "..." suffix and amaximum length of 100 characters, thereturned string contains the first 97characters of the original string, followed byan ellipsis.

Set the last parameter to true to avoidtrimming in the middle of words.

<%# LimitLength("Example of long text", 10, "...", true) %>

Localize object text Resolves all insidelocalization expressionsthe specified text.

RemoveDiscussionMacros object inputText Removes all BBCode tags from theprovided text.

<%#RemoveDiscussionMacros("[quote]Sampletext[/quote]") %>

RemoveDynamicControls object inputText Removes all controls from the specified text(such as inline ).widgets

<%#RemoveDynamicControls(Eval("NewsText")) %>

StripTags object inputText_______________

Completely removes HTML tags from thespecified text.

<%# StripTags("Sample text <br />") %>

> Back to the list of transformation method categories

Images

Method Parameters Description and examples

GetEditableImage string controlIdobject maxSideSizeobject widthobject heightobject alt

Returns an image tag that displays thecontent of an editable image control or webpart on the page. Specify the editable imageusing the control ID (web part control ID).

<%# GetEditableValue("mainImage") %>

GetEditableImageUrl string controlId Returns the URL of the image selectedinside the specified editable image controlor web part. Specify the editable imageusing the control ID (web part control ID).

<%# GetEditableImageUrl("mainImage") %>

GetImage object attachmentGuidColumnobject (int) maxSideSizeobject (int) widthobject (int) heightobject alt__________________________

Returns an image tag that displays theimage file whose GUID is stored in thespecified column of the transformed object'sdata.

<%# GetImage("NewsTeaser") %><%# GetImage("NewsTeaser", 200) %><%# GetImage("NewsTeaser", 200, 100)%><%# GetImage("NewsTeaser", 200, 200,100) %><%# GetImage("NewsTeaser", 200, 200,100, "image alternate text") %>

GetImageByUrl object imageUrlobject (int) maxSideSizeobject (int) widthobject (int) heightobject alt

Returns an image tag that displays theimage stored under the specified URL.

<%#GetImageByUrl("~/Images/Image1.aspx")%><%#GetImageByUrl("~/Images/Image1.aspx",100, 200) %><%#GetImageByUrl("~/Images/Image1.aspx",200) %><%#GetImageByUrl("~/Images/Image1.aspx",200, 100, 200, "image alternate text") %>

IfImage object attachmentGuidColumnobject isImageobject notImage

Checks whether the page attachmentspecified by the GUID in the first parameteris an image file. If the file is an image, themethod returns the value of the secondparameter, otherwise the value of the thirdparameter.

<%# IfImage("NewsTeaser", "The file is animage", "The file is not an image") %>

> Back to the list of transformation method categories

E-commerce

SKU price

Method Parameters Description and examples

GetSKUPrice bool discountsbool taxesstring column

OR

string column

Returns an SKU price based on the SKUdata and the data of the current shoppingcart

Set whether discountscatalog shouldbe calculated (bool discounts).Otherwise, the current configuration of

are applied (the e-commerce settings D settiisplay price including discounts

ng specifically).Set whether taxes should be calculated(bool taxes). Otherwise, the current con

e-commerce settings arefiguration of applied (the Display price including

setting specifically).taxesEnter the name of the column with theprices ( ). If you leave thisstring columnparameter empty, the default pricecolumn ( ) is used.SKUPrice

 

<%# (true, true,GetSKUPrice"ColumnName") %>

If you want to display the listprice of a product, you canuse the tranGetSKUListPricesformation and therefor avoidsetting up any columns.

GetSKUFormattedPrice bool discountsbool taxesstring column

OR

string column

Returns a SKU priceformatted based on theSKU data and the data of the current

.shopping cart

Set whether shouldcatalog discountsbe calculated ( ).bool discountsOtherwise, the current configuration of

are applied (the e-commerce settings D settiisplay price including discounts

ng specifically).Set whether taxes should be calculated(bool taxes). Otherwise, the current con

e-commerce settings arefiguration of applied (the Display price including

setting specifically).taxesEnter the name of the column with theprices ( ). If you leave thisstring columnparameter empty, the default pricecolumn (SKUPrice) is used.

 

<%# (true, true,GetSKUFormattedPrice"ColumnName") %>

GetSKUListPrice bool taxes Returns a SKU list price based on the SKUdata and the data of the current shoppingcart. The list price comes from the SKUReta

column.ilPrice

Set whether taxes should be calculated(bool taxes). Otherwise, the current con

e-commerce settings arefiguration ofapplied (the Display price including

setting specifically).taxes

<%# (true) %>GetSKUListPrice

GetSKUFormattedListPrice bool taxes Returns a SKU list price based onformatted the SKU data and the data of the currentshopping cart. The list price comes from the

column.SKURetailPrice

Set whether should be calculatedtaxes( ). Otherwise, the currentbool taxes  con

e-commerce settings arefiguration ofapplied (the Display price including

setting specifically).taxes

<%# (true) %>GetSKUFormattedListPrice

GetSKUOriginalPrice - Depending on what is the bigger number,returns the product's list price (from the SKURetailPrice column) or the product's price(from the column) before applyingSKUPricediscounts in the currency used in the currentshopping cart. If both prices equals theproduct's price (i.e. the list price equals theproduct's price and the does notproduct have any discounts), 0 is returned. Taxesare calculated in both of the prices.

<%# () %>GetSKUOriginalPrice

If you want to display the listprice of a product, you canuse the tranGetSKUListPricesformation and therefor avoidsetting up any columns.

GetSKUFormattedOriginalPrice -

_________________________

Depending on what is the bigger number,returns the product's list priceformatted(from the column) or SKURetailPrice the

product's price (from the SKUPrice column)before applying discounts in the currencyused in the current shopping cart. If bothprices equals the product's price (i.e. the listprice equals the product's price and the

, isproduct does not have any discounts) 0returned. Taxes are calculated in both of theprices.

<%# () %>GetSKUFormattedOriginalPrice

GetSKUPriceSaving bool discountsbool taxesstring column1string column2bool percentage

OR

bool discountsbool taxesbool percentage

OR

string column1string column2bool percentage

OR

bool percentage

Returns the amount of saved money(percentually or in the current )currencybased on the difference between theproduct's price and the product's list price. Ifthe product's price is bigger than the listprice, is returned.0

Set whether are calculated indiscountsthe product's price ( ).bool discountsOtherwise, the current configuration of e-commerce settings are applied (the Display price including discounts setti

.ng specifically)Set whether are calculated intaxesboth prices ( ).bool taxes Otherwise, thecurrent configuration of e-commercesettings are applied (the Display priceincluding taxes setting specifically).Enter the name of the column of theproduct's price ( ). Ifstring column1empty, the default product's pricecolumn ( ) is used.SKUPriceEnter the name of the column of the listprice ( ). If empty, thestring column2default product's list price column (SKU

) is used.RetailPriceSet whether the result should be inpercentage ( ).bool percentageOtherwise, the result is returned in the

currency.current

<%# GetSKUPriceSaving(true, false,"PriceColumnName", " PriceColumnNamListe", true) %>

GetSKUFormattedPriceSaving

__________________________

bool discountsbool taxesstring column1string column2

OR

bool discountsbool taxes

OR

string column1string column2

OR without any parameter

Returns the amount of savedformattedmoney based on the difference between theproduct's price and the product's list price. Ifthe product's price is bigger than the listprice, is returned.0

Set whether are calculated indiscountsthe product's price ( ).bool discountsOtherwise, the current configuration of

are applied (the e-commerce settings D settiisplay price including discounts

ng specifically).Set whether are calculated intaxesboth prices ( ). Otherwise, thebool taxescurrent e-commerceconfiguration ofsettings are applied (the Display price

setting specifically).including taxesEnter the name of the column of the pro

price ( ). If empty,duct's string column1the default product's price column (SKU

) is used.PriceEnter the name of the column of the listprice ( ). If empty, thestring column2default product's list price column (SKU

) is used.RetailPrice

<%# (true,GetSKUFormattedPriceSavingfalse, "PriceColumnName","ListPriceColumnName") %>

SKU price formatting

Method Parameters Description and examples

ApplyExchangeRate double price Returns the price in the current shoppingcart's ( 's) when applies site currency the exchange rates to the specified price in the

.current site's main currency (double price)

<%# (100) %>ApplyExchangeRate

FormatPrice

__________________________

double pricebool round

_________________________

Returns the specified price (formatted doubl) in the current shopping cart's ( 's)e price site

.currency

Set whether the price should berounded ( ) to the specifiedbool roundnumber of decimal field in the currentsite's currency setting. If not specified,the price is rounded.

<%# FormatPrice(100, true) %>

SKU properties

Method Parameters Description and examples

GetSKUIndicatorProperty string column Returns a value from the specified column () of the 's .string column product public status

If the product is evaluated as a new product,the public status is set by the Public status

. settingfor 'new products'

<%#GetSKUIndicatorProperty("ColumnName")%>

IsSKUAvailableForSale - Returns whether the given SKU can bebought by on the live site basedcustomerson the properties of the SKU.

<%# () %>IsSKUAvailableForSale

IsSKUInStock - Returns whether the given SKU is availableor not based on the opropertystock amount f the SKU.

<%# IsSKUInStock() %>

GetSKUNodeAlias

__________________________

-

_________________________

Returns the node alias of the given SKU. Ifthere are multiple nodes for the SKU, thefirst occurrence is returned. If there is notany node for the SKU, an empty string isreturned.

<%# GetSKUNodeAlias() %>

URLs

Method Parameters Description and examples

GetSKUUrl -

_________________________

Returns the user-friendly permanent URL ofthe SKU.

<%# GetSKUUrl() %>

GetProductUrl object (Guid) skuGuidobject (string) skuNameobject (string) siteName

Returns the user-friendly URL of the productspecified by the ( ) andGUID object skuGuidname ( ) of the product onobject skuNamethe specified ( ). If yousite object siteNamedo not specify the site name, the systemuses the current site.

<%# GetProductUrl(Eval("SkuGuid"),Eval("SkuName"), Eval("SiteName")) %>

GetProductUrlById object (int) skuIDobject (string) skuNameobject (string) siteNameObj

Returns the user-friendly URL of the productspecified by the ID ( ) and nameobject skuID(object skuName) of the product on thespecified site ( ). object siteName If you donot specify the site name, the system usesthe current site.

<%# GetProductUrlByID(Eval("SkuID"),Eval("SkuName"), Eval("SiteName")) %>

GetProductUrlForFeed object (Guid) skuGUIDobject (string) skuNameobject (string) siteName

Returns the URL of the specified product (o) with the specified name (bject skuGUID obj

) with the feed query stringect skuNameparameter in the URL for the feed on thespecified site ( ).object siteName If you donot specify the site name, the system usesthe current site.

<%#GetProductUrlForFeed(Eval("SkuGuid"),Eval("SkuName"), Eval("SiteName")) %>

GetSKUImageUrl

__________________________

_________________________ 

int widthint height

OR

int maxSideSize

Returns the URL of the product image.Specify the required width ( ) andobject widthheight ( ) of the image, or theobject heightmaximum side width ( of the image object

).maxsidesize

If the product image is not specified, theURL of the isdefault product imagereturned.

<%# GetSKUImageUrl(200, 300) %>

Discounts

Method Parameters Description and examples

GetMultiBuyDiscountNames

__________________________

-

_________________________

Returns the names of the applied Buy X Get for the current shopping cartY discounts

item surrounded with the HTML tag.li

<%# GetMultiBuyDiscountNames() %>

> Back to the list of transformation method categories

Membership and community

Method Parameters Description and examples

GetAge object dateOfBirthstring unknownAge

Returns age calculated according to thedate of birth given in the first parameter. Ifthe date of birth is not available, the methodreturns the string specified in the secondparameter.

<%#GetAge(Eval("UserDateOfBirth"),"Unknownage") %>

GetBadgeImage int badgeId Returns an image tag that displays thespecified user .badge

<%#GetBadgeImage(Eval<int>("UserBadgeID"))%>

GetBadgeName int badgeId Returns the display name of the specified b.adge

<%#GetBadgeName(Eval<int>("UserBadgeID"))%>

GetGender object genderObj_____________________

Returns the gender of users according tothe value specified in the parameter. Loadthe value from the user's gender field.

1 = Male2 = Femaleunspecified (0) = N/A

<%# GetGender(Eval("UserGender")) %>

GetGroupAvatarImage object avatarId int maxSideSizeint widthint heigthobject alt

Returns an image tag that displays the avat of a . The group is either identifiedar group

automatically using the field ofAvatarGuidthe transformed group, or you can optionallyspecify an identifier value using the firstparameter.

<%# GetGroupAvatarImage(200, "Alternatetext") %><%#GetGroupAvatarImage(Eval("GroupAvatarID"), 200, "Alternate text") %><%#GetGroupAvatarImage(Eval("GroupAvatarID"), 200, 150, 150, "Alternate text") %>

GetGroupProfileUrl object groupNameOjbstring siteName

Returns the URL of the specified progroup'sfile page.

<%#GetGroupProfileUrl(Eval("GroupName") %>

GetMemberProfileUrl object memberNameObjstring siteName

Returns the URL of the user profile page forthe specified group member.

<%#GetMemberProfileUrl(Eval("UserName"))%>

GetUserAvatarImage object avatarIdobject userIdint maxSideSizeint widthint heigthobject alt

Returns an image tag that displays the avat of a user. The user is either identifiedar

automatically using the field ofAvatarGuidthe transformed user, or you can specifyeither an avatar identifier or user identifier.

<%# GetUserAvatarImage(200, "Alternatetext") %><%# GetUserAvatarImage(Eval("UserID"),200, 150, 150, "Alternate text") %><%#GetUserAvatarImage(Eval("UserAvatarID"),Eval("UserID"), 200, "Alternate text") %><%#GetUserAvatarImage(Eval("UserAvatarID"),Eval("UserID"), 200, 150, 150, "Alt") %>

GetUserAvatarImageUrl object avatarIdobject userIdstring userEmailint maxSideSizeint widthint heigth

Returns the URL of the specified user's avat image. If the user does not have anar

avatar, the method returns the URL of thedefault avatar image.

<%#GetUserAvatarImageUrl(Eval("UserAvatarID"), Eval("UserID"), 200, 150, 150) %>

GetUserFullName int userId Returns the full name of the specified user.

<%# GetUserFullName(Eval<int>("UserID"))%>

GetUserProfileUrl object userNameObjstring siteName

Returns the URL of the user profile page forthe specified user.

<%# GetUserProfileURL(Eval("UserName"))%>

TrimSitePrefix object userName Removes the site prefix from user names (ifsite prefixes are enabled in Settings-> Security & Membership -> Use site

).prefix for user names

> Back to the list of transformation method categories

Date & time

Method Parameters Description and examples

FormatDate object dateTime_____________________

Displays the specified date without the timecomponent. The method automaticallyformats the date according to the currentculture.

<%# FormatDate(DateTime.Now) %>

FormatDateTime object dateTimestring format

Displays the date and time value accordingto a . The method formats theformat stringdate and time according to the currentculture.

<%# FormatDateTime(DateTime.Now,"MM/dd/yyyy HH:mm") %>

GetDate string dateTimeField Loads a date value from the specified fieldof the transformed object's data.

<%# GetDate("NewsReleaseDate") %>

GetDateTime string dateTimeFieldORobject dateTimeORDateTime dateTime

string format

Loads a date and time value from thespecified field of the transformed object'sdata. The value uses the set fortime zonethe server.

Optionally, you can format the date and timevalue according to a .format string

<%# GetDateTime("NewsReleaseDate") %>

GetCustomDateTime object dateTimestring timeZoneName

Converts a date and time value to thespecified .time zone

<%# GetCustomDateTime(DateTime.Now,"GreenwichMeanTime") %>

GetDateTimeString object dateTimebool showTooltip

Converts the specified date and time valueto the set for the server. Thetime zonesecond parameter determines whether thedisplayed date and time has a tooltip.

<%#GetDateTimeString("NewsReleaseDate",true) %>

GetSiteDateTime object dateTime Converts the specified date and time valueto the current site's .time zone

<%#GetSiteDateTime(Eval("NewsReleaseDate")) %>

GetUserDateTime object dateTime Converts the specified date and time valueto the set for the user viewing thetime zonepage.

<%#GetUserDateTime(Eval("NewsReleaseDate")) %>

> Back to the list of transformation method categories

Smart search

Method Parameters Description and examples

See for more information.Setting up search on your website

SearchResultUrl bool absolutebool addLangParameter

Returns the URL of the page containing thedetails of the search result.

The optional 'absolute' parameterindicates if the returned URL isabsolute. 

False by default.The optional 'addLangParameter'indicates if a culture specific queryshould be added to the URL. 

True by default. Note that clickinga link leading to a different culturechanges the visitor's site culture.

<%# SearchResultUrl(true, false) %>

Note: The SearchResultUrl method doesnot return valid URLs for search resultsproduced by general indexes, since theindexed objects are not pages and there isno default page to display the object details.You need to write and use a customtransformation method to generate thecorrect URL of a custom page displaying theappropriate information.

Combine with default culture 

When the Combine with default culture setting is enabled, visitors will see pages in thedefault culture if they aren't translated totheir current culture.

 If the addLangParameter is set tofalse, the site culture will NOT changeonce visitors click the link leading to thepage in the default culture. That is, theykeep on browsing the site in the culturethey made the search in.If the addLangParameter is set to true,the site culture will change once visitorsclick the link leading to the page in thedefault culture. That is, they keep onbrowsing the site in the default cultureafterwards.

SearchHighlight string textstring startTagstring endTag 

Wraps the text of the first parameter into thetags specified by the other two parameters.

<%#SearchHighlight(SearchResultUrl(),"<strong>","</strong>")%>

GetSearchImageUrl string noImageUrl int maxSideSize 

Returns the URL of the current searchresult's image.

The first parameter specifies the URL usedif no image is found – enter either the fullrelative path starting from the applicationroot (~/), or a partial path starting from the ~/

directorApp_Themes/<skin_folder>/Images/y. The second parameter specifies themaximum side size to which the methodresizes the image.

<%#GetSearchImageUrl("~/App_Themes/Default/Images/CMSModules/CMS_SmartSearch/no_image.gif", 90) %>

<%#GetSearchImageUrl("/CMSModules/CMS_SmartSearch/no_image.gif", 90) %>

GetSearchValue string columnName_____________________

Returns the value of the specified field forthe current search result. Allows you toaccess both the general fields of the givenobjects type (page, custom table etc.) andany other fields included in the searchindex.

<%# GetSearchValue("DocumentName")%>

GetSearchedContent string content Parses the searched content as XML ifrequired, and removes dynamic controlsand macro expressions.

> Back to the list of transformation method categories

Syndication (RSS, Atom, XML)

Method Parameters Description and examples

GetAtomDateTime object dateTime Returns the specified date and time value ina format suitable for Atom feeds (accordingto ).RFC 3339

<%#GetAtomDateTime(Eval("DocumentCreatedWhen")) %>

GetRSSDateTime object dateTime Returns the specified date and time value ina format suitable for RSS feeds (accordingto ).RFC 882

<%#GetRSSDateTime(Eval("DocumentCreatedWhen")) %>

GetBlogCommentUrlForFeed object documentIdObj__________________

Returns the URL of the comments added tothe specified by a page identifier.blog postIncludes the feed query string parameter inthe URL.

<%#GetBlogCommentUrlForFeed(Eval("DocumentID")) %>

GetDocumentUrlForFeed - Returns the URL of the transformeddocument with the feed query stringparameter in the URL. The method takesthe feed name from the propertFeed namey of the syndication web part used togenerate the feed.

Note: Since the method adds the querfeedy string parameter, please use a differentparameter name in the Feed querystring

property of the syndication web part.key

<%# GetDocumentUrlForFeed() %>

GetForumPostUrlForFeed object postIDPathobject forumId

 Returns the URL of the forum postspecified by the path in the first parameterand the forum identifier in the secondparameter. Includes the feed query stringparameter in the URL.

<%#GetForumPostUrlForFeed(Eval("PostIDPath"), Eval("PostForumID")) %>

See also: Setting up syndication feeds

GetMediaFileUrlForFeed object fileGUIDobject fileName

Returns the URL of the media file specifiedby the GUID in the first parameter and thefile name in the second parameter. Includesthe feed query string parameter in the URL.

<%#GetMediaFileUrlForFeed(Eval("FileGUID"),Eval("FileName")) %>

GetMessageBoardUrlForFeed object documentIdObj Returns the URL of the message boardspecified by the identifier of the pagecontaining the message board. Includes thefeed query string parameter in the URL.

<%#GetMessageBoardUrlForFeed("DocumentIdObj") %>

> Back to the list of transformation method categories

Microsoft SharePoint

Method Parameters Description and examples

GetSharePointFileUrl string fileRefColumnNameint cacheMinutesint cacheFileSizeint widthint heightint maxSideSize

Returns the URL of a file from a SharePointserver. The first parameter sets the name ofthe data column containing the name of thefile by default). Has optional(FileRefparameters for specifying file caching andimage dimensions.

<%#GetSharePointFileUrl("NameOfColumnContainingPathToFile", 5, 1024) %>

GetSharePointImageUrl string fileRefColumnNameint widthint heightint maxSideSize

Returns the URL of an image file from aSharePoint server. The first parameter setsthe name of the data column containing thename of the file by default). Has(FileRefoptional parameters for specifying imagedimensions.

<%#GetSharePointImageUrl("NameOfColumnContainingPathToFile", null, null, 300) %>

> Back to the list of transformation method categories

Placeholders for sublevels in hierarchical data

If you are writing transformations for items from a hierarchical data source (for example page data from the web part), youUniversal viewercan add a placeholder that sets the position of sublevels:

For transformations:ASCX

<cms:SubLevelPlaceHolder runat="server" ID="plcSub" />

For transformations:Text

{^SubLevelPlaceHolder^}

When displaying items that have descendants in the hierarchy, the placeholder is replaced by the child level under the given item. If you donot add the sublevel placeholder, the system automatically renders child levels after the code of parent items.

You can use the sublevel placeholder in , as well as standard transformations applied to hierarchical data.hierarchical transformations

See also: Displaying SharePoint data in Kentico

> Back to the list of transformation method categories

Editing buttons for pages displayed by listing web parts

You can configure listing web parts (such as the ) to display special buttons in editing mode (on the tab of the applicatiRepeater Page Pageson). The buttons allow users to edit or delete individual items displayed in the list.

To set the exact position of the editing buttons, add the following expression into the code of item transformations:ASCX

##editbuttons##

> Back to the list of transformation method categories 

Filtering and paging dataPaging and filtering are features that help users navigate through large lists of data.

Filters allow users to limit which data is displayed directly on the live site. The system provides several built-in filters for various types ofdata, and also allows developers to . Filters connect to data sources, and dynamically generate additional conditions thatcreate custom filtersthe system applies when loading data.

Pagers separate lists of data into multiple pages and provide navigation between the pages. To implement paging, connect a Universal to your listing components. You have full control over the appearance of the pager (the design is based on ). See thepager transformations

documentation of the for details.UniPager control

The diagram below illustrates how to link together data web parts with a pager and filter. You can place the web parts anywhere on the samepage without any change in functionality. The captions at the beginning and end of the lines between the web parts show the properties thatconnect the components. The linked properties must have identical values.

Note: The sublevel placeholder only works if the property of the viewer web part is set to .Hierarchical display mode Inner

Note: When adding filters or pagers to lists of data, we strongly recommend using a separate data source web part connected to B listing web part. Because of differences in the life cycle of individual components, filters and pagers may not work correctly inasic

all possible scenarios for web parts with built-in data sources.

1. 2. 3. 4. 5.

6. 7. 8.

9.

 

  

Example

The following example demonstrates how to provide filtering and paging functionality for a list of articles.

Creating the list of articles

Start by creating a page with components that generate a basic list of articles:

Open the application.PagesCreate a new page on your website.Open the tab.DesignAdd the web part onto the page.Pages data sourceSet the following properties for the :Pages data source

Path: /Articles/%Page types: DancingGoat.Article

Click .Save & CloseAdd the web part below the data source.Basic repeaterSet the following properties for the :Basic repeater

Data source name: PagesDataSource (the default ID of the Pages data source web part)Transformation name: DancingGoat.Article.ListSelected item transformation: DancingGoat.Article.Detail 

Click . Save & Close

The data source loads all pages with articles on the website, and the connected displays the data on the page.Basic repeater

Data loading when using paging

By default, and data sources when you connect a Universal pager. Instead of retrieving the full datapage query load data per-pagefor all pages, the data source loads and individual pages separately, which reduces the initial load time. You can disablecachesper-page loading through the property of data source web parts (in the category).Load pages individually System settings

Note: To use per-page loading for query and page attachment data sources, you need to fill in values into the ORDER BY and properties.expression Selected columns

Note: The example works with data from the sample site. You can, for example, replace the original webDancing Goat Repeaterpart for displaying articles on the page.Articles

1. 2. 3. 4. 5.

6.

Adding a filter

The system provides a default filter that allows users to limit which articles the page displays (based on various criteria). To integrate thefilter:

Add the web part above the Basic repeater.Page name filterSet the web part's property to .Web part control ID PageNameFilterClick .Save & CloseConfigure (double-click) the web part.Pages data sourceType the filter's name ( ) into the data source's property.PageNameFilter Filter name

6.

1. 2.

3.

Click .Save & Close

The filter is now connected to the web part. The data source loads a limited set of items according to the selected filterPages data sourceoptions.

You can try out the filter on the live site. For example, use the filter to display only articles containing the word .techniques

Setting up paging

Paging can be useful when displaying a large number of records. To add a pager to the list of articles:

Add the web part onto the page, below the .Universal pager Basic repeaterSet the following properties for the pager:

Target control name: BasicRepeater (the default ID of the Basic repeater web part)Page size: 3Paging mode: PostbackPager layout transformation: CMS.PagerTransformations.General-PagerLayout

Click .Save & Close

The Universal pager connects to the and separates the displayed data into multiple shorter pages.Basic repeater

You can try out the pager on the live site. The page now only includes up to 3 articles, and allows users to switch between pages.

1. 2. 3. 4. 5.

 

Displaying data - advanced scenarios

 

Creating wizards on websitesKentico allows you to create — pages that guide users through a sequence of steps. A common example of a wizard is the checkoutwizardsprocess of an on-line store. You can build wizards using the and a set of predefined .portal engine web parts

The wizard uses standard pages to define the steps. You have full control over the step content, and can leverage the features of Kenticopages for every step:

Multilingual step contentUnique step URLsTracking of for individual stepsweb analyticsOn-line marketing features (such as or )optimization testing content personalization

Defining page wizards

To set up a page wizard on your website:

Open the application and select your site.PagesCreate a new page.Switch to the tab.DesignAdd the web part.Page wizard managerAdd the web part.Page placeholder

The page serves as the "parent" of the page wizard and provides a master page for the content of steps. The ensuresPage wizard managerthe overall logic of the wizard. The represents the area where the wizard displays the content of individual steps.Page placeholder

You cannot use when creating a wizard or , use only the .ASPX templates Portal engine sections of ASPX templates Portal engine

1. 2. 3.

Tip: If the parent page of your wizard does not have any content of its own, you can redirect visitors to the first wizard step:

In the application, open the page's tab.Pages Properties -> NavigationSelect in the section.Redirect to first child Menu actionsClick .Save

1. 2. 3. 4.

 

Adding steps

To create the wizard steps, add child pages (or other types of pages) under the page containing the web part. BuildPage wizard managerthe content of steps just like any other .portal engine pages

You also need to configure for all child pages that you wish to use as steps:page nesting

In the application, select the page.PagesOpen the tab.Properties -> TemplateEnable nesting within the parent page (and any other required levels of the website).Click .Save

You can choose which child pages to use as steps by configuring the properties of the web part. Thepage filtering Page wizard managerwizard only loads steps from the of direct child pages.first level

By default, the step order matches the order of the child pages in the content tree. You can use the property of the OrderBy Page wizard web part to load the steps in a different order determined by an SQL clause.manager

Building step navigation

Navigation allows users to move between the steps of the page wizard. Add navigation elements using the following web parts:

Web part Description

Note

If you add, remove or reorder the steps of an existing wizard, you need to restart the application to ensure that the wizard behavescorrectly. Open the application and click .System Restart application

1.

Page wizard button_______________________

Displays a button or link that sends users to the previous/next stepin the wizard. Choose whether the button leads to the next orprevious step when configuring the web part's properties.

If you set the property of the Final step URL Page wizard web part, the next button also works on the last step inmanager

the wizard. When a user clicks the final next button, the wizardredirects to the specified URL.

Note: The step transitions only work on the live site and in previewmode.

Page wizard navigation Displays an overview of all steps in the wizard. The wizardnavigation highlights the current step and allows users to movebetween steps.

You can fully customize the format of the navigation by assigning tr through the web part's properties.ansformations

You can position the wizard navigation in two different ways:

Shared navigation for the entire wizard - place the web parts onto the wizard's parent page, around the represepage placeholdernting the step contentSeparate navigation for individual steps - add the web parts directly into the content of step pages

Restricting the step order

If you enable the property of the web part, the wizard forces users to progress through the stepsRestrict step order Page wizard managerin the defined order. The system tracks which steps individual users have passed through, and stores the information in the HTTP session.

Restricting the step order causes the following behavior:

Users can only move forward through the wizard's steps using the buttonNextThe web part renders unvisited steps as inactive items without linksPage wizard navigationIf a user attempts to access an unvisited step through the URL of the step page, the wizard opens the last visited step instead

If the property is filled for the web part, the wizard automatically clears the history of visited steps forFinal step URL Page wizard managerusers who click the button on the last step.Next

Setting up automatic step transitions

You can create wizards that automatically move users between steps under certain conditions:

1. 2. 3.

4.

5.

In the application, select the page representing the step where you want the transition to occur.PagesOpen the tab and add the web part (anywhere on the page).Design Page wizard step actionChoose the type of step transition in the property:Action type

Skip - continues to the next step according to the direction the user is moving in the wizardNext - always moves one step forwardPrevious - always moves one step back

Enter the that triggers the step transition into the property. The condition must return a true ormacro condition Action conditionfalse value.Click .OK

When a user arrives on the step containing the web part, the system evaluates the action condition. If true, the web part immediatelyperforms the selected step transition.

For example, if you have a step that requires users to log in or register, you can make the wizard skip the step for already authenticatedusers:

CurrentUser.IsAuthenticated

Validating step data

Validation rules are a set of conditions that must be fulfilled to successfully complete wizard steps. Validation typically occurs on steps thatrequire users to input data.

The wizard performs step validation:

when users move to the step by clicking the next Page wizard buttonduring automatic transitions done by the web part (if the property is enabled)skip Page wizard step action Validate step

The step validation requirements depend on the implementation of the web parts placed on the step. If the validation fails, the wizard cancelsthe step transition and the related web parts display a validation error message.

Page wizard macros

You can use within the context of the page wizard to load the data of steps.macro expressions

Getting steps:

DocumentWizard.FirstStepDocumentWizard.CurrentStepDocumentWizard.PreviousStepDocumentWizard.NextStepDocumentWizard.LastStep

DocumentWizard.Steps - accesses the collection of all steps in the wizardDocumentWizard.Steps.Count - returns the total number of steps in the wizardDocumentWizard.Steps[5] - gets the 6th step

Getting step data:

Step.StepIndex - gets the step's index in the page wizard step collection. The index of the first step is 0.Step.StepUrl - returns the relative URL of the step's page, including the virtual directory and extension. For example: /Checkout/Shipping.aspxStep.StepData["NodeName"] - gets the name of the step's page. You can use the property to get the values of any otherStepDatapage columns.

For example, you can add the following macro into the property of the web part that displays the next step button:Text Page wizard button

Action conditon

Note: Automatic step transitions only work on the live site and in preview mode.

Tip: If you need to implement custom validation rules for web parts, refer to .Connecting web parts with the page wizard

Note: The following expressions are macros, so you need to enclose them in  parentheses.{% ... %}

{%DocumentWizard.CurrentStep == DocumentWizard.LastStep ? "Finish" :DocumentWizard.NextStep.StepData["NodeName"]%}

The macro uses a to dynamically set the caption of the button:ternary operator Next

The button text is on the last step in the wizard (if the page wizard has a final step URL specified) FinishThe button displays the name of the next step page on all other steps

 

Setting up syndication feedsKentico allows you to create of your website's content. The functionality is provided by a set of . These web partssyndication feeds web partsgenerate feeds which conform to the , or general format.RSS Atom XML

We have prepared these examples of typical usage:

Creating a page RSS feed using the CMS RSS feed web part.Creating an object RSS feed using the RSS feed web part and a data source.Creating a dedicated page with an RSS feed using the RSS repeater web part and a data source.Displaying content of an external RSS feed on your website using the RSS data source and Basic repeater web parts.

You can find live usage examples of these web parts on the sample Corporate Site, under the node./Examples/Web-parts/Syndication/

For information about specific web part properties, click the help icon in the corner of the Web part properties dialog.

Creating RSS feeds manually

If you prefer to create RSS feed pages manually through the API, see Creating custom RSS feed pages manually. 

Syndication transformationsSyndication web parts render feeds according to . You need to set the property of each feed web part.transformations Transformation

Default transformations

You can generate the default RSS, Atom and XML transformations when editing transformations of a or a . Click nepage type custom table ...xt to the button and select the appropriate format. Generate default transformation

 

RSS transformations page type

Additional feed transformations are available in the page type. This is a container pageRSS transformations (CMS.RSSTransformations)type used to store RSS transformations for , such as blog comments, board messages, forum posts, media library files andKentico objectsproducts.

CDATA in feed transformations

If you need to include sections in your feeds, you can use the method. This method works in a similar manner as theCDATA EvalCDATAstandard method. The difference is that the retrieved string is wrapped in a CDATA section and all occurences of the characterEval ]]>sequence in the string are escaped.

Escaping is performed by replacing each occurrence of with and the whole text is then wrapped in a standard ]]> ]]]]><!CDATA[> <![CDATAenclosure.["wrapped text"]]>

The method has two overrides:

EvalCDATA("FieldName") - specify the name of the retrieved field as the parameter.EvalCDATA("FieldName", true) - has one extra boolean parameter, which determines if the wrapping is performed. If the secondparameter is , the value of the field is retrieved, escaping of the sequence is performed, but the whole retrieved text is notfalse ]]> wrapped in the standard enclosure.<![CDATA["wrapped text"]]>

The second override with the second parameter set to is particularly useful if you use the method within another CDATA section.falseBecause nesting of CDATA sections is not possible, you only want to have the retrieved string escaped, but not wrapped in the enclosure.The code example below is a transformation extract where the method is used exactly this way.

...

<description> <![CDATA[ <strong><%# EvalCDATA("CommentUserName",false) %></strong><br /><%#EvalCDATA("CommentText",false) %> ]]></description> ...

 

Usage example - CMS RSS feedThe web part can be used to create RSS feeds from pages in the content tree. It has a , whichCMS RSS feed built-in Pages data sourcemeans that the web part can work separately without any connected data source and can be used to create feeds from pages of any type.

The following example demonstrates how to use the web part to create a feed link on the page of the sample . The/Products Corporate sitesame procedure can be used on any other page and for pages of any other type. You just need to specify the required path, page type andtransformation in the web part properties.

1. 2. 3. 4. 5.

6.

 To create a RSS feed link on a page:

Open the Corporate site in the application.PagesSelect the page in the content tree./ProductsSwitch to the tab.DesignAdd the  web part to the web part zone.CMS RSS feed Left zoneSet the following web part properties:

Link text: Products RSS feedFeed name: MyProductsFeedFeed title: Corporate Site ProductsFeed description: This is a sample RSS feed of products on the Corporate Site.Path: /Products/%/%Transformation name: CMS.RSSTransformations.Products

Leave the default values for the rest of the properties and click .OK

If you now view the page on the live site, you can see the RSS icon and link.Products

If you click the link, your browser detects that you are accessing an RSS feed and displays the content. The URL of the feed is actually theURL of the page where the web part is placed with the query string parameter appended (this can be modified using?rss=MyProductsFeedthe and web part properties). You can use the same URL to access the feed directly both from a browser orFeed querystring key Feed namea dedicated RSS reader program. 

Usage example - RSS feed + Data sourceBy connecting the web part to a , you can create an RSS feed of the data provided by the data source. The RSS feed data source Atom

web part can be used exactly the same way, but the rendered feed is in the format. You can use this approach to create feedsfeed Atomfrom Kentico objects (forum posts, board comments, media files, ...).

The following example demonstrates how to create an RSS feed containing forum posts on the sample Corporate site. You can achieve thisusing the and web parts. The same procedure can be used for any other data. You only need to use aRSS feed Forum posts data sourceproperly configured data source and process the provided data using a suitable .transformation

 

  To create an RSS feed of forum posts:

Apart from this universal web part, you can use syndication web parts that are pre-configured for specific page types. See thelisting in .Syndication web parts and widgets

Note

The result of the following example can also be achievable using a single web part - the web part, whichForum posts RSS feedhas a built-in . Similarly, there are all-in-one web parts for other frequently used page types and objectsForum posts data source(see the list in ).Syndication web parts and widgets

1. 2. 3. 4. 5.

6. 7.

8.

Open the applications.PagesSelect the page in the content tree.Community -> ForumsSwitch to the tab.DesignAdd the web part to the .Forum posts data source Content zoneLeave the web part's properties at the default values and click .OK

This results in the data source providing all forum posts from all forum groups on the site.Add the web part to the page.RSS feedEnter the following properties for the web part:

Link text: Forum posts RSS feedFeed name: MyForumPostsFeedFeed title: Corporate Site Forum PostsFeed description: This is a sample feed of all forum posts on the Corporate Site.Data source name: ForumPostsDataSourceTransformation name: CMS.RSSTransformations.ForumPosts

Leave the defaults for the rest of the properties and click .OK

You can now see the two web parts at the bottom of the web part zone.

If you view the page on the live site, you can see the RSS icon and link.Community -> Forums

Click the icon or link. Your browser detects that you are accessing an RSS feed and display the content. The URL of the feed is actually theURL of the page where the web part is placed with the query string parameter appended (this can be modified?rss=MyForumPostsFeedusing the and web part properties). You can use the same URL to access the feed directly both from aFeed querystring key Feed namebrowser or a dedicated RSS reader program. 

Usage example - RSS repeater + Data sourceThe allows you to transform pages into RSS feeds. When a page containing the web part is accessed, the responseRSS repeater web parttype is changed to and the page renders the content of the feed. This is useful if you want your feed to have a dedicatedapplication/xmlURL, without the need for a querystring parameter. The and web parts can be used exactly the same way, butAtom repeater XML repeaterthe rendered feed is in the or format.Atom XML

The following example demonstrates how to create an RSS feed containing the data of forum posts on the sample Corporate site. Theexample uses a dedicated feed page containing the web part.RSS repeater

Note

1. 2.

3. 4. 5. 6. 7. 8. 9.

1. 2.

3.

1. 2. 3. 4.

5.

 

  Create a page containing the web part:Forum posts data source

Open the application.PagesSelect the page in the content tree.Community -> Forums

Click ( ) and choose the page type.New Page (menu item)Type as the and choose the option.RSS Page name Create a blank pageClick .SaveOpen the tab.DesignAdd the web part.Forum posts data sourceLeave all properties at the default values, which causes the data source to load all forum posts from all forum groups on the site.Click .OK

Add the second web part:

On the tab, add the web part onto the page.Design RSS repeaterSet the following properties:

Feed name: MyForumPostsFeedFeed title: Corporate Site Forum PostsFeed description: This is a sample feed of all forum posts on the Corporate Site.Data source name: ForumPostsDataSourceTransformation name: CMS.RSSTransformations.ForumPosts

Leave defaults for the rest of the properties and click .OK

The RSS feed is now ready. To allow visitors to access the feed, create a link using the web part:Feed link

In the application, select the page.Pages Community -> Forums Switch to the tab.DesignAdd the web part.Feed linkSet the following properties:

Link text: Forum posts RSS feedFeed URL: ~/Community/Forums/RSS.aspxFeed title: My Forum Posts Feed

Leave defaults for the rest of the properties and click .OK

The Feed link web part displays the RSS icon with a link leading to the specified URL.

If you view the page on the live site, you can see the RSS icon and link.Community -> Forums

The result of the following example can also be achieved using a single web part - the web part, whichForum posts RSS feedhas a built-in . Similarly, there are all-in-one web parts for other frequently used page types and objectsForum posts data source(see the list in ).Syndication web parts and widgets

1. 2.

3. 4. 5.

6. 7. 8.

9.

1. 2.

3.

If you click the link, your browser detects that you are accessing an RSS feed and displays the content. The URL of the feed matches theURL of the page containing the web part. You can use the same URL to access the feed from both browsers and dedicatedRSS repeaterRSS reader programs. 

Usage example - External RSS feedIn addition to creating RSS feeds for Kentico content, you can also use external RSS feeds (i.e. feeds published on other websites) as asource of data and display the data on your website.

The following example demonstrates how to use the and web parts to display content of an external feedRSS data source Basic repeateron your website. The example uses the main article feed from Kentico DevNet: http://devnet.kentico.com/rss/articles

  Add the web part onto your site:RSS data source

Open the application.PagesSelect the root of your website's content tree.

Click ( ) above the content tree and create a page of the .New Page (menu item) typeType into the field and choose .External RSS Page name Create a blank pageClick .Save

The system creates the page and selects it in the content tree.Switch to the tab.DesignAdd the web part onto the page.RSS data sourceEnter the following values into the dialog:Web part properties

Web part control ID: KenticoBlogsRSS (this ID will be used to connect the repeater that displays the data)RSS feed URL:  (this is the URL of the external RSS feed)http://devnet.kentico.com/rss/articles

Leave the rest of the properties at their default values and click .Save & Close

Add the second web part:

On the tab, add the web part onto the page.Design Basic repeaterConfigure the web part's properties as follows:

Data source name: KenticoBlogsRSSTransformation name: click and create a new transformation with the code below.New

<h2> <a href="<%# Eval("link")%>"> <%# Eval("title") %> </a></h2><p> <strong>Published</strong>: <%# Eval("pubdate") %></p><p> <%# Eval("description") %></p><br/>

Leave the rest of the web part properties at their default values and click .Save & Close

On the tab, you can see the web parts.Design

The transformation code transforms the , and elements of each record provided by thelink pubdate descriptionfeed. Content of the elements is retrieved using the method, with the element name specified as theEvalparameter.

If you switch to the live site and view the new page, you can see the content of the RSS feed.

 

Syndication web parts and widgetsSyndication are stored under the category in the web part catalog.web parts Syndication

From a functional point of view, there are two basic types of syndication web parts — repeaters and feeds:

Syndication feeds display a feed icon with an optional text link. When clicked, the link appends a query string parameter with thefeed ID to the URL and the page renders the feed.

Syndication repeaters change the page on which they are placed to a feed. If you place one of the syndication repeaters on a

1.

2.

page, the page response type changes to . The retrieved data transforms into the required feed format serves as theapplication/xmlcontent of the feed. This means that the page is no longer a standard HTML page — it becomes a syndication feed.

 The web parts can also be divided according to the type of the data:

Basic feed web parts

These are universal web parts which can create a feed of data provided by a connected data source. Without a data source, the web partsare not functional. The data provided by the data source can be of any type, it just needs to be handled properly by the used transformation.

XML repeaterRSS repeaterAtom repeaterRSS feedAtom feed

Page feed web parts

These web parts are based on the web part, but have a built-in data source for the in their names. This means thatRSS feed page typesyou don't need a connected data source — all you need is included in a single web part. The web parts provide "all-in-one" solutions forfrequently used page types.

CMS RSS Feed - you can use this for pages of any type, which makes it a universal web part for any page feedEvents RSS Feed

Object feed web parts

Object feeds have a built-in data source, letting you create feeds from by adding a single "all-in-one" web part.Kentico objects

Blog comments RSS feedCustom tables RSS feedMedia files RSS feedMessage board RSS feedProducts RSS feedForum posts RSS feed

Other syndication web parts

Custom feeds can be created using the following two web parts:

Query RSS feed - generates a feed based on a and .custom database query transformationWeb service RSS feed - transforms a dataset provided by a web service into an RSS feed.

The last web part does not create a feed, but links to an existing feed:

Feed link - displays the RSS icon with a link leading to a URL. Typically used for links to feeds created by syndication repeaters.

Syndication widgets

The default installation of Kentico contains a set of derived from the web parts listed above. The widgets provide the samewidgetsfunctionality, but only a limited set of properties can be configured. The following widgets are available:

Blog comments RSS feedEvents RSS FeedForum posts RSS feedMedia files RSS feedProducts RSS feed

Further information

For detailed information about the properties of web parts or widgets, click the help link in the corner of the dialoWeb part (widget) properties g. 

Displaying related pages using named relationshipsYou can add relationships between pages in your website's content tree. Page relationships allow you to:

Display related pages on pages using listing web parts or controlsWork with connections between pages in your custom logic (API)

Defining page relationship types

Before you can connect pages through relationships, you need to set up the relationship types (names) in the system. You can add anynumber of different relationship types.

Open the application.Relationship names

2. 3. 4. 5. 6.

1. 2. 3. 4. 5. 6. 7.

Click .New relationship nameType a for the relationship type.Display nameSet the to .Type PagesClick .SaveSwitch to the tab and add all sites where you wish to use the relationship.Sites

You can now create relationships of the given type between pages.

  

Creating relationships between pages

To connect two pages through a relationship:

Open the application.PagesSelect one of the pages in the content tree.Switch to the tab.Properties -> Related pages Click .Add related pagesChoose the (type).Relationship nameSelect the other related page on the right side of the relationship (type the alias path or click ).Select pageClick .Save

The two pages are now related. The relationships are not symmetric — each relationship has one of the pages on the left side and the otheron the right. You can add any number of relationships to pages.

Note that creating and removing relationships between pages is not a versioned operation. That is, changes to the relationships areimmediately reflected on the published version of the pages.

Displaying related pages using web parts

On pages, you can display related pages using listing web parts. Web parts that support relationships have the followingportal engineproperties available in the category:Relationships

Page relationship properties (Web parts) Description

Main page Allows you to configure the web part to display only related pages:

Display pages related to the current page - pages related tothe page that contains the web part.Display pages related to the page with NodeGUID - pagesrelated to the page with the specified Node GUID identifier.You can find the Node GUID of pages on the Properties ->

tab of the Pages application.General

Main page is on the left side Determines whether the specified page ( ) is on the left orMain pageright side of the relationship.

If checked, the web part displays pages on the right side of therelationship.If disabled, the web part displays pages on the left side of therelationship.

Relationship name The web part uses the selected page relationship type.

Example

The following example shows how to display news items related to a product using the Repeater web part. The example assumes you are

Note: The relationship properties do ensure that web parts load all pages belonging to the specified relationship — they onlynotfilter the source data. You still need to set the remaining data source properties to load the required pages (such as the ).Path

1. 2.

3. 4.

5.

using the sample Corporate site.

Open the application and select the sample Corporate site.PagesSelect the page and ( ) with the /Products/Laptops-and-Tables/Apple iPad2 add a relationship is related to /News/Apple-iPad2-In-

page.StockSwitch to page's tab and a web part to .Apple iPad2 Design add Repeater Main zoneConfigure the following properties for the Repeater:

Path: /% (displays related news items from the whole website)Page types: CMS.NewsTransformation: CMS.News.PreviewRelationships -> Main page: Display pages related to the current pageRelationships -> Main page is on the left side: yes (checked)Relationships -> Relationship name: is related toHTML Envelope -> Content before: <h3>Related news:</h3>

Save & Close.

The page now displays a preview of the news items related to the product.

Displaying pages using controls

Use controls to display related pages on or in the code of custom components. The following controls supportASPX page templatesdisplaying of related pages:

CMSCalendarCMSDataGridCMSDataListCMSRepeaterCMSUniViewCMSViewer

The following properties allow you to filter the pages loaded by the controls according to relationships:

Page relationship properties Description Sample value

1.

2. 3.

4. 5. 6. 7.

RelationshipWithNodeGUID______________________________

If set, the control only loads pages that are r to the page with the specified elated NodeG

. You can find the Node GUID of pagesUIDon the tab in theProperties -> GeneralPages application.

Enter "11111111-1111-1111-1111-1111111 to dynamically load pages related to11111"

the page.current

"36f8c4bc-f702-4736-8a25-a82295668794"

RelatedNodeIsOnTheLeftSide Determines whether the page specifiedthrough the prRelationshipWithNodeGUIDoperty is on the left or right side of therelationship.

If true, the control displays pages onthe right side of the relationship.If false, the control displays pages onthe left side of the relationship.

 

RelationshipName Specifies the type of the page relationship.Enter the code name of the relationship.

"isrelatedto"

Example

The following example shows how to display related news pages on pages that use ASPX page templates. The example assumes you areusing the sample Corporate site.

Create a new web form in your web project as an .ASPX page templateSelect the default file as the web form's master page.CMSTemplates/CorporateSite/root.master

In Visual Studio, drag the  control from the toolbox onto the page template's form.CMSRepeaterSet the following properties for the CMSRepeater control:

Path: /%ClassNames: CMS.NewsTransformationName: cms.news.previewRelationshipName: isrelatedtoRelationShipWithNodeGUID: 11111111-1111-1111-1111-111111111111

<cms:CMSRepeater ID="CMSRepeater1" runat="server" ClassNames="CMS.News"Path="/%" TransformationName="cms.news.preview" RelationshipName="isrelatedto"RelationshipWithNodeGUID="11111111-1111-1111-1111-111111111111" />

Save the web form.Register the web form as an ASPX page template in the application.Page templatesOpen the application and create a page based on the ASPX template.PagesAdd relationships ( ) between the new page and news pages on the website.is related to

The page displays a preview of the news items related to the page. 

Displaying image galleriesWe recommend creating image galleries in the application. You can then load the images in the media library using the Media library Media

web part and display them using a repeater.files data source

1.

2. 3.

4. 5. 6.

Creating an image gallery

Create a and upload . This doesn't have to be the first step, but having some images already in place can helpmedia library imagesyou when setting the gallery up.Place the web part on an existing page.Media files data source Configure the web part and select the media library that contains the images you want to display.

Place a repeater web part, for example, the on the page.Basic repeaterConfigure the web part and link the web part to the data source web part using the field.Data source nameIn the , configure the and properties if you want to wrap the image gallery inHTML Envelope section Content before Content afterspecific HTML.

6.

7.

8.

Modify how the images are displayed in the web part's . We recommend using the transformations MediaLibraryFunctions.GetMedia for retrieving URLs of files stored in media libraries.FileUrl transformation method

The following transformation creates a link to each of the images in the media library:

<div class="image"> <a href="<%# MediaLibraryFunctions.GetMediaFileUrl(Eval("FileGUID"),Eval("FileName")) %>"><img class="image-tile" src="<%#MediaLibraryFunctions.GetMediaFileUrl(Eval("FileGUID"), Eval("FileName"))%>"><a/></div>

Note: if you're using , use the method with the following parameters:secured media libraries MediaLibraryFunctions.GetMediaFileUrl

<%# MediaLibraryFunctions.GetMediaFileUrl(Eval("FileLibraryID"),Eval("FilePath"), Eval("FileGUID"), Eval("FileName"),GetDataControlValue<bool>("UseSecureLinks")) %>

You can then to match your website. For example:style the gallery

.image-gallery { min-height: 480px; width: 100%; padding: 10px 0px 10px 0px; }

.image { width: 25%; float: left; padding-right: 2px;}

.image-tile { width: 100%;}

1. 2. 3. 4.

5.

6.

   

Displaying mapsYou can display both static and dynamic maps on your pages using web parts and widgets. Maps can be useful for displaying your offices,stores, location of the products that you offer, such as real estate, and many other information.

You can make use of the following two map providers for displaying your maps:

Google Maps - use the  .Google maps API v3Bing Maps - use the  .Bing maps API

Certain Bing maps services require that you to have a Bing maps account. As a Bing map account holder, you can createkeys to use these services.

Each of these providers has its dedicated web parts and a widget.

Learn more about displaying particular maps:

 

Displaying static mapsStatic maps allow you to display a predefined place on a map. For example, an office building, a shop or a street. You only need to place the

or web part on the page. In the web part, you specify the address or coordinates (latitude, longitude)Static Google maps Static Bing mapsof the location.

Placing a static map on a page

In the application, navigate to the page on which you want to display the map.Pages Switch to the tab.DesignPlace the or the web part on the page. The dialog opens.Static Google maps Static Bing maps web part properties Fill in the or the and fields.Location or address Latitude Longitude

Using latitude and longitude allows the system to process the location faster. These properties can also be more accurate. Select the option if you want the server to process and cache the processed (translated to latitudeUse server processing and longitude) field. Location or address If you decide to do so, please check that your map service query limits (IP-based)are sufficient for your needs.

Specify the rest of the web part properties, especially in the and categories. Hover over a property to seeContent Map propertiesits description.Click .OK

Examples

You can see the web parts configured and working on the sample Corporate Site, under the Examples -> Web Parts -> Maps node of the content tree.

The  and are derived from their   web part counterparts. They provide the sameGoogle maps Bing maps widgets Static mapfunctionality as the web part, only with a limited set of properties.

1. 2.

 

Displaying dynamic mapsKentico offers two ways of displaying dynamic maps on a page:

- display geographical locations based on the properties of specified pages. You can display multiple locations atPage-related mapsthe same time.

- displays geographical location based on a data source web part. For example, a pages data source, query dataData source mapssource, xml data source web part or others. You can display multiple locations at the same time.

Either of these can use the Google maps or Bing maps service.

Page-related maps

Page-related maps allow you to display multiple predefined places on a map. The places that the map displays are loaded from pages thatyou specify. The usual example is a list of pages, each representing a different company office. By default, the page type can beCMS.Officeused for this purpose, but any page type with fields specifying a geographical location will do. The web part ( or Google maps web part Bing

) then loads the geographical coordinates off of these pages and displays them on the map.maps web part

The process consists of two steps:

Setting up the pages from which the map loads data.Placing a page-related map on a page.

Pages from which you can display data on a map

The pages from which you can display data on a map need to have fields that represent a geographical location. These pages need to haveeither of these:

Two fields representing and . latitude longitude —OR—

A field or multiple fields representing an address in a human readable form.

You can use the predefined page type to load data onto a map. You can also use the page type as a reference when creatingCMS.Office

1. 2. 3. 4. 5.

6.

7.

8.

9.

1. 2. 3.

1. 2. 3. 4. 5. 6.

your own page types. 

Placing a page-related map on a page

In the application, navigate to the page on which you want to display the map.Pages Switch to the tab.DesignPlace the or the web part on the page. The dialog opens.Google maps Bing maps web part properties Specify the to the pages from which you want the map to load data.PathSelect the that you want the map to load. For example, .Page types CMS.Office

Load a human-readable address onto the map

If you want the map to use a human-readable address, specify the that the use for location in the Field name Page types Locat property. For example, OfficeAddress1 in the page type loads the first address line. You can also specifyion field CMS.Office

multiple field names separated by semicolons, for example, , if the whole address is divided into more OfficeAddress1;OfficeCitythan one field.

You can select the option if you want the server to process and cache the processedUse server processing (translated to latitude and longitude) field. If you decide to do so, please check that your mapLocation or address service query limits (IP-based) are sufficient for your needs. 

—OR—Load coordinates onto the map

If you want the map to use coordinates, specify the that the use for longitude and latitude in the Field names Page types Longiand properties. For example, and in the page type.tude field Latitude field OfficeLatitude1 OfficeLongitude1 CMS.Office

Using latitude and longitude allows the system to process the location faster. These properties can also be more accurate.

Fill in either the or the and fields. These fields represent the map'sDefault location or address DefaultLatitude DefaultLongitude initial view location.Specify the rest of the web part properties, especially in the , , and categories. Hover overTransformation Content Map propertiesa property to see its description.Click .OK

The page now displays a map with the location entered into the pages that you specified.

Data source maps

Data source maps allow you to display multiple places on a map. The places that the map displays are loaded from a predefined data sourceweb part. The usual example is a Page data source web part, which the map uses to load data from a list of pages. Each of the pages canrepresent a different company office, for example. By default, the page type can be used for this purpose, but any page type withCMS.Officefields specifying a geographical location will do. The web part ( or ) then loads theBasic Google maps web part Basic Bing maps web partgeographical coordinates off of these pages and displays them on the map.

The process consists of the following:

Setting up the pages from which the map loads data.Placing a data source that defines which pages are loaded into the mapPlacing a data source map on a page.

Pages from which you can display data on a map

The pages from which you can display data on a map need to have fields that represent a geographical location. These pages need to haveeither of these:

Two fields representing and . latitude longitude—OR— A field or multiple fields representing an address in a human readable form.

You can use the predefined page type to load data from onto a map. You can also use the page type as a reference whenCMS.Officecreating your own page types.

Placing a page data source

In the application, navigate to the page on which you want to display the map.Pages Switch to the tab.DesignPlace the web part on the page. The dialog opens.Pages data source web part properties Specify the to the pages from which you want the map to load data.PathSelect the that you want the map to load. For example, .Page types CMS.OfficeClick .OK

You can now connect the data source to a map web part.

The described process uses the Page data source web part.

1. 2. 3. 4.

5.

6.

7.

8.

1. 2.

3.

4. 5. 6.

Placing a data source map on a page

In the application, navigate to the page on which you want to display the map.Pages Switch to the tab.Design Place the or the web part on the page. The dialog opens.Basic Google maps Basic Bing maps web part properties Enter the . Data source name

Load a human-readable address onto the map

If you want the map to use a human-readable address, specify the that the use for location in the Field name Page types Locat property. For example, OfficeAddress1 in the page type loads the first address line. You can also specifyion field CMS.Office

multiple field names separated by semicolons, for example, , if the whole address is divided into more OfficeAddress1;OfficeCitythan one field.

You can select the option if you want the server to process and cache the processedUse server processing (translated to latitude and longitude) field. If you decide to do so, please check that your mapLocation or address service query limits (IP-based) are sufficient for your needs. 

—OR—Load coordinates onto the map

If you want the map to use coordinates, specify the that the use for longitude and latitude in the Field names Page types Longiand properties. For example, and in the page type.tude field Latitude field OfficeLatitude1 OfficeLongitude1 CMS.Office

Using latitude and longitude allows the system to process the location faster. These properties can also be more accurate.

Fill in either the or the and fields. These fields represent the map'sDefault location or address DefaultLatitude DefaultLongitude initial view location.Specify the rest of the web part properties, especially in the , , and categories. Hover overTransformation Content Map propertiesa property to see its description.Click .OK

The page now displays a map with the location entered into the pages that you specified in the Page data source web part. 

Designing websites using CSSKentico websites use standard to define the appearance and design of pages and their components. The system organizes CSS codeCSSinto stylesheets.

There are two ways in which we recommend that you style your website:

Styling websites using the CSS stylesheets applicationUsing automation tools to write your CSS

Also on this page:

Using automation tools to style websitesAssigning stylesheets to sites and pagesDefault styling of Kentico components

Creating custom component styles for sitesUsing CSS blocks for easier navigation in CSS codeBrowser and languagespecific styles

Styling websites using the CSS stylesheets application

If you don't need any automation tools, like preprocessors and bundling tools, we recommend using the CSS stylesheets application to styleyour website. Styles managed in the CSS application are stored in the database instead of the file system.

Open the application.CSS Stylesheets Create a . We recommend the following naming convention, where is the of your site:New CSS stylesheet YourSite Code name

Display name: YourSite - Style

 Save. Open the application.Sites Edit the site in which you want to include the stylesheet.Select the stylesheet you just created in .Site CSS stylesheet

6.

7.

1.

2. 3. 4. 5.

 Save.

This is now the site's main CSS stylesheet. You may consider separating your CSS into multiple stylesheets for simpler management. Forexample, you may want to use a stylesheet for your website's navigation and stylesheet forSiteName - Navigation SiteName - Landing pagea specific landing page on your site. You would then in the main stylesheet that you just created. This iscombine all the specific stylesheetsdone using the macro. The main stylesheet can then contain only general styles, like the general styles for the {% CSS["Stylesheet"] #%} htm, , and elements that apply to the whole website.l body form

 

Using automation tools to style websites

If you want to make use preprocessors, code hinting or CSS bundling when creating your CSS, you need to store your CSS files on the filesystem.

This approach doesn't make use of the CSS stylesheets application.

Create a folder in For example Stylesheets <project folder>\CMS\<site name>. C:\inetpub\wwwroot\Kentico\CMS\CorporateSite\Styl.esheets

Set your automation tools to create CSS files in the folder.Open the application.Pages Select the master page and switch to the tab.Master pageInclude the stylesheets in the head section of the page. For example, for a Styles.css file, you would enter the following:

<link href="~/CMSPages/GetResource.ashx?stylesheetfile=/{% CurrentSiteName %}/Stylesheets/Styles.css" type="text/css"rel="stylesheet" />

On the actual live site, changes made to CSS stylesheets only take effect after you clear your browser cache and/or restart theapplication ( ).System -> Restart application

Tips

If you wish to use a dynamic stylesheet language, you need to .register a CSS preprocessor in the systemYou can download a from the Kentico Marketplace.LESS PreprocessorThe system provides a that allows you to check if the styles of individual pages are valid against CSSCSS validatorstandards.

5.

6.

1.

2. 3.

4.

1. 2. 3. 4.

5.

Save.

The stylesheets are now included in all the pages on the site.

Assigning stylesheets to sites and pages

Each website in the system has a default CSS stylesheet. To assign a stylesheet to a site:

Open the application.Sites

Edit ( ) the site.Select an option in the field. You can only choose stylesheets that are allowed for the given site (on the tSite CSS stylesheet Sitesab of the stylesheet editing interface).Click .Save

Individual pages either use the website's stylesheet, or you can assign a different stylesheet. By default, pages automatically inherit thestylesheet from their parent page in the content tree, so you can quickly set the stylesheet for entire website sections.

Open the application.PagesSelect the page in the content tree.Open the tab.Properties -> GeneralSelect the .CSS stylesheet

Uncheck the box to use a different stylesheet than the parent page.InheritYou can only choose stylesheets that are allowed for the given site (on the tab of the stylesheet editing interface).Sites

Click .Save

When displaying pages, the system automatically adds a request that loads the assigned stylesheet into the HTML code.

Default styling of Kentico components

Kentico projects contain the physical stylesheet by default, which provides basic styling for and other components on theSkin.css web partslive site.

A global file is located in the folder. Individual sites have their own dedicated Skin.css files, which import theSkin.css ~/App_Themes/Globalglobal Skin.css stylesheet. For example, the Corporate Site sample site has its Skin.css file in the folder. If you~/App_Themes/CorporateSiteedit the file, you can see that the stylesheet imports the global Skin.css file, and contains several additional styles for the Corporate Site.

The styles in use the class to have stronger (more specific) selectors.Skin.css .ContentBody

Tip: When assigning stylesheets to sites or pages, you can directly create new stylesheets (click ) or edit the code of theNewselected stylesheet (click ).Edit

Stylesheet URLs

You can access stylesheets using a URL in the following format:

~/CMSPages/GetCSS.aspx?stylesheetname=<stylesheet code name>

The system page retrieves unmodified, userfriendly stylesheet code even if isGetCSS.aspx minification of stylesheet resourcesenabled.

Creating custom component styles for sites

The default Skin.css styles may interfere with your site's custom stylesheets.

Use one of the following approaches to implement custom component styling for your website:

Do not include on your site, define all required styles as Kentico or .Skin.css CSS stylesheets CSS files on the file systemUse the directive or stronger selectors (with more classes) in your CSS to override the default styles!importantEdit the skin stylesheets directly

Note: If you edit the skin stylesheet, the changes affect all sites in your Kentico instance, and may be overwritten when you upgradeglobalthe site to a new version of Kentico.

Using CSS blocks for easier navigation in CSS code

You can use comments in format to improve navigation in the code of large CSS stylesheets. You can access blocks/* #BLOCKNAME# */within the stylesheet code through the bookmark list next to the editor. 

To create a hierarchy of sub-blocks, separate the names of individual block levels using forward slashes, for example: /*#BLOCKNAME/SUBBLOCK# */

/* #Menu# */

...

/* #Menu/TreeMenu# */

...

/* #Menu/MainMenu# */

...

Note: The stylesheet is linked by default on the pages of all Kentico sample sites except the and Skin.css Blank Site ASPX Blank.Site

LESS code base

Skin.css is generated from the LESS file. You can modify Skin.css directly, but you lose the advantages of theSkin.lessstructured, commented and more readable .less file.

The Skin.less file is located in and includes multiple skin sub-files in the folder.~/App_Themes/Global ~/App_Themes/Global/Skin

If you are uncertain how to work with LESS, you can find articles describing the process at Using the LESS CSS Preprocessor for.Smarter Style Sheets

Example

Browser and languagespecific styles

The system automatically assigns CSS classes to the element of pages according to the characteristics of the selected language<body>(the text direction and exact culture) and the browser used to display the page. For example:

<body class="LTR IE IE9 ENUS">

 Four types of classes are added:

Text direction - the class is assigned for lefttoright languages, and for righttoleft.LTR RTLBrowser type - added according to the browser in which the page is opened. The following classes are used:

Browser Class names

Internet Explorer IE

Firefox Gecko

Google Chrome Chrome, Safari

Safari Safari

Opera Opera

Browser version - the class name is the same as for the browser type, but with the number of the browser's major versionappended, for example , etc.IE9 Gecko26Culture - the name of the class is added based on the culture code of the page's content (without the hyphen), for example foENUSr pages using the culture.en-US

This feature allows you to style page elements differently according to the browsing environment of the current visitor. You can define stylesfor any combination of the classes mentioned above.

For example, you can add the following into a website's stylesheet:

_:-ms-fullscreen, :root .ie11up .MyFont { font-size: 20px; }

.Opera .MyFont { font-size: 18px; }

Now elements styled using the class have a different font size when viewed in Internet Explorer 11 or Opera (all versions) browsers.MyFont 

Combining stylesheets from multiple sourcesKentico allows you to combine the content of different stylesheets by entering macros into stylesheet text. When the system resolves themacros, they are replaced by the content of the specified stylesheet. For example, this can be useful when creating a pagespecific stylesheetas an extension of the main website stylesheet with additional CSS classes.

You can link stylesheets into the code of other stylesheets by inserting in the following format:macro expressions

{% CSS[“<stylesheet code name>“] %}, e.g. {% CSS[“CorporateSite“] %}{% CSS.Stylesheets[“<stylesheet code name>“] %}, e.g. {% CSS.Stylesheets[“CorporateSite“] %}

 If the code name of the stylesheet does not contain any dots, you can also use the following simplified notation:

{% CSS.<stylesheetname> %}, e.g. {% CSS.CorporateSite %}

Similarly, you can link the following way:component stylesheets

{% CSS.Containers[“<web part container code name>“] %}, e.g. {% CSS.Containers[“BlackBox“] %}{% CSS.Templates[“<page template code name >“] %}, e.g. {% CSS.Templates[“CorporateSite.HomePage“] %}{% CSS.WebParts[“<web part code name>“] %}, e.g. {% CSS.WebParts[“AbuseReport“] %}{% CSS.WebPartLayouts[“<web part layout full name>“] %}, e.g. {% CSS.WebPartLayouts[“AbuseReport.MyCustomLayout“] %}{% CSS.Transformations[“<transformation full name>“] %}, e.g. {% CSS.Transformations[“CMS.Article.Default“] %}

The simplified notation can also be used if the component name does not contain any dots (web part layouts and transformations alwayscontain dots in their full names, so their stylesheets can only be linked using the notation above):

{% CSS.Containers.<web part container code name> %}, e.g. {% CSS.Containers.BlackBox %}{% CSS.Templates.<page template code name > %}, e.g. {% CSS.Templates.MyTemplate %}{% CSS.WebParts.<web part code name> %}, e.g. {% CSS.WebParts.AbuseReport %}

Disabling resolving of CSS macros

Resolving of CSS macros is enabled by default, but can be disabled if needed via the setting in Resolve macros in CSS Settings -> (only available if you choose option in the selector).System -> Performance (global) Site

Using the @import directive

You can alternatively load the content of other stylesheets by adding the standard directive to the beginning of the stylesheet code,@importfor example:

@import url(~/CMSPages/GetResource.ashx?stylesheetname=corporatesite);

This may also be used to import external CSS stylesheets from static files in your web project, for example:

If you wish to disable the setting, you first need to remove all occurrences of macros from yourResolve macros in CSSstylesheets. Unresolved macro expressions are not valid CSS code and as a result, the given stylesheets will not be processedcorrectly by browsers.

1. 2. 3.

4. a. b. c. d.

e.

@importurl(~/CMSPages/GetResource.ashx?stylesheetfile=/Kentico/App_Themes/CorporateSite/Blue.css);

 

Using printer friendly CSS stylesThis page explains how to use printer friendly CSS styles on your website. These styles are used only if a page is sent to a printer.

Create a new stylesheet in the application.CSS stylesheetsName the stylesheet and set the to (for example). Printer styles Code name Printer_stylesWrite the printer friendly CSS styles, for example:

.zoneLeft, .zoneRight, .zoneTopInfo, .zoneTop, .horizontalmenu, .zoneBottom { display: none;}

.eventCalendarDetail .zoneLeft, .eventCalendarDetail zoneRight { display: block;}

.eventCalendarDetail zoneRight { float: left;}

.logonReg .zoneLeft, .logonReg .zoneRight { display: block;}

.logonReg .zoneRight { float: left;}

.zoneContent { float: left !important;}

Add a link to the printer CSS stylesheet into the tag of your master page:<head>Open the application.PagesSelect the root page of your website.Switch to the tab.Master pageAdd the link into the section. For example:head

<link href="CMSPages/GetResource.ashx?stylesheetname=Printer_styles"type="text/css" rel="stylesheet" media="print" />

Click .Save

The stylesheet applies to the media, i.e. when your sites pages are sent to a printer.print 

Creating printable versions of pagesKentico allows you to add a link button to your pages that creates a print version of the given page.

CSS

Tip: To hide elements that you do not want in the print version, add the style to the appropriate classes.display:none;

1. 2. 3. 4. 5.

6. 7.

a.

Creating a Print button

The following example shows how to create a print button for the news section on the sample Corporate Site.

Open the application.PagesSelect the page in the content tree.NewsSwitch to the tab.DesignAdd the web part into the .Static text Main zoneConfigure the web part properties:

Web part control ID: PrintLinkShow for page types: CMS.NewsText:

<div class="PrintLink"> <br /> <ahref="~/SpecialPages/E-Shop/Print.aspx?printpath={%NodeAliasPath%}&classname={%ClassName%}" target="_blank" > <img class="PrintImage"src="~/App_Themes/CorporateSite/Images/Print.gif" alt="Print" /> Print </a></div>

Save & Close.Create a print for the News page type:transformation

7.

a.

b. c. d. e.

f.

1. 2. 3. 4. 5. 6. 7.

8. 9.

Open the application.Page types

Edit ( ) the page type.NewsSwitch to the tab.TransformationClick .New TransformationType as the and copy the following content into the code editor.Print Transformation name

<h1><%# Eval("NewsTitle") %></h1><%# IfEmpty(Eval("NewsTeaser"), "", GetImage("NewsTeaser")) %><div class="gray"><%# GetDateTime("NewsReleaseDate", "d") %></div><p><%# Eval("NewsSummary") %></p><p><%# Eval("NewsText") %></p>

Click .Save

You can now open the live version of the Corporate site and select a news article in the section. The page contains the button,News Printwhich opens and displays the print version of the given article (using the Corporate site's default Print page and the created transformation).

  

Creating the Print page on your site

The page used in the previous example is already included as part of the sample Corporate Site. On your own website, you need toPrintcreate the Print page yourself:

Open your site in the application.PagesAdd a new page (outside of the site's standard navigation).Page (menu item)Name the page and use the option when selecting the page template. Print Create a blank pageDisable in -> .page nesting Properties TemplateReturn to the tab.DesignAdd the web part to render the Print transformation.RepeaterSet the following properties for the Repeater web part:

Path: {? printpath|(default)/% ?}Page types: {? classname|(default)cms.root ?}Transformation: {? classname|(default)cms.root ?}.print

Click .OKAdd the path to your print page into the print links that you use on your website.

 

Creating skins using ASP.NET themesWhen creating styles for your websites, you can leverage the built-in support for . You can use themes to set styles for webASP.NET themesparts or controls that do not have their own CSS class name, such as the Datagrid or Calendar.

The values are that dynamically load data from the URL query string parameters in the printmacro expressionslink ( and ). The macros also provide default values that the web part uses if no values areprintpath classnamesupplied in the URL (for example if you navigate directly to the page without a print button link).Print

Themes must be defined in a folder located under the directory. The name of this folder needs to be the same as the codeApp_Themesname of the used CSS stylesheet. For example, if you use the stylesheet on your site, your themes must be stored in the Green App_Theme

sub-folder.s\Green

Skins for your controls need to be added to the file under this folder. For example, the following is a skin for the Default.skin CMSCalendarcontrol / web part:Calendar

<cms:CMSCalendar Runat="server"> <NextPrevStyle ForeColor="Red"></NextPrevStyle> <WeekendDayStyle BackColor="#E0E0E0"></WeekendDayStyle></cms:CMSCalendar>

 

Website design files

It is recommended to store all image files, flash movies and other resources that are part of the website design template under the themefolder of the stylesheet that uses them. This ensures that the files are exported together with the stylesheet if you deploy it to another server.

You can manage the content of a stylesheet's theme folder directly from the administration interface in the application. EditCSS stylesheets

( ) the given stylesheet and switch to the tab.Theme

Only file formats commonly used by CSS stylesheets are displayed here. This includes files with the following extensions: , , , .css .skin .gif .p, , ng .bmp .jpg

Text files (.css or .skin) can be modified using an editor with syntax highlighting support and images are opened in the builtin .image editor

Themes folders for component styles

CSS files and images may also be stored separately for the CSS styles assigned to the page components described in the Adding CSS to topic. The theme folders of these components are located under the directory. Furtherpage components App_Themes\Components

subfolders depend on the type of the component:

WebParts\<web part code name>WebParts\<web part code name>\Layouts\<layout code name>Containers\<container code name>Transformations\<class name>\<transformation name>Layouts\<layout code name>PageTemplates\<template code name>

Just like for stylesheets, it is recommended to store all required files in the appropriate theme folder for each component. The systemautomatically exports and imports the files in the theme folders along with the objects representing the given component.

You can manage the content of the theme folders directly in the administration interface on the tab, which is available when editingThemeany type of component. 

Adding CSS to page components

In addition to the main stylesheets that can be assigned to , you can set CSS styles directly for various types ofsites or individual pages

Not recommended

Component CSS is not a recommended approach for styling your website. Only use this approach for special scenarios, wherestyling your website wouldn't make sense. Keep in my mind that extensive website stylingin a stylesheet applied to the whole sitevia individual page components can prove very difficult to maintain. 

components that make up the content of pages:

Web parts - CSS styles can be added to a web part by editing it in the application on the tab. The systemWeb parts CSSautomatically links the styles on pages containing the given web part.

 Web part layouts - to define styles for a specific , open the application, select the web part in the treeWeb part layout Web parts

and open the tab. Edit ( ) the layout and click below the layout code editor.Layouts Add CSS styles

The field appears, where you can add any required CSS classes. The system links the styles on all pages that contain aCSS stylesweb part using the specific layout.

Web part containers - to manage the styles of , open the application, edit the givenWeb part containers Web part containerscontainer and click . The system links the styles on pages where the container is used.Add CSS styles

Transformations - when editing the of a page type or custom table, you can define CSS styles by clicking Transformation Add CSS below the transformation code editor. The system links the styles on pages where the given transformation is used to displaystyles

data (e.g. through a viewer web part).

Shared (predefined) page layouts - CSS styles can be added to in the application, where the Page layouts Page layouts Add button is available when editing a specific layout. Once the shared layout is assigned to a , the systemCSS styles Page template

links the specified styles on all pages that use the given template.

Page layouts of specific page templates - in many cases, page templates use a custom page layout that is unique for the giventemplate. To add CSS styles to such templates, open the application, select the template, switch to the tab,Page templates Layoutand click below the code of the custom layout.Add CSS styles

Custom device layouts of specific page templates - page templates support the creation of custom page layouts for specific. To add CSS styles to device layouts, edit the template in the application, open the tdevice profiles Page templates Device layouts

ab, edit the device layout and click below the code of the custom layout.Add CSS styles

When a page is displayed in a user's browser, the system loads the assigned stylesheet and then requests any styles defined for thecomponents used on the given page. The final stylesheet available for the page is a combination of the main stylesheet and all componentstyles. If any of the components contain an alternative definition for a CSS class that already exists in the main stylesheet, then thecomponent style has a greater priority and overrides the original class.

By defining styles directly for components, you can reduce the size of your site (or page) stylesheets and organize them into moremanageable sections. It also means that pages need to load less total CSS data, since each page only has to request styles for thosecomponents that are actually used on it.

Additionally, the styles of components are automatically exported and imported along with the corresponding objects, which makes it easierto deploy them to websites that use a different stylesheet. The disadvantage of this approach is that at least one additional resource request

must be added to pages containing styled components to ensure that all required CSS code is loaded.

Configuring component CSS

The system provides global settings that affect the behavior of component CSS on all sites. You can configure the settings via the aSettingspplication in the category (only available if you choose the option in the selector).System -> Performance (global) Site

The setting indicates if pages containing components automatically request the corresponding styles. TheAllow CSS from componentssetting is enabled by default. If you disable the setting, you either need to define all styles directly in the main stylesheet, or link the styles ofthe required components into the stylesheet via CSS macros. Use the following macro expressions to link component styles into otherstylesheets:

{% CSS.WebParts["<web part code name>"] %}{% CSS.WebPartLayouts["<web part code name>.<layout code name>"] %}{% CSS.Containers["<container code name>"] %}{% CSS.Transformations["<full transformation name>"] %} - the transformation name must include the class name of the parentpage type or custom table, for example: CMS.News.Preview{% CSS.Layouts["<page layout code name>"] %}{% CSS.Templates["<page template code name>"] %}

The system dynamically resolves the macros into the CSS code defined for the specified component. The settingResolve macros in CSSmust be enabled if you wish to link styles using macros.

If the setting is enabled, pages bundle the loading of CSS styles of all contained components into a singleCombine CSS from componentsrequest. Otherwise, different types of components each generate a separate request. The styles of multiple components of the same type(e.g. several web parts) are always retrieved by one request. Combining CSS requests may improve the load time of individual pages and isrecommended in most cases. 

Previewing design changesThe administration interface provides a convenient way to edit the code of web design components side-by-side with a view of the results onthe actual website. This allows you to quickly check how changes affect pages without having to leave the editing interface or switch betweenbrowser tabs.

This preview functionality is available for all objects in Kentico that influence the design or appearance of the site's pages, including:

TransformationsCSS stylesheetsPage layoutsWeb part containersWeb part layouts

To access the preview mode, click in the header above the code editor.Preview

The preview interface is divided into two parts:

An editing area where you can modify the code or other fields of the given objectA section displaying a live site view of a selected page

You can select the following options on the preview toolbar:

Close preview - returns to the standard editing form without a preview section.Horizontal layout - splits the area horizontally. The top section contains the editing area (i.e. the code), and the preview of the pageis displayed in the bottom half.Vertical layout - splits the area vertically, with the editing area on the left and the page preview on the right.

This allows you to choose the layout that best fits the dimensions of the previewed page and the edited code.

Style priority

Component styles do not automatically take priority when linked through macros. The styles that are processed last (i.e. thosewhich are "lower" in the code) are applied to the page. If you want your components to override the definitions of existing CSSclasses, place the linking macros below all other code in the stylesheet.

1.

2.

By default, the code editor automatically expands to completely cover the first section. You can access the other fields on the form by

minimizing the editor via the ( ) button on the toolbar below the code. Saving the editing form automaticallyToggle fit-to-window moderefreshes the page preview.

 

  

Selecting the preview page

You need to view an appropriate page to see the effects of the changes made in the code. For example, when editing a transformation,select a page containing a web part that uses the given transformation to display data.

To configure the page in the preview section:

Select a page via the path selector on the toolbar. You have two options:

Click to choose a page from the content tree.Select

Specify a page by manually entering its alias path into the textbox. You need to click ( ) to reload the page inRefreshthe preview section.

On , switch between culture versions of the selected page using the language selector on the toolbar.multilingual websites

Note

The section displaying the page works like the mode of the application, which means that the specified page doesPreview Pagesnot actually need to be published on the live site. You can also preview pages that are scheduled to be published in the future orare currently in an unapproved step.Workflow

When editing a design component in the application, the preview section automatically loads the currently selectedPagespage.

2.

3.

1. 2. 3. 4. 5.

1.

2. 3. 4. 5.

If the page is configured to display different content for specific , choose the preferred profile for the preview. device profilesWhen previewing content for a specific device profile, you can switch between and orientation.Landscape Portrait

 

Developing websites for mobile devicesKentico offers mobile development features that allow you to create pages that are .easily viewable on various types of mobile devicesBy grouping devices with similar properties into and creating page layouts specifically designed for the device profiles, youdevice profilescan provide visitors with websites that bring an optimal browsing experience and require a minimum amount of scrolling and zooming. 

Configuring mobile development

Enabling device profiles

Device profiles allow you to customize the layout and content of pages according to the devices that visitors use to view pages. To start usingdevice profiles, enable the feature in the settings:

Open the application.SettingsNavigate to the category.Content -> Content management(Optional) Select a site where you want to enable device profiles.In the section, select the checkbox.Mobile development Enable device profilesClick .Save

With device profiles enabled, the system evaluates whether the device that is requesting a page belongs to one of the device profiles definedin the application.Device profiles 

Setting up device detection

By default, Kentico only detects a limited set of mobile devices. The basic detection uses XML data stored in the ~/App_Data/CMSModules/D file, which contains information about specific devices.eviceProfile/devices.xml

Each device has a set of properties describing its capabilities and a list of user agents used for identification. For example:

<Device name="Nokia_710" displayname="Nokia - 710" width="480" height="800"mobile="true"> <UserAgent> Mozilla/5.0 (compatible; MSIE 9.0; Windows Phone OS 7.5; Trident/5.0;IEMobile/9.0; NOKIA; Lumia 710) </UserAgent> <UserAgent> Mozilla/5.0 (compatible; MSIE 9.0; Windows Phone OS 7.5; Trident/5.0;IEMobile/9.0; NOKIA; 710) </UserAgent></Device>

You can manually expand the data by adding devices and their user agents. The system reloads the data when the application starts, so youneed to restart the application for changes to take effect (open the application, click ).System Restart application

When creating device profiles, you can assign the devices from the XML file using the device selector.

Using 51degrees.mobi device data

The 51degrees.mobi mobile device detection software integrated into Kentico allows you to extend the detection data to include all devicesthat are available on the market. The data also provides access to all device properties (listed in ).Device macros

To use the data, you need to obtain a license from 51degrees.mobi and register it within Kentico:

Buy a license for Premium Data at 51degrees.mobi at . http://51degrees.mobi/You will receive either a license key that enables you to download device data automatically, or a data file that you need tomanually upload into the system.

Open the application.SettingsSelect the category.Integration -> 51Degrees.mobiEnter your 51degrees.mobi license key into the text box and click , or select a data file from your disk and click .Activate UploadClick .Save

The system now has access to the 51degrees.mobi mobile device data set. You can select devices directly from the device selector whencreating device profiles and you can access additional device properties within the .CurrentDevice macro object

1. 2.

3.

1. 2. 3. 4.

5.

6.

Disabling the 51Degrees.mobi device detection

The 51Degrees.mobi device detection is enabled by default. If you plan on not using the the device detection software at all, you canconsider completely disabling it. This also frees up some of the server's memory resources.

Open your project's web.config file.In the section of the file, add the following key:<appSettings>

<add key="CMSEnable51D" value="false" /> 

Save the web.config file.

The 51Degrees.mobi device detection software is now disabled. 

Creating device profilesDevice profiles allow you to customize the layout and content of pages according to the parameters of the devices that visitors use to viewthe pages. Before you start using device profiles, you need to in the settings.enable mobile development

To create a new device profile:

Open the application.Device profilesClick .New profileType the of the device profile.Display name(Optional) Set the and .Preview width Preview height

Fill in the parameters that define which devices belong to the profile. You can combine the parameters as needed.

Property Description

Devices Select devices directly from a list.

User agents Allows you to identify devices based on . The profileuser agentsincludes devices that contain the entered text in their useragent string. You can add multiple entries, each on a new line.

Macro___________

Use the macro rule designer to specify the condition thatdevices must meet to fit the device profile, or type in any macrocondition.

You can use the object to retrieve data of theCurrentDevicecurrent device. See  and docDevice macros Macro expressionsumentation for more details.

Click .Save

Once you create a device profile, it appears in the device selector in the application.Pages

The preview dimensions of the device profile determine the following:

The maximum size of images if is enabled.automatic image resizing for devicesThe size of the displaying area when in the Pages application.previewing pages

Device profile order

The system evaluates the device profiles from top to bottom according to the list order in the application. DevicesDevice profilesare assigned to the first matching profile.

To change the order, drag device profiles to a different position using the ( ) area or expand the menu ( )Move Other actions ...and click / .Move up Move down

1. 2. 3. 4.

1.

2. 3. 4.

You can then select a device profile using the selector and start , which will be used on individual pagescreating page layouts for devicesinstead of the default layouts if the current device fits the profile. Or you can that will replace shared layouts when the currentMap layoutsdevice fits the profile. 

Resizing images for devicesYou can configure the system to automatically resize images to match the dimensions of :device profiles

Open the application.SettingsSelect the category. Content -> Content managementEnable the setting. Resize images according to device profileClick .Save

When a user views the website on a device that matches a , images automatically their maximum side size to the largercertain profile reduceof the dimensions set for the given profile.

To change the dimensions of device profiles:

Open the application.Device profiles

Edit ( ) a profile.Set the and properties (the values are in pixels).Preview width Preview heightClick .Save

Disabling the resizing for individual images

If you wish to disable device profile resizing for an image, add the query string parameter to the image source URL.resizemode=1

For example:

<imgsrc="~/getattachment/Community/Blogs/LargeImage.png.aspx?width=800&resizemode=1">

 

Creating page layouts for devicesVarious devices have different capabilities and screen resolutions, which makes it difficult to build a single page layout suitable for alldevices. Individual page templates allow you to .define alternative page layouts for specific device profiles

Pages based on these templates automatically use the appropriate layout according to the device profile detected for each visitor. 

Adding device layouts for pages

Note: The resizing only works for images loaded through one of the Kentico system pages (getattachment, getmetafile, getmedia,etc.). Device profile resizing does not work for images that use web links or direct paths in their source.

1. 2. 3. 4. 5. 6.

7.

8. 9.

10.

To create a dedicated device layout for a page:

Open the application.PagesSelect the page in the content tree.Open the tab.DesignSwitch to the device profile for which you intend to create the layout (use the device selector in the header of the Design tab).Right-click the header of the page template area and select in the menu.Edit layoutClick .Create device layout

Select the source for the new device layout's initial content:Copy from device profile - copies the layout code from the template's default page layout or from one of its other deviceprofile layouts.Use existing layout - allows you to select an existing shared page layout.

If you leave the box checked, the system creates the device layout as a separate copy of theCopy as customselected layout. Otherwise the page template directly uses the shared layout for the device profile (changes madeto the layout code affect all pages based on the same shared layout).

Use empty layout - creates a new custom layout for the device profile with a single web part zone and no other formatting.

Click .Save & CloseDefine the code of the page layout for the given device profile.

(Optional) Click below the layout's code. Add CSS stylesThe editor appears, where you can define any device-specific CSS classes used within the layout code. TheCSS styles

Adding web part zones

The page template allows you to share web part content between the default page layout and device layouts. Toimplement this scenario, set identical ID values ( attributes) for the web part zones in the code of the template'sZoneIDvarious page layouts.

If you add web part zones with unique zone IDs, the zones are only available in the specific device layout. When thesystem renders the page, it only displays the content of zones that exist in the currently active page layout.

10.

11.

1. 2.

3.

1.

2. 3. 4.

5.

1. 2. 3.

page loads these styles when a visitor views it on a device that matches the given profile.

Click .Save & Close

The page now automatically adjusts its layout based on the device profile detected for individual visitors.

You can modify the web part content of the page for different device profiles by using the tab of the application in combinationDesign Pageswith the device selector. See for details.Creating mobile pages

Managing device layouts of templates

You can also manage device layouts through the page template editing interface.

Open the application and select a page template.Page templatesOpen the tab.Device layouts

This tab displays a list of the template's page layouts designed for specific device profiles. You can Create device layoutsand edit or delete existing ones.

Create or edit a device layout. The following sub-tabs become available:Layout - allows you to modify the device layout's code.Design - displays the current page template in Design mode (using the given device layout).Theme - allows you to manage files required by the device layout's CSS styles, such as images or skinsVersions - allows you to view the device layout's .version history

Any changes made on these tabs have the same effect as when editing page layouts directly in the application.Pages 

Mapping shared mobile layoutsDevice profiles allow you to replace shared page layouts with other layouts that are customized for displaying on the given device.

For example, if a page uses a three-column layout, it won't fit on a mobile phone's display. With the appropriate layout mappings, the systemautomatically replaces the columns with rows, which reorganizes the content of the page into a readable format on the given device. 

Preparing shared layouts for mapping

You can only create mappings for layouts that are .convertible

Open the application.Page layouts

Edit ( ) the layout for which you want to map alternative device layouts.Select the check box.Is convertibleEnter the that the layout contains. Number of zones

The system automatically counts the number of web part zones in the layout code, but you can manually override the value(for example in the case of conditional layouts or layouts that load web part zones dynamically).

Save the layout.

The layout appears in the list of layouts on the tab in the device profile editing interface, where you can map the layout to aLayout mappingreplacement layout. The replacement layout applies when a device matching the given profile loads a page that uses the original sharedlayout.

Mapping shared layouts

Open the application.Device profilesEdit the device profile for which you want to map layouts.Switch to the .Layout mapping tab

Prerequisite: Enable the setting for the website in .Enable layout mapping Settings -> Content -> Content management

3.

4. 5.

6.

Find the source layout on the left side of the list.Click the question mark on the right side to create a new mapping, or click a mapped layout on the right side to change the mapping.The dialog opens.Select a target layout

Choose a layout and click .Select

The mapping is complete. When visitors with devices that fit the profile view the website, all pages with the source page layout now use thetarget layout instead.

You can now start designing pages for different device profiles on the tab of the application. See forDesign Pages Creating mobile pagesdetails. 

If you want to select a layout that has a different number of web part zones than the original, uncheck Show only layouts.with a matching number of zones

Device layout priority

Automatically mapped page layouts do not override created for individual page templates. If a pagecustom device layoutstemplate has a custom layout for the given device profile, it always uses the custom layout, even if its default page layout ismapped to a different shared layout.

1. 2.

Creating mobile pagesThis page describes tasks that are common when developing mobile pages in Kentico.

Switching device views

Kentico allows you to develop pages and page templates for specific devices. Once you and device profiles, the deviceenable createselector appears in the application, and you can switch the context between different profiles.Pages

Click the device selector. A list of enabled device profiles appears.Click a device profile.

By default, pages do not have device-specific layouts. When you view a page on the tab, you can see and modify the content of theDesign default page layout for the given page.

If you create a for the page template, or if the page uses a shared layout that has a defined fordevice-specific page layout layout mappingthe current device profile, you can see the structure of the device-specific layout.

Page templates share web part zones between their default page layout and all device layouts. If you modify the content or configuration of aweb part zone, the changes also affect the output of the template's other page layouts that contain a zone with the same ID.

You can find all web part zones that do not exist in the current page layout at the bottom of the page with a gray header and the (not in suffix.layout)

When the system renders the page on the live site, only the content of zones that exist in the currently active page layout are visible.

  

Device layout priority

Custom always take priority over . If you defined a custom device layout for a page'sdevice layouts shared layout mappingstemplate, the page always uses the custom layout even if the template originally uses a shared layout with a mapping for thecurrent device.

1. 2.

1.

2. 3. 4. 5.

6. 7.

1. 2.

3. 4.

5.

Previewing pages on different devices

The modes of the application allows you to view pages as they appear on different devices.Preview Pages

Select the device profile that you want to preview.Switch to mode.Preview

The page is shown in a frame that imitates the device. To rotate the device 90 degrees, switch between and orientation.Portrait Landscape

Customizing the preview frame

Kentico allows you to customize the dimensions and look of the mode when using device profiles.Preview

The preview consists of nine pieces, eight forming the frame and one center piece, which contains the content of the page.

Open the application.Device profiles

Edit ( ) the device profile for which you want to design a custom preview frame.On the tab, enter the and .General Preview width Preview heightClick .SaveSwitch to the tab and upload files that represent pieces of the frame. Upload the following pieces and their alternatives forThemethe rotated version of the preview frame. It is recommended to upload the files into a separate folder.

top left, top center and top right piececenter left and center right piecebottom left, bottom center and bottom right piece

On the tab, click to add a new CSS file. Name the fileTheme Create DeviceProfile.In the stylesheet, specify which image corresponds to which part of the preview frame. Each part of the frame has a CSS class. Usethe following pattern to construct a CSS selector that identifies a particular class:

.DeviceFrame.<device profile name>[.Rotated] .<vertical direction>

.<horizontal direction>

 Add the .Rotated suffix to identify pieces of the device when it is rotated.Replace <vertical direction> with one of the following: , , TopLine CenterLine BottomLineReplace <horizontal direction> with one of the following: , , LeftPiece CenterPiece RightPiece

The following is an example definition of a preview frame piece.

.DeviceFrame.iPad.Rotated .TopLine .LeftPiece{ background-image: url('./Images/top_left_rotated.png'); width: 126px; height: 114px;}

Allowing visitors to override the device detection

Some visitors may prefer to view the standard version of the website (i.e. the content of the device profile) even when using a deviceDefaultthat fits into a different device profile. Kentico provides a component that allows users to switch between the content created for the detecteddevice profile and the default version of the website.

Open the application.PagesSelect a page and switch to the tab. For best results, use a page that visitors can access anywhere on the site, such as theDesignmaster page.Add the web part onto the page.Switch mobile device detectionSet the following properties for the web part:

Mobile link content - sets the text of the link that the web part displays on the device-specific version of the site. This linkallows users to switch to the default version of the website.Desktop link content - sets the text of the link that returns visitors to the device-specific version of the site.

(Optional) Define the CSS class in the website's stylesheet or directly in the web part's CSS styles. The webSwitchDeviceDetectionpart applies this class to the generated links. See also: .Designing websites using CSS

The web part appears only for visitors whose device matches a non-default device profile. If a visitor switches to the default (desktop)

The Preview mode only imitates the size and appearance of the device. The pages are still rendered with your browser engine.

1. 2. 3. 4. 5.

6. 7.

8. 9.

1. 2. 3. 4. 5.

content, the web part displays a link that re-enables device detection for the given visitor and returns them to the device-specific version ofthe site.

Adjusting web part properties for specific device profiles

If you need to change the behavior of web parts according to the current device profile, insert the appropriate into the webmacro expressionspart properties. This allows you to dynamically adjust pages that use the same content for their default page layout and device layouts.

See also: Device macros

Example

The following steps show how to make a web part visible only for the device profile.Medium (Tablet)

Open the application.PagesSelect the page containing the web part.Switch to the tab.DesignConfigure (double-click) the web part. The dialog opens.Web part propertiesExpand the section of the web part properties.Visibility

Click ( ) next to the checkbox of the property. The dialog opens.Edit value Visible Edit valueEnter the following macro expression:

{% CurrentDeviceProfileName == "MediumDevice" %}

Click to insert the macro value into the property.OKClick to save the configuration of the web part.OK

The system evaluates the macro expression when rendering the page. If the name of the current device profile matches the text (MediumDev), the macro returns a true value, which dynamically enables the web part's property.ice Visible

Using device-specific transformations

The that you use to display data have a significant effect on the design of pages. If you need to assign differenttransformationstransformations for specific devices or device profiles, add into the transformation properties of the appropriate web parts.macro expressions

See also: Device macros

Example

This example demonstrates how to create and assign a dedicated transformation for displaying news pages on mobile devices.

Open the sample Corporate Site in the application.PagesSelect the page and switch to the tab.News DesignConfigure (double-click) the web part. The dialog opens.News repeater Web part propertiesScroll down to the property and click next to the textbox. The dialog opens.Transformation New New transformationType as the and enter the following code:NewsList_mobile Transformation name

<div class="description" style="width:500px;"> <a class="header bold" href="<%# GetDocumentUrl() %>"><%# Eval("NewsTitle",true) %></a> <p> <%# Eval("NewsSummary") %><br /><br /> <span class="black bold"><%# GetUserFullName(Eval<int>("NodeOwner")) %> |</span> <span class="gray"><%# Eval("NewsReleaseDate") %></span> </p> </div>

This is a simplified version of the default transformation, without teaser images and with acorporatesite.transformations.NewsListlimited text width.

K#

5.

6.

7. 8.

9. 10.

 Click and the dialog.Save Close

Click ( ) next to the property.Edit value TransformationEnter the following macro expression in the dialog:Edit value

{%

if (CurrentDevice.IsMobile AND GlobalObjects.DocumentTypes["CorporateSite.Transformations"].Children.Transformations.Exists(CodeName == "NewsList_mobile")) {"corporatesite.transformations.NewsList_mobile"} else {"corporatesite.transformations.NewsList"}

%}

 

 Click to insert the macro value into the property.OK Click to save the configuration of the web part. OK

When a visitor views the News page on a mobile device, it automatically displays the simplified list of news items according to the newtransformation ( ).corporatesite.transformations.NewsList_mobile

Users with non-mobile devices can still see the original full-sized transformation ( ).corporatesite.transformations.NewsList 

Creating separate website sections for mobile devices

K#

This macro evaluates a condition and returns the transformation name according to the result.

The part of the condition checks whether the page is being viewed by a mobile device.CurrentDevice.IsMobileThis directly searches the data available for the current device (the device profile of the current visitor does notaffect the result).The second condition checks if the transformation actually existscorporatesite.transformations.NewsList_mobilein the system. While not necessary in this example, similar conditions allow you to load transformations designedfor specific devices. In these cases, you can use a dynamic parameter in the transformation name, such as theexact device name ( ).CurrentDevice.DeviceName

Kentico allows you to create a dedicated sub-section of the website for visitors with mobile devices.

You can redirect users to the mobile section by placing the web part placed onto the website's main landingMobile device redirectionpage. This web part redirects mobile users to one of two URLs according to the user agent of the detected device.

 You can configure the behavior of the web part through its properties:

Property Description

Small device redirection URL URL to which the web part redirects mobile devices recognized assmall. The properties below determine which devices areconsidered large or small.

Large device redirection URL URL to which the web part redirects mobile devices recognized aslarge. The properties below determine which devices areconsidered large or small.

Redirect Android Determines if Android mobile devices are considered as small orlarge devices.

If you set the value to , Android devices are recognizedAutomaticas small. Choose to disable redirection for Android devices.Never

Redirect BlackBerry Determines if BlackBerry mobile devices are considered as small orlarge devices.

If you set the value to , BlackBerry devices areAutomaticrecognized as small. Choose to disable redirection forNeverBlackBerry devices.

Redirect iPad Determines if iPad devices are considered as small or largedevices.

If you set the value to , iPad devices are recognized asAutomaticlarge. Choose to disable redirection for iPad devices.Never

Redirect iPhone Determines if iPhone devices are considered as small or largedevices.

If you set the value to , iPhone devices are recognized asAutomaticsmall. Choose to disable redirection for iPhone devices.Never

Redirect Nokia Determines if Nokia mobile devices are considered as small or largedevices.

If you set the value to , Nokia devices are recognized asAutomaticsmall. Choose to disable redirection for Nokia devices.Never

Always redirect When the website is accessed from a mobile device, the systemstores a redirection cookie in the device's browser.

If you disable this property, the web part does not redirect devices ifthe cookie is already present in the browser, i.e. redirection is onlydone for the first visit. If enabled, the web part redirects mobiledevices on every visit.

Other small devices (User agent) Specifies a list of additional user agents that the web partrecognizes as small mobile devices.

Enter each user agent on a separate line.

Other large devices (User agent) Specifies a list of additional user agents that the web partrecognizes as large mobile devices.

Enter each user agent on a separate line.

Preserve query string If enabled, the web part adds all query string parameters from theoriginal page URL to the mobile redirection URLs.

Example

Device detection

The web part uses its own device detection logic that is related to the device data or Mobile device redirection not device profiles.

The sample contains an example of a mobile website section. You can view the example in the application.Corporate Site Pages

The main page uses a web part to send mobile visitors to a dedicated website section.Home Mobile device redirection

The page serves as the master page of the mobile section. This page does not use , so it doesn’t display contentMobile template inheritancefrom the site’s main master page. Under it, you can find the following pages:

Home - mobile users get redirected to this page from the site’s main page. The page uses a web part toHome Repeaterdynamically load content from the region on the website's main page.Editable text HomeNews - uses a web part to display the pages stored under the website's main section. The news item titlesRepeater News /Newslink to the page, which uses a ( ) containing the of the exact news item./Mobile/News/Detail wildcard URL /Mobile/News/{id} IDArticles - the web part on this page displays the articles stored under it. The content is stored directly in the mobileRepeatersection. It is not shared with the rest of the site.About us - contains only two web parts. Its content is separate and used only in the mobile section.Editable textSearch - this page is not accessible through navigation. The on the master page redirects users here ifSmart search box Mobilethey perform a search within the mobile section. The page displays search results using the web part.Smart search results

CSS stylesheet for the mobile section

The pages of the mobile section use a different CSS stylesheet than the rest of the website — . The mobileCorporate Site – Mobilesection's master page has the stylesheet assigned in . All pages in the mobile section inherit thisProperties -> General -> CSS stylesheetconfiguration and use the same stylesheet. 

Device macros

CurrentDevice

The object holds information about the device detected for the current visitor. The system identifies devices based on theirCurrentDeviceuser agent and retrieves the data about the capabilities of devices from the integrated 3rd party component or the 51degrees.mobi ~\App_Da

file.ta\CMSModules\DeviceProfile\devices.xml

You can take advantage of the object when defining conditions for device profiles and in general . CurrentDevice macro expressions You cansee a full list of device properties on the 51Degrees website.

Most of the properties are accessible through the Data container. For example:

 {% CurrentDevice.Data["Javascript"] %}

Some of the properties are accessible directly:

{% CurrentDevice.IsMobile %}

Note that most of the properties are only available in the 51degrees.mobi Premium data. By default, Kentico includes the Lite license whichyou can .upgrade

CurrentDeviceProfile

To get information about the device profile assigned to the current visitor, use the object in macros:CurrentDeviceProfile

You can access the device profile's system data through its properties, for example: {% CurrentDeviceProfile.ProfilePreviewWidth %}To directly get the device profile's name, use the following expression: {% CurrentDeviceProfileName %}

    

Preparing widgets for usersWidgets are page components that display content and provide functionality. Like , widgets serve as building blocks for creating theweb partscontent of pages through a browser. You can think of widgets as lightweight versions of , typically with a simplified configurationweb partsinterface. Every widget is based on an existing web part.

The purpose of widgets is to allow customization of specific page areas by users who do not have — content editors ordesign permissionsend users of websites.

Users can work with widgets in the following scenarios:

Widget type Description

Editor widgets Content editors can manage widgets inside predefined zones:

on the tab of the applicationPage Pageswhen editing pages in modeon-site editing

See: Adding page content through widgets

Inline widgets Content editors can insert widgets directly into text regions onpages and into page fields.

See: Adding inline widgets into text

User widgets Registered users can personalize the content of special page areason the . Each user has their own unique version of thelive sitepersonalized page.

Group widgets Administrators of can work with widgets on the community groups li inside zones on group pages.ve site

See: Customizing group pages using widgets

Dashboard widgets Widgets serve as components that users can add to dashboardswithin the Kentico administration interface.

See: Managing widget dashboard content

Kentico provides a set of widgets by default. You can also with any required functionality.create additional widgets 

Creating widgetsEvery is based on a . You can create widgets with the same functionality as any web parts in the system. If you require awidget web partwidget with completely new custom functionality, you need to an appropriate web part first.develop

To manage widgets, open the application.Widgets

The system groups widgets into categories, organized in a tree structure. The categories do not influence the functionality or usability ofwidgets in any way — they only determine the structure of the widget catalog. When you select a category, the page displays a list of allwidgets in the category.

1. 2. 3. 4.

Tip: You can create web parts that serve exclusively as base templates for widgets:

Create the web part.Edit the web part in the application.Web partsOn the tab, set the web part's to .General Type Widget onlyClick .Save

Such web parts cannot be placed onto the website's pages, but you can choose them when creating new widgets.

1. 2.

3. 4.

1. 2. 3.

4.

To add a new widget:

Click the category where you want to store the new widget.Click .New widget

The web part selection dialog opens.Choose the web part that provides the functionality you want for the widget.Click .Save & Close

The system creates the new widget under the selected category. Continue by defining the widget's properties and configuring the security.settings

  

Defining widget properties

Properties are parameters that adjust the behavior of the widget. Users can set the values of properties through a configuration dialog whenadding or editing individual widget instances.

Each widget has the same as the original web part. When you create a new widget, all of the properties are configured to bepropertieshidden in the widget's configuration dialog by default.

To set up the properties of a widget:

Open the application.WidgetsSelect the widget in the tree.Open the tab, where you can manage the available properties:Properties

To make a property visible in the widget configuration dialog, check .Display field in the editing formIf you check , the property appears only when configuring widgets on the Display field only on dashboards widget

sections of the administration interface.dashboard

Click to confirm the change for each property.Save

We recommend keeping the widget configuration interface as simple as possible for users.

1. 2. 3.

Additionally, you can:

Set the for propertiesDefault valueModify the appearance and behavior of properties in the configuration dialogAdd additional properties (to have an effect on the widget's behavior, the property must be in the code of the original webhandledpart)

You cannot:

Remove propertiesChange the , or of propertiesField name Data type Size

Adjusting system properties for widgets

All widgets have a set of default properties for configuring common system functionality. Like standard properties, the system properties arenot visible in the widget configuration dialog by default. To allow users to change the values of system properties for widget instances, modifythe settings on the tab of the widget editing interface.System properties

You can edit the system properties of a widget just like when working with the regular properties on the tab. Clicking fProperties Reset fieldor a system property returns the settings to their default state (hides the property in the widget configuration dialog).

Managing existing widgets

To work with existing widgets in the application, click the actions above the category tree:Widgets

New category (click next to the button) - creates a new widget category under the currently selected category.... New widget

 Delete selected - removes the selected widget or category.

  - creates an containing the widget.Export widget export package

To widgets between categories:move

Select the widget in the category tree.On the tab, select the target .General CategoryClick .Save

Tip: Click to load the exact settings from the original web part for the selected property.Reset field

Adding into the default values of widget propertiesmacros

Properties use the when users create new instances of the widget. You can set dynamic default values through Default value mac. The system resolves the macros according to the following rules:ro expressions

If the property is available in the widget's configuration dialog ( is checked), the macroDisplay field in the editing formresolves directly in the dialog when adding new instances of the widget.If the property is NOT visible in the configuration dialog, the system dynamically resolves the macro when displaying thepage containing the widget instance.

Changing the default values of widget system properties

When you set a for a widget's system property:Default value

The property's value changes for all instances that were added as , except for instances that have their ownin-line widgetsvalues assigned (for system properties that are visible in the editing form).The value does NOT change for all other types of widget instances that are already placed on the pages of your website.

Widgets load the default system property definitions from XML files in the web project's ~/App_Data/CMSModules/PortalEngine/Pr folder.operties/Widget/

To learn more about individual system properties, see (widgets and web parts use theReference - Web part system propertiessame system properties).

Warning: Deleting a widget does NOT automatically remove instances of the given widget from pages. Any pages containing adeleted widget display an error message instead of the missing widget.

1. 2. 3.

1. 2. 3.

1. 2. 3. 4.

5.

On the tab, you can type a and set a image for each widget. You can choose between two types ofGeneral Description Thumbnailimages:

Image - upload a standard image file (for example a png). The recommended thumbnail image size is 64x64px.Font icon class - enter the name of a CSS class that defines a .font icon

Users can see the description and thumbnail in the widget selection dialog.

If you need to rename a widget category, select it in the tree and switch to the tab. You can also change the folder's icon by enteringGenerala leading to an alternate image file (the recommended image size is 16x16px).Category image path

Using custom layouts for widgets

Layouts allow you to modify the appearance and design of widgets, or even add further content. You can choose one of the layouts defined for each widget:for the parent web part

In the application, select the widget in the category tree.WidgetsOn the tab, select the required (options are only available if the parent web part has at least one custom layout).General LayoutClick .Save

The system applies the selected layout to all instances of the widget across all sites.

Disabling the initial configuration dialog

You can configure widgets to skip the configuration dialog that opens when adding widget instances onto pages. This saves time whenworking with widgets that usually use the default property values.

In the application, select the widget in the category tree.WidgetsOn the tab, check .General Skip initial configurationClick .Save

When adding new instances of the widget, the system directly places the widget onto the page without opening the property configurationdialog. 

Setting up widget zones on pagesTo allow users to work with , you need to create widget zones on your website's pages. You can set up widget zones on:widgets

Portal engine page templatesPortal engine sections of ASPX templates

By default, all zones on portal engine templates are static web part zones. Only the website's designers can modify the content of web partzones by . Widget zones represent sections of the page that other types of users can customize.adding web parts

To change a web part zone into a widget zone:

Open the application.PagesSelect the page in the content tree.Switch to the tab.DesignOpen the properties dialog of the given web part zone:

Expand the zone's menu ( ) and click .ConfigureorDouble click the zone header.

Set the zone's property:Widget zone type

Zone type Description

None Standard zones.web part

User personalization Allows registered users to personalize the zone's widgetcontent on the .live site

Each user has their own unique version of the zone. Thepersonalized content cannot be seen by other users.

Tip: If you wish to use a different layout for certain instances of the same widget, make a clone of the widget and assign thealternative layout.

Warning: Changing the widget type of a zone removes all instances of web parts or widgets placed in the given zone.

5.

6.

1.

2. 3. 4.

5.

Customization by page editor Allows website editors to :work with widgets

on the tab of the applicationPage Pageswhen editing pages in modeon-site editing

Customization by group administrator Allows administrators of the that owns the page to workgroupwith widgets on the .live site

Click .OK

The zone now provides an area on the page that users can customize (according to the selected zone type). You can add default widgetcontent into the zone. 

Creating default widget content for zones

You can set default content for widget zones by editing pages in the application on the tab:Pages Design

Right-click the header of the widget zone and click in the menu.Add new widget

Select a widget from the catalog. You can only choose the widgets that are for the given type of widget zone.allowedClick .SelectSet the values of the widget's (some widgets may be configured to skip the property configuration dialog).properties

Click .OK

The system adds the widget into the zone. Repeat the process to define any default widget content for the zone. The zone displays thedefault widgets on the page until users edit the content (depending on the type of the zone).

Adding widget actions to pages

You can place the onto pages that contain widget zones. The web part allows users to:Widget actions web part

Add widgetsReset all widget zones to their default content

Macros and widget properties

For security reasons, the system does not resolve added into values in the widget properties dialog.macro expressions

You can pre-set macros into the default values of widget properties when editing widgets in the application on theWidgets tab.Properties

See: Creating widgets

Important: The widgets that you add on the tab only represent the content of the zone. Changes that you make toDesign defaultthe default widgets do NOT affect pages where users have already modified the widget content.

1. 2. 3.

The web part only works with the type of widget zone specified in its property. When a user clicks the buWidget zone type Add new widgettton, the web part places the widget into the zone specified by the property. Users can drag the widget into another zone ifWidget zone IDthe default placement is not suitable.

 

Configuring permissions for widgetsWidget security works on two separate levels:

Where can users create instances of the widget?Which users (roles) are allowed to work with the widget?

To edit the permissions of a widget:

Open the application.WidgetsSelect the widget in the catalog tree.Switch to the tab.Security

You can allow widgets for the following locations:

In group, editor or user zones - see Setting up widget zones on pagesIn dashboard zones - users can insert the widget as a component on widget dashboardsAs inline widget - users can insert the widget into editable text regions via the WYSIWYG editor

and one of the following types of users:

Authenticated users - all logged in users (including on the live site)Global Admin only - only users with the Global administrator privilege levelAuthorized roles - only members of the roles selected in the section below (you can switch between the roles of specific )Sites

The security settings only apply when:

Adding new widget instancesConfiguring the properties of existing widget instances

The system does NOT automatically remove existing instances of widgets if you cancel the permissions for the given zone type or the userwho added the widget.

Tip: When creating pages with widget zones, you can enable the property of the web part.editor Use main menu Widget actionsThis causes the web part to display the action buttons in the header of the main edit menu on the tab in the applicatioPage Pagesn, instead of inside the page content.

By default, new widgets are forbidden for all zone types and allowed only for authorized roles (without any roles selected). Youneed to explicitly allow your widgets for specific types of zones and users.

Note: The user permissions do NOT apply for group widget zones. Users who are administrators of groups can work with allwidgets that are allowed for group widget zones (on pages owned by the given group). See also: Customizing group pages usingwidgets

1. 2. 3. 4.

 

Validating website code and accessibilityKentico provides built-in features. The main advantage of the built-in validators over standard web based validation servicespage validationis that your to get validated. All that is required is to have an Internet connection. You can validate pagespages do not need to be livebefore you publish them.

To validate your website's pages:

Open the application.PagesSelect a page in the content tree.Switch to mode.PreviewSelect the tab.Validate

The following validators are available:

HTML validator - checks page output code validity against the (X)HTML standard version declared in page code.CSS validator - checks validity of CSS styles used by the page against the CSS 2.1 standard.Validating links - checks availability of links on a page.Validating accesibility - checks accessibility of the page.

Note: The validators always validate the version of the page that is displayed in mode (the version published on the livePreviewsite may be different when using ).workflow

1. 2. 3. 4. 5.

1. 2. 3. 4. 5.

1.

2.

 

Validating HTML codeThe system allows you to check the HTML validity of page code. Validation is always performed against the version of HTML declared in thevalidated code.

To validate a page's HTML:

Open the application.PagesSelect the page in the content tree.Switch to mode.PreviewOpen the tab.Validate -> HTML Click .Validate

If the validator finds issues in the page's HTML code, the page displays a list. You can see the following information for each issue:

Line - the line number of the HTML code on which the issue appears.Column - the column of the HTML code (i.e. number of characters from the beginning of the respective line) where the issueappears.Error message - message describing the validity issue.Error explanation - detailed explanation of the validity issue.Source - extract of the part of the code where the validity issue appears.

 

Validating CSSThe system allows you to validate the CSS style definitions used on pages against the . The validator checks styles from:CSS 2.1 standard

Linked CSS stylesheetsStyles declared in the head section of the page code

Inline styles declared as attributes of individual HTML elements are not validated.

To validate a page's CSS:

Open the application.PagesSelect the page in the content tree.Switch to mode.PreviewOpen the tab.Validate -> CSSClick .Validate

If the validator finds invalid style definitions, the page displays a list of all detected issues. You can see the following information for eachissue:

Line - the line number in the CSS stylesheet (or approximate line of the HTML source code) where the issue was found.Context - name of the CSS class that contains the issue.Error message - message explaining the issue.Source - if the issue was found in a stylesheet, the column displays a link to the stylesheet. If you have permissions to edit thestylesheet, the link opens an editing dialog.

 

Validating linksThe system allows you to check pages for broken links. Only links within , , and elements are validated by the link<a> <img> <script> <link>checker.

Open the application.Pages

Warning: During validation, your data is sent to an external . If you have sensitive, nonpublic content,3rd party validation servicewe recommend using other types of validation.

Note: If you navigate to another page in preview mode using links on the displayed pages, and then switch to the tab, theValidatesystem still validates the page selected in the content tree.

Warning: During validation, your data is sent to an external . If you have sensitive, nonpublic content,3rd party validation servicewe recommend using other types of validation.

Notes:

We recommend waiting at least 30 seconds between validation requests. If you submit a page for validation multiple timeswithin a short interval, the validation service may temporarily block your page's URL.If you navigate to another page in preview mode using links on the displayed pages, and then switch to the tab,Validatethe system still validates the page selected in the content tree.

2. 3. 4. 5.

1. 2. 3. 4. 5.

6.

Select a page in the content tree.Switch to mode.PreviewOpen the tab.Validate -> Link checker Click .Validate

If the validator finds broken links on the page, you can view the following information for each detected issue:

Status code - the HTML status code returned when the link is accessed. Statuses of redirected links are shown for each page withinthe redirection.Type - W for links redirected to a different location (301 status code), E for broken links (404 status code).Error message - details about the link issue.URL - URL to which the link is pointing.Request time - time elapsed between sending a request to the link and receiving a response.

 

Validating accesibilityThe system allows you to validate the accessibility of pages. You can perform the validation against several standards:

BITV 1.0 (Level 2)U.S. Section 508Stanca ActWCAG 1.0 (Level A)WCAG 1.0 (Level AA)WCAG 1.0 (Level AAA)WCAG 2.0 (Level A)WCAG 2.0 (Level AA)WCAG 2.0 (Level AAA)

We recommend using the , and before you use the accessibility validator.HTML validator CSS validator Link checker

To validate the accessibility of a page:

Open the application.PagesSelect the page in the content tree.Switch to mode.PreviewOpen the tab.Validate -> Accessibility Choose the validation .Standard

Warning: During validation, your data is sent to an external . If you have sensitive, nonpublic content,3rd party validation servicewe recommend using other types of validation.

6.

1. 2. 3. 4.

Click .Validate

If the page contains accessibility issues, you can view the following information for each detected problem:

Line - the line number of the HTML code on which the issue appears.Column - the column of the HTML code (i.e. number of characters from the beginning of the respective line) where the issueappears.Accessibility rule - the standard's accessibility rule based on which the error was generated.Error - message describing the validity issue.Fix suggestion - description of steps that you can perform to address the accessibility issue.Source - extract of the part of the code where the accessibility issue appears.

 

Managing JavaScript filesThe system allows you to manage custom JavaScript files through the administration interface, without requiring direct access to the filesystem.

Open the application.Javascript files

Here you can either create new files in the system or access the files stored in the web project's directory. You can~/CMSScripts/Custom/use the JavaScript files on the pages of websites or anywhere within the application.

Linking JavaScript files to pages

To use JavaScript code on your website, you need to link it to pages.

Linking JavaScript files through the Javascript web part

You can link JavaScript files which are accessible through the Javascript application to pages using the web part.Javascript

Open the application.PagesAdd the web part to a web part zone.JavascriptIn the web part properties, click next to the field and select the required JavaScript file.Select Linked fileClick .Save & Close

The system adds the web part to the web part zone. This way, the system links your JavaScript file to the page, where theJavascriptJavaScript code will be executed.

When linking JavaScript code through the web part, the system automatically uses the minification functionality to optimizeJavascriptrequests for JavaScript code. Please see for details.Using code minification and compression

Linking JavaScript files through the Head HTML code web part

You can use the web part to link JavaScript files through an HTML tag.Head HTML code external

Note: If you navigate to another page in preview mode using links on the displayed pages, and then switch to the tab, theValidatesystem still validates the page selected in the content tree.

Note: Only files with the extension are supported..js

1. 2.

3. 4.

5.

However, external JavaScript files are not minified automatically, but you can utilize the minification by using the /GetResource.ashx?script clause. For example <script src="/kentico82/CMSPages/GetResource.ashx?scriptfile=/myscript.js>.file=/location.js

Linking JavaScript files in page templates

Open the application.Page templatesEdit a page template.

You can for example edit a Master page template to include the JavaScript file on all pages of the website.Switch to the tab.HeaderAdd a reference to a JavaScript file using a HTML tag.

For example <script src="/myscript.js></script>.Click .Save

 

Troubleshooting websitesKentico offers tools that provide information about the system, and help identify problems when developing or running websites:

System overviewEvent logDebugging tools

 

Viewing system informationTo find information about your web application and the environment in which it is running, open the application and view the System Generaltab.

System information

Machine name - name of the server machine on which the system is running.ASP.NET account - name of the user account used by ASP.NET in the server's operating system.ASP.NET versionApplication pool name - name of the IIS application pool in which the instance of Kentico is running.Application trust level - the of the environment where the application is running (only the Full trust level is supported).trust levelYour IP address - IP address from which you are accessing the system.

Database information

Server name - name of the database server on which the system's database is running.Server version - SQL Server version installed on the database server.Database name - the name of the system database on the database server.Database size - the current size of the database, including the actual database data (the .mdf file) and the database log (the .ldffile).

 

Memory statistics

Allocated memory - size of memory allocated for the system.Peak memory usage - maximum memory used by the process.Process physical memory - physical memory used by the process.Process virtual memory - memory allocated by the process in the virtual memory space.

Click to free up memory space by deleting unused data.Clear unused memory

Garbage collection statistics

Shows how many times the initiated cleaning of unused memory.garbage collector

Cache statistics

Cache items - number of items stored in the application's memory.Expired - number of expired cache items.Removed - number of items removed from the system cache since the last restart.Dependency changed - number of cache items that the system dropped as a result of .cache dependenciesUnderused - number of cache items dropped earlier than the planned expiration time (possibly due to lack of memory).

Click to remove all cached content from the memory of the Kentico application.Clear cache

Page view statistics

Views of content pages - number of content pages displayed since the last application restart.File downloads and views - number of files downloaded and viewed since the last restart.Views of system pages - number of system pages viewed since the last restart.Non-page requests - number of non-page requests handled since the last restart.Number of pages not found - number of page view requests to which the server responded with a 404 Page Not Found error.Pending requests - number of currently pending (not yet processed) page requests.

Restarting the application

You can restart the application or its components by clicking the buttons in the header of the tab:General

Restart application - restarts Kentico (needed to apply certain types of changes).Restart all web farm servers - restarts all running the instance of Kentico.web farm serversRestart windows services - restarts all Kentico Windows services (if any are installed). See for moreKentico Service Managerdetails.Clear performance counters - clears the values stored in all registered for the Kenticoperformance counters (Health monitoring)instance. Also resets the section.Page view statistics

 

Working with the system event logThe event log stores information about all events that occur in the system. It is useful to view logged information if unwanted behavior occursin the system and you want to find out where the problem originates or get additional details.

Viewing the event log

Contact management database separation

If the application has a (on-line marketing), the page displays information for bothseparated contact management databasedatabases.

See also: Configuring caching

To view the event log, open the application.Event log

If you click ( ) next to an event, the system displays a dialog with full details about the event.Display event 

Configuring the event log

You can configure the following event log settings:

General event log settingsLogging page not found exceptionsConfiguring permissions for the event logLogging system events to traceLogging system events in the Windows Event ViewerSetting up e-mail notifications for errors

General event log settings

You can configure the following settings for the event log in :Settings -> System

Setting location Description

Event log size The number of events stored in the Event log.

When exceeded by 10% (or a different percentage set bymeans of the web.config key), theCMSLogKeepPercentpercentage of the oldest events is deleted from the log in abatch.Set 0 if you do not want the system to log any events.

Log metadata changes If enabled, changes of object and page metadata (i.e. when anobject or a page is created, edited or deleted) are logged in theEvent log.

Log to database Indicates if events are logged to database. Doesn't override Eventlog size set to 0.

1. 2. 3. 4.

1. 2. 3.

1. 2. 3. 4.

1. 2. 3. 4.

1. 2.

3.

Log to filesystem If enabled, the system writes the event log into the CMS\App_Data\ file on the server's file system. Doesn't overridelogEvents.log

Event log size set to 0.

Log to trace Indicates if events are logged to trace. Doesn't overwrite Event logsize set to 0.

Use EventLog trace listener Indicates if the system logs events in your Windows Event Viewer.

Use the Modify feature of the Kentico installer, if you haven't turnedon the Registration of Kentico in Windows Event Log option wheninstalling Kentico.

Logging page not found exceptions

You can enable logging of exceptions in the event log. To do so:Page not found

Open the application.SettingsSelect the category.ContentIn the group, enable .Page not found Log page not found exceptionSave the changes.

Configuring permissions for the event log

To allow users to work with the event log, for your website's :configure permissions roles

Open the application.PermissionsSelect permissions for and the .Modules Event logAssign the following permissions to roles: 

Read - allows members of the roles to access the event log. Only users with the Global administrator canprivilege levelview events logged on a global application level.Clear log - allows members of the roles to delete the records in the event log.

Logging system events to trace

You can set up Kentico to log application events in trace. You can then implement your own listener, such as the orTextWriterTraceListeneruse the out-of-the-box Kentico functionality to log events into the .Windows Event Viewer

To enable logging of system events to trace:

In Kentico, open the application.SettingsSelect the category.SystemIn the settings group, enable .Event log Log to traceSave the changes.

Kentico now logs system events to trace. You can now implement your own listener, such as the .TextWriterTraceListener

Logging system events in the Windows Event Viewer

You can set up Kentico to log application events in the Windows Event Viewer. Note that to do that, Kentico uses the :EventLogTraceListener

Registering Kentico in Windows Event LogEnabling logging of Kentico events into Windows Event Log

Registering Kentico in Windows Event Log

Run the Kentico installer.Modify the installation that you want to register in .Windows Event LogSelect the check box.Registration of Kentico in Windows Event Log Apply Changes.

The installer registers Kentico in the Windows Event Log.

Enabling logging of Kentico events into Windows Event Log

In Kentico, open the application.SettingsSelect the category.System

You can also configure the event log by adding keys to the appSettings section of your application's web.config file. The keys workin combination with the settings listed above. For more information, see  Reference - Web.config application keys.

3. 4.

1. 2. 3.

4.

5.

In the settings group, enable and .Event log Log to trace Use EventLog trace listenerSave the changes.

Kentico now logs system events to both the Kentico event log and Windows Event Viewer.

Setting up e-mail notifications for errors

You can configure the system to automatically send e-mail notifications whenever errors occur in the application.

Open the application.SettingsSelect the category.SystemEnter the target e-mail addresses for the notifications into the setting.Error notification e-mail address

Use semicolons to separate multiple addresses.Type a sender address into the settings.No-reply e-mail address

The notification e-mails use the sender address in their field.FromSave the settings.

Event log API

You can find an API example of logging events into the event log in . More examples are provided in the Designing secure error messages A.PI examples documentation

Disabling logging for specific types of events

If you wish to disable logging for events of a specific type, you can use custom code and the Kentico API.

The static class (available in the library) provides the following properties:EventLogProvider CMS.EventLog

RegExExcludeLogSourceRegExExcludeLogCodeRegExExcludeLogDescription

The properties allow you to define that exclude events whose value in the , or fieldregular expressions Source Event code Descriptionmatches the specified expression (each field corresponds to one of the properties). Create and assign an instance of the System.Text.Regul

class as the value of the properties.arExpression.Regex

You need to set the properties at the beginning of the application's life cycle. Choose one of the following options:

During the initialization process of the application itself – use the partial class in the folder.CMSModuleLoader App_CodeWhen initializing  – override the method of the module class.custom modules OnInit

For example, you can add a new class to the folder of your web project (or on webApp_Code CMSApp_AppCode -> Old_App_Codeapplication installations) with the following code:

Note: Using the regular expression properties to filter the event log may have a negative impact on the performance of the website(particularly on sites under heavy load where a large number of events is logged).

using System;using System.Text.RegularExpressions;

using CMS.Base;using CMS.EventLog;

[EventLogExcluder]public partial class CMSModuleLoader{ /// <summary> /// Attribute class for running code during the application initialization. /// </summary> private class EventLogExcluderAttribute : CMSLoaderAttribute { /// <summary> /// Called automatically when the application starts. /// </summary> public override void Init() { // Excludes all events with the "CREATEOBJ" or "UPDATEOBJ" event codes. // Disables event log records notifying about the creation or update of objectsin the system, // but still allows events related to object deletion. EventLogProvider.RegExExcludeLogCode = new Regex("^(CREATEOBJ|UPDATEOBJ)$"); } }}

 

DebuggingDebugging allows you to monitor internal activity within the system. You can use the debugging tools to:

Find and fix problems with performance or specific featuresGet detailed information when reporting issues to Kentico support

The following types of debugging are available:

Global system debugs

Hash tables - provides information about the hash tables used by system objectsWorker threads - allows you to track and manage background tasks

Cache items - shows which data is cached in the application's memoryE-mail debugging - allows you to monitor and test the sending of e-mails from Kentico

Debugs for individual web requests

Request details - provides an analysis of recently processed requestsSQL queries - shows which SQL queries the system executes when loading pagesIO operations - allows you to monitor file operations that occur in the system (both input and output)Page ViewState - allows you to inspect the view state values saved by controlsPage output code - shows the output code of recently requested pagesEvent handlers - displays the system events that were triggered while processing requests

Macros - allows you to analyze how the system resolves macro expressionsCache access - shows the cache operations that the system performs during requestsSecurity - shows the details and results of security operations (permission checks)Web farm synchronization - monitors the synchronization activity of web farm serversWeb analytics - shows the web analytic statistics logged for requests

 

Enabling debugging

Most debugs are disabled by default, because debugging requires the system to perform extra operations and reduces website performance.

Example

To configure debugging, adjust the settings in .Settings -> System -> Debug

The settings in the category affect debugging globally:General

Setting Description

Disable debugging Globally disables all debugging tools, regardless of individual debugsettings.

Debug Import/Export__________________________________

If disabled, the system does not log debug information for the pagesof the interface. For performance reasons, it isImport/Exportrecommended to leave this option disabled unless you need todebug the Import/Export process.

Debug resources If disabled, the debug ignores all resource requests ( aGetResourcend ).GetCSS

Debug scheduler If disabled, the debug ignores all operations executed by the sched.uler

Configure individual debug types through the corresponding setting categories. The category provides equivalent settings that enable allAlldebugs:

Setting Description

Debug everything everywhere__________________________________

Enables:

All debug typesDebugging of user interface pages for all debugsLive site debugging (for all debugs)

Enable all debugs Enables all debugs and the corresponding tabs in the interface ofthe application.Debug

Display all debugs on live site If checked (true), all debugs display their information on theenabledlive site below the regular content of pages.

Include UI pages in all debugs If checked (true), all debugs include actions performed onenabledthe pages of the user interface.

Default log length Sets the default maximum length of the debug log in the appDebuglication. The default log length is used by debug types that do nothave their own log length set.

Display stack information in every debug If enabled, the system tracks the code stack for all debug types anddisplays the information in the column of the debugContextinterface in the application. Debug

Log everything to file Enables logging of all possible operations into files stored in the.log folder (including the and )~/App_Data/ Event log E-mail sending log

.

Global system debugs

Global debugs provide general information about the status of the application. To access the debug interface, open the application.Debug

System object hash tables

On the tab of the debugging interface, you can view the number of objects stored in the system's hash tables. The debugSystem objectsshows two types of information:

The number of records in individual hash tablesThe current number of hashed objects for individual object types

Click to delete the content of all hash tables.Clear hash tables

Worker threads

The system uses worker threads to perform tasks in the background, so that the main application can remain responsive to users. Examplesof separate threads in Kentico are and sending of or .Smart search indexing campaign emails mass e-mails

Note: Always disable debugs before deploying websites to the production environment.

You can manage threads on the tab of the debug interface. Debugging of worker threads can be useful if your application isWorker threadsconsuming significantly more resources than expected. Background threads may be the cause.

The debug shows two types of threads:

Running threads - all worker threads currently running in the system. You can ( ) individual running threads, or (Cancel View

) their progress log.Finished threads - the latest threads that have finished their activity.

Debugs for individual web requests

The system provides debugs for analyzing web requests that occurred during recent activity on websites, or in the administration interface ofKentico. The recommended way to use web request debugs is to view pages or perform actions in one browser tab (or a different browser),and then check the results in the appropriate debug log.

Like with global debugs, you can access the web request debugging interface through the application.Debug

Request processing details

The debug on the tab allows you to detect performance bottlenecks, and view detailed information about all processed webRequestsrequests. You can analyze pages with slow response times, determine whether the cause is inside the application itself, and find the exactsource of the problem.

The following information is available for each request:

A breakdown of individual steps in the request processing life cycle, showing the duration and result of each stepCookies sent by the client with the request, and cookies returned in the response (if available)Details about the request (HTTP method, User-Agent etc.)

Click to remove all data in the request debug.Clear debug log

SQL queries

To check which database queries the system executes when loading pages, open the tab of the debugging interface. TheSQL queriesdebug log displays a list of recent web requests, along with the queries called within the context of every request. You can find the followinginformation for each query:

The name and SQL code of the query.The in which the query was called.Context

Click on the method to see the full stack trace.If you enable the option at the top of the interface, the stack trace is displayed for all queries.Show complete context

The of the query execution.DurationThe total size of the data retrieved by the query.

Click to remove all data in the SQL debug.Clear debug log

Tip: To view the data of all enabled debugs for a specific request, click the request URL in any debug log.

Note: Loading a single page often generates multiple web requests. The additional requests retrieve uncached files and resourcesrequired by the content of the page.

Tip: The system does not execute SQL queries if the required data is already in the application's memory. If you wish tocachedforce pages to execute queries while you are debugging, click to flush the application's cache.Clear cache

IO operations

The tab of the debugging interface allows you to monitor file operations that occur in the system (both input and output).File system (IO)The IO debug displays a list of recent web requests, and all file operations carried out while processing individual requests. For eachoperation, you can see:

The type of the operation.The size of the transferred data (if any).How many times the system accessed the file.The path of the affected file.The in which the file operation occurred.Context

Click on the method to see the full stack trace.If you enable at the top of the interface, the stack trace is displayed for all operations.Show complete context

The selector above the debug log allows you to filter the operations for individual file system providers (such as the Provider Local file, or ). See providers for more information.system Azure blob storage Amazon S3 Configuring file system

Click to remove all data in the IO debug.Clear debug log

Page ViewState

The debug on the tab displays a list of recent page requests, along with the values saved by the controls on thePage ViewState view state given pages. The log provides the following information for each control:

Control IDIs dirty - indicates if the item was added to the view state after the method was called (typically occurs during TrackViewState OnInit).

You can display only controls with such items by checking above the log. Show only controls with dirty valuesViewState - the value of the control's ViewState field.Total size - the size of the control's ViewState data.

To remove all previously logged view state data, click .Clear debug log

Note: The system retrieves the view state of controls using reflection. The ViewState debug may not work correctly when runningin an environment that does not support reflection.

Page output code

You can view the exact output code of recently requested pages on the tab of the debugging interface. Output debugging isPage outputparticularly useful for AJAX requests, where you cannot view the output code of the response directly in the page source.

Click to delete the current output debug data (for all requests).Clear debug log

Event handlers

On the tab of the debugging interface, you can find a list of all events that the system triggered while processing recentEvent handlersrequests.

Click to delete the current data in the event debug (for all requests).Clear debug log

Debugging on the live site

You can enable live site debugging in through the settings. The result is that pages onSettings -> System -> Debug "debug on live site"the live site display a debug log below the regular content. The log only includes information related to the requests used to load the givenpage.

 

 

 

For more information, see:

Handling global eventsReference - Global system events