====== Namespaced Template ======

---- template ----
description   : template heavily based on DokuWiki's default template with namespace related magic
author        : Simon Delage
email         : simon.geekitude@gmail.com
lastupdate_dt : 2015-02-10
compatible    : Hrun
depends       :
conflicts     :
similar       : DokuWiki
screenshot_img: template:dokuwiki_template.png
tags          : sidebar, topbar, mobile, responsive, namespace, logo, banner

sourcerepo    : https://github.com/geekitude/dokuwiki-template-namespaced
downloadurl   : https://github.com/geekitude/dokuwiki-template-namespaced/archive/master.zip
bugtracker    : https://github.com/geekitude/dokuwiki-template-namespaced/issues

----

This is a modification of the [[template:dokuwiki|default template bundled with DokuWiki]] with added features (list below).

The original template was designed by [[clarencedglee@gmail.com|Clarence Lee]] and authored by [[anika@selfthinker.org|Anika Henke]].

===== Features =====

  * Optional [[tips:topbar]] (can be namespace dependent, inherited from parent(s) or not)
  * Optional [[config:sidebar]]
  * Optional logo (can be namespace dependent, inherited from parent(s) or not)
  * Optional banner (can be namespace dependent, inherited from parent(s) or not)
  * Tagline can be replaced by current page title beside at wiki start (tagline and title positions can be switched)
  * Nice integration of [[plugin:translation|Translation]] and [[plugin:userhomepage|User Homepage]] plugins if they're enabled
  * Mobile support (Desktop, Tablet, Phone sizes)
  * HTML5 compatible

===== Download and Install ======

Install the template using the Extension Manager and the download URL above, which points to the latest version. 

Refer to [[template|Templates]] on how to manually install and use templates in DokuWiki.

===== Customizing =====

This template offers quite a few settings to customize it to suit your likings. Let me know if you feel something should be added USING GITHUB ISSUE?????????????????????????????????????????????

==== Settings ====

^  Setting (''default value'')  ^  Possible values  ^  Effect  ^
^ topbarwidth (''480'') | positive integer < or = 100 | Topbar width in % of window |
^ ::: | positive integer > 100 | Topbar width in pixels |
^ topbarposition (''absolute'') | absolute | Topbar will scroll with page |
^ ::: | fixed | Topbar will stick to the top of browser window |
^ topbarbgcolor (''empty string'') | empty string | <nowiki>__background_neu__</nowiki> from ''...lib/tpl/namespaced/style.ini'' ([[template:namespaced#A few hints|see hints]]) |
^ ::: | Any valid CSS color string((including RGB or RGBA expressions)) | Topbar background color |
^ topbarfrom (''nowhere'') | nowhere | Disable topbar feature |
^ ::: | root | Search for topbar at wiki root only |
^ ::: | inherit | ...or in current namespace then it's parent(s) |
^ ::: | namespace | ...or in current namespace only |
^ taglinereplace (''on'') | on/off | If enabled, tagline will be replaced with current page title (except at wiki start page) |
^ titleinvert (''on'') | on/off | If enabled, wiki title and tagline will be inverted (except at wiki start page) |
^ logofrom (''inherit'') | nowhere | Disable logo feature |
^ ::: | root | Search for logo at wiki root only |
^ ::: | inherit | ...or in current namespace then it's parent(s) |
^ ::: | namespace | ...or in current namespace only |
^ logomaxheight (''0'') | 0 | No maximum height |
^ ::: | any positive integer | Logo with bigger height will be resized to that height |
^ logoaction (''N'') | N | On click or ''N'' shortcut, go to parent namespace |
^ ::: | H | On click or ''H''shortcut, got to wiki start page |
^ titleaction (''H'') | H | On click or ''H''shortcut, got to wiki start page |
^ ::: | N | On click or ''N'' shortcut, go to parent namespace |
^ addwikistart (''on'') | on/off | If enabled while both ''logoaction'' and ''titleaction'' are set to ''N'', a link to wiki start page will be added in site tools |
^ bannerfrom (''nowhere'') | nowhere | Disable banner feature |
^ ::: | root | Search for banner at wiki root only |
^ ::: | inherit | ...or in current namespace then it's parent(s) |
^ ::: | namespace | ...or in current namespace only |
^ bannerwidewidth (''600'') | any integer >1 | If banner is wider than this, it will be placed between breadcrumbs and page content instead of being reduced to fit under site tools |
^ ::: | 0 | Banner will allways be placed under site tools (and reduced if needed) |
^ ::: | 1 | Banner will allways be placed between breadcrumbs and page content |
^ mediamanagermove (''on'') | on/off | If enabled link to Media Manager will be moved from Site tools to Page tools |
^ translationplugin (''on'') | on/off | If [[doku>plugin:translation|Translation plugin]] is active and this option is enabled, it will be placed on breadcrumbs line (either ''breadcrumbs'' or ''youarehere'' options must be enabled |
^ userhomepageplugin (''on'') | on/off | If [[doku>plugin:userhomepage|User Homepage plugin]] is active and this option is enabled, default ''Logged in as...'' string will be replaced by the one provided by ite plugin |



==== Adding a Topbar ====

==== Adding a Sidebar ====

The template supports a sidebar as configured in [[config:sidebar|Configuration Setting: sidebar]].

==== Changing the Width and other Styles ====

Additionally to the standard guaranteed [[devel:style.ini]] placeholders, the template uses the following variables:

^placeholder variable       ^meaning                                    ^
|''%%__background_site__%%''|background colour of the whole site        |
|''%%__link__%%''           |colour of links                            |
|''%%__existing__%%''       |colour of links to existing internal pages |
|''%%__missing__%%''        |colour of links to missing internal pages  |
|''%%__site_width__%%''     |width of the whole site                    |
|''%%__sidebar_width__%%''  |width of the sidebar                       |


E.g. you can adjust the width of the template by overriding the ''%%__site_width__%%'' variable. Simply create the file ''conf/tpl/dokuwiki/style.ini'' (or old location: ''lib/tpl/dokuwiki/style.local.ini'' in Adora Belle) and set the variable accordingly. You can either use a fixed value (px or em) or a percent value (%) if you prefer a dynamic width.

<code ini conf/tpl/dokuwiki/style.ini>
[replacements]
__site_width__  = "100%"
</code>

You can use this file to override any other variable from the ''style.ini'' as well. E.g. for changing some of the colors.

==== Changing the Logo ====

The Logo, Favicon and Apple Touch (bookmark) icons are looked up from multiple locations. The default icons (DokuWiki logo) provided by the template can be easily exchanged by uploading the image files to their correct locations using the [[:media_manager|Media Manager popup]] or [[:fullscreen mediamanager|Fullscreen Media Manager]].

Here are the locations checked by the template code:

  * The site's logo
    * '':wiki:logo.png''
    * '':logo.png''
    * ''lib/tpl/dokuwiki/images/logo.png''
  * The favicon
    * '':wiki:favicon.ico''
    * '':favicon.ico''
    * ''lib/tpl/dokuwiki/images/favicon.ico''
  * The bookmark icon used by Apple and Android devices
    * '':wiki:apple-touch-icon.png''
    * '':apple-touch-icon.png''
    * ''lib/tpl/dokuwiki/images/apple-touch-icon.png''

==== Action Hooks ====

Plugins can integrate into the template without any need for modifying the template by providing an [[devel:action_plugins|Action component]] to handle the custom action hooks triggered by the template.

=== TEMPLATE_PAGETOOLS_DISPLAY ===

This [[devel:event:TEMPLATE_PAGETOOLS_DISPLAY|event]] allows to extend or modify the floating pagetools menu. ''%%$event->data['items']%%'' contains an array with HTML for each item in the menu. Plugin authors should match the existing style and provide needed CSS and background image. You can use different styling or classes or markup depending on ''$conf['template']''. ''%%$event->data['view']%%'' contains information whether the pagetools are called in the ''main'' or the ''detail'' view.
==== Supported Include Hooks ====

Include hooks allow you to add additional HTML or PHP to the template without modifying any of the template files itself, making them safe to survive an update. Just create the appropriate file in either the template directory (''lib/tpl/dokuwiki/'') or your ''conf/'' directory.

^ Filename               ^ Position of included HTML                                                ^
| ''meta.html''          | Inside the HTML <head>, use this to add additional styles or metaheaders |
| ''sidebarheader.html'' | At the top of the sidebar (if any) |
| ''sidebarfooter.html'' | At the bottom of the sidebar (if any) |
| ''pageheader.html''    | At the top inside the content box, above the actual content |
| ''pagefooter.html''    | At the bottom inside the content box, below the actual content |
| ''header.html''        | At the top of the page, above the logo and wiki title |
| ''footer.html''        | At the very end of the page after all other page content |

===== A few hints =====

==== Provide a topbar template ====
Simply install [[doku>plugin:templatebyname|TemplateByName plugin]] and create ''<nowiki>.../data/pages/__topbar.txt</nowiki>'' with a simple template to guide users into creating topbars consisting of a list with the correct syntax.

==== Use a different CSS placeholder for Topbar background color ====
If you want to change the default topbar background color but keep using a placeholder from ''.../lib/tpl/namespaced/style.ini'' (ie use ''<nowiki>__background__</nowiki>'' or ''<nowiki>__background_alt__</nowiki>'' instead of ''<nowiki>__background_neu__</nowiki>''), simply add a line like the following one in ''.../conf/userstyle.css'' :
<code css>.dokuwiki .topbar ul { background-color: __background_alt__; }</code>

===== Sites using this Template =====

  * Add yours here