Download the PHP package hananils/xslt without Composer

XSLT is a template component for Kirby 3 enabling XSLT support in your templates. It let's you specify the needed data for each blueprint which is then provided as XML on the frontend:

• Settings up XML output
• Creating templates
• Shortcomings

Installation

Download

Download and copy this repository to /site/plugins/xslt.

Git submodule

Composer

Data

By default, the plugin provides XML nodes for the $kirby, $site, $pages and $page objects. As soon as you are logged in, you can view the data of any page by appending ?data to the URL. The base output without additional setting using the Plainkit looks similar to this:

Any object defined in a controller will be added to the XML output as well, e. g.:

Known types are:

• Kirby\Cms\App, see Kirby docs
• Kirby\Cms\Site, see Kirby docs
• Kirby\Cms\Pages, see Kirby docs
• Kirby\Cms\Page, see Kirby docs
• Kirby\Cms\Files, see Kirby docs
• Kirby\Cms\File, see Kirby docs
• Kirby\Cms\Users, see Kirby docs
• Kirby\Cms\User, see Kirby docs
• DomDocument, see PHP docs
• DomElement, see PHP docs

Included Elements

In order to customize the XML output, you have to create a new folder definitions inside your site folder. Similar to your blueprints, you can create definitions files for each template. The default.yml might look like this for example:

The key equals the object name, let this be the default $kirby, $site, $pages or $page objects or a custom controller returning a project object. Setting an object to true will show the full content, setting an object to false will exclude its content.

The different type have different options:

Kirby

The kirby object has the following options that either switch a node on or off:

The attributes object allows to creation of node attributes from kirby methods. The name of the attribute has to match the method’s name, see the Kirby docs.

If you are working on a multilingual install, language settings are available:

Site and Page

The page objects have the following options:

• The attributes object allows to creation of node attributes from page methods. The name of the attribute has to match the method’s name, see the Kirby docs.
• The title object can be switched on and off by setting true or false.
• The path object is helpful to apply different templates base on the URL, it can be switched on and off by setting true or false.
• The languages object is available in multilingual installs and offers link for all languages, it can be switched on and off by setting true or false.
• The content subsetting takes and array of fields you'd like to include, e. g. content: title, description, tags.
• The files object can be switched on and off by setting true or false. It also takes additional settings, see below.
• The children object can be switched on and off by setting true or false. It also takes additional settings from the pages object, see below.

If you'd like to pass options to a specific fields, you can still include all other field by using a wildcard:

Textarea field

The textarea field offers additional settings to define formatters to be applied to the field content. By default, Kirbytext is applied to all textareas:

To get unformatted source text, the field has to be set to unformatted in the page definitions:

To get formatted output, the field has to be set to either markdown or kirbytext:

To apply multiple formatters – like Kirbytext and SmartyPants –, the field also accepts a list of method:

Methods are applied from top to bottom. Any existing field method can be used so it's also possible to apply the lower method for example:

Telephone field

When using a Composer setup, you can install the optional libphonenumber library. This will add additional phone number formats to the XML output (E164, national, international and RFC3966).

Pages

The pages objects returns a collection of child pages. It takes the same settings as the page object which are applied to all children.

Files

The files object returns a collection of files grouped by file template:

• The filename can be switched on and off by setting true or false.
• The meta object equals the content object of a page, see above.
• The thumbs object lets you setup image thumbnails. It takes a list of thumbs with optional settings for width, height and crop position. If your crop position is stored in a field, you can reference it using the syntax file.fieldname.

Extending Included Elements

You can create subfolders for files and pages, /site/definitions/files and /site/definitions/pages to create subsets for settings you'd like to reuse across definitions files. This works like in blueprints.

Extending the default definitions:

Extending file definitions

/site/defintions/files/image.yml

/site/definitions/project.yml

Extending page definitions

/site/definitions/pages/default.yml

/site/definitions/project.yml

Helper Objects

The plugin bundles two helper objects to be used inside your controllers:

Date and Time

This object returns current date and time information as well as localized month and weekday names:

The used locale can be set in the config:

If you are working on a multilingual site, all languages you've set up will be available.

It’s possible to set the included node in the definition files:

Assets

This object return information about all files and folders inside the /asset folder:

This information can be used to automatically generate links for scripts and styles:

It's also possible to use the modified attribute to create timestamped links:

Templates

Templates are defined in the default templates and snippets folders. If you are using the Kirby Starterkit or Plainkit, please remove the default PHP templates and add a new default.xsl file. This works well as a starting point:

Template naming conventions follow the default Kirby scheme, see https://getkirby.com/docs/guide/templates/basics#naming-your-templates.

Doctype

If you use doctype-system="about:legacy-compat" as in the example above, the plugin will automatically shorten the default doctype output <!DOCTYPE html SYSTEM "about:legacy-compat"> to <!DOCTYPE html>.

Content representations and emails

As of version 3.0, XSL template are only enabled for HTML and XML content by default. For any other content representations and for emails, native templating is used. You can set allowed types for XSLT rendering in your config:

Disable XSL templates

As of version 3.0, you can disable XSL templating in your config:

Shortcomings

The plugin is work in progress. We are extending it based on our own needs:

• Field support is limited to the core fields and a few additional fields we use ourselves.

Contributions are always welcome.

License

This plugin is provided freely under the hana+nils · Büro für Gestaltung.
We create visual designs for digital and analog media.