[dokuwiki] Core devs: I need some info to keep my templates maintainable

  • From: Andreas Haerter <list+dokuwiki@xxxxxxxxxxxxxxxxxxx>
  • To: DokuWiki mailing list <dokuwiki@xxxxxxxxxxxxx>
  • Date: Wed, 09 Feb 2011 23:44:44 +0100

Hi all,

after my frist steps with dokuwiki ~1,5 years ago, I read a post by
chimeric[1]. Cause his blog is closed: copy of the text as DokuWiki
source is attached, licensed under the Creative Commons BY-NC-SA License.

For the lazy ones: The text describes a strategy to get a maintable
template through directly using the content+admin related .css files of
the DokuWiki default template without any direct modifications to them
(_admin.css, _linkwiz.css, design.css, media.css etc.).
Instead of editing these "original" files, the cascade (-> you know, the
first "C" in "CSS" :-P) is used to overwrite and adapt the original
styles to the needs of your template. Summary:
1. Import DokuWiki styles
2. Import you own sytles + overwriting non fitting DokuWiki styles. Use
"!important" if needed.

This ensures a painless update if there are new versions of DokuWiki +
new CSS. Because the "original" CSS was not edited or partially copied,
I do not have to track the changes in detait but simply copy the new
file versions of them into my template. A check if everything works and
make small adjustments if not and you're done. So far, so good. I used
this principle for vector and monobook (but the situation is a bit more
complicated there because I have to  import the original DokuWiki
styles, the original MediaWiki vector/monobook styles afterwards and my
own ones at last to merge everything together + beeing flexible
regrading "third party" updates).

My questions:

1) What about the future? I'm asking because of this new
<http://www.dokuwiki.org/template:starter>. And AFAIK there will be a
new default template soon. Is is better to use the "starter" or the new
"default" template css as starting point for the approach described
above? Wich one will be more "modular"? This information/discussion is
really important for me cause I also have to maintain Chi's templates
Artic and DokuBook in the future... both are also adjusting the
default-theme CSS the same way. And I have to plan when to switch the
"CSS base" if needed.

2) Is "Directory Layout" at <http://www.dokuwiki.org/devel:templates>
still valid? This is not important for monobook/vector (I'm merging two
third party compents with my own stuff there - this so special that I
used a non-standard dir layout without any bad conscience) but for Artic
and DokuBook. Chi's templates are respecting the described directory
layout but <http://www.dokuwiki.org/template:starter> does not. I also
prefer a non-standard layout like starter, I like to keep things tidy,
putting images, css etc. in own folders. Is "Directory Layout" just a


Andreas <http://blog.andreas-haerter.com>

O< ascii ribbon campaign - stop html mail - www.asciiribbon.org
====== How To Create An Easy Maintainable DokuWiki Template ======
Creating templates for all kinds of web applications isn`t really a hard task 
(well, there are [[http://phpbb.com|exceptions]] of course). But if you plan to 
share your work with the public you face a little problem every now and then, 
namely when there`s a new version of the application available and you have to 
track down what has changed since the last release, to be able to update your 
work accordingly. Sure, not everyone has the time to follow the development of 
an application close enough to notice every small change which affects his 
work. IMHO that could be the cause why some of the available 
[[doku>wiki:dokuwiki|DokuWiki]] [[doku>wiki:tpl:templates|templates]] are a 
little outdated and likely not 100% compatible with the 
[[http://splitbrain.org/go/dokuwiki|latest release]]. However, I would like to 
show a way to take advantage of DokuWikis' [[doku>wiki:styleshetts|stylesheet 
handling]] and to keep the effort needed to keep such a template up-to-date at 
a minimum (we`re all lazy people, right ;-)).

===== #1 Creating A New Template =====
To create a new template all you have to is to copy the default template to a 
new folder below ''<dokuwiki>/lib/tpl/templates'' and select it in the 
configuration manager. If you`re on GNU/Linux:

% cd <dokuwiki>/lib/tpl
% cp -av default newtemplate

That`s it! Well, almost. Now you surely like to modify the stylesheets to make 
it look different ;-).

===== #2 Taking Advantage Of DokuWikis Stylesheet Handling =====
DokuWiki provides an advanced stylesheet handling system which uses a PHP .ini 
file named ''style.ini'', which is part of the template, to determine which 
stylesheet gets loaded for a certain display mode. So lets have a look at the 
''style.ini'' provided by the default template. Right now we`re interested in 
the first section of the file:

<file txt style.ini>
layout.css     = screen
design.css     = screen
style.css      = screen

media.css      = screen

rtl.css        = rtl
print.css      = print

The above describes which .css file gets loaded for a certain display mode. 
"''screen''" is the normal display mode when you watch the page in a browser, 
"''rtl''" is loaded for right-to-left languages, and "''print''" obviously when 
you like to print a wiki page. For more information regarding the loading order 
of stylesheets refer to the [[doku>wiki:stylesheets#stylesheet_loading|docs]].

So here`s the key part:
<WRAP important>
**We`re not gonna edit any of the .css files we copied over from the default 

Instead we add our own .css files and modify the ''style.ini'' so they get 
loaded **after** the original ones.

% cd <dokuwiki>/lib/tpl/mytemplate/
% touch mytemplate_design.css mytemplate_print.css

<file txt style.ini>
layout.css     = screen
design.css     = screen
style.css      = screen
mytemplate_design.css = screen

media.css      = screen

rtl.css        = rtl
print.css      = print
mytemplate_print.css = print

So, instead of editing any of the .css files we copied over form the default 
template we add our CSS rules to the files we just created and make use of a 
certain CSS feature. CSS rules simply override previous rules which affect the 
same element. So we just override any rule of the ''design.css'' we like to 
change in our ''mytemplate_design.css''. Developing a stylesheet this way is a 
little bit more advanced than if you just edit the existing .css files but it 
has an advantage as you`ll see later. 

Another thing you may like to consider while modifying DokuWikis CSS is that 
it`s best to access the elements the same way as done in the ''design.css'' and 
prepend every id or class with ''div.dokuwiki'' (**hint:** 
[[doku>wiki:stylesheets#pattern_replacement|color placeholders]]). Also if you 
happen to edit the ''main.php'' of your template to add a sidebar or something 
else you shouldn`t remove the <div class="dokuwiki"> as it will break the whole 

As you may have noticed this approach has one drawback. The size of the final 
stylesheet delivered to the browser will be bigger than if you just edit the 
existing .css files. In case of the [[projects:dokuwiki:template:simple|simple 
template]] it`s around 8.7k of extra CSS (uncompressed). Since the whole CSS 
gets compressed and is usually delivered only once and then cached I don`t 
think it`s that much of a problem (I am sure there`re other opinions on that 
topic though). 

===== #3 Keeping It Up-To-Date =====
If you follow the approach given above, keeping your template up-to-date after 
a new DokuWiki release is a task that can be done in only a view minutes! After 
a new release the only thing you have to do is to run a diff against all .css 
files you copied from the default template against the original ones (i.e. 
''design.css''). If there have been changes just copy the changed .css files of 
the default template to your template folder overriding the old ones, and, only 
if needed, add some extra rules to your custom .css files. The best place to 
check if everything is OK is the [[wiki:syntax|syntax page]] included in every 
DokuWiki release. Also, don`t forget to diff the .php files against the ones 
provided by the default template after every release. As you see, that`s really 
not much of work.

====== ======
That`s it! At least this approach works pretty well for me ;-). For the last 
two DokuWiki releases all I had to do to upgrade my 
[[projects:dokuwiki#templates|templates]] was to override the .css files I 
copied over from the default template. Of course this only covers CSS issues 
but it assures that things don`t get totally messed up. If you`ve added new 
functionality to a template you surely have to put more time into 
testing/debuging things. But if you only like to create a different look for 
DokuWiki and like to [[doku>wiki:tpl:templates|share it]], this is one way to 
keep things easy over time.

Other related posts: