TwigStarter Template

Compatible with DokuWiki

No compatibility info given!

A starter template that uses Twig for templating

Last updated on: 2022-09-30
Repository: Source

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to starter

Tagged with sidebar, starter, twig

Needed for notos

By Andreas Gohr

This template is not meant for direct use! It's meant to be a starting point to create your own template based on it. The template introduces the Twig templating engine to make working with the mix of HTML and DokuWiki functions a tiny bit cleaner.

The template is meant as an alternative to the Starter Template. It has much less code and comments. It's meant for more experienced template developers to quickly get started.

Getting started

There are two ways to use this template to create your own.You can either simply copy it and start customizing it, or you can copy only parts of it and make your template depend on the twigstarter template. In the latter case, users will need to install your template and the twigstarter template.

DokuWiki expects three files in a template directory: main.php, detail.php and mediamanager.php. When you look at these files in twigstarter you will notice that all three files are the same and simply initialize a namespaced TemplateController class defined in TemplateController.php.

There's also a blog post available giving a bit more background information.

Depending on what way you want to use, there are different things to do:

TwigStarter Copy

For a template copy, you need to adjust the namespace for the TemplateController in the mentioned PHP files. Replace the twigstarter part with the name of your own template.

TwigStarter Child

If you want to depend on the original twigstarter template, copy over the following files:

main.php
detail.php
mediamanager.php
style.ini

Next create your own templates directory and start writing the templates you want.

Styles

The twigstarter template comes with a style.ini that references the dokuwiki template's styles. This ensures that most of the basic features of the wiki (Mediamanagement, Recent Changes, Admin Screens, etc) are already styled. Since plugins often expect some styles from the default template, this approach also ensures maximum compatibility.

You need to add your own styles after the included ones. TwigStarter itself defines absolutely no styles on its own out of the box.

Templating

The HTML for your template is created using Twig. You should read their documentation first.

Template files need to go into the templates sub directory and end in .twig.

DokuWiki requires three components in a template (as mentioned above), these correspond to:

templates/main.twig
templates/detail.twig
templates/mediamanager.twig

If you picked the “TwigStarter Child” approach, any template not found in your template will be used from the twigstarter template. This is mostly useful for the templates/mediamanager.twig file that you most probably don't want to adjust anyway.

Layout

Twig supports extending templates. The example templates provided with twigstarter use this to extend from a common layout.twig file. This is as basic as possible but should contain all important bits a template needs:

<head>
- contains the title, meta infos and favicon setup
<div id="dokuwiki__top">
- contains (nearly) everything
- has the dokuwiki class (and others) set – many plugins do require a div.dokuwiki at toplevel
<header>
- contains the logo, title, tagline and mobile menu
<aside>
- contains the desktop menus
<nav>
- only set if a sidebar exists
- contains the sidebar
<main>
- the main content area
- messages are printed here
<article>
- the actual content
<footer>
- license info
The indexer webbug comes at the very end

This is not the most semantic setup, but it would be enough to create a basic template with just styling alone. It should give you an easy starting point to create your own, more complex layout.

Variables and Functions

All variables that are usually globally available in a template are also available in the twig template as variables.

Examples:

{{ACT}} {{conf.title}} {{_SERVER.REMOTE_USER}}

In addition, there is an object called TPL available. This is the TemplateController and gives you access to it's own public methods. Most importantly it also gives you access to all DokuWiki defined functions.

Examples:

{{TPL.view}} This accesses TemplateController::getView
 
{{TPL.menu('site')}} Helper method to instantiate a dokuwiki\Menu\SiteMenu
 
{{TPL.html_msgarea()|raw}} Outputs the raw HTML created by DokuWiki's html_msgarea function

The template controller will ensure that output of functions that print instead of return their data will still be passed correctly to Twig.

Note: Twig escapes by default, when you call functions that return HTML you need to pass them through the raw filter!

Custom Controller

Usually you want some additional PHP code in your template. The easiest way to do so is to create class \dokuwiki\template\YOURTEMPLATE\CustomController that implements the \dokuwiki\template\twigstarter\CustomControllerInterface. This class will automatically be instantiated and be made available as the variable SELF in Twig.

Caching and Debugging

Twig templates are compiled and cached. During development you don't want that. To disable caching, simply enable the allowdebug option. This will also print stack traces when something goes wrong.

Templates based on TwigStarter

Most templates that have been made with TwigStarter are not publically available as they have been built for clients at my dayjob. However below is (currently short) list of publically available template based on TwigStarter:

Notos (Child-Theme)

Table of Contents