(en-US) Razor Templates

Developers Guide
Razor templates
HOW TO USE RAZOR BASED TEMPLATES IN DYNAMICWEB
Version: 1.0
2013.06.24
English
Razor templates, How to use Razor based templates 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.
2013 Dynamicweb Software A/S (Ltd).
ii
CONTENTS
Introduction _________________________________ v
What this document is about..................................................... v
Who this document is for .......................................................... v
Related documents ................................................................... v
Revision history ........................................................................ v
What is Razor ____________________________ 1

1.1
Introduction.................................................................... 1
1.1.1 Read more ......................................................................... 1
1.2
Razor vs. ASP.NET MVC .............................................. 2
Using Razor in Dynamicweb ________________ 3

2.1
2.3
Using a Razor template ................................................. 3

Tags .............................................................................. 4
2.3.1 Tag values ......................................................................... 5
2.4
2.5
2.6
Loops ............................................................................ 6
Conditionals................................................................... 8
Convert HTML templates to Razor ................................ 8
2.6.1 Editing Razor templates ................................................... 11
2.7
Layouts in Razor _________________________ 13

3.1
3.2
3.3
3.4
The @model ................................................................ 12

Content placeholders ................................................... 13
Navigation ................................................................... 14
Using master pages and sections ................................ 15
Attribute values ............................................................ 16
Differences and similarities ________________ 17

4.1
4.2
4.3
Snippets ...................................................................... 17
Global tags .................................................................. 18
Date extension tags ..................................................... 19
iii
Contents
iv
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 8.2.3. See http://developer.dynamicwebcms.com/releases/dynamicweb-8.2.3.aspx
Revision history
Documentation updates:
First version (12th June, 2013): Released
Bug fixes/improvements:
8.2.3.2: Introduces a GlobalTags property to the PageView object to get hold of the
global tags known from the HTML based templates.
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: http://www.asp.net/mvc/mvc4
Dynamicweb 8.2.3 (8.2.3.0) is required in order to use this implementation approach.

Released May 2013
1.1.1 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 1.0
1.2
What is Razor
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 the @Html and
@Url which are ASP.NET MVC specific helper classes.
Version 1.0
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 1.0
2.3
Using Razor in Dynamicweb
Tags
To get the value of a tag, use a method called GetValue:
@GetValue("ParagraphText")
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 1.0
2.3.1 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 GetString:
@{
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 1.0
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 this:
@foreach (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
object:
@foreach (LoopItem i in GetLoop("Images"))
{
<div>
@i.GetValue("Gallery.Image.Thumb.Medium")
</div>
}
The full loop example would look like this:
Figure 5. Razor template loop syntax.

Version 1.0
And the HTML version of the same template
Figure 6. HTML template loop syntax.
Version 1.0
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# http://msdn.microsoft.com/en-us/library/5011f09h.aspx
2.6
Read
more on
condition
als in C#
Dynamicweb has the possibility of converting an existing HTML based template to Razor
http://ms
(C#).
dn.micro
soft.com/
enThere are two ways of converting an existing HTML template to Razor.
us/library
/5011f09
h.aspx
1. From any template selector where a HTML template is selected (See Figure 2),
Convert HTML templates to Razor
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 1.0
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 1.0
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 1.0
10
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 ()
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.
2.6.1 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: http://manual.dynamicwebcms.com/Dynamicweb-On-line-Manual/Management-Center/Web-andHTTP/WebDAV.aspx. Any other text based editor can be used as well.
Version 1.0
11
2.7
The @model
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 this:
@Model.PropertyName
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 use @Model yet. @Model.Template can be used, but is not guaranteed to stay
on the Model.
Version 1.0
12
LAYOUTS IN RAZOR
3.1
Content placeholders
Layouts in Razor
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 1.0
13
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 1.0
14
3.3
Layouts in Razor
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 1.0
15
3.4
Layouts in Razor
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 1.0
16
DIFFERENCES AND SIMILARITIES
4.1
Snippets
Differences and similarities
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  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 1.0
17
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  tag. In Razor that would translate
into @GetValue(Global:Area.ID) 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 1.0
18
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:
http://templates.dynamicweb-cms.com/TemplateTags/Dynamicweb-templatetags/General-tags/Date/time-tag-extensions.aspx
The extended tags are not available in the Razor context.
@GetValue() 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 the @GetDate() 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 http://msdn.microsoft.com/enus/library/system.datetime.aspx
Figure 22. Using GetDate and .NET date formatting.
Date extension tags are not available in Razor templates. Use @GetDate() and .NET
date formatting instead.
Version 1.0
19

(en-US) Razor Templates

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

(en-US) Razor Templates

Cargado por

Copyright:

Formatos disponibles

Developers Guide

Razor templates, How to use Razor based templates in Dynamicweb

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

What is Razor ____________________________ 1

Razor vs. ASP.NET MVC .............................................. 2

Using Razor in Dynamicweb ________________ 3

Using a Razor template ................................................. 3

Layouts in Razor _________________________ 13

The @model ................................................................ 12

Differences and similarities ________________ 17

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Who this document is for

Release Notes, Dynamicweb 8.2.3: Describes features and technical issues

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Figure 1. Razor example.

Dynamicweb 8.2.3 (8.2.3.0) is required in order to use this implementation approach.

1.1.1 Read more

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Razor vs. ASP.NET MVC

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

USING RAZOR IN DYNAMICWEB

Using a Razor template

Figure 2. Selecting a Razor template.

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Using Razor in Dynamicweb

The GetValue method will return a representation of the property specified

Figure 3. Razor template tag syntax.

Figure 4. HTML template tag syntax.

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Using Razor in Dynamicweb

2.3.1 Tag values

Available Get* methods:

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Using Razor in Dynamicweb

The full loop example would look like this:

Figure 5. Razor template loop syntax.

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Using Razor in Dynamicweb

And the HTML version of the same template

Figure 6. HTML template loop syntax.

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Using Razor in Dynamicweb

Figure 7. Conditional example in C#.

Read more on conditionals in C# http://msdn.microsoft.com/en-us/library/5011f09h.aspx

Convert HTML templates to Razor

click the Edit icon ( ).

2013 Dynamicweb Software A/S (Ltd).

Razor templates, How to use Razor based templates in Dynamicweb

Using Razor in Dynamicweb

Figure 3. The file editor with a HTML template.

2013 Dynamicweb Software A/S (Ltd).