Differences

This shows you the differences between two versions of the page.

--- devel:templates [2011-03-12 08:23] – 71.183.122.50
+++ devel:templates [2023-09-24 01:08] (current) – Klap-in
@@ Line 1: / Line 1: @@
 ====== DokuWiki Template Development ======
-You can customize the design of [[:DokuWiki]] by creating a new template. A template is determined by some PHP and CSS files stored in a directory beyond the ''<dokuwiki>/lib/tpl/'' directory. (actually, the template is made of HTML, the PHP in it is used to insert the content.)
+You can customize the design of [[:DokuWiki]] by creating a new template. A template is determined by mainly some PHP and CSS files stored in a directory beyond the ''<dokuwiki>/lib/tpl/'' directory.
 ===== Getting Started =====
-The easiest way to create a new template is by taking an already existing one as starting point. It's a good idea to use the default template because it is clean and follows the DokuWiki template standards. Template names (directories) have to be lowercase, and "." or "_" are not allowed.
-  - Copy the ''lib/tpl/default'' directory to ''lib/tpl/yourname''
+The easiest way to create a new template is by taking an already existing one as starting point. It's a good idea to use the starter template because it is clean and follows the DokuWiki template standards.
+  - Install the [[template:starter]] template (optionally, its "minimal" branch is a cleaner starting point)
+  - Rename the ''lib/tpl/starter'' directory to ''lib/tpl/yourname''
   - Select the new template in the configuration manager
-  - Then have a look at the template files (see [[#Directory Layout]])
+  - Then change your template to your heart's desire; to understand how DokuWiki templates are built, have a look at the [[#directory layout|template files]] and how DokuWiki handles [[CSS]]
-  - Have a look on how [[:DokuWiki]] handles [[CSS]] using its [[devel:css|CSS dispatcher]].
+  - When your template is ready, consider [[#Publishing a Template on dokuwiki.org|publishing]] it on DokuWiki's [[:template]] page.
-  - Handling of configuration settings is analogous to [[common_plugin_functions|plugins]]. Use ''%%tpl_getConf(<setting>)%%'' to retrieve custom template settings.
+=== Template naming conventions ===
+A valid template name (directory):
+  * Should only contain the characters a-z and 0-9.
+  * Dot ''.'', dash ''-'' and underscore ''_'' are **not** allowed as:
+    * DokuWiki's infrastructure doesn't support them anywhere
+    * Using underscore will also give a [[:popularity|popularity]] rating of zero.
+  * Spaces '' '' are also not allowed in the base name of the template defined in ''template.info.txt'' and the folder name, including the page name used in the [[:templates|template listing]] e.g. ''template:myfirsttemplate''
+  * If the same name is used by two different templates
+    * they are mutually exclusive and inherent incompatible,
+    * furthermore only one of them can have a template homepage on [[:dokuwiki|dokuwiki.org]]
+**It is important to have a unique base field value (i.e. template name) in [[devel:template_info|template.info.txt]] or an already existing template with that name could be overwritten.**
 ===== Directory Layout =====
-The templates should follow the following directory structure (all paths are relative to the template directory). The CSS files are specified in the ''[[CSS#style.ini]]'' file but you should try to at least provide one CSS file for the screen presentation and one for printing.
+Templates should follow the following directory structure (all paths are relative to the template directory).
+CSS files are specified in the ''[[style.ini]]'' file. Use as many files as you like, but you should at least provide one CSS file for the screen presentation and one for printing.
   * ''<dokuwiki>/lib/tpl/<template>/''
-    * ''<filename>.css''
+    * ''<filename>.css'' -- [[devel:css#templates_styles|template's stylesheets]] (if more than a few are provided, it makes sense to group them in a ''css/'' subdirectory)
+    * ''script.js'' -- optional, if your template needs [[devel:JavaScript]]
     * ''[[devel:templates:main.php]]'' -- general layout of DokuWiki
     * ''[[devel:templates:detail.php]]'' -- the image detail page
     * ''[[devel:templates:mediamanager.php]]'' -- the media-selection popup
-    * ''images/'' -- all images used in the template
+    * ''images/'' -- all images used in the template (if any)
-    * ''conf/''
+    * ''conf/'' -- configuration files (optional, if configuration is used)
-      * ''default.php'' -- [[configuration#default settings]] (see ''[[#tpl_getConf]]'')
+      * ''default.php'' -- [[configuration#default settings]] for the [[devel:configuration#template settings]]
-      * ''metadata.php'' -- [[configuration#configuration metadata]] (see ''[[#tpl_getConf()]]'')
+      * ''metadata.php'' -- [[configuration#configuration metadata]] describe properties of the settings as used by the Configuration Manager
     * ''lang/'' -- language files
-      * ''<lang code>/lang.php'' -- localization strings used in the template
+      * ''<lang code>/lang.php'' -- [[[[devel:localization#template_localization|localization strings]] used in the template (optional, use when needed)
-      * ''<lang code>/settings.php'' -- localization strings used in the configuration manager
+      * ''<lang code>/settings.php'' -- localization strings used in the configuration manager (if configuration is used)
-    * ''style.ini'' -- see [[CSS#Style.ini]]
+    * ''style.ini'' -- see [[devel:style.ini]]
+    * ''favicon.ico'' -- favicon (can be overwritten by uploading another one into the root or wiki namespace when [[xref>tpl_favicon()|tpl_favicon()]] is used)
+    * ''template.info.txt'' -- A text file with [[devel:template info|template information]] **required!**
-===== Functions =====
+Handling of configuration settings is analogous to [[common_plugin_functions|plugins]]. Use ''%%tpl_getConf(<setting>)%%'' to retrieve custom template settings. Saved local settings are stored in DokuWiki's global ''conf/local.php''.
-A list of available functions can be found in [[http://dev.splitbrain.org/reference/dokuwiki/nav.html?inc/template.php.html|API documentation]]. Some specialties are listed here.
-==== tpl_content() ====
+===== Inner workings explained =====
-This function outputs the page body, or in other words the content of your wiki page, including the [[:TOC]]. You can prevent it from outputting the TOC by passing ''false'' while calling it:
-<code php>
+==== Functions ====
-tpl_content(false);
-</code>
-This can be used to separate the TOC from the content and place it somewhere else on the screen. See ''[[#tpl_toc()]]'' for further details.
+A list of available functions can be found in [[xref>inc/template.php|API documentation]]. Some specialities are listed here.
-==== tpl_toc() ====
+  * **''[[xref>tpl_content()]]''** \\ This function outputs the page body, or in other words the content of your wiki page, including the [[:TOC]]. You can prevent it from outputting the TOC by passing ''false'' while calling it: <code php>
+tpl_content(false);
-By default, the ''[[#tpl_content()]]'' function will take care of displaying a [[:TOC|Table of Contents]] itself, prepending it to the actual page content. If your template uses a sidebar or other more complex layout you may want to place the TOC independently from the page content. This can be done with the ''tpl_toc()'' function. When using it, it is important to disable automatic TOC placement by passing the argument ''false'' to the ''tpl_content()'' function.
+</code>This can be used to separate the TOC from the content and place it somewhere else on the screen. See ''tpl_toc()'' below for further details.
-**Example:**
+  * **''[[xref>tpl_toc()]]''** \\ By default, the ''tpl_content()'' function will take care of displaying a [[:TOC|Table of Contents]] itself, prepending it to the actual page content. If your template uses a sidebar or other more complex layout you may want to place the TOC independently from the page content. This can be done with the ''tpl_toc()'' function. When using it, it is important to disable automatic TOC placement by passing the argument ''false'' to the ''tpl_content()'' function.\\ \\ **Example:** \\ <code php>
-<code php>
 <div id="content">
     <?php tpl_content(false)?>
@@ Line 56: / Line 71: @@
     <?php tpl_toc()?>
 </div>
-</code>
+</code>The ''tpl_toc()'' function renders the TOC from three different sources: a global [[environment#$TOC]] variable, the page [[metadata]] or the ''getTOC()'' method of [[admin plugins]]. Because there is no metadata available for old revisions or preview ''tpl_toc()'' can only use the global [[environment#$TOC]] variable for these cases. Because the [[environment#$TOC]] variable is filled by the page renderer this will only work when ''tpl_toc()'' is called **after** ''tpl_content()''. If this is not possible in your template layout you may use output buffering to circumvent the problem. \\ \\ **Example:**\\ <code php>
-The ''tpl_toc()'' function renders the TOC from three different sources: a global [[environment#$TOC]] variable, the page [[metadata]] or the ''getTOC()'' method of [[admin plugins]]. Because there is no metadata available for old revisions or preview ''tpl_toc()'' can only use the global [[environment#$TOC]] variable for these cases. Because the [[environment#$TOC]] variable is filled by the page renderer this will only work when ''tpl_toc()'' is called **after** ''tpl_content()''. If this is not possible in your template layout you may use output buffering to circumvent the problem.
-**Example:**
-<code php>
 <?php
     // render the content into buffer for later use
@@ Line 79: / Line 88: @@
 </code>
-==== tpl_getConf() ====
+  * **''[[xref>tpl_getConf()|tpl_getConf('key')]]''** \\ This function is used to access [[configuration|configuration settings]] from within the template.
-This function is used to access [[configuration|configuration settings]] from within the template.
-===== Global Variables And Constants =====
+  * **''[[xref>tpl_getLang()|tpl_getLang('key')]]''** \\ This function is used to access localized strings  of the template. For details see the [[devel:localization]] development documentation.
+  * Further many other useful template functions are available. Please have a look in [[xref>inc/template.php|API documentation]].
+==== Global Variables And Constants ====
 For a complete list of useful global variables and constants please refer to the [[environment]] page.
-===== Automated Housekeeping =====
+==== Automated Housekeeping ====
+Almost at the bottom of the default template's [[devel:templates:main.php]] file you'll see a function call to ''[[xref>tpl_indexerWebBug()]]''. The function generates a HTML ''%%<img>%%'' tag which results in a request to ''[[:taskrunner|lib/exe/taskrunner.php]]''. This **vital** part of DokuWiki provides important housekeeping work to keep the wiki running smoothly. All templates should include this function, without it the wiki may not function correctly (for example the [[:search|search index]] wont be built).
+==== 'dokuwiki' class ====
+A class named ''dokuwiki'' should be added to some content surrounding element (either around everything or at least around ''tpl_content()'') in each template's [[devel:templates:main.php]], [[devel:templates:detail.php]] and [[devel:templates:mediamanager.php]]. This is to make sure that DokuWiki's styles don't interfere with other styles if it gets integrated into an existing site with potentially conflicting CSS.
+==== Include Hooks ====
+Include Hooks are a simple way to add some static content to your [[:DokuWiki]] installation without writing your own [[:Template]]. You can use them for adding a standard header at the top or a disclaimer at the bottom of each page.
+The DokuWiki's default template looks for files with special names in the template directory and simply includes them at the correct places when displaying the page. You can add whatever HTML or even PHP you like into these files. Of course this only works if you are using the //dokuwiki// template or a template supporting the [[template:dokuwiki#supported_include_hooks|same include hooks]] (like the starter template).
+===== Converting existing templates =====
+If you're lacking design skills you can also convert existing templates. There are lots of free options available. If you'd like to publish one of those as well, please make sure it is [[https://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses|GPL2-compatible]].
+  * [[WP_to_DW_template|How to convert a WordPress theme to a DokuWiki template]]
+===== Avoiding problems =====
+Here are a few problems template developers run into and how to avoid them:
+===Don't put JavaScript commands in the <body> tag of a page===
+This includes ''onLoad'' and others. Although breaking this rule doesn't affect FireFox at all, Internet Explorer (even IE 7) will have JavaScript errors due to the JavaScript required for page editing, and this can result in pages that won't display correctly, and you will find the editing bar will be missing when you need it.
+===Turn off "Compact CSS and JavaScript files" while developing a template===
-Almost at the bottom of the default template's [[devel:templates:main.php]] file you'll see a function call to ''tpl_indexerWebBug()''. The function generates a HTML ''%%<img>%%'' tag which results in a request to ''[[:indexer|lib/exe/indexer.php]]''. This **vital** part of DokuWiki provides important housekeeping work to keep the wiki running smoothly. All templates should include this function, without it the wiki may not function correctly (for example the [[:search|search index]] wont be built).
+Some template developers experience problems with DokuWiki cacheing CSS and JS files due to this option being on, although this has been hard to pinpoint. To be safe, turn this off temporarily.
-===== 'dokuwiki' class =====
+===Use "forced refreshing" after you make changes to CSS files===
+You can accomplish this by pressing Ctrl+F5 or by holding down shift-control-alt and hitting the refresh button in your browser.
-A class named ''dokuwiki'' should be added to some content surrounding element (either around everything or at least around ''tpl_content()'') in each template's main.php, detail.php and mediamanager.php. This is to make sure that DokuWiki's styles don't interfere with other styles if it gets integrated into an existing site with potentially conflicting CSS.
+This is not due to how DokuWiki works, but how current browsers cache files. Browsers cache stylesheets even when new versions are available, so you will need to do this.
-===== Include Hooks =====
+===== Publishing a Template on dokuwiki.org =====
-Include Hooks are a simple way to add some static content to your [[:DokuWiki]] installation without writing your own [[:Template]]. You can use them for adding a standard header or company logo to each page or add a disclaimer at the bottom of each page.
+If you created a template, please share it with the community. Just create a page named after your template in the [[:template]] namespace. E.g. if your template folder is named ''sample'' create a page ''template:sample'' here in the wiki.
-DokuWiki's default template looks for files with special names in the ''lib/tpl/default/'' directory and simply includes them at the correct places when displaying the page. You can add whatever HTML you like into these files. Of course this only works if you are using the //default// template.
+The page should contain all needed documentation on how to install and use the template. Adding screenshots might be a good idea as well.
-__Hint for PHP developers:__ You may be happy to hear that you can even include PHP in these files.
+At the top of the template page a few metadata fields have to be filled in. A description of each field can be found on the [[plugin:repository#template_entry|Repository Plugin]] page.
-==== Available Hooks ====
+From version Ponder Stibbons on an automated update signalling is possible. For the update process to work properly it is necessary that the date “Last updated on” on the template's wiki page equals the date in the file [[devel:template_info|template.info.txt]] in the source tarball/zip file. If this is not the case the update will not take place or the “Update” signal persists.
-All these files are searched for in the ''lib/tpl/default/'' directory.
+Uploads are not allowed on dokuwiki.org, so you need to host your template files somewhere else. We recommend to manage your source with a Revision Control System like [[git]]. If you do, it's easiest to use a public repository host like [[https://github.com|GitHub]] which also offers a bug tracker for your repository.
-^ Filename        ^ Position of included HTML                                                ^
-| ''meta.html''       | Inside the HTML <head>, use this to add additional styles or metaheaders |
-| ''topheader.html''  | At the very top of the page right after the <body> tag |
-| ''header.html''     | Above the upper blue bar, below the pagename and wiki title |
-| ''pageheader.html'' | Below the breadcrumbs, above the actual content |
-| ''pagefooter.html'' | Above the lower blue bar, below the last changed Date |
-| ''footer.html''     | At the very end of the page just before the </body> tag |
-DokuWiki comes with an example ''footer.html'' containing some buttons and a CC license RDF description.