Developers Guide. Designs and Layouts HOW TO IMPLEMENT WEBSITE DESIGNS IN DYNAMICWEB. Version: English

Transcription

1 Developers Guide Designs and Layouts HOW TO IMPLEMENT WEBSITE DESIGNS IN DYNAMICWEB Version: English

2 Designs and Layouts, How to implement website designs in Dynamicweb LEGAL INFORMATION Copyright 2013 Dynamicweb Software A/S (Ltd). All rights reserved. Alteration or reproduction of this document or parts hereof is strictly prohibited, regardless of form or means, unless explicit permission has been acquired from Dynamicweb Software. Dynamicweb is a registered trademark of Dynamicweb Software. Company and product names mentioned in this document may be registered trademarks or trademarks of third parties Dynamicweb Software A/S (Ltd). ii

3 Designs and Layouts, How to implement website designs in Dynamicweb CONTENTS Introduction v What this document is about... v Who this document is for... v Related documents... v Revision history... v 1 Designs Concept Location Layouts What is a layout? Installing a layout Applying a layout Making the layout template dynamic Content placeholders Navigation Requirements Search forms Send to friend Printing Using media print Using alternative layout template Paragraphs content Placeholders Default placeholder Changing a placeholder Paragraph templates Applying a paragraph template Location Default placeholder paragraph template Placeholder settings Editor CSS Static content images, CSS and JS 22 6 Using master pages 23 7 Template tags Master and page tags Extending layout templates Parsing Dynamicweb Software A/S (Ltd). iii

4 Designs and Layouts, How to implement website designs in Dynamicweb Contents 8.1 How parsing works what it does, how and where Head node settings Content placeholders Navigation Search forms Overruling the parsing procedure Keeping your markup Miscellaneous Requirements Changing layout for pages Dynamicweb Software A/S (Ltd). iv

5 Designs and Layouts, How to implement website designs in Dynamicweb INTRODUCTION What this document is about This document explains how to implement designs in Dynamicweb 7.1 and future versions. It introduces the concept of Designs and Layouts and explains how these templates are composed and used. Who this document is for This document is for frontend developers and designers that needs to implement the overall design of a Dynamicweb solution. Related documents Technical Release Notes, Dynamicweb 7.1: Describes technical issues included in Dynamicweb 7.1. Revision history Documentation updates: Using master pages (6 th July 2010): Document updated with information on using master pages. See 6 Using master pages. Bug fixes/improvements: : InlineStylesheet template tag no longer includes background-image from Dynamicweb stylesheet : Stylesheets template tag no longer includes the external CSS chosen on the Dynamicweb stylesheet : Possibility to overrule parsing of Title-tag, Content placeholders and navigation. See 8.2 Overruling the parsing : Using parenttag and sitemap settings for navigations. Using sort setting for paragraphs Dynamicweb Software A/S (Ltd). v

6 Designs and Layouts, How to implement website designs in Dynamicweb 1 DESIGNS 1.1 Concept Designs and Layouts are a concept introduced with Dynamicweb 7.1 to really improve the time and effort when implementing a design in Dynamicweb. A design is a collection of layouts. A layout is an html file containing the markup that makes up an entire webpage layout. Example 1 design and layout structure Design 1 (Folder on disk) o Front Page (File on disk i.e. Frontpage.html) o Sub Front Page (SubFrontPage.html) o Content Page (ContentPage.html) o Product Page (ProductPage.html) This new approach handles several issues with the current way of implementing designs. Today the design, templates and setup is dependent on some registration in the administration. This information is placed in the database and makes it cumbersome to move a design from one solution to another. This new approach makes it possible to copy a design from one solution to another in matter of minutes. It takes a great deal of knowledge regarding the Dynamicweb template hierarchy to setup a design. You have to split the html of the design in several different templates making it not that transparent. Paragraph setup templates are needed in order to have multiple containers for content. This requires setup on every page and an editor needs to learn how to use the paragraph setup concept. All of these issues are eliminated or minimized with the new approach. Layout templates are Extremely fast to implement Easy to understand Provides you with total design freedom Can be copied from one solution to another Are contextual so templates for one website is not used on other websites Layout templates are a compilation of the previous Master, Page and Paragraph setup templates all of which is deprecated when using the layouts approach. Dynamicweb 7.1 ( ) is required in order to use this implementation approach. Released May Location Layout templates are placed in a new folder in the main Templates folder. The root location of the new templates is /Files/Templates/Designs/. Each design is a collection of Layouts. Every design has its own subfolder of Designs, and the name of that folder is the name of the design as shown in the following: Version Dynamicweb Software A/S (Ltd). 1

7 Figure 1. Design location and folder structure. Throughout this document we will use a design called Condition giving a subfolder with that name: /Files/Templates/Designs/Condition/. Version Dynamicweb Software A/S (Ltd). 2

8 Designs and Layouts, How to implement website designs in Dynamicweb 2 LAYOUTS 2.1 What is a layout? A layout is simply a html file that makes a webpage layout. It consists of one html file containing markup and whatever CSS, JS and image files, which are necessary to complete a layout. For this guide a free downloaded example from will be used ( 2.2 Installing a layout A layout is installed by copying the required files to the design folder (/Files/Templates/Designs/Condition/) where Condition is the name of this design. Figure 2. The layout files copied to the appropriate folder. The layout can now be previewed either by double clicking Index.html, which opens the file in a new browser window or by accessing the URL where it is located, e.g.: The layout is now installed on the solution and that is it! 2.3 Applying a layout It can now be applied to a website (area) in Dynamicweb so it will be used on pages created in for that website. Go to the website properties (Websites or Frontpage module), and choose the Layout ribbon tab. Version Dynamicweb Software A/S (Ltd). 3

9 Figure 3. The Layout tab. In the layout dropdown choose the layout just added (Condition) to the design repository. Save and preview the page. Figure 4. Preview of the website with the assigned layout. It is now a Dynamicweb page showing the layout, but it has no dynamic content it is just showing the layout as it was downloaded. Revising the source code will reveal some changes in the references for the included CSS, JS and image files though. Version Dynamicweb Software A/S (Ltd). 4

10 3 MAKING THE LAYOUT TEMPLATE DYNAMIC 3.1 Content placeholders To alter the layout template to show content from Dynamicweb instead of the static content it already contains in the markup, content placeholders have to be defined. A content placeholder is a location in the markup where the output of the paragraphs of that page will be displayed. A content placeholder can be any html element in the layout template and you can define as may placeholders as you like. Content placeholders are defined by applying a CSS class to the html elements that we want to be dynamic. Open the layout template in an appropriate html editor and locate the html element that should act as a placeholder. Given the layout in our example, the layout file (index.html), is opened and the markup that contains the main content is located the piece of text starting with Welcome to Condition. See Fejl! Henvisningskilde ikke fundet.. To change the static html to a Dynamic content placeholder, set the class attribute to dwcontent and set the title on the html element. A basic requirement for a valid content placeholder, is that the element has an ID, class= dwcontent and a title. Figure 5. Editing the layout setting content placeholders. If the content placeholder html element already has a CSS class specified, simply add dwcontent to the list of classes, e.g.: <div class= myclass dwcontent ></div>. After defining the content placeholder, it can now be seen in the administration. Version Dynamicweb Software A/S (Ltd). 5

11 Figure 6. A content placeholder shows up in the administration. Create a paragraph with some content and preview the page. The content from the paragraph is now displayed in the newly defined content placeholder. Figure 7. Preview with a content placeholder and some content. The layout now has one dynamic content area. The layout also has some text in the left column that needs to be dynamic (see above). Go back to the markup of the layout template and locate the markup that contains the text in the left column. Change it to a placeholder by adding dwcontent as the CSS class, and enter an ID and a title. Version Dynamicweb Software A/S (Ltd). 6

12 Figure 8. Second placeholder. The layout now has 2 dynamic content place holders. The newly created placeholder appears in the administration as shown below. Figure 9. Second dynamic placeholder. Add some content by right clicking the placeholder header, choose New paragraph. Preview the page to see the result. Version Dynamicweb Software A/S (Ltd). 7

13 Figure 10. Preview with 2 dynamic content placeholders. An unlimited number of content placeholders can be created but make sure the ID is unique (also a W3C requirement). 3.2 Navigation The next step is to make the navigation dynamic so it represents the navigation structure of the website. The navigation for layout templates relies on XML/XSLT based navigation. Locate the markup in the layout that holds the navigation. Assign an ID and a class named dwnavigation to the UL element. Figure 11. Defining a dynamic navigation. By doing only this, the navigation uses a set of default values to render navigation and uses a default layout template (LIClean.xslt). Preview the page to see the result. Version Dynamicweb Software A/S (Ltd). 8

14 Figure 12. Dynamic navigation. The navigation is now dynamic using the default values. This layout has room for sub navigation items below the left content container. Locate the markup in the layout template to make this dynamic. By adding dwcontent as the class attribute and an ID, it will use the default values and generate a navigation with the same items as in the top navigation. Figure 13. Sub navigation with top pages. The default values can be overruled by adding a Dynamicweb specific attribute to the UL tag called settings. Version Dynamicweb Software A/S (Ltd). 9

15 Figure 14. Settings for a navigation item. Preview the page after applying the new settings. Figure 15. Subpage navigation with settings. In the table below it is possible to see all available settings and their default values. Available settings: Property Description Default Possible values startlevel endlevel template expandmode parentid parenttag The absolute level from which the XML should include navigation items from The absolute level to which the XML should include navigation items to Name of XSLT template used for parsing the navigation XML How the navigation XML expands and which nodes it includes. Limits the navigation to items placed under the page with the ID specified Limits the navigation to items placed under the page with a specific navigation tag. It LIClean.xslt Path Any valid existing navigation XSLT template. Must be placed in /Templates/Navigation, /Templates/Designs/Navigation or /Templates/Design/DesignName/Navigation None, Path, All, Pathonly 0 Any valid page id A name from the parent tag field on a pages properties, navigation dialog. Version Dynamicweb Software A/S (Ltd). 10

16 areaid sitemapmode works like parentid setting, but where parentid is a unique key, the parent tag can be on several pages in different languages and the value is language/website context sensitive. Limits the navigation to items placed under the area/website with the ID specified Specifies which items to include in the XML. If set to true, hidden navigation items are included, but not items where show in sitemap is not set. If set to false, hidden items are not included, but do not show in sitemap are included. 0 Any valid area/website id (these can be seen under the Websites module) False True or False In the following you can see an example using some of the settings. It will display all navigation items in level 2 below the page with ID 2131 using the template LIClean.xslt. Figure 16. Example of static navigation using all settings. In the following example see the use of parent tag setting Requirements It has to be a UL element that defines the navigation. If the navigation markup in a layout template is not wrapped in an UL it has to be wrapped in that before it can be made a dynamic navigation. Version Dynamicweb Software A/S (Ltd). 11

17 Figure 17. Defining navigation for non-ul based markup. 3.3 Search forms Search forms can also be made dynamic. Start by creating a page in Dynamicweb and attach the search module to a paragraph on that page. Figure 18. Page with search. Locate or add the form in the layout template that you want to use as search form and apply a class named dwsearch. Version Dynamicweb Software A/S (Ltd). 12

18 Figure 19. Defining a search form. Preview the website and try performing a search using the search form in the layout template. Figure 20. A search result from the layouts search form. 3.4 Send to friend Adding a send to friend functionality can be accomplished by using the Add This ( or Add To Any ( services which are available as template tags in Dynamicweb. Figure 21. Adding an Add This feature to the layout template. Preview the website with the new settings. Version Dynamicweb Software A/S (Ltd). 13

19 Figure 22. Preview of the send to friend feature included in Add this. 3.5 Printing Using media print It is recommended to use the media attribute on stylesheet references to do printer friendly versions of the content. Create a separate print stylesheet and include it in the head section of the layout and apply the print media attribute. Figure 23. Using the media CSS attribute to show printer friendly pages. Add This and Add To Any also provides printer friendly features. See section 3.4 Send to friend on how to set this up. Version Dynamicweb Software A/S (Ltd). 14

20 Figure 24. Using add this for printer friendly pages Using alternative layout template It is also possible to apply an alternative layout template for printing purposes with different layout. Create a layout template specific for printing and add a link to the page with at parameter that specifies the alternate template. LayoutTemplate=Designs/Condition/Print.html Figure 25. Using an alternate layout template for printing. Clicking the print link will result in the page being rendered using the alternative template. Figure 26. Using an alternative layout template. Version Dynamicweb Software A/S (Ltd). 15

21 4 PARAGRAPHS CONTENT 4.1 Placeholders Multiple placeholders can be created for each layout template. The ID of the content placeholder acts as the reference to the paragraphs that are inserted in that placeholder. The ID of the content placeholder which the paragraph belongs to is registered in the database (Dynamic.mdb), in the Paragraph table, under the ParagraphContainer column. Content or paragraphs can be moved from one content placeholder to another simply by dragging it to another location in the list of paragraphs on the page (as shown below). Figure 27. Moving content from one placeholder to another. The placeholder for a paragraph can also be changed by clicking Layout under the Options tab when editing a paragraph. Figure 28. Changing the content placeholder under the paragraph settings. Version Dynamicweb Software A/S (Ltd). 16

22 4.2 Default placeholder When a layout is applied, the existing content (paragraphs) on the pages will be linked to the default content placeholder. The default placeholder is the first one in the markup. This can be changed through the settings attribute on the HTML element defining the content placeholder by adding settings= default:true. Figure 29. Changing the default content container using the settings attribute. 4.3 Changing a placeholder If there is a need to change an existing placeholder in the layout template, be aware that it can move content around. If the ID of a content placeholder element is changed it will lose the reference to the paragraphs linked to that placeholder. They will then be linked to the default content container instead. The name of the content placeholder (title attribute) can be changed it is simply a name used in the administration and a change will not break anything. 4.4 Paragraph templates When configuring a website to use layout templates instead of legacy Dynamicweb stylesheets, another set of paragraph templates are used. If the paragraphs where created in a stylesheet context and have a paragraph template attached, they will be ignored after applying the layout Applying a paragraph template When editing a paragraph, the template selector shows a list of paragraph templates. By default the paragraph will not get a template attached that will be done on runtime using the content placeholders default paragraph template. By choosing a paragraph template under the paragraph settings you force Dynamicweb to display the paragraph using that specific template. Figure 30. Choosing a paragraph template. Version Dynamicweb Software A/S (Ltd). 17

23 4.4.2 Location Paragraph templates for layouts are by default located under /Files/Templates/Designs/Paragraph. The paragraph template selector creates a list of templates inside that folder. The templates can be made contextual so different designs and layouts can have different paragraph templates. This can be accomplished by creating a paragraph template folder inside a design folder (e.g. /Files/Templates/Designs/Condition/Paragraph.), which will limit paragraphs will to only use paragraph templates from that design. Figure 31. Creating a paragraph template folder for a specific design. By creating a paragraph folder in the design folder, all layouts share the same set of paragraph templates. This can be limited even more so that one layout in a design can have a specific set of paragraph templates. This is done by creating a folder in the design folder with the name of the layout file and place a paragraph folder in that, i.e. /Files/Templates/Designs/Condition/Index/Paragraph. Figure 32. Creating a paragraph template folder for a specific layout. By doing this, pages using the layout /Condition/index.html can only use templates from /Condition/Index/Paragraph folder Default placeholder paragraph template By default all paragraphs on pages using layouts do not have a paragraph template attached to them. They will use the default template that applies for that content placeholder or for that layout. If no paragraph template is specified on the paragraph, it will look for a template in this order: Version Dynamicweb Software A/S (Ltd). 18

24 1. If the content placeholder has a paragraph template specified, that will be used. See Fejl! Henvisningskilde ikke fundet.. 2. Otherwise if the nearest context paragraph template folder contains a paragraph template called Default.html, that will be used. See Fejl! Henvisningskilde ikke fundet.. 3. Otherwise the first template in the nearest context paragraph template folder will be used 4. Fallback to the first template in /Files/Templates/Paragraph. Figure 33. Defining the default paragraph template for a content container. Figure 34. Defining the default paragraph template in the nearest context folder. 4.5 Placeholder settings In the table below it is possible to see all available settings and their default values. Available settings Property Description Default Possible values default template sort removeid Specifies if the content placeholder is default or not. If more than one content placeholder is set to true, the first one in the markup will be used. Reference to default paragraph template to use for this specific content placeholder. Defines the sort order of the placeholders in the paragraph list in the administration. Tells the parser to remove the id attribute when creating the parsed file. Relevant if the ID is not needed or when creating xml. False True False 99 Location to a valid paragraph template file, i.e.: False Designs/Paragraph/Left.html Or simply specify a name and it will be located recursively: left.html Must be placed in /Templates/Paragraph, /Templates/Designs/ Paragraph or /Templates/Design/DesignName/ Paragraph True False Example: Version Dynamicweb Software A/S (Ltd). 19

25 Figure 35. Settings for a content placeholder. 4.6 Editor CSS By default the editor in the administration uses the first CSS file found in the layout used on the page. This can be overruled by creating a file in the design folder called Editor.css containing basic styles for use in the Editor. Figure. Placing a Editor.css file The CSS file should contain styles for body (body), headings (h1, h2, h3), paragraphs (p), lists (ul, ol, li) and links (a). Version Dynamicweb Software A/S (Ltd). 20

26 Figure. Example of Editor.css file Version Dynamicweb Software A/S (Ltd). 21

27 5 STATIC CONTENT IMAGES, CSS AND JS Referencing static content like images, CSS and JS is done using the relative path in the layout template. Files can be organized as shown in the example below. Figure 36. Location of static content and external scripts. Usage of images, CSS and JS files is done simply by referencing them relatively to where the layout template is located. Figure 37. Adding static references. Dynamicweb automatically handles the references when the layout template is used. Version Dynamicweb Software A/S (Ltd). 22

28 6 USING MASTER PAGES It is possible to reuse markup across different layouts by using Master pages. The concept is known from ASP.NET and works in the same way. A master page can be used across several layouts that share the same markup for e.g. headers, navigations and footer. A master page is created by defining placeholders for the html markup of the different layouts. This is done by using the following template tag: <!--@ContentPlaceholder--> Figure 38. Inserting the placeholder tag in the master template. In the layout template a master page is defined in the first line of the html: <!--@MasterPageFile(Master.html)--> Figure 39. Defining the master page. Before the parsing initiates, the master template is merged with the layout template meaning that the content of the layout template is inserted where the tag is located in the master page. Version Dynamicweb Software A/S (Ltd). 23

29 7 TEMPLATE TAGS 7.1 Master and page tags Layout templates can use the same template tags as are available for Master and Page templates: Also all general tags from Dynamicweb are available: Layout templates are proxied through the Master and Page template objects in the pageview and have all the same capabilities. Insert to see all available tags in a layout template. 7.2 Extending layout templates Layout templates can be extended using the same template extenders as for page and master templates. See below for examples. Figure 40. Extending a layout template using a page template extender. Figure 41. Extending a layout template using a notification subscriber. Version Dynamicweb Software A/S (Ltd). 24

30 8 PARSING A layout template is parsed before it is used in the frontend. This is done to make the template dynamic, update all references to static files and to add the capabilities it needs to be a template. The parsing relies on valid markup the parsing will fix minor errors, but if the markup is in bad shape, the parsing might not work as expected. 8.1 How parsing works what it does, how and where A layout template is parsed whenever it is changed and the parsed version of the template is placed in the same location as the original with.parsed added to the filename. Using a layout template called index.html results in a parsed template called index.parsed.html in the same location. Figure 42. The location of the parsed template. The parsing handles a number of things that Dynamicweb relies on to work as intended. These include the following things: Title tag Meta tags Stylesheet and javascript tags References to static content like images, CSS and JS Content placeholders Navigations Search forms See below for an example of an unparsed and parsed layout template. Version Dynamicweb Software A/S (Ltd). 25

31 Figure 43. Unparsed layout template. Figure 44. Parsed layout template. Version Dynamicweb Software A/S (Ltd). 26

32 8.1.1 Head node settings It is possible to disable the parsing of the head node so that the parser does not insert title tags, metatags, scripts etc. Available settings Property Description Default Possible values disableparsing If set to true, the head node will not be parsed and Title, MetaTags, CopyRightNotice, InlineStylesheet, Stylesheets and JavaScripts tags are not inserted. If any is needed, you have to insert them. False True False Figure 45. Unparsed head section Content placeholders Content placeholders are parsed using the following rules: 1. The added dwcontent class is removed from the element 2. Title attribute is removed 3. Inner html of the element is replaced with a template tag, <!--@DwContent(contentPlaceholderID)--> Figure 46. Unparsed content placeholder. Version Dynamicweb Software A/S (Ltd). 27

33 Figure 47. Parsed content placeholder Navigation Navigations are parsed using the following rule: The entire element (always a UL) is removed and replaced with a template tag, <!--@DwNavigation(NavigationID)--> Since the entire UL tag is replaced with the template tag, remember to take CSS classes and element ID into consideration. If they layout depend on these, make sure to move them to the layout template. Figure 48. Unparsed navigation element. Figure 49. Parsed navigation element Search forms Search forms are parsed using the following rules: 1. The added dwsearch class is removed from the form element 2. Action attribute is set to /Default.aspx 3. Method is set to get 4. A hidden field with name ID is added with the value of which will return the first page ID on that website that contains a search module. 5. The first input element of type text is changed to have the name q. If no input element of type text exists, one will be created. Version Dynamicweb Software A/S (Ltd). 28

34 Figure 50. Unparsed search form. Figure 51. Parsed search form. 8.2 Overruling the parsing procedure The parser has some rules for where to insert the different elements such as Dynamicweb template tags. If the location chosen by the parser is causing problems, e.g. because of the sequence of CSS files, simply insert the template tag in the original layout template at the desired location the parser will not insert them if they already exist. On the contrary content placeholders and navigations cannot be overruled like this the system needs this information and reads them from the original Keeping your markup It is possible to have the parser leave your HTML and text alone. Consider a title tag like this: <title>condition by Free CSS Templates</title> - it will be parsed to <title><!--@title--></title>. Title This can be overruled by adding the template tag to your layout template and the parser will not manipulate the existing markup or text. <title><!--@title--> - Condition</title> will not be parsed because the required template tag is already there the parsed template will look like the original: <title><!--@title--> - Condition</title>. Content containers The same can be accomplished for content containers. By default the inner html of the container is replaced with a template tag. Version Dynamicweb Software A/S (Ltd). 29

35 Figure 52. The original template. Figure 53. The template parsed. By adding the content template tag to the original, the parser will leave the inner html making it possible to overrule the parser. Figure 54. Adding the DwContent template tag to the original layout template. Navigations By default the outer html of the navigation is replaced with a template tag. Figure 55. The original template. Figure 56. The template parsed. By adding the navigation template tag (<!--@DwNavigation ([idofnavigation])-->) to the original, the parser will leave the outer html making it possible to overrule the parser. Version Dynamicweb Software A/S (Ltd). 30

36 Figure 57. Adding the DwNavigation template tag to the original layout template. Figure 58. The parsed navigation with html from the original template. Version Dynamicweb Software A/S (Ltd). 31

37 9 MISCELLANEOUS 9.1 Requirements Layout templates have these requirements Html, cshtml and xml files are supported (*.htm, *.html, *.xml, *.cshtml, *.vbhtml) The markup have to be (more or less) valid html o The parser relies on valid html/xml and will try to fix potential issues but really messed up markup will not work. XSLT templates are not supported. 9.2 Changing layout for pages You can choose a different layout template for a specific page under Page properties > Layout tab. The layout chosen applies to only that page. By checking the Inherit to subpages the layout is applied to all pages in the structure placed as a child to the page. Figure 59. Choosing an alternate layout template for a page. Version Dynamicweb Software A/S (Ltd). 32