Developers Guide. Razor templates HOW TO USE RAZOR BASED TEMPLATES IN DYNAMICWEB. Version: English

Transcription

1 Developers Guide Razor templates HOW TO USE RAZOR BASED TEMPLATES IN DYNAMICWEB Version: English

2 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 CONTENTS Introduction v What this document is about... v Who this document is for... v Related documents... v Revision history... v 1 What is Razor Introduction Read more Razor vs. ASP.NET MVC Using Razor in Dynamicweb Using a Razor template Tags Tag values Loops Conditionals Convert HTML templates to Razor Editing Razor templates Layouts in Razor Content placeholders Navigation Using master pages and sections Attribute values Differences and similarities Snippets Global tags Date extension tags Dynamicweb Software A/S (Ltd). iii

4 Contents 2013 Dynamicweb Software A/S (Ltd). iv

5 INTRODUCTION What this document is about This document explains how to use Razor as the template language in Dynamicweb. Traditionally templates in Dynamicweb have been based on HTML and XSLT. This document explains how to convert to and use Razor templates. Who this document is for This document is for developers and designers that needs to implement design and modules in Dynamicweb and want to utilize the scripting capabilities of Razor based templates. Related documents Release Notes, Dynamicweb 8.2.3: Describes features and technical issues included in Dynamicweb See Revision history Documentation updates: First version (12 th June, 2013): Released Bug fixes/improvements: : Introduces a GlobalTags property to the PageView object to get hold of the global tags known from the HTML based templates Dynamicweb Software A/S (Ltd). v

6 1 WHAT IS RAZOR 1.1 Introduction Razor is an ASP.NET programming syntax released by Microsoft in January 2011 as one of the view engines for ASP.NET MVC. It is a template markup syntax and is a mix of HTML and.net code in the same file, like classic ASP and PHP. This means that templates have the simplicity of HTML and the power of.net. Where the HTML based templates in Dynamicweb have very limited scripting capabilities and requires.net based add-ins to do more advanced rendering logic, the Razor based templates have the possibility to utilize all of the Dynamicweb and.net APIs to perform the rendering. Figure 1. Razor example. Razor is maybe a new technology for some developers, but is fast to learn since it is HTML and.net (C# or VB) so not a new language, but a new combination of existing implementation methods. The benefits is that implementation and rendering logic can be developed faster and gives the developer full freedom to achieve a well working website. Do install ASP.NET MVC 4 when developing Razor templates in your Visual Studio for better syntax support: Dynamicweb ( ) is required in order to use this implementation approach. Released May Read more You can read more on Razor on these sites: 1. Learn the Razor syntax and capabilities 2. Introduction to ASP.NET Web Programming using the Razor Syntax 3. Introducing Razor 4. ASP.NET MVC 4 Version Dynamicweb Software A/S (Ltd). 1

7 What is Razor 1.2 Razor vs. ASP.NET MVC Razor was released as part of an ASP.NET MVC release. ASP.NET MVC is a Microsoft framework for building web applications and websites and is an alternative to classic ASP.NET with controls (.aspx). MVC means Model-vew-controller, which is a software architecture pattern. This pattern is what ASP.NET MVC is based on. Razor is one of more View engines available for ASP.NET MVC. The Dynamicweb Razor implementation is using the Razor view engine from ASP.NET MVC but Dynamicweb is not an ASP.NET MVC application. Dynamicweb is not an ASP.NET MVC application but uses the Razor view engine from ASP.NET MVC. ASP.NET MVC extends the capabilities in the Razor view engine and these capabilities are not available in Dynamicweb Razor templates. Examples could be which are ASP.NET MVC specific helper classes. Version Dynamicweb Software A/S (Ltd). 2

8 2 USING RAZOR IN DYNAMICWEB 2.1 Using a Razor template Everywhere in Dynamicweb where templates can be used, it is possible to change to use a Razor template instead of a HTML template. Razor templates are placed in the same folders as the HTML templates. Razor templates are named *.cshtml, *.cshtm, *.vbhtml or *.vbhtm. Cshtml means C# based Razor syntax, VBhtml means VB based Razor syntax. Figure 2. Selecting a Razor template. Upload your razor template to any template folder and select the template where you want to apply it. You do not have to change all templates to Razor. You can change just one or more templates as needed. Version Dynamicweb Software A/S (Ltd). 3

9 Using Razor in Dynamicweb 2.3 Tags To get the value of a tag, use a method called The GetValue method will return a representation of the property specified (ParagraphText) as a System.Object. This is a paragraph template and how it will look in Razor compared to HTML syntax. Figure 3. Razor template tag syntax. Figure 4. HTML template tag syntax. Version Dynamicweb Software A/S (Ltd). 4

10 Using Razor in Dynamicweb Tag values Tags in Dynamicweb HTML templates are always strings. When using Razor the tag values are in the type they are, either string, integer, boolean, double, long or date. When using GetValue("TagName") an object is returned containing the value. If the tag value has to be part of a conditional, needs to be formatted or otherwise be part of any code blocks, put the value into a variable of the correct type using type specific GetValue equivalents. Create a string variable using } string paragraphtext = GetString("ParagraphText"); Available Get* methods: GetValue("TagName") GetString("TagName") GetInteger("TagName") GetBoolean("TagName") GetDouble("TagName") GetLong("TagName") GetDate("TagName") These Get methods returns safe values meaning i.e. GetInteger will ALWAYS return a valid integer. If the passed tag name does not exist or is not an integer, it will return 0. If the original value is required, including null references etc, use i.e. (int)getvalue( TagName ) Version Dynamicweb Software A/S (Ltd). 5

11 Using Razor in Dynamicweb 2.4 Loops To loop elements in a Dynamicweb template loop, use a method called GetLoop: GetLoop("Images") The GetLoop method will return a Generic.List(Of LoopItem) of the loop name specified (Images) that can be iterated. The entire syntax could look like (LoopItem i in GetLoop("Images")) { //Loop items } Inside the foreach statement, the items of the loop are available in the current LoopItem (i) in the above example. To get a value of a property of a loopitem, use the GetValue method of the LoopItem (LoopItem i in GetLoop("Images")) { </div> } The full loop example would look like this: Figure 5. Razor template loop syntax. Version Dynamicweb Software A/S (Ltd). 6

12 Using Razor in Dynamicweb And the HTML version of the same template Figure 6. HTML template loop syntax. Version Dynamicweb Software A/S (Ltd). 7

13 Using Razor in Dynamicweb 2.5 Conditionals In Dynamciweb HTML templates conditionals are a Dynamicweb specific syntax. In Razor conditionals are regular.net syntax (C# or VB) and gives full programming capabilities against the template values. Figure 7. Conditional example in C#. Consider putting your tag value into a type specific variable if used in conditional statements for better intellisense support. Read more on conditionals in C# Convert HTML templates to Razor Dynamicweb has the possibility of converting an existing HTML based template to Razor (C#). There are two ways of converting an existing HTML template to Razor. 1. From any template selector where a HTML template is selected (See Figure 2), click the Edit icon ( ). 2. In the file manager in any template folder, list the templates, right click a HTML template and choose Edit. Both of these actions will open the file editor. Version Dynamicweb Software A/S (Ltd). 8

14 Using Razor in Dynamicweb Figure 3. The file editor with a HTML template. In the Ribbon, click the button Convert to Razor. This will convert the contents of the editor to Razor. Version Dynamicweb Software A/S (Ltd). 9

15 Using Razor in Dynamicweb Figure 4. The converted template. After the conversion, click the Save as... button, and rename the file to.cshtml Figure 5. Save the converted file to cshtml. Version Dynamicweb Software A/S (Ltd). 10

16 Using Razor in Dynamicweb The conversion will handle the most common scenarios in the HTML templates it will convert these things 1. Template tags 2. Loops 3. If Defined Defined(SomeTag)-->) More advanced template implementations are not converted (conditionals). The converter may not always convert all your code 100% correctly and you therefore need to manually validate the conversion to see if it is ok and make the needed changes to have it work fully. The conversion cannot be guaranteed to be 100% correct the converted file can have some syntax errors. These have to be handled manually Editing Razor templates Razor templates can be edited using the built in editor in the Dynamicweb File manager by right clicking in the list of filed and choose edit Figure 6. Editing Razor templates. The best editor for Razor templates is Visual Studio 2012 with ASP.NET MVC 4 installed. You can connect to the filemanager using webdav: cms.com/dynamicweb-on-line-manual/management-center/web-and- HTTP/WebDAV.aspx. Any other text based editor can be used as well. Version Dynamicweb Software A/S (Ltd). 11

17 Using Razor in Dynamicweb 2.7 In MVC and Razor, you normally access data properties on the Model dynamic object. In Dynamicweb, you can access Model but in this first implementation of Razor in Dynamicweb Model is not the type being rendered, but the Template instance in context. In Dynamicweb Razor templates you can access the model like The object returns a generic Dynamicweb.Rendering.RazorTemplateModel<t> where t is the model being rendered, for now Dynamciweb.Rendering.Template. In addition, the model has a Template property returning the same instance of Dynamciweb.Rendering.Template. In future Dynamicweb releases the Model will be the model being rendered, i.e. the PageView, Product, Item etc. Do not can be used, but is not guaranteed to stay on the Model. Version Dynamicweb Software A/S (Ltd). 12

18 Layouts in Razor 3 LAYOUTS IN RAZOR 3.1 Content placeholders Content placeholders in Razor based Layout files are defined in the same way as in the HTML based templates. See layout documentation (en-us) Designs and Layouts.pdf for full examples. Figure 8. Defining a placeholder in a Razor based layout file. The placeholder is defined by having a class (dwcontent), and id and a title attribute specified. None of these can contain Razor code. Do not use Razor code in the attributes of a placeholder. It is possible though, to add additional classes to the placeholder element using Razor. Just make sure the class name is added using a variable. The additional class name is then added runtime. The dwcontent class name has to be static. Figure 9. Using a variable as additional class names. Version Dynamicweb Software A/S (Ltd). 13

19 Layouts in Razor It is possible to test if a placeholder returns a value by checking if the tag containing the rendering of the content of the placeholder has a value. Figure 10. Using a conditional to check if a placeholder returns content. 3.2 Navigation Navigations in Razor based Layout files are defined in the same way as in the HTML based templates. See layout documentation (en-us) Designs and Layouts.pdf for full examples. Figure 11. Defining a dynamic navigation in a Razor based layout template. The template applied to the UL is a XSLT template and cannot be converted to a Razor template. The navigation is defined by having a class (dwnavigation), and id and a title attribute specified. None of these can contain Razor code. Do not use Razor code in the attributes of a navigation. Unlike placeholders, the class attribute cannot contain a Razor specified class. Wrap the entire UL in a div instead. Version Dynamicweb Software A/S (Ltd). 14

20 Layouts in Razor 3.3 Using master pages and sections Razor supports master pages (called layouts in Razor) and sections. Currently Dynamicwebs Razor implementation does not support the Razor syntax for using master pages. It is possible to use master pages in Dynamicwebs Razor implementation by using the regular syntax used for HTML based layout templates. Use the definition in the top of a layout template. Figure 12. Defining a master page in a Razor based layout template. The master template can be either html or cshtml. Dynamicweb will load and merge the master and layout template into one Razor template that will be parsed by the Razor engine as one. The content placeholder in the master template is defined using the ContentPlaceHolder tag. Even though it looks like a regular Dynamicweb template tag, it is not, so it has to follow this syntax. Figure 13. Defining the placeholder in the master template. Since the master and layout template are merged into one, they share context and the same Razor code can be used in both. Figure 14. Using Razor in the master template. Razor sections (@section) are defined in Razor views and rendered in the Razor layout file (Master page). Since Dynamicweb does not currently have a Razor layout file, sections are not supported. Snippets can be used instead of sections. Version Dynamicweb Software A/S (Ltd). 15

21 Layouts in Razor 3.4 Attribute values The attributes of HTML elements in a template can sometimes have the need for getting a Dynamic value defined in the code of the Razor code or have the value from a Dynamicweb template tag. Attributes in HTML are defined as attribute= value. In Razor it is possible to let the value be a code block. Figure 15. Using a code block as an attribute value. This will work just fine in all templates except Layout templates (/Templates/Designs/nameOfDesign/Layoutfile.html). Layout files are loaded as a DOM in Dynamicwebs layout engine and having code blocks with inside an attribute value will make the DOM parser fail. To use Razor in attribute values in Dynamicweb layout and master templates, define a variable with the value and use that variable as the attribute value. Do not use Razor code in the attributes values in layout files.do define a variable in a code block and use that variable as the attribute value. Figure 16. Correct syntax of Razor in attribute values in layout files. Figure 17. Wrong syntax of Razor in attribute values in layout files. Version Dynamicweb Software A/S (Ltd). 16

22 Differences and similarities 4 DIFFERENCES AND SIMILARITIES 4.1 Snippets Dynamicweb 8.2 introduced snippets. They define a piece of markup that is moved from one place in any template (source) to any other place in any template (destination). Snippets are defined using a HTML template syntax <!--@Snippet--> and in Razor templates this syntax is the same. This is because the snippets are not handled by the template engine itself, but by the output replacer. Define a snippet source with the SnippetStart and SnippetEnd tags. Figure 18. Defining a snippet source. And the destination Figure 19. Defining a destination. Version Dynamicweb Software A/S (Ltd). 17

23 Differences and similarities 4.2 Global tags Global tags in HTML templates gives the possibility to get hold of information from the execution context in any template, like Pageview, cart etc. Razor has the possibility to get access to everything because the Dynamicweb API can be utilized directly in the template. Therefore, global template tags are not available as regular tags when using a Razor template. It coulde be the <!--@Global:Area.ID--> tag. In Razor that would translate but this is not available in Razor templates. No Global.* tags are available from Razor using the GetValue, GetString etc. Instead of using the global tags, consider using the API instead. Figure 20. Using the API to get values normally available in Global tags. Using the API is the recommended approach. As an alternative the global tags can be accessed using the GetGlobalValue property. Figure 21. Using GetGlobalValue. Version Dynamicweb Software A/S (Ltd). 18

24 Differences and similarities 4.3 Date extension tags All tags that are dates in Dynamicweb HTML templates have a range of date extensions available. See the extensions here: The extended tags are not available in the Razor returns the value as an object of the specific type, and if used as is applied with a ToString and will fall back to the returned objects ToString method. When working with dates, use method which returns a DateTime object and use the date properties and date formatting methods available in.net to format to the proper date strings. See Figure 22. Using GetDate and.net date formatting. Date extension tags are not available in Razor templates. and.net date formatting instead. Version Dynamicweb Software A/S (Ltd). 19