Liquid (OrchardCore.Liquid
)¶
This module provides a way to create templates securely from the admin site.
For more information about the Liquid syntax, please refer to this site: https://shopify.github.io/liquid/
General concepts¶
HTML escaping¶
All outputs are encoded into HTML by default.
This means that any HTML reserved chars will be converted to the corresponding HTML entities.
If you need to render some raw HTML chars you can use the raw
filter.
Content Item Filters¶
All the default filters that are available in the standard Liquid syntax are available in OrchardCore.
On top of that each Orchard module can provide custom filters for their own purpose.
Here is a list of common filters that apply to content items.
display_url
¶
Returns the URL of the content item.
Input
{{ Model.ContentItem | display_url }}
Output
/blog/my-blog-post
display_text
¶
Returns the title of the content item.
Input
{{ Model.ContentItem | display_text }}
Output
My Blog Post
slugify
¶
Convert a text into a string that can be used in a URL.
Input
{{ "This is some text" | slugify }}
Output
this-is-some-text
container
¶
Returns the container content item of another content item.
Input
{{ Model.ContentItem | container | display_text }}
In this example we assume ContentItem
represents a blog post.
Output
Blog
local
¶
Converts a UTC date and time to the local date and time based on the site settings.
Input
{{ "now" | local | date: "%c" }}
or
{{ Model.ContentItem.CreatedUtc | local | date: "%c" }}
Output
Wednesday, 02 August 2017 11:54:48
t
¶
Localizes a string using the current culture.
Input
{{ "Hello!" | t }}
Output
Bonjour!
html_class
¶
Converts a string into a friendly HTML class.
Input
{{ "LandingPage" | html_class }}
Output
landing-page
liquid
¶
Renders a liquid string template.
Input
{{ Model.ContentItem.Content.Paragraph.Content.Html | liquid }}
In this example we assume that Model.ContentItem.Content.Paragraph.Content
represents an HtmlField
, and Html
is the field value.
Output
<p> <img src="/blog/media/kitten.jpg" /> </p>
Optionally you can pass a class for model binding.
markdownify
¶
Converts a Markdown string to HTML.
Input
{{ "### Services" | markdownify }}
Output
<h3>Services</h3>
Properties¶
By default the liquid templates have access to a common set of objects.
Model.Content
¶
When available, a zone shape that contains all the shapes generated by the content's parts and fields.
Model.ContentItem
¶
When available, represents the current content item being rendered.
The following properties are available on the ContentItem
object.
Property | Example | Description |
---|---|---|
Id |
12 |
The id of the document in the database. |
ContentItemId |
4qs7mv9xc4ttg5ktm61qj9dy5d |
The common identifier of all versions of the content item. |
ContentItemVersionId |
4jp895achc3hj1qy7xq8f10nmv |
The unique identifier of the content item version. |
Number |
6 |
The version number. |
Owner |
admin |
The username of the creator of this content item. |
Author |
admin |
The username of the editor of this version. |
Published |
true |
Whether this content item version is published or not. |
Latest |
true |
Whether this content item version is the latest of the content item. |
ContentType |
BlogPost |
The content type. |
CreatedUtc |
2017-05-25 00:27:22.647 |
When the content item was first created or first published. |
ModifiedUtc |
2017-05-25 00:27:22.647 |
When the content item version was created. |
PublishedUtc |
2017-05-25 00:27:22.647 |
When the content item was last published. |
Content |
{ ... } |
A document containing all the content properties. See specific documentation for usage. |
Content property¶
The Content
property of a content item exposes all its elements, like parts and fields. It is possible to
inspect all the available properties by evaluating Content
directly. It will then render the full document.
The convention is that each Part is exposed by its name as the first level.
If the content item has custom fields, they will be available under a part whose name will match the content type.
For example, assuming the type Product
has a Text field named Size
, access the value of this field for a
content item as follows:
{{ Model.ContentItem.Content.Product.Size.Text }}
Similarly, if the content item has a Title
part, we can access it like this:
{{ Model.ContentItem.Content.TitlePart.Title }}
User¶
Represents the authenticated user for the current request.
The following properties are available on the User
object.
Property | Example | Description |
---|---|---|
Identity.Name |
admin |
The name of the authenticated user. |
Identity.Claims |
The claims of the authenticated user. |
User has_permission filter¶
Checks if the User has permission clearance, optionally on a resource
{{ User | has_permission:"EditContent",Model.ContentItem }}
User is_in_role filter¶
Checks if the user is in role
{{ User | is_in_role:"Administrator" }}
User has_claim filter¶
Checks if the user has a claim of the specified type
{{ User | has_claim:"email_verified","true" }} {{ User | has_claim:"Permission","ManageSettings" }}
Site¶
Gives access to the current site settings, e.g Site.SiteName
.
Property | Example | Description |
---|---|---|
BaseUrl |
The base URL of the site. | |
Calendar |
The site's calendar. | |
Culture |
en-us |
The site's default culture as an ISO language code. |
MaxPagedCount |
0 |
The maximum number of pages that can be paged. |
MaxPageSize |
100 |
The maximum page size that can be set by a user. |
PageSize |
10 |
The default page size of lists. |
SiteName |
My Site |
The friendly name of the site. |
SuperUser |
admin |
The user name of the site's super user. |
TimeZoneId |
America/Los_Angeles |
The site's time zone id as per the tz database, c.f., https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
UseCdn |
false |
Enable/disable the use of a CDN. |
ResourceDebugMode |
Disabled |
Provides options for whether src or debug-src is used for loading scripts and stylesheets |
CdnBaseUrl |
https://localhost:44300 |
If provided a CDN Base url is prepended to local scripts and stylesheets |
Request¶
Represents the current request.
The following properties are available on the Request
object.
Property | Example | Description |
---|---|---|
QueryString |
?sort=name&page=1 |
The query string. |
ContentType |
application/x-www-form-urlencoded; charset=UTF-8 |
The Content-Type header. |
ContentLength |
600 |
The Content-Length header. |
Cookies |
Usage: Request.Cookies.orchauth_Default |
The collection of cookies for this request. |
Headers |
Usage: Request.Headers.accept |
The request headers. Each property value is an array of values. |
Query |
Usage: Request.Query.sort |
The query value collection parsed from QueryString . Each property value is an array of values. |
Form |
Usage: Request.Form.value |
The collection of form values. |
Protocol |
https |
The protocol of this request. |
Path |
/OrchardCore.ContentPreview/Preview/Render |
The path of the request, unescaped. |
PathBase |
/mytenant |
The base path of the request, unescaped. |
Host |
localhost:44300 |
The Host header. May contain the port. |
IsHttps |
true |
True if the scheme of the request is https . |
Scheme |
https |
The scheme of the request. |
Method |
GET |
The HTTP method. |
Culture¶
Represents the current culture.
The following properties are available on the Culture
object.
Property | Example | Description |
---|---|---|
Name |
en-US |
The request's culture as an ISO language code. |
Dir |
rtl |
The text writing direction. |
Shape Filters¶
These filters let you create and filter shapes.
shape_new
¶
Returns a shape with the specified name as input.
Input
{% assign date_time = "DateTime" | shape_new %}
You can also pass properties when creating the shape.
Property names get converted to PascalCase. Ex: prop_name1
can be accessed via Model.PropName1
in the shape template.
{{ Model.Content | shape_new: prop_value1: "some value", prop_value2: 5 }}
shape_render
¶
Renders a shape.
{{ Model.Content | shape_render }}
shape_stringify
¶
Converts a shape to its string representation. Unlike shape_render
, the result of this filter will
be encoded if rendered in the output.
Input
{{ "DateTime" | shape_new | shape_stringify }}
Output
Monday, September 11, 2017 3:29:26 PM
shape_properties
¶
Returns a shape with the added properties.
Property names get converted to PascalCase. Ex: prop_name1
can be accessed via Model.PropName1
in the shape template.
Input
{% assign my_shape = "MyCustomShape" | shape_new | shape_properties: prop_value1: "some value", prop_value2: 5 %}
Layout Tags¶
layout
¶
Sets the layout of a view.
Input
{% layout "CustomLayout" %}
Internally an alternate is added to the current theme Layout
shape.
render_body
¶
In a layout, renders the body of the current view.
Input
{% render_body %}
render_section
¶
In a layout, renders the section with the specified name.
Input
{% render_section "Header", required: false %}
page_title
¶
Alters and renders the title of the current page.
Input
{% page_title Site.SiteName, position: "before", separator: " - " %}
The default parameter is a text that is appended to the current value of the title.
position
is where the value is appended, in this example at the beginning.
separator
is a string that is used to separate all the fragments of the title.
Shape Tags¶
shape_clear_alternates
¶
Removes any alternates from a shape.
Input
{% shape_clear_alternates my_shape %}
shape_add_alternates
¶
Adds alternates to a shape.
Input
{% shape_add_alternates my_shape "alternate1", "alternate2" %} {% shape_add_alternates my_shape "alternate1 alternate2" %}
shape_clear_wrappers
¶
Removes any wrappers from a shape.
Input
{% shape_clear_wrappers my_shape %}
shape_add_wrappers
¶
Adds wrappers to a shape.
Input
{% shape_add_wrappers my_shape "wrapper1", "wrapper2" %} {% shape_add_wrappers my_shape "wrapper1 wrapper2" %}
shape_clear_classes
¶
Removes any classes from a shape.
Input
{% shape_clear_classes my_shape %}
shape_add_classes
¶
Adds classes to a shape.
Input
{% shape_add_classes my_shape "class1 class2" %} {% shape_add_classes my_shape "class1", "class2" %}
shape_clear_attributes
¶
Removes any attributes from a shape.
Input
{% shape_clear_attributes my_shape %}
shape_add_attributes
¶
Adds attributes to a shape.
Input
{% shape_add_attributes my_shape attr_name1: "value1", attr_name2: "value2" ... %}
shape_add_properties
¶
Adds properties to a shape. This can be useful to pass values from a parent shape.
Property names get converted to PascalCase.
Ex: prop_name1
can be accessed via Model.PropName1
in the shape template.
Input
{% shape_add_properties my_shape prop_name1: "value1", prop_name2: 2 %}
shape_remove_property
¶
Removes a property from a shape by name.
Input
{% shape_remove_property my_shape "prop_name1" %}
shape_type
¶
Sets the type of a shape.
Input
{% shape_type my_shape "MyType" %}
Whenever the type is changed, it is recommended to clear the shape alternates before using the shape_clear_alternates
tag.
shape_display_type
¶
Sets the display type of a shape.
Input
{% shape_display_type my_shape "Summary" %}
Whenever the display type is changed, it is recommended to clear the shape alternates first.
shape_position
¶
Sets the position of a shape.
Input
{% shape_position my_shape "Content:before" %}
shape_tab
¶
Sets the tab of a shape.
Input
{% shape_tab my_shape "properties" %}
shape_remove_item
¶
Removes a shape by its name in a Zone.
Input
{% shape_remove_item Model.Content "HtmlBodyPart" %} {{ Model.Content | shape_render }}
In this example, the Model.Content
property evaluates to a zone shape, typically from a Content Item shape template, which contains the HtmlBodyPart
shape
rendered for the Body Part element. This call will remove the specific shape named HtmlBodyPart
.
shape_pager
¶
Replaces the properties of a Pager shape.
Input
{% shape_pager Model.Pager next_class: 'next', next_text: '>>' %}
shape_build_display
¶
Creates the display shape for a content item. It can be used in conjunction with shape_render
to render a content item.
Input
{{ mycontentitem | shape_build_display: "Detail" | shape_render }}
shape
¶
Creates and renders a new shape, with optional caching arguments.
Input
{% shape "menu", alias: "alias:main-menu", cache_id: "main-menu", cache_expires_after: "00:05:00", cache_tag: "alias:main-menu" %}
When using the shape tag a specific wrapper and / or alternate can be specified.
{% shape "menu", alias: "alias:main-menu", alternate: "Menu_Footer" %}
shape_cache
¶
Sets the caching parameters of a shape.
Input
{% shape_cache my_shape cache_id: "my-shape", cache_expires_after: "00:05:00" %}
For more information about the available caching parameters please refer to this section
zone
¶
Renders some HTML content in the specified zone.
Input
{% zone "Header" %} <!-- some content goes here --> {% endzone %}
The content of this block can then be reused from the Layout using the {{ Model.Header | shape_render }}
code.
Tag Helper tags¶
ASP.NET Core MVC provides a set of tag helpers to render predefined HTML outputs. The Liquid module provides a way to call into these Tag Helpers using custom liquid tags.
link
¶
Invokes the link
tag helper from the Orchard.ResourceManagement
package.
meta
¶
Invokes the meta
tag helper from the Orchard.ResourceManagement
package.
resources
¶
Invokes the resources
tag helper from the Orchard.ResourceManagement
package.
script
¶
Invokes the script
tag helper from the Orchard.ResourceManagement
package.
style
¶
Invokes the style
tag helper from the Orchard.ResourceManagement
package.
a
¶
Invokes the a
content link tag helper from the OrchardCore.Contents
package.
antiforgerytoken
¶
Renders a <hidden>
element (antiforgery token) that will be validated when the containing <form>
is submitted.
Example
{% antiforgerytoken %}
helper
and block
¶
Allows custom Razor TagHelpers to be called from liquid.
For attributes (HtmlAttributeName) use camel-case and replace all -
with _
.
Helper Tag example
{% helper "mycustomtag", customAttribute: "foo" %}
Block Tag example
{% block "mycustomtag", customAttribute: "foo" %} {% endblock %}
Razor Helpers¶
LiquidToHtmlAsync
¶
To render a liquid string template as IHtmlContent
within Razor use the LiquidToHtmlAsync
helper extension method on the view's base Orchard
property, e.g.:
Input
@await Orchard.LiquidToHtmlAsync((string)Model.ContentItem.Content.Paragraph.Content.Html)
In this example we assume that Model.ContentItem.Content.Paragraph.Content
represents an HtmlField
, and Html
is the field value, and we cast to a string, as extension methods do not support dynamic dispatching.
Output
<p> <img src="/media/kitten.jpg" /> </p>
Optionally you can pass a class for model binding.
CREDITS¶
Fluid¶
https://github.com/sebastienros/fluid
Copyright (c) 2017 Sebastien Ros
MIT License