[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
recommendation?
[1]<http://www.m-klier.de/blog/2007/0816_how_to_create_an_easy_maintainable_dokuwiki_template>
--
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:
<code>
% cd <dokuwiki>/lib/tpl
% cp -av default newtemplate
</code>
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>
[stylesheets]
layout.css = screen
design.css = screen
style.css = screen
media.css = screen
rtl.css = rtl
print.css = print
</file>
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
template**
</WRAP>
Instead we add our own .css files and modify the ''style.ini'' so they get
loaded **after** the original ones.
<code>
% cd <dokuwiki>/lib/tpl/mytemplate/
% touch mytemplate_design.css mytemplate_print.css
</code>
<file txt style.ini>
[stylesheets]
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
</code>
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
stylesheet!
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:
