1 | Title: README of the monobook template for DokuWiki
|
---|
2 | Creation date: 2010-01-05
|
---|
3 | Last Update: 2011-11-24
|
---|
4 | Author: Andreas Haerter <development [Àt] andreas-haerter.com>
|
---|
5 | Web: <http://andreas-haerter.com/projects/dokuwiki-template-monobook>
|
---|
6 | <http://www.dokuwiki.org/template:monobook>
|
---|
7 |
|
---|
8 |
|
---|
9 |
|
---|
10 | PLEASE NOTE: I am NO native English speaker. If you find any errors please let
|
---|
11 | me know (e.g. by mail). Otherwise, my English is not getting better
|
---|
12 | (as desired by myself). Thank you! -- Andreas Haerter
|
---|
13 |
|
---|
14 |
|
---|
15 |
|
---|
16 | I. Using/Installing the template
|
---|
17 | Using "monobook" is simple and works just as described at
|
---|
18 | <http://www.dokuwiki.org/template>: extract the downloaded archive into
|
---|
19 | your DokuWiki's "lib/tpl/" folder. Then select the template in the Config
|
---|
20 | Manager by adjusting the template option. Done. :-)
|
---|
21 |
|
---|
22 | If you are updating an existing monobook-installation: please have a look at
|
---|
23 | <http://www.dokuwiki.org/template:monobook>, you should find all needed
|
---|
24 | information there.
|
---|
25 |
|
---|
26 | NOTE: If everything will be displayed unformatted, your PHP environment is
|
---|
27 | probably affected by PHP bug #49692 (see bugreport at
|
---|
28 | <http://bugs.php.net/bug.php?id=49692> for details). You may find errors
|
---|
29 | like "syntax error, unexpected '/' in ../../lib/tpl/monobook/style.ini
|
---|
30 | on line XX" in your PHP logs when this is the case. monobook provides
|
---|
31 | a workaround for this, simply delete monobook's "style.ini" to trigger
|
---|
32 | the template to use it.
|
---|
33 |
|
---|
34 |
|
---|
35 |
|
---|
36 | II. Customizing the template
|
---|
37 | In order to make updates of your installed "monobook" template easy, follow
|
---|
38 | these hints for customizing the template:
|
---|
39 |
|
---|
40 | - Place your files in "monobook/user"
|
---|
41 | The place for *all* userdefined, custom stuff is "monobook/user".
|
---|
42 | Reason: this folder will not be touched on updates. Therefore you may delete
|
---|
43 | everything except "monobook/user" and copy all new files into "monobook/" to
|
---|
44 | update without loosing your changes. Do not forget to empty your browser's
|
---|
45 | cache afterwards.
|
---|
46 |
|
---|
47 | - Own logo
|
---|
48 | If you want to replace the default logo showed in the upper left, simply
|
---|
49 | create a "logo.[png|gif|jpg]" in "monobook/user". The template recognizes
|
---|
50 | the file automatically and will use it instead of the default logo.
|
---|
51 | Do not forget to empty your browser's cache afterwards.
|
---|
52 |
|
---|
53 | - Own favicon
|
---|
54 | If you want to replace the default favicon, simply create a "favicon.ico" in
|
---|
55 | "monobook/user". The template recognizes the file automatically and will use
|
---|
56 | it instead of the default one. Do not forget to empty your browser's cache
|
---|
57 | afterwards. By the way: you might find the following online tool useful:
|
---|
58 | <http://tools.dynamicdrive.com/favicon/>.
|
---|
59 | Note: "favicon.png" is also possible but not recommended (cause it is not
|
---|
60 | supported by most MSIE versions).
|
---|
61 |
|
---|
62 | - Own CSS
|
---|
63 | To apply additional CSS rules, edit "monobook/user/screen.css" (influences
|
---|
64 | normal layout) and/or "monobook/user/print.css" (influences print layout)
|
---|
65 | and/or "monobook/user/rtl.css" (influences "right-to-left" languages like
|
---|
66 | hebrew). These files will be included automatically (as the last ones for
|
---|
67 | the relevant media, therefore you are able to overrule existing styles). Do
|
---|
68 | not forget to empty your browser's cache afterwards.
|
---|
69 |
|
---|
70 | - Own JavaScript
|
---|
71 | To load additional JavaScript, edit "monobook/user/user.js". Do not forget
|
---|
72 | to empty your browser's cache afterwards.
|
---|
73 | ATTENTION: Do not forget to activate the template option
|
---|
74 | "monobook_loaduserjs" (->"Load 'monobook/user/user.js'?") in the
|
---|
75 | DokuWiki Config Manager!
|
---|
76 |
|
---|
77 | - Own CSS, language specific
|
---|
78 | To apply additional CSS rules only for a specific language, edit/create
|
---|
79 | "monobook/lang/<your-language>/style.css". This file will be included
|
---|
80 | automatically if DokuWiki runs/shows a page in the language of choice (as
|
---|
81 | the last one, therefore you are able to overrule existing styles). Do
|
---|
82 | not forget to empty your browser's cache afterwards.
|
---|
83 |
|
---|
84 | - Own tabs
|
---|
85 | To apply own tabs, have a look at "monobook/user/tabs.php". Don't worry:
|
---|
86 | you will find some examples how to define the tabs. If you still have
|
---|
87 | questions after playing with the examples, search
|
---|
88 | <http://dokuwiki.org/template:monobook> and/or the DokuWiki Forum at
|
---|
89 | <http://forum.dokuwiki.org> and/or ask the community if you can't get it
|
---|
90 | work.
|
---|
91 | If "monobook/user/tabs.php" does not exist, simply copy it out of the
|
---|
92 | current actual installation archive.
|
---|
93 |
|
---|
94 | - Own footer buttons
|
---|
95 | To apply own buttons/graphics in the footer (-> these small 80x15 pics),
|
---|
96 | have a look at "monobook/user/buttons.php". Don't worry: you will find some
|
---|
97 | examples how to define the buttons. If you still have questions after
|
---|
98 | playing with the examples, search <http://dokuwiki.org/template:monobook>
|
---|
99 | and/or the DokuWiki Forum at <http://forum.dokuwiki.org> and/or ask the
|
---|
100 | community if you can't get it work.
|
---|
101 | If "monobook/user/buttons.php" does not exist, simply copy it out of the
|
---|
102 | current actual installation archive.
|
---|
103 |
|
---|
104 | - Own boxes
|
---|
105 | To apply own boxes in the left column/sidebar, have a look at
|
---|
106 | "monobook/user/boxes.php". Don't worry: you will find some examples how to
|
---|
107 | define the boxes. If you still have questions after
|
---|
108 | playing with the examples, search <http://dokuwiki.org/template:monobook>
|
---|
109 | and/or the DokuWiki Forum at <http://forum.dokuwiki.org> and/or ask the
|
---|
110 | community if you can't get it work.
|
---|
111 | If "monobook/user/boxes.php" does not exist, simply copy it out of the
|
---|
112 | current actual installation archive.
|
---|
113 |
|
---|
114 | - Web analytics software (Piwik, Google Analytics etc.)
|
---|
115 | Tools like Piwik and Google Analytics normally provide a small code snippet
|
---|
116 | ("tag") which you have to include at your website to make everything work.
|
---|
117 | If you want to use such software with this template, have a look at
|
---|
118 | "monobook/user/tracker.php". This file exists to make it easier for you.
|
---|
119 | You don't have to deliberate where you have to copy and paste the code,
|
---|
120 | simply do it there.
|
---|
121 |
|
---|
122 | - Own Apple Touch Icon
|
---|
123 | If you want to replace the default Apple Touch Icon, simply create a
|
---|
124 | "apple-touch-icon.png" in "monobook/user". The template recognizes the file
|
---|
125 | automatically and will use it instead of the default one. Have a look at
|
---|
126 | Apple's developer database if you need more information ("Configuring Web
|
---|
127 | Applications" <http://j.mp/sx3NMT>).
|
---|
128 |
|
---|
129 |
|
---|
130 |
|
---|
131 | III. Some notes about the dirs of this template
|
---|
132 | * "monobook/conf"
|
---|
133 | Contains some configuration files (do NOT edit them!), especially
|
---|
134 | default.php: default settings, see
|
---|
135 | <http://www.dokuwiki.org/devel:configuration#default_settings>
|
---|
136 | metadata.php: configuration metadata, see
|
---|
137 | <http://www.dokuwiki.org/devel:configuration#configuration_metadata>
|
---|
138 | * "monobook/lang"
|
---|
139 | Language files (subdir names = language code). You may copy the English
|
---|
140 | language files and translate them if your language is missing. Simply mail
|
---|
141 | me, Andreas Haerter, the translated files and I will include them in the
|
---|
142 | next release :-D.
|
---|
143 | * "monobook/static"
|
---|
144 | Static files (images, CSS, JavaScript). The interesting stuff is located
|
---|
145 | in subdirs (as described below).
|
---|
146 | - "3rd"
|
---|
147 | Static files originally taken from a third party like MediaWiki or
|
---|
148 | DokuWiki. The subdir "dokuwiki" contains files originally taken from the
|
---|
149 | DokuWiki "default" or "starter" template. The subdir "monobook" contains
|
---|
150 | files taken from the MediaWiki "monobook" skin.
|
---|
151 | - "css"
|
---|
152 | All non-3rd-party Cascading Style Sheets (CSS). See <http://j.mp/eq8zSo>
|
---|
153 | for more information about how the CSS is handled.
|
---|
154 | - "img"
|
---|
155 | All non-3rd-party images files.
|
---|
156 | - "js"
|
---|
157 | All non-3rd-party JavaScript files.
|
---|
158 | * "monobook/user"
|
---|
159 | Place for userdefined stuff. E.g. if you want to replace the default-logo,
|
---|
160 | simply copy a logo.[png|gif|jpg] in here. See "II. Customizing the template"
|
---|
161 | for details.
|
---|
162 |
|
---|
163 |
|
---|
164 |
|
---|
165 | IV. Other notes
|
---|
166 | - Even if it is not required: If you like the template, think about a small
|
---|
167 | donation (see <http://andreas-haerter.com/donate/dokuwiki-template-monobook>)
|
---|
168 | and/or a link to <http://andreas-haerter.com/projects/dokuwiki-template-monobook>.
|
---|
169 | Thanks :-).
|
---|
170 |
|
---|
171 | - This template follows the DokuWiki coding style (see
|
---|
172 | <http://www.dokuwiki.org/devel:coding_style>). If you want to submit any
|
---|
173 | patches, please respect its rules (even if you don't like it - I also don't
|
---|
174 | love it but this simply does not matter).
|
---|
175 |
|
---|
176 | - Feel free to send patches or suggestions via mail (or post on
|
---|
177 | <http://www.dokuwiki.org/template:monobook>).
|
---|
178 |
|
---|
179 | - Please don't delete the "index.html" and ".htaccess" files for security
|
---|
180 | reasons, even if you don't know why they are there. These files should
|
---|
181 | prevent others from listing directory contents (a built in feature of most
|
---|
182 | webservers) and providing additional access protection for some files. Even
|
---|
183 | if everything should be secure without, I prefer some additional
|
---|
184 | precautions.
|
---|
185 |
|
---|
186 |
|
---|
187 |
|
---|
188 | V. About
|
---|
189 | "monobook" is a template to offer MediaWiki/Wikipedia Look&Feel to DokuWiki.
|
---|
190 | It is created by me, Andreas Haerter and heavily inspired and partially based
|
---|
191 | on the great "Monobook for DokuWiki" template originally maintained by
|
---|
192 | Terence J. Grant (<http://tjgrant.com/>) from 2006 until the end of 2009.
|
---|
193 | If you have any suggestions and/or bug reports, feel free to post on
|
---|
194 | <http://www.dokuwiki.org/template:monobook>, send me an email or have a look
|
---|
195 | at <http://andreas-haerter.com/contact>.
|
---|
196 |
|
---|
197 | After some discussion and a quick release as "monodoku", this template was
|
---|
198 | renamed to "monobook" to replace the existing "Monobook for DokuWiki" by
|
---|
199 | Terence J. Grant cause Terence got no more time for maintenance (BTW: Terence,
|
---|
200 | thank you for your work and your great(!) ideas I got from your "Monobook for
|
---|
201 | DokuWiki"). To cut a long story short: you may call this template a
|
---|
202 | rewrite/successor of Terence J. Grant's "Monobook for DokuWiki".
|
---|
203 |
|
---|
204 | There are some reasons for a complete rewrite (instead of improving/patching
|
---|
205 | Terence J. Grant's one), let me explain the initial situation:
|
---|
206 | * "monobook" is a wide-spread skin for the MediaWiki-Software. It is also
|
---|
207 | used by Wikipedia right now (Jan 2010).
|
---|
208 | * Terence J. Grant (<http://tatewake.com/>) created "monobook for DokuWiki".
|
---|
209 | He emulated some missing MediaWiki features within the DokuWiki
|
---|
210 | environment with his template (e.g.: discussion pages) - he did a great
|
---|
211 | job! The styles themselfs are a relatively hard copy of the original
|
---|
212 | "monobook" css- and js-files from MediaWiki's "monobook" and the Wikipedia
|
---|
213 | website. IMHO Terence had quick updates in mind when doing this (means:
|
---|
214 | when Wikipedia is updating its styles, he might just want to copy the
|
---|
215 | static stuff, comment out some lines and the "porting" would be done). You
|
---|
216 | will find some information about his actions in the README of the replaced
|
---|
217 | "monobook for DokuWiki" by Terence J. Grant (still available at
|
---|
218 | <http://www.dokuwiki.org/template:monobook>).
|
---|
219 | * Terence J. Grant does not have enough time for maintenance (as he said on
|
---|
220 | his website at the end of 2009). Additionally, the roughly wrapped
|
---|
221 | Wikipedia/monobook-styles and the structure were makinging some trouble:
|
---|
222 | - The styles were bloated (-> they are not designed for DokuWiki, most
|
---|
223 | styles are simply not used plus they are specialized for Wikipedia's
|
---|
224 | websites, not even MediaWiki in special).
|
---|
225 | - Hardcoded URLs within some css-files were resulting in problems in SSL
|
---|
226 | environments (-> loading unencrypted content from
|
---|
227 | http://upload.wikimedia.org... additionally, calling third party hosts
|
---|
228 | is bad behaviour + LAN-only environments simply will not get needed
|
---|
229 | files).
|
---|
230 | - The styles.ini was not used, leading to *much* bigger stylesheets and
|
---|
231 | much more HTTP requests because some nice DokuWiki features were not
|
---|
232 | used and/or "Monobook for DokuWiki" was not compatible to (-> "Compact
|
---|
233 | CSS and javascript output").
|
---|
234 | * Terence J. Grant's template needed the "Display Wiki Page"-plugin (which
|
---|
235 | is/was developed by him, too). Right now, this is simply not needed
|
---|
236 | anymore: DokuWiki got a core function named "tpl_include_page()" to do
|
---|
237 | this.
|
---|
238 | That is why I decided to take the great ideas plus some lines of code of
|
---|
239 | Terence J. Grant's "monobook for DokuWiki" to rewrite it, following the
|
---|
240 | appreciated DokuWiki template structure guidelines
|
---|
241 | (-> <http://www.dokuwiki.org/devel:templates>).
|
---|
242 | The downside of this desicion is, that if Wikipedia updates its styles,
|
---|
243 | reverse engineering instead of simple file copying is needed if the new
|
---|
244 | rules should be applied. But I think this is not really dramatical cause
|
---|
245 | not every pinch of change should be ported (and if Wikipedia would get a
|
---|
246 | completely new layout, a new DokuWiki template should be created instead
|
---|
247 | of forcing people to decide: a) not using updates or b) using a style the
|
---|
248 | might not like). I want an optical, not a technical clone.
|
---|
249 |
|
---|
250 |
|
---|
251 |
|
---|
252 | VI. Creation transcript
|
---|
253 | Some developers may find this interesting. Additionally, I am very oblivious
|
---|
254 | :-P.
|
---|
255 |
|
---|
256 | - Installed DokuWiki (Release "2009-12-25", "Lemming") + Terence J. Grant's
|
---|
257 | "monobook" template for testing purpose.
|
---|
258 |
|
---|
259 | - Copied the default template from DokuWiki (Release "2009-12-25", "Lemming")
|
---|
260 | as mentioned at <http://www.dokuwiki.org/devel:templates> and renamed the
|
---|
261 | copy to "monobook". Afterwards, the following files/dirs where deleted:
|
---|
262 | * monobook/images
|
---|
263 | * monobook/_admin.css
|
---|
264 | * monobook/design.css
|
---|
265 | * monobook/footer.html
|
---|
266 | * monobook/layout.css
|
---|
267 | * monobook/_linkwiz.css
|
---|
268 | * monobook/media.css
|
---|
269 | * monobook/print.css
|
---|
270 | * monobook/rtl.css
|
---|
271 |
|
---|
272 | - Created the dirs mentioned in "II. Some notes about the dirs of this
|
---|
273 | template".
|
---|
274 |
|
---|
275 | - Created "index.html" files in all subdirs of the template to prevent
|
---|
276 | directory browsing. Plus "deny from all" .htaccess files in all relevant
|
---|
277 | template subdirs containing PHP (this is simply some ADDITIONAL security
|
---|
278 | precaution - everything should also be save without these files. But better
|
---|
279 | safe than sorry).
|
---|
280 |
|
---|
281 | - Configured DokuWiki to use Terence J. Grant's "monobook" template to
|
---|
282 | determine which styles/files copied from the MediaWiki monobook and/or
|
---|
283 | Wikipedia are really in use (after looking and understanding the template
|
---|
284 | itself, for sure).
|
---|
285 | The interessting folders (as mentioned in the README by Terence J. Grant):
|
---|
286 | * common is from mediawiki
|
---|
287 | * monobook is from mediawiki
|
---|
288 | * wikipedia is from wikipedia
|
---|
289 | After this, I looked at "monobook/lang/*" and "monobook/conf*" (from
|
---|
290 | Terence J. Grant's "monobook") to take some ideas.
|
---|
291 |
|
---|
292 | - After investigation, some files were copied into the provided places within
|
---|
293 | "/monobook/static/3rd".
|
---|
294 | - The following 3rd-party styles and files were used/are needed for further
|
---|
295 | development and therefore were copied from Terence J. Grant's "monobook"
|
---|
296 | template:
|
---|
297 | * /monobook/monobook/buttonshadow.png
|
---|
298 | * /monobook/monobook/bullet.gif
|
---|
299 | * /monobook/monobook/discussionitem_icon.gif
|
---|
300 | * /monobook/monobook/external.png
|
---|
301 | * /monobook/monobook/file_icon.gif
|
---|
302 | * /monobook/monobook/headbg.jpg
|
---|
303 | * /monobook/monobook/IE50Fixes.css
|
---|
304 | * /monobook/monobook/IE55Fixes.css
|
---|
305 | * /monobook/monobook/IE60Fixes.css
|
---|
306 | * /monobook/monobook/IE70Fixes.css
|
---|
307 | * /monobook/monobook/IEMacFixes.css
|
---|
308 | * /monobook/monobook/lock_icon.gif
|
---|
309 | * /monobook/monobook/mail_icon.gif
|
---|
310 | * /monobook/monobook/main.css
|
---|
311 | * /monobook/monobook/news_icon.gif
|
---|
312 | * /monobook/monobook/rtl.css
|
---|
313 | * /monobook/monobook/user.gif
|
---|
314 | - The following files were copied from Andreas Gohr's "default" template:
|
---|
315 | * /default/*.css (see <http://j.mp/eq8zSo> why I did that)
|
---|
316 | * /default/images/closed.gif
|
---|
317 | * /default/images/favicon.ico
|
---|
318 | * /default/images/link_icon.gif
|
---|
319 | * /default/images/mail_icon.gif
|
---|
320 | * /default/images/open.gif
|
---|
321 | * /default/images/tocdot2.gif
|
---|
322 | * /default/images/windows.gif
|
---|
323 | - The following files were downloaded from Wikipedia
|
---|
324 | * http://de.wikipedia.org/skins-1.5/common/IEFixes.js
|
---|
325 | * http://de.wikipedia.org/skins-1.5/common/commonPrint.css
|
---|
326 |
|
---|
327 | - Edited "monobook/static/3rd/monobook/main.css"
|
---|
328 | - All url() rules were edited (-> "static/3rd/...").
|
---|
329 | - "#catlinks" was replaced with ".catlinks" cause the styles are needed for
|
---|
330 | more than one element.
|
---|
331 | To make this clear, a comment was added at the top of the files.
|
---|
332 |
|
---|
333 | - Edited "monobook/static/3rd/dokuwiki/design.css"
|
---|
334 | All url() rules were edited (-> replaced "url(images/" through
|
---|
335 | "url(static/3rd/dokuwiki/").
|
---|
336 | To make this clear, a comment was added at the top of the files:
|
---|
337 | /* ATTENTION: This file was edited for the "monobook template for DokuWiki".
|
---|
338 | - All url() rules where changed.
|
---|
339 | See README for details. */
|
---|
340 |
|
---|
341 | - Edited "monobook/static/3rd/monobook/IE60Fixes.css"
|
---|
342 | - "#catlinks" was replaced with ".catlinks" cause the styles are needed for
|
---|
343 | more than one element.
|
---|
344 | To make this clear, a comment was added at the top of the files.
|
---|
345 |
|
---|
346 | - Created
|
---|
347 | * "monobook/static/css/print.css"
|
---|
348 | * "monobook/static/css/rtl.css"
|
---|
349 | * "monobook/static/css/screen.css"
|
---|
350 | All relevant information should be found within the inline comments.
|
---|
351 |
|
---|
352 | - Created the "main.php" for "monobook". Used the main.php of the "default"
|
---|
353 | template as base (as mentioned on the DokuWiki template developer sites),
|
---|
354 | and doing some cherry picking on the Terence J. Grant's "monobook" main.php.
|
---|
355 | After few hours and some coffees later, work was done.
|
---|
356 |
|
---|
357 | - Placed the obligatory 80x15 buttons in "/static/img". I copied them
|
---|
358 | from the "default" DokuWiki template (exept "button-monobook.png", for
|
---|
359 | sure). Added the needed markup in the "main.php".
|
---|
360 |
|
---|
361 | - Took Andreas Gohr's original "mediamanager.php" and "detail.php" out of the
|
---|
362 | "default" template. After working a little bit, I found a way to prevent
|
---|
363 | additional work and/or redundant code to realize the output of these files.
|
---|
364 | Everything is described through the PHP comments in the files... look at
|
---|
365 | them if needed. I mainly choose the same way like Terence J. Grant.
|
---|
366 |
|
---|
367 | - Copied the "do_cite.php" from Terence J. Grant's "monobook", renamed it to
|
---|
368 | "inc_cite.php", and edited everything until it was useful for my template.
|
---|
369 |
|
---|
370 | - Worked worked worked.... and done! :-P
|
---|
371 |
|
---|
372 | - After ~1 year, I switched the CSS base from DokuWiki's default template
|
---|
373 | to <http://www.dokuwiki.org/template:starter>. See
|
---|
374 | <http://www.freelists.org/post/dokuwiki/Core-devs-I-need-some-info-to-keep-my-templates-maintainable>
|
---|
375 | for more information about this. I edited some files, see
|
---|
376 | "monobook/static/3rd/dokuwiki/00_starter-tmpl-notes.txt" for details.
|
---|
377 |
|
---|