// How to create an easily maintainable DokuWiki template

Creating templates for most web applications is not really a hard task. 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: you have to track down what has changed since the last release to be able to update your template 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 DokuWiki templates are a little outdated and likely not 100% compatible with the latest release. However, I would like to show a way to take advantage of DokuWiki's 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 ;-)).

Creating a new template

The easiest way to create a new template is the Starter template by Anika Henke.1) Just download and extract it. Rename the folder, place it below <dokuwiki>/lib/tpl/templates and select it in the DokuWiki configuration manager.

The idea: taking advantage of DokuWiki's CSS handling

DokuWiki provides an advanced CSS handling system which uses a PHP .ini file named style.ini, which is part of the template. It is used to determine which files are getting loaded for a certain display mode. So lets have a look at the style.ini provided by the Starter template. Right now we're interested in the first section of the file:

style.ini
[stylesheets]
 
css/basic.css             = screen
css/structure.css         = screen
css/design.css            = screen
css/content.css           = screen
css/_imgdetail.css        = screen
css/_media_popup.css      = screen
css/_media_fullscreen.css = screen
css/_fileuploader.css     = screen
css/_tabs.css             = screen
css/_links.css            = screen
css/_toc.css              = screen
css/_footnotes.css        = screen
css/_search.css           = screen
css/_recent.css           = screen
css/_diff.css             = screen
css/_edit.css             = screen
css/_modal.css            = screen
css/_forms.css            = screen
css/_admin.css            = screen
css/includes.css          = screen
 
css/rtl.css               = rtl
css/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.2) For more information regarding the loading order of stylesheets refer to the docs.

So here is the key part:

We're not gonna edit any of the .css files we copied over from the Starter template!

We just add our own .css files for each mode at <dokuwiki>/lib/tpl/template/<mytemplate>/css instead and modify the style.ini so they get loaded after the original ones:

style.ini
[stylesheets]
 
css/_imgdetail.css        = screen
css/_media_popup.css      = screen
css/_media_fullscreen.css = screen
css/_fileuploader.css     = screen
css/_tabs.css             = screen
css/_links.css            = screen
css/_toc.css              = screen
css/_footnotes.css        = screen
css/_search.css           = screen
css/_recent.css           = screen
css/_diff.css             = screen
css/_edit.css             = screen
css/_modal.css            = screen
css/_forms.css            = screen
css/_admin.css            = screen
css/mytemplate_screen.css = screen
 
css/rtl.css                = rtl
css/mytemplate_rtl.css     = rtl
css/print.css              = print
css/mytemplate_print.css   = print

Instead of editing any of the .css files we copied over from the Starter template we add our CSS rules to the files we just created and make use of a key CSS feature: the so-called cascade.3) Expressed in simplified terms, CSS rules simply override previous rules affecting the same element.4) And in some cases where the specificity of your rule is not enough, you may use !important5) or an own class to solve such problems.

So we just override any Starter template CSS rule we like to change in our own mytemplate_screen.css, mytemplate_rtl.css and mytemplate_print.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. Additionally, you may noticed that I removed some original Starter template files which are not starting with an underscore (basic.css, structure.css, design.css, content.css and includes.css). The reason for this is simple: only the files starting with an underscore plus rtl.css and print.css are the important core styles, the rest is supposed to be adjusted. Therefore use them as starting point for your own mytemplate_screen.css.

Another thing you may like to consider while modifying DokuWiki's CSS is that it is best to access the elements the same way as done in the Starter template CSS files and prepend most ids or classes with .dokuwiki. And have a look at the color placeholders. If you happen to edit the main.php of your template to add or edit something you shouldn't remove the <div class="dokuwiki"> as it will break the whole stylesheet!

To get a clue about which rules to overwrite, it may help you to look at the CSS files of my templates prsnl10 and mnml-blog:

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. This should be around ~2kB till 15kB (uncompressed), depending on the things you are changing. 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.6) And it is not “unclean” or something like that because the Wiki's data is not affected and a template is not triggering any dependencies for your data in general.

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 very quickly! The only thing you have to do is to run a diff against all .css files you copied from the Starter template against the original ones (or have a look at the Commits, e.g. if you are not familiar with tools like diff). Checking the Starter template changelog is also a good idea. If there have been changes, just copy the changed .css files of the Starter template to your template folder overriding the old ones, and, only if needed, add some extra rules to your custom .css files to adjust everything to your needs. The best place to check if everything is OK is the syntax page included in every DokuWiki release.7) It is also recommendable to have a look at the .php files provided by the Starter template to determine if there are any changes needed for new features. The official Developers Changelog may help you to support new features, too.

Some additional notes

That's it! At least this approach works pretty well for me ;-). 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 create a different look for DokuWiki and like to share it, this is one way to keep things easy over time. Keeping things maintained is normally much harder than creating something new, therefore the additional work when starting a new template should pay off quickly. The approach is even powerful enough to make things like vector8) or this blog's template mnml-blog possible without getting to much trouble when a new DokuWiki version was released.

In the past, the best way to start an own template was to copy DokuWiki's default template. The reason is simple: there was no such useful thing as the Starter template. Therefore all of my existing templates were based on the default template CSS. But things changed a bit. First of all, DokuWiki will get a new default template called “dokuwiki” in the near future. Therefore I asked on the mailing list if it is better to use the “Starter” template CSS or wait for the new “dokuwiki” template CSS as technical base for the development approach described in this text. And the answer is clear: use the Starter template as the new default template is based on Starter, too. Therefore I switched all of my templates over from the old default template CSS to the Starter template CSS as technical base.9) I'm sure a comparable situation won't happen again. Relying on the default template simply was less future-proof than relying on the now existing Starter template which is just existing to make template developing easier.

Update 2011-12-03: I updated parts of the article to fit the newest changes and Anika's recommendations.

This post is based on a text created by Michael Klier. He decided to shut down his blog. The unmodified text was originally posted on August, 16th 2007 and is licensed under the Creative Commons BY-NC-SA License and accordingly this text also is. I just took his post and changed the needed things to fit the facts of 2011.

1)
Anika is an important and reliable part of the DokuWiki development and also responsible for the coming DokuWiki default template called “dokuwiki”.
2)
You can have a look at it by using your browser's print preview.
3)
The first “C” in CSS, you know.
4)
In fact, the priority scheme is a little bit more complicated but this should not matter in general. If you want to know more about, have a look at the weblinks at the end of this text.
5)
Usage example: p { font-size:1em !important; }
6)
I am sure there are other opinions on that topic though
7)
Tip: open two tabs in Firefox (one for the old, one for the new version) and use Ctrl+Page↑ / Ctrl+Page↓ to quickly switch between them for a comparison. Use the headline navigation (e.g. :wiki:syntax#tables) to jump to the exactly same point in both versions.
8)
which merges DokuWiki and MediaWiki CSS
9)
This sounds harder than it really is…

Comments

No. 1 @ 2011/03/20 03:17

Hello,

What about modifications in your monobook theme ? I am doing a test in a local install, to integrate it visually first, with Wordpress (for the site that is linked with my comment), and found that in order to change the color of the upper navigation links, I had to change the file main.css which is here under “/var/www/html/wiki/lib/tpl/monobook/static/3rd/monobook”.

I added just this: #p-personal a { color: #3B81C9 !important; font-weight: bold; } #p-personal a:hover { color: #FFFE94 !important; font-weight: bold; }

and while reading the above tutorial I was wondering if there would be a way in monobook to externalise the changes as well, so that future updates would not mess it up ? (I created a dark blue background out of the bgheader.jpg, to match the header of the website therefore I needed to change the default color for these links).

Thanks a lot for this very ingenious theme !

Regards Mélodie

No. 2 @ 2011/03/21 00:26

@Mélodie: Hi Mélodie. In fact, this feature is already built-in. All you have to do is: put your additions into /lib/tpl/monobook/user/screen.css, cause files in /user/ will be preserved on updates, so you don't have to do your customizations over and over again. /user/screen.css is loaded as last file, using the principle described in the blog posting.

Have a look at:

Hope that helps ;-)

No. 3 @ 2011/03/28 16:33

[…] How to create an easy maintainable DokuWiki template […]

No. 4 @ 2011/06/19 17:09

Thanks for supporting the Starter template. :)

There is one thing which I would do differently: Don't keep basic.css, structure.css, design.css and content.css if you don't use them! Only the files starting with an underscore are the important core styles, the rest is supposed to be adjusted. I understand that you'd like to make upgrading easier. But in that case you should rather remove (or comment) those 4 css files from the style.ini and create your “mytemplate_screen.css” as proposed. (Or create mytemplate_basic.css, mytemplate_structure.css, etc.) The rtl and print styles might be an exception to that rule, because they are already quite universal.

One other thing: It's considered bad practice to use “!important”. Instead you could add a class to your <body> (or to a div around everything) and override other rules by e.g. body.mytemplate .dokuwiki { font-size: 90%; }.

No. 5 @ 2012/01/23 19:51

Thanks! This helps me understand templates more better!

No. 6 @ 2013/01/29 02:23

Thank you to Andreas and also Anika Henke for clearing up many questions I had about templates. I did have one question in regards to this:

“Another thing you may like to consider while modifying DokuWiki's CSS is that it is best to access the elements the same way as done in the Starter template CSS files and prepend most ids or classes with .dokuwiki.”

Why is it a good idea to prepend ids or classes with .dokuwiki? I apologies as I am a bit clueless about CSS.

Leave a comment…




E᠎ T D᠎ F​ Q
  • E-Mail address will not be published.
  • Formatting:
    //italic//  __underlined__
    **bold**  ''preformatted''
  • Links:
    [[http://example.com]]
    [[http://example.com|Link Text]]
  • Quotation:
    > This is a quote. Don't forget the space in front of the text: "> "
  • Code:
    <code>This is unspecific source code</code>
    <code [lang]>This is specifc [lang] code</code>
    <code php><?php echo 'example'; ?></code>
    Available: html, css, javascript, bash, cpp, …
  • Lists:
    Indent your text by two spaces and use a * for
    each unordered list item or a - for ordered ones.
I'm no native speaker (English)
Please let me know if you find any errors (I want to improve my English skills). Thank you!
QR Code: URL of current page
QR Code: URL of current page 2011:03:16:how-to-create-a-maintainable-dokuwiki-template (generated for current page)