====== TwigStarter Template ====== ---- template ---- description : A starter template that uses Twig for templating author : Andreas Gohr email : andi@splitbrain.org lastupdate_dt : 2022-09-30 compatible : depends : conflicts : # prefix templates by template: similar : starter screenshot_img: # URL to a screenshot (should be a bigger one) tags : starter, twig, sidebar downloadurl : https://github.com/splitbrain/dokuwiki-template-twigstarter/zipball/master bugtracker : https://github.com/splitbrain/dokuwiki-template-twigstarter/issues sourcerepo : https://github.com/splitbrain/dokuwiki-template-twigstarter/ donationurl : ---- 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 [[https://twig.symfony.com/|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 [[template:starter|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 [[https://www.patreon.com/posts/combining-twig-27328611|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 [[https://twig.symfony.com/|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 [[https://twig.symfony.com/doc/2.x/tags/extends.html|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: * '''' * contains the title, meta infos and favicon setup * ''%%
%%'' * contains (nearly) everything * has the ''dokuwiki'' class (and others) set -- many plugins do require a div.dokuwiki at toplevel * ''
'' * contains the logo, title, tagline and mobile menu * ''