Templates (OrchardCore.Templates
)¶
The templates module allows editors to create custom Liquid templates.
Available templates¶
Templates can be defined using the web editor, or in a theme. Templates are distinguished by their name.
Orchard Core doesn't render HTML directly, but instead will usually render something called a Shape, which is an object that represents
the thing to render and has all the necessary data and metadata to render HTML.
When rendering a Shape, Orchard Core will look for specific templates, passing the Shape to this template.
Orchard Core can match with many templates for the same Shape.
These potential templates are called Alternates.
A Shape contains a list of acceptable template names (the alternates) and will look into providers to get the most appropriate one.
For instance, when rendering a Content Item of type Article, the corresponding Shape that is rendered will be configured
to look for a template that handles all articles, but also one that handles an article when used in a list, and so on.
This document provides a list of pre-defined templates that can be used when rendering shapes.
It uses the internal name of a template and also the filename in case it's provided by a Theme.
Content templates¶
Content__[ContentType]
¶
This template is called when displaying a content item with the Detail
display type, for instance when accessed from its own URL.
Content Examples¶
Template | Filename |
---|---|
Content__BlogPost |
Content-BlogPost.cshtml |
Content__Article |
Content-Article.cshtml |
Content Available properties¶
Property | Description |
---|---|
Model.Content |
A zone shape that contains all the shapes generated by the content's parts and fields. |
Model.ContentItem |
Represents the current content item being rendered by the template. |
Model.ContentItem.Content |
A JSON object containing all the data of the content item. |
Content_[DisplayType]__[ContentType]
¶
This template is called when displaying a content item with a specific display type.
For instance, when a content item is displayed in a list, the Summary
display type is commonly used.
Content with Display Type Examples¶
Template | Filename |
---|---|
Content_Summary__BlogPost |
Content-BlogPost.Summary.cshtml |
Content_Summary__Article |
Content-Article.Summary.cshtml |
Widget templates¶
Widget__[ContentType]
¶
This template is called when a widget is rendered on a page.
Widget Examples¶
Template | Filename |
---|---|
Widget__Paragraph |
Widget-Paragraph.cshtml |
Widget__Blockquote |
Widget-Blockquote.cshtml |
Widget Available properties¶
Property | Description |
---|---|
Model.Content |
A zone shape that contains all the shapes generated by the widget's parts and fields. |
Model.ContentItem |
Represents the current content item being rendered by the template. |
Model.ContentItem.Content |
A JSON object containing all the data of the content item. |
Model.Classes |
An array of all the classes attached to the widget. |
Content Part templates¶
Each driver is free to return a shape type of its choosing, but the usage is
to render a content part using a shape with a name that matches the type name.
For instance the HtmlBodyPart
content part will return a single shape of type HtmlBodyPart
, but the ListPart
returns many
shapes, one among them being ListPart
.
As a consequence the following list of templates use the [ShapeType]
term where
most of the time it will be equal to the name of the content part. The examples use
common content part names for this reason.
Properties¶
The properties available on a shape rendered for a content part are unique for each content part. Please refer to the documentation for each content part.
[ShapeType]
¶
This template is called when a Content Part is rendered.
Shape Examples¶
Template | Filename |
---|---|
HtmlBodyPart |
HtmlBodyPart.cshtml |
ListPartFeed |
ListPartFeed.cshtml |
[ShapeType]_[DisplayType]
¶
This template is called when a Content Part shape type is rendered in a specific display type.
Shape with Display Type Examples¶
Template | Filename |
---|---|
HtmlBodyPart_Summary |
HtmlBodyPart.Summary.cshtml |
[ContentType]_[DisplayType]__[PartType]
¶
This template is called when a content part type is rendered for a given content type, with or without a given display type.
Content with Part Name Examples¶
Template | Filename |
---|---|
Blog__HtmlBodyPart |
Blog-HtmlBodyPart.cshtml |
LandingPage__BagPart |
LandingPage-BagPart.cshtml |
Blog_Summary__HtmlBodyPart |
Blog-HtmlBodyPart.Summary.cshtml |
LandingPage_Summary__BagPart |
LandingPage-BagPart.Summary.cshtml |
[ContentType]_[DisplayType]__[PartName]
¶
This template is called when a content part name is rendered for a given content type, with or without a given display type.
Content with Part Type Examples¶
Template | Filename |
---|---|
LandingPage__Services |
LandingPage-Services.cshtml |
LandingPage_Summary__Services |
LandingPage-Services.Summary.cshtml |
[ContentType]_[DisplayType]__[PartType]__[ShapeType]
¶
This template is called when a shape type is rendered in a given content part type for a given content type, with or without a given display type.
Content with Part Name and Shape Examples¶
Template | Filename |
---|---|
Blog__ListPart__ListPartFeed |
Blog__ListPart__ListPartFeed.cshtml |
Blog_Summary__ListPart__ListPartFeed |
Blog__ListPart__ListPartFeed.Summary.cshtml |
[ContentType]_[DisplayType]__[PartName]__[ShapeType]
¶
This template is called when a shape type is rendered in a given content part name for a given content type, with or without a given display type.
Content with Part Name and Custom Shape Examples¶
Template | Filename |
---|---|
LandingPage__Services__CustomShape |
LandingPage-Services-CustomShape.cshtml |
LandingPage_Summary__Services__CustomShape |
LandingPage-Services-CustomShape.Summary.cshtml |
Widget parts¶
All the previous alternates can be used by replacing [ContentType]
with Widget
whenever a content type has the stereotype Widget
. This also applies
to any stereotype other than Content
.
Content Field templates¶
Each driver is free to return a shape type of its choosing but the usage is
to render a content field using a shape with the same type name.
For instance the TextField
content field will return a single shape of type TextField
,
but other fields might return many shapes.
Shape Properties¶
The properties available on a shape rendered for a content field are unique for each content field. Please refer to each content field documentation.
[ShapeType]_[DisplayType]
Field¶
This template is called when a content field type is rendered in a given display type.
Field And Display Type Examples¶
Template | Filename |
---|---|
TextField_Summary |
TextField.Summary.cshtml |
[PartType]__[FieldName]
¶
This template is called when a content field name is rendered for a given content part type when the shape type matches the field type, with or without a given display type.
Part Type and Field Examples¶
Template | Filename |
---|---|
HtmlBodyPart__Description |
HtmlBodyPart-Description.cshtml |
HtmlBodyPart_Summary__Description |
HtmlBodyPart-Description.Summary.cshtml |
[ContentType]__[PartName]__[FieldName]
¶
This template is called when a content field name is rendered for a given content type and content part name when the shape type matches the field type, with or without a given display type.
Content Type, Part Name and Field Name Examples¶
Template | Filename |
---|---|
Blog__HtmlBodyPart__Description |
Blog-HtmlBodyPart-Description.cshtml |
LandingPage__Services__Image |
LandingPage-Services-Image.cshtml |
Blog_Summary__HtmlBodyPart__Description |
Blog-HtmlBodyPart-Description.Summary.cshtml |
LandingPage_Summary__Services__Image |
LandingPage-Services-Image.Summary.cshtml |
[ContentType]__[FieldType]
¶
This template is called when a content field type is rendered for a given content type when the shape type matches the field type, with or without a given display type.
Content Type and Field Type Examples¶
Template | Filename |
---|---|
Blog__TextField |
Blog-TextField.cshtml |
LandingPage__TextField |
LandingPage-TextField.cshtml |
[FieldType]__[ShapeType]
¶
This template is called when a content field shape type is rendered for a given content field type, with or without a given display type.
Field Type and Shape Type Examples¶
Template | Filename |
---|---|
CustomField__CustomFieldSummary |
CustomField-CustomFieldSummary.cshtml |
CustomField_Summary__CustomFieldSummary |
CustomField-CustomFieldSummary.Summary.cshtml |
[PartType]__[FieldName]__[ShapeType]
¶
This template is called when a content field shape type is rendered for a given content field name in a given content part type, with or without a given display type.
Part Type, Field Name and Shape Type Examples¶
Template | Filename |
---|---|
HtmlBodyPart__Description__CustomFieldSummary |
HtmlBodyPart__Description__CustomFieldSummary.cshtml |
HtmlBodyPart_Summary__Description__CustomFieldSummary |
HtmlBodyPart__Description__CustomFieldSummary.Summary.cshtml |
[ContentType]__[PartName]__[FieldName]__[ShapeType]
¶
This template is called when a content field shape type is rendered for a given content field name in a given content part name in a given content type, with or without a given display type.
Content Type, Part Name, Field Name and Shape Type Examples¶
Template | Filename |
---|---|
Blog__HtmlBodyPart__Description__CustomFieldSummary |
Blog-HtmlBodyPart-Description-CustomFieldSummary.cshtml |
LandingPage__Services__Description__CustomFieldSummary |
LandingPage-Services-Description-CustomFieldSummary.cshtml |
Blog_Summary__HtmlBodyPart__Description__CustomFieldSummary |
Blog-HtmlBodyPart-Description-CustomFieldSummary.Summary.cshtml |
LandingPage_Summary__Services__Description__CustomFieldSummary |
LandingPage-Services-Description-CustomFieldSummary.Summary.cshtml |
[ContentType]__[FieldType]__[ShapeType]
¶
This template is called when a content field shape type is rendered for a given content field type in a given content type, with or without a given display type.
Content Type, Field Type and Shape Type Examples¶
Template | Filename |
---|---|
Blog__TextField__TextFieldSummary |
Blog-TextField-TextFieldSummary.cshtml |
LandingPage__TextField__TextFieldSummary |
LandingPage-TextField-TextFieldSummary.cshtml |
Shape differentiators¶
The differentiator uniquely identifies a shape in a zone. When rendering a content item, the shape has a Content
property that contains
all the shapes provided by content display drivers, including the ones for content parts and content fields.
Differentiators can be used to configure the placement information (c.f. Placement documentation page), or to access specific shapes in a zone using these template helpers:
Content Part differentiator¶
If the shape type is the same as the content part name, the shape will be named [PartName]
, e.g. HtmlBodyPart
, Services
.
If the shape type is different than the content part name, it will be [PartName]-[ShapeType]
, e.g. ListPart-ListPartFeed
Content Field differentiator¶
If the shape type is the same as the content field name, the shape will be named [PartName]-[FieldName]
, e.g. HtmlBodyPart-Description
, Services-Image
.
If the shape type is different than the content field name, it will be [PartName]-[FieldName]-[ShapeType]
, e.g. HtmlBodyPart-Description-CustomFieldSummary
, Services-Image-ImageFieldSummary
Razor¶
Access a specific shape by name:
Model.Content.HtmlBodyPart
Removing a specific shape by name:
Model.Content.Remove("HtmlBodyPart");
Liquid¶
Display a shape after removing a specific shape by name:
{% shape_remove_item Model.Content "HtmlBodyPart" %} {{ Model.Content | shape_render }}
Display a specific shape by name:
{{ Model.Content.HtmlBodyPart | shape_render }}
To access or render the shapes for a field that is added to the content type directly, the [PartName]
is equal to the content type.
For instance, given a content type Article
with a Text field named Description
, the shapes for this field would be named "Article-Description"
. To render these shapes in Liquid:
{{ Model.Content["Article-Description"] | shape_render }}
In this example the index syntax is necessary, because the name of the differentiator is not compatible with Liquid language.
Instead of rendering the shape directly, you can also access its properties. In the case of a text field you have access to the Field
property which has a Text
property.
{{ Model.Content["Article-Description"].Field.Text }}
Overriding Views¶
Some modules (namely the OrchardCore.Users module) allow you to override some of its views in your Theme. Since these views are not shapes, the way to override them is a little different than mentioned above.
View Resolution paths¶
The ThemeViewLocationExpanderProvider.cs
file defines the search paths used by the RazorViewEngine.
Views/{2}/{1}/{0}.cshtml Views/{2}/Shared/{0}.cshtml Views/Shared/{0}.cshtml
- 2 = area / module
- 1 = controller
- 0 = action
Overriding Login view¶
For example, if you want to override the OrchardCore.Users\Views\Account\Login.cshtml
view you would need to create a file in your theme and place it under YourTheme\Views\OrchardCore.Users\Account\Login.cshtml
.
For this particular file, you would also need to select the Use site theme for login page
option under the Configuration->Login
page in the admin.