DESIGNER S GUIDE This guide is intended for front-end developers and web designers. The guide describes the procedure for creating website templates using Sitefinity and importing already created templates in Sitefinity, how to create and register a theme in Sitefinity, and how style Sitefinity widgets. How to read Sitefinity offline documentation [2] Intended audience [3] Who can find this guide helpful. Website templates file structure [3] This section describes how to organize the templates and the themes for the backend and the frontend. Creating a template [4] Use this section to learn how to create a template using Sitefinity build-in Layout editor or how to upload your own Master page. Creating a template using the Layout editor [4] Creating a template using Master pages [5] Including JavaScript and CSS resources [6] Creating a theme [6] Use this section to learn how to upload, register and use a theme in Sitefinity. Registering a theme [7] Using XML file to order the loading of the CSS files [8] Applying a theme [8] Using widget templates [8] Use this section to learn how to create an apply templates to widgets or how to upload an use an existing widget template. Using the Widget templates editor [8] Using external widget template file [10] 1
HOW TO READ SITEFINITY OFFLINE DOCUMENTATION Text formatting conventions The following table contains examples and descriptions of all the styles you will encounter in the Sitefinity 4.0 RC 2 offline documentation: Format Meaning Example Example Hyperlink A clickable text that is link to another topic from the documentation or an external resource. Link to a topic in the same guide: For more information, see Creating pages. Link to an external resource: For more information, see Help. Google Analytics Example Example Words or characters that appear on the screen. For example, menu and button labels, titles of windows, etc. Important text that needs to be emphasized Titles of tables and of table columns Titles of graphs. Click Administration Roles and in Assign to dropdown box, select Backend users. Make sure you have selected at least one checkbox. Example Source code, names of files and folders. The error.log file is located in folder Logs. Example <Example> Exact user entry. Enter the text in the system, exactly as it appears in the documentation. Variable user entry Replace the text in the brackets with the appropriate entry. In the input field that appears, enter 23 kilograms and click Next. In the input field, enter <your age>. EXAMPLE Key on your keyboard When you are finished, press ENTER. NOTE: The above styles do not apply to Sitefinity 4.0 RC 2 Developer s Guide. Navigating the documentation Navigation pane Sitefinity PDF documentation support bookmark links. To use navigation to all topics of a document, you must open the navigation pane. For more information, see your PDF reader documentation. In you are using Adobe Reader, you open the navigation pane, by clicking icon in the upper-left part of the window. Using Table of contents and Section contents The documentation is divided in topics. Topics are organized in section topics. If a topic is a section topic and it has subtopics, it contains a Section contents. The Section contents contains links to its subtopics. Using the breadcrumb, you can navigate from each subtopic to its section topic. NOTE: In Table of contents, all topics and subtopics are displayed with their page number in squared parentheses. Using the breadcrumbs Each topic has breadcrumb links at the end of the topic. Following is an example of breadcrumbs: Structuring the pages of your website Creating and managing pages Table of contents You can use the bread crumbs to navigate to the section topic and all existing levels of topics above the section topic up to the section of contents. Navigating between different guides and tutorials You can download all offline versions of Sitefinity documentation from http://www.sitefinity.com/4.0/documentation/. 2
INTENDED AUDIENCE This guide describes how a web developer, can create custom website templates for Sitefinity 4.0 RC 2. The possible users of the Designer s Guide include: Web designers working on the company s website. Web designers in media agencies creating themes for clients. Web designers creating themes for the Sitefinity Marketplace. Table of contents WEBSITE TEMPLATES FILE STRUCTURE Sitefinity 4.0 RC 2 uses specific structure for organizing the templates and the themes for the backend and the frontend. The scheme below displays the structure convention: For more information about Sitefinity files, see Sitefinity 4.0 RC 2 Installation and Administration Guide Managing Sitefinity files. Table of contents 3
CREATING A TEMPLATE In Sitefinity 4.0 RC 2, you can use one of the following approaches to create a layout template (not a website templates): Section contents Create a template using the Sitefinity Layout editor The Layout editor, developed in Sitefinity 4.0 RC 2, is an easy and intuitive way to create grid-like layouts for your website. Using this flexible approach, you can reorder and resize all of the blocks and rename them with custom classes. With the Layout editor you can easily define new content placeholders, using entirely the Sitefinity backend there is no need to download any template files, edit them, and re-upload them. Create a template using Master pages (.master files) Using ASP.NET Master Pages is the common way to add consistent layout for.net developers. You can use this approach in case you need more complex HTML layout or you need logic in Code-Behind files. Including JavaScript and CSS resources Table of contents Creating a template using the Layout editor Sitefinity 4.0 RC 2 comes with 9 different layouts. You can use them or create your own layouts through the Layout editor. With the Layout editor you can start from scratch or build a layout template based upon already prepared one. Creating a layout template from scratch To create your own layout template, perform the following: 1. In the main menu of your website s backend, click Design Page Templates. 2. Click Create a Template. 3. In Name input field, enter a name for your template. 4. Select Don't use template (start from scratch). 5. Click Create this template. Your layout template is created. The next step is to configure your own grid of content placeholders. Design a layout template To create your own content blocks configuration, perform the following: 1. In the main menu of your website s backend, click Design Page Templates. 2. Click the template that you have created in the previous procedure. 3. Click Layout button in the upper-right upper. A list with predefined layout elements is appears in the right pane. 4. Drag predefined layout elements and drop them in the pink area. The pink area is getting yellow to suggest where you can drop a predefined element. You can use as many elements as you need to achieve the configuration you desire. For more information about using the Layout Editor, see Sitefinity 4.0 RC 2 User Guide Editing your page layout Modifying the layout. 5. To save your work, click Publish. Your layout template is arranged. You can further fine-tune the layout elements. For more information about resizing columns, editing spaces, and applying CSS classes, see Sitefinity 4.0 RC 2 User Guide Editing your page layout Modifying the layout Editing layout elements. Creating a layout template based on an existing template To create a template based on other template: 1. In the main menu of your website s backend, click Design Page Templates 2. Click Create a Template 4
3. In Name input field, enter a name for your template. 4. Select Use template and click Select another Template. 5. From the window, which appears, click a template, which will serve as basis for your new template. 6. Click Done. 7. Click Create this template. Your new template opens in the Layout editor, where you can divide and reorder the blocks as you desire. NOTE: Rules for nested templates: Changes of a template are applied to its child template. You cannot edit the parent template while editing the child template. If you delete a template all of its child templates and all pages that uses this template will be deleted. Creating a template Table of contents Creating a template using Master pages You can use Master pages to define placeholders in the layout together with more complex HTML structure in case the Layout editor cannot satisfy your needs. Place your.master files in: ~/App_Data/Sitefinity/WebsiteTemplates/YourTemplate/App_Master/ Creating the HTML structure The.master file is a simple HTML file with few additional specific.net tags. The following is a simple code of a.master page: File: ~/App_Data/Sitefinity/WebsiteTemplates/YourTemplate/App_Master/yourtemplate.master <%@ Master Language="C#" AutoEventWireup="true" CodeFile="MasterPage2.master.cs" Inherits="App_Master_MasterPage2" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml1- transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head runat="server"> <title></title> </head> <body> <form id="form1" runat="server"> <asp:scriptmanager ID="ScriptManager1" runat="server"> <div id="header"> <asp:contentplaceholder id="header" runat="server" /> </div> <div id="content"> <asp:contentplaceholder id="content" runat="server" /> </div> <div id="footer"> <asp:contentplaceholder id="footer" runat="server" /> </div> </form> </body> </html> The code above has the following differences from the standard HTML page: The head line before the DOCTYPE declaration. All of the body content is inside the form tag. In the form tag there is a ScriptManager responsible for the loading of the script and the styles in your.master file. 5
Content placeholders are placed inside some of the elements. Content placeholders are ASP.NET native tags that will tell Sitefinity where you want to have an editable area. Content placeholders are making the element that wrap them into a layout element. Adding an existing Master page in Sitefinity If you already have a Master page and you want to use it in Sitefinity, perform the following: 1. Place the file in folder ~/App_Data/Sitefinity/WebsiteTemplates/YourTemplate/App_Master/. 2. Go to Sitefinity s backend (http://<yoursite>/sitefinity) 3. In the main menu, click Design Page Templates. 4. Click Create a Template. 5. In Name input field, enter a name for your template. 6. Select Use template and click Select another Template. 7. Click Use your own.master file. 8. Browse the file in your App_Master folder and select the.master file. 9. Click Use Selected Create this template. In the current implementation of Sitefinity RC 2 there is no difference if you use some other folders in the root of the project. When your templates and themes are inside App_Data we allow you to dynamically control these files from Sitefinity's UI. In one of the next release we are going to make synchronization between marketplace and Sitefinity which will allow you to pick up themes directly from there and the only way to control this is using App_Data and its subfolders. If you want to redistribute a theme you should better use App_Data folder. If you just work locally there is no restriction to use folder like App_Themes. The folder App_Master was introduced by us in the older versions of Sitefinity - 3.x which was a global storage for templates. In 4.0 you can specify the path to your templates from the UI and there is no point for using App_Master as a storage. When you are working in Visual Studio it is more convenient to use folders like App_Master and App_Themes. When you are ready with the development and you can go live and distribute the project you can move your files under ~/App_Data/Sitefinity/WebsiteTemplates/ In 4.0 we allow you to create a template directly from the UI and actually you do need a physical master file in your project. Creating a template Table of contents Including JavaScript and CSS resources If you need to include JavaScript code or CSS code in your website, use one of the following approaches: If you are using Master pages, add the CSS and JavaScript in your.master page, using HTML. Add CSS and JavaScript on your pages or templates using Sitefinity build-in widgets. For more information, see Sitefinity 4.0 RC 2 User Guide Displaying content using widgets Scripts and Styles widgets group Configuring the CSS widget. and Configuring the Java Script widget. Creating a template Table of contents CREATING A THEME In Sitefinity 4.0 RC 2 themes are part of the website templates. You can set custom colors, images, and styles for the different layout templates. The following is a simple scheme of a theme s folder content: 6
NOTE: Folder Global is mandatory. If the folder is missing it is not possible to register or load the theme. Section contents Registering a theme Using XML file to order the loading of the CSS files Applying a theme Table of contents Registering a theme If you already have prepared a theme for Sitefinity 4.0 RC 2, you must register it in your site s backend. To register a theme in your site, perform the following: 1. Place you theme inside any of the App_Themes folders. For example, place the template in folder /App_Data/Sitefinty/WebsiteTemplates/YourTemplate/App_Themes/YourTheme. 2. Go to Sitefinity s backend (http://<yoursite>/sitefinity) 3. In the main menu, click Administration Settings. The Basic Settings page appears. 4. To open all setting, click Advanced. The Settings page appears. 5. From the left menu expand the section Appearance. 6. Click Appearance Frontend themes. 7. Click Create new button. A form for new theme appears. 8. In Name input field, enter a name for the theme. 9. In Path input field, enter the physical path to your theme. For example, enter ~/App_Data/Sitefinity/WebsiteTemplates/YourTemplate/App_Themes/YourTheme. 10. To finish the registration of the theme, click Save changes. Your theme is registered and can be assigned to your layout templates. 7
Creating a theme Table of contents Using XML file to order the loading of the CSS files In Global folder of you theme file structure you can place as many CSS files as you want, but if you need to load them in specific order, you must describe them in cssloadorder.xml. The file must be placed in Global folder and it has the following content: File: ~/App_Data/Sitefinity/WebsiteTemplates/YourTemplate/App_Themes/MyTheme/Global/cssLoadOrder.xml <?xml version="1.0" encoding="utf-8"?> <cssfiles> <file>reset.css</file> <file>layout.css</file> <file>colors.css</file> <file>font_styles.css</file> </cssfiles> The sequence of loading the files will be according to their arrangement in cssloadorder.xml. Creating a theme Table of contents Applying a theme If you have prepared themes you can assign them to your template. After assigning theme to a template all pages that are using this template will use the theme also. To assign theme to a template, perform the following: 1. In the main menu of your website s backend, click Design Page Templates. 2. Click on the name of the template that you want to bind with a theme 3. In the upper-right corner click Theme. 4. From the dropdown menu select a theme that you want to assign to the template. 5. To save your changes, click Publish. Creating a theme Table of contents USING WIDGET TEMPLATES With widget templates you can change the look of the build-in Sitefinity widgets Blog posts, News, Events, Generic content, Images, Videos, etc. Section contents If you want to create new widget templates or edit the current templates there are two approaches: Using the Sitefinity s Widget templates editor. The Widget template editor in Sitefinity 4.0 RC 2 is an easy and intuitive way to create or edit widget templates directly in Sitefinity backend. With this approach you do not need to download the files, edit them, and reload them again. All of the properties of the widget are listed in the editor and with ready-to-use syntax. Using external file (.ascx) You can point the widget the path to an external file that contains its template an.ascx file. We recommend this approach in case of using Code-Behind logic and some very complex scenarios. Table of contents Using the Widget templates editor You use the Widget templates editor to create and edit templates for your widgets directly in Sitefinity backend. Section contents 8
To use your own template for a widget, perform the following: Create a new widget template Apply the template to the widget Using widget templates Table of contents Creating a new widget template 1. Go to Sitefinity s backend (http://<yoursite>/sitefinity) 2. In the main menu, click Design Widget Templates. 3. Click Create a template. 4. In the This template is applied to... dropdown box, select the widget for which you want to create a template For example if you want to create new template for the single post item view of the blogs, select Blogs posts single. 5. In the text area, write your code for the template. 6. To insert a property field of the widget, in the template click the desired field from the right menu. A window displaying the syntax of the field appears. 7. To add the sample code, in the text area, click Insert. 8. When you have entered the code, in Template name field, enter name of your template. 9. To save your work, click Create this template. NOTE: For your widget template to work properly, you need some specific declarations. For example, the Document Single template must have the following declarations: <%@ Control Language="C#" %> <%@ Register TagPrefix="telerik" Namespace="Telerik.Web.UI" Assembly="Telerik.Web.UI" %> <%@ Register TagPrefix="sf" Namespace="Telerik.Sitefinity.Web.UI" Assembly="Telerik.Sitefinity" %> <%@ Register TagPrefix="sf" Namespace="Telerik.Sitefinity.Web.UI.ContentUI" Assembly="Telerik.Sitefinity" %> <%@ Register Assembly="Telerik.Sitefinity" Namespace="Telerik.Sitefinity.Modules.Libraries.Web.UI.Documents" TagPrefix="sfLibraries" %> To find the correct declarations for your template you can go and edit some of the templates that are coming with Sitefinity. Using the Widget templates editor Using widget templates Table of contents Applying a widget template created with the widget templates editor To apply a template to a widget, perform the following: 1. Go to Sitefinity s backend (http://<yoursite>/sitefinity) 2. Click Pages. 3. Click the page that you want to edit. 4. Add the widget to your page and open it for editing. For more information about adding and configuring widgets, see Sitefinity 4.0 RC 2 User Guide Displaying content using widgets. 5. On List Settings tab, in the List template box, select the widget template you want to apply. The following screenshot displays the List template box of the Blog posts widget: 9
6. Click Save. The editing mode of the widget closes. 7. To save the changes to the page, click Publish. The widget, which you have added to the page, is using the template that you have selected. Using the Widget templates editor Using widget templates Table of contents Using external widget template file If you want to use external (.ascx) files for your widget templates you must placed them in WidgetTemplates folder that is in your website template folder. The following scheme displays the structure: The content in your external widget template file is the same as the content of the template in the widget templates editor. You can use the same fields and syntax to achieve the desired result. Applying external widget template To apply an external widget template to a widget, perform the following: 1. Go to Sitefinity s backend (http://<yoursite>/sitefinity). 2. Click Pages. 10
3. Click the page that you want to edit. 4. Add the widget to your page and open the advanced editing mode. For more information about adding and configuring widgets, see Sitefinity 4.0 RC 2 User Guide Displaying content using widgets. 5. Click ControlDefinition Views. 6. Select a view for the widget. For example, NewsFrontendDetails or NewsFrontendList. 7. In field TemplatePath, enter the path to the widget template. For example: ~/App_Data/Sitefinity/WebsiteTemplates/YourTemplate/WidgetTemplates/Blogs/List/BlogList.ascx. 8. Click Save. The advanced editing mode closes. 9. To apply the changes to the page, click Publish. NOTE: A possible reason for an error message in the layout editor can be the incorrect path to the widget template. Using widget templates Table of contents 11