Page Filters

Joomlatools Pages comes with page filters which allow you to process the content of a page. The filters are defined in the page frontmatter of either a page or a layout and apply to the page, its layout, and any partials that are loaded within the page or layout itself.

Some filters are enabled by default while others need to be specified in the frontmatter in order to be activated.

Table of Contents

• Inline partial
• Content Plugins
• Table of contents
• Code highlighter
• Multiple filters
• Responsive images
• Video filter
• Asset versioning

Inline Partial

To render an inline partial, that has a different format from the current page's format, use the <ktml:partial> tag and specify the format. This can, for example, be used to render a piece of Markdown inline.

Example:

<ktml:partial format="md">
    Markdown goes here...
</ktml:partial> 

Note: Partial rendering is enabled by default and doesn't need to be added to the page filters.

See also: Templates > Partials

Content Plugins

To pass content to the content plugins for processing, wrap the content in a <ktml:plugins>[...]</ktml:plugins> block.

Example:

<ktml:plugins>
    Content goes here
</ktml:plugins> 

The content is passed to the following plugin events:

• onContentBeforeDisplay
• onContentPrepare
• onConntentAfterDisplay

The result is returned and the <ktml:plugins></ktml:plugins> block is replaced with the result.

Plugin processing needs to be enabled by adding the plugins filter to the process:filters list in the page frontmatter.

process:
  filters: plugins

Table of contents

Generate a table of contents (toc) from a page's HTML headers by adding a <ktml:toc> tag to the page. By default, the toc will use <h1> to <h6>. The min and max headers can be configured using the min and max attributes. <ktml:toc min="2" max="4"> will only use the headings <h2>,<h3>,<h4>.

Dynamic anchors are added to the header tags automatically using anchor.js.

The table of contents filter needs to be enabled by adding the toc filter to the process:filters list in the page frontmatter.

process:
  filters: toc

Note: The TOC filter will only create links from within the <article> tag of a page.

Code highlighter

To use the code highlighter either use:

1. The default Markdown approach using triple backticks (```)
2. The advanced way using fenced code blocks. This is a feature of PHP Markdown Extra.
3. The html way using <pre><code class="[language]"></code></pre>. The default language is PHP.

Code highlighting needs to be enabled by adding the highlight filter to the process:filters list in the page frontmatter.

process:
  filters: highlight

The highlighter uses the Atom One Light style.

Multiple Filters

To use more than one template filter, wrap the set in square brackets:

process:
  filters: [toc, highlight]

Responsive image filter

Pages has implemented a responsive image filter that transforms a standard <img> element to a responsive image element.

It provides automatic lazy-loading, preloading of critical images, correct sizing across devices, and automatically supports modern formats with images from any source (including remote images).

Full documentation of this filter can be found on the responsive image filter page.

Video filter

Pages implements video player support through a video template filter which transforms a standard html <video> element to a a full fledged video player. The template filter makes use of the popular https://plyr.io/ video player.

Features

1. HTML5 video player

Plyr is a simple, lightweight, accessible and customizable HTML5, YouTube and Vimeo media player that supports modern browsers. For a complete list of features and customisation options please check: https://github.com/sampotts/plyr#features

2. Lazy video loading

The video player is automatically lazy-loaded using the Lazysizes js library meaning that it's only rendered when the user is close to seeing the video player. This prevents loading videos that are images outside of the initial viewport.

3. Poster image support

Pages can generate an optimised poster image by making use of the features provided by Joomlatools Server. For more info please also see: #812

4. Adapts to users device capabilities and preferences

Pages will consider device capabilities and user preferences to serve the most optimised video format possible for the context of the device and or user. It makes use of:

• Save-Data
• The connection type

Rules:

• If the connection is 2g load lowest quality video (*)
• If save-data is enabled load lowest quality video () () Requires multi quality videos to be available.

Getting started

To use the image filter simple add the filter to your page or layout:

---
@layout: template://pages/document.html
@process:
    filters:
        - video
---

Asset versioning

Asset versioning provides automatic cache-busting of assets. Implementation is explained on the cache page.