Twig Functions

Herbie is using Twig Functions for generating content in layout and content files. In addition to the built-in functions of Twig itself, the following functions are available.

css_add

Adds a CSS asset to the HTML page.

Parameter Type Description Default
paths string|array One or more paths to CSS resources.
attr array Attribute for the HTML tag. []
group string A name to group the CSS. null
raw bool Returns CSS inline instead of as a link. false
pos int The sort order of the CSS asset. -1
[return] void
Example:
{{ css_add("@site/themes/styles.css", {class: "styles"}, "default", false, 1) }}

css_classes

Returns a string with CSS classes, to be used within an HTML attribute, for example the html or body tag. This allows to address any page, theme, layout or language via CSS selector. Such a string looks like: "page-blog theme-default layout-blog language-en"

Parameter Type Description Default
[return] string The string with CSS classes.
Example:
{{ css_classes() }}

css_out

Outputs the CSS assets for a given group.

Parameter Type Description Default
group string The grouped CSS. null
timestamp bool If true, a GET param with the modification timestamp of the file is added.
[return] void The CSS assets
Example:
{{ css_out("default") }}

image

Returns an image markup tag. No image processing is performed.

Parameter Type Description Default
src string The relative web path to the image file.
width int The width of the image. 0
height int The height of the image. 0
alt string The alt text of the image. ""
class string The HTML class attribute. ""
[return] string The image markup
Example:
{{ image("media/portrait.jpg", 100, 200, "Portrait", "photo") }}

js_add

Adds a JavaScript asset to the HTML page.

Parameter Type Description Default
paths string|array One or more paths to JavaScript resources.
attr array Attribute for the HTML tag. []
group string A name to group the JavaScript. null
raw bool Returns JavaScript inline instead of as a link. false
pos int The sort order of the JavaScript asset. -1
[return] void
Example:
{{ js_add("@site/themes/script.js", {class: "scripts"}, "default", false, 1) }}

js_out

Outputs the JavaScript assets for a given group.

Parameter Type Description Default
group string The grouped JavaScript. null
timestamp bool If true, a GET param with the modification timestamp of the file is added.
[return] string The JavaScript assets
Example:
{{ js_out("default") }}

Returns a link to a file with additional info like file type and size.

Parameter Type Description Default
path string The relative web path to the file.
label string The label for the HTML tag. "
info bool If true file info will be added after the link. false
attribs array One or more HTML attributes. [ ]
[return]
Example:
{{ link_file("media/download.pdf", "Download", true, {class:"download"}) }}

Returns a HTML mailto link.

Parameter Type Description Default
email string The email.
label string The label.
attribs array The HTML attributes passed as an associative array.
template string The aliased path to the template file.
[return] string The mailto link
Example:
{{ link_mail("me@example.com", "John Doe", {class: "link-page"}, "@snippet/link.twig") }}

Returns a HTML link with a file from site/media folder.

Parameter Type Description Default
path string The path to the file in site/media folder.
label string The label.
info bool Adds info with file size und file extension.
attribs array The HTML attributes passed as an associative array.
[return] string The link to a file
Example:
{{ link_media("dummy.pdf", "My dummy file", true, {class: "link-file"}) }}

Returns a HTML link with label and attributes for a given route or an URL.

Parameter Type Description Default
route string The route or the URL to a page.
label string The label.
attribs array The HTML attributes passed as an associative array.
[return] string The link to a route
Example:
{{ link_page("doc/contents/variables", "Content variables", {class: "link-page"}) }}

Creates a text based (=ascii) tree of all pages. All parameters are optional and passed as named parameters.

Parameter Type Description Default
route string The tree from the given route. ""
depth int The maximum depth level of the tree (-1 = unlimited). -1
hidden bool Show hidden pages. false
[return] string The tree rendered as ascii text
Example:
{{ menu_ascii_tree("doc", 2, true) }}

Returns a breadcrumb path for the given page. All parameters are passed as an associative array.

Parameter Type Description Default
delim string The delim. ""
home array|string The link to the homepage. An array must be like [route, label]. ""
reverse bool Reverse the breadcrumb. false
[return] string The breadcrumb path as HTML.
Example:
{{ menu_breadcrumb(" / ", ["", "Homepage"], true) }}

Returns a paginated list of page items with links to the first, previous, next, and last page. For the paging the GET query parameter "page" is used.

Parameter Type Description Default
where array|string The where clauses to be applied internally in query builder. ""
order callable|string The order field to be applied internally in query builder. ""
shuffle bool If true the menu list is shuffled first. false
limit int The pagination limit 10
template string The path to the twig template. @snippet/menu_list.twig
[return] string The rendered markup
Example:
{{ menu_list("type=blog", "-title", false, 10, "@snippet/menu_list.twig") }}

Creates a pagination with links to the previous an next page within the current page branch. All parameters are optional and passed as named parameters (see twig).

Parameter Type Description Default
limit string Limits the pagination to a certain branch of the page tree.
prev_label string The label for the "previous" link. If empty the page title will be shown.
next_label string The label for the "next" link. If empty the page title will be shown.
prev_icon string The icon for the "previous" link.
next_icon string The icon for the "next" link.
class string The CSS class name for the element. Various other class names are assembled from this class name.
template string The template. <div class="{class}">{prev}{next}</div>
[return] string The generated markup
Example:
{{ pager("doc/contents/", "Previous", "Next", "&lt;", "&gt;", "nav-pager", "<div class=\"{class}\">{prev}{next}</div>") }}

Creates a simple sitemap for all pages of the website based on an unordered list. All parameters are optional and passed as named parameters.

Parameter Type Description Default
route string Limits the sitemap to a certain branch of the page tree. ""
depth int The maximum depth level of the sitemap. -1
hidden bool Show hidden pages. false
class string The CSS class name. sitemap
[return] string The generated markup
Example:
{{ menu_sitemap("doc", 1, false, "nav-sitemap") }}

Returns an HTML menu as unordered list. All parameters are optional and passed as named parameters.

Parameter Type Description Default
route string The menu from the given route. ""
depth int The maximum depth level of the tree. -1
hidden bool Show hidden pages. false
class string The CSS class for the menu. menu
[return] string The menu as unordered list
Example:
{{ menu_tree("doc", 1, false, "nav-menu") }}

page_title

Returns the SEO optimized page title of the website. All parameters are optional and passed as named parameters.

Parameter Type Description Default
delim string The delim. " / "
site_title string The title of the website. If set this title is appended on every page. null
root_title string The title of the root page of the website. If set this title is displayed on root page only. null
reverse bool Reverse the page title path. false
[return] string The page title of the website
Example:
{{ page_title(" / ", "My Blog", "Welcome to My Blog", true) }}

query

Find entries with the help of the built-in fluent query builder. The query builder can be applied to any type of iterable data structure. The queried data can be narrowed down, filtered, sorted and limited.

Parameter Type Description Default
iterator iterable The data to be queried. iterable
[return]
Example:
{{ query(data).where("type=page", "title*=news").limit(3).order("-date").all() }}

snippet

Includes a snippet and outputs the rendered content of that file. Automatic escaping is disabled for all escaping strategies.

Parameter Type Description Default
path string The path to the snippet.
context array The context variables to pass to the snippet. []
[return] string The included snippet
Example:
{{ snippet("@site/custom-snippet.twig", {foo: "bar"}) }}

translate

Translates a string according to the configuration and locale settings.

Parameter Type Description Default
category string The translate category
message string The message to translate
params array Params injected into translate function [ ]
[return] string The translated message
Example:
{{ translate("app", "Plugin {plugin} enabled but not found!", {plugin: "dummy"}) }}

url_abs

Returns the absolute URL for a given route.

Parameter Type Description Default
route string The route to a page.
[return] string The absolute URL.
Example:
{{ url_abs("doc/contents/variables") }}

url_rel

Returns the relative URL to a given route.

Parameter Type Description Default
route string The route to a page.
[return] string The relative URL.
Example:
{{ url_rel("doc/contents") }}

Built-in Functions

In addition to the functions mentioned above, Twig's built-in functions are of course also available. Please note that some of the functions may require the installation of additional Composer packages.