README
1
2 I. About
3
4 "vector" brings you the MediaWiki/Wikipedia 2010 look and feel for DokuWiki.
5 It is a mostly optical port of the original MediaWiki "vector" skin.
6
7 Website: <https://www.dokuwiki.org/template:vector>
8 Maintainer: ARSAVA <https://dev.arsava.com/>
9 Contact: See "IV. Support" and "V. Contact".
10
11
12
13 II. Installation and update
14
15 The installation works as described [1] on DokuWiki.org. Extract the
16 downloaded archive into your DokuWiki's "lib/tpl/" folder. Then select the
17 template in the Config Manager by adjusting the template option.
18
19 See the vector template website for update instructions [2].
20
21 [1] <https://www.dokuwiki.org/template>
22 [2] <https://www.dokuwiki.org/template:vector#update>
23
24
25
26 III. Customizing the template
27
28 In order to make updates of your installed "vector" template easy, follow
29 these hints for customizing the template:
30
31 - Place your files in "vector/user"
32 The place to store *all* user-defined, custom stuff is the "vector/user"
33 directory because your files will not be touched or overwritten on
34 template updates! So you normally can copy all new files into "vector/"
35 to update the template without loosing your changes.
36 Note: There are example files helping you modifying the template.
37 The are delivered with the ".dist" extensions. Just remove the
38 ".dist" extension to use them.
39
40 - Own logo
41 If you want to replace the default logo showed in the upper left, simply
42 create a "logo.[png|gif|jpg]" in "vector/user". The template recognizes
43 the file automatically and will use it instead of the default logo.
44 Note: Do not forget to empty your browser's cache if you cannot see any
45 effect.
46
47 - Own favicon
48 If you want to replace the default favicon, simply create a "favicon.ico"
49 in "vector/user". The template recognizes the file automatically and
50 will use it instead of the default one. You might find the online FavIcon
51 Generator [1] useful.
52 Note: "favicon.png" is also possible but not recommended (because it is
53 not supported by older MSIE versions).
54
55 - Own CSS
56 To apply additional CSS rules, create a
57 - "vector/user/screen.css" file to influence the normal layout. You
58 can rename the "screen.css.dist" to "screen.css" as starting point.
59 - "vector/user/print.css" file to influence the print layout. You
60 can rename the "print.css.dist" to "print.css" as starting point.
61 - "vector/user/rtl.css" file to influences "right-to-left" languages
62 like Hebrew. You can rename the "rtl.css.dist" to "rtl.css" as
63 starting point.
64 The file(s) will be included automatically (as the last ones for the
65 relevant media, therefore you are able to overrule existing styles).
66 Note: Do not forget to empty your browser's cache if you cannot see any
67 effect.
68
69 - Own JavaScript
70 To load additional JavaScript, create a "vector/user/user.js" file. You
71 can rename the "user.js.dist" to "user.js" as starting point (it contains
72 some examples and useful comments how to define your own JavaScript).
73 ATTENTION: You have to activate the template option "vector_loaduserjs"
74 (->"Load 'vector/user/user.js'?") in the DokuWiki Config
75 Manager!
76
77 - Own CSS, language specific
78 To apply additional CSS rules only for a specific language, edit/create
79 "vector/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).
82 Note: Do not forget to empty your browser's cache if you cannot see any
83 effect.
84
85 - Own tabs
86 To apply own tabs, create a "vector/user/tabs.php" file. You can rename
87 the "tabs.php.dist" to "tabs.php" as a good starting point (it contains
88 some examples and useful comments how to define your own tabs). If you
89 still have questions after playing with the examples, see "IV. Support"
90 on how to get help.
91
92 - Own footer buttons
93 To apply own buttons/graphics in the footer (-> these small 80x15 pics),
94 create a "vector/user/buttons.php" file. You can rename the
95 "buttons.php.dist" to "buttons.php" as a good starting point (it contains
96 some examples and useful comments how to define your own buttons). If you
97 still have questions after playing with the examples, see "IV. Support"
98 on how to get help.
99
100 - Own boxes
101 To apply own boxes in the left column/sidebar, create a
102 "vector/user/boxes.php" file. You can rename the "boxes.php.dist" to
103 "boxes.php" as a good starting point (it contains some examples and useful
104 comments how to define your own boxes). If you still have questions after
105 playing with the examples, see "IV. Support" on how to get help.
106
107 - Web analytics software (Piwik, Google Analytics etc.)
108 Tools like Piwik and Google Analytics normally provide a small code
109 snippet ("tag") which you have to include at your website to make
110 everything work. If you want to use such software with this template,
111 create a "vector/user/tracker.php.dist". You don't have to deliberate
112 where you have to copy and paste the code, simply do it there. You can
113 rename the "tracker.php.dist" to "tracker.php" as a good starting point
114 (it contains some examples and useful comments how to define your own
115 boxes).
116
117 - Own Apple Touch Icon
118 If you want to replace the default Apple Touch Icon, simply create a
119 "apple-touch-icon.png" in "vector/user". The template recognizes the file
120 automatically and will use it instead of the default one. Have a look at
121 Apple's developer database (cf. "Configuring Web Applications" [2]) if you
122 need more information.
123
124 [1] <http://tools.dynamicdrive.com/favicon/>
125 [2] <http://j.mp/sx3NMT>
126
127
128
129 IV. Support
130
131 If you need help, check the FAQ [1] and try to find useful information by
132 using the DokuWiki Search page [2]. If you found nothing helpful, ask your
133 question at the DokuWiki forum [3] (preferred) or IRC channel [4].
134
135 [1] <https://www.dokuwiki.org/template:vector#faq>
136 [2] <http://search.dokuwiki.org/>
137 [3] <https://forum.dokuwiki.org/>
138 [4] <https://www.dokuwiki.org/irc>
139
140
141
142 V. Contact
143
144 If you think you have found a bug or have a useful idea (a.k.a. "feature
145 request"), create an issue [1] on GitHub (preferred), or contact us by
146 mail [2].
147
148 Feel free to submit patches as GitHub pull requests (preferred) or by mail
149 as well. However, please try to respect the DokuWiki coding style [3] as
150 this template follows its rules.
151
152 [1] <https://github.com/arsava/dokuwiki-template-vector/issues>
153 [2] ARSAVA <dokuwiki@dev.arsava.com>
154 [3] <https://www.dokuwiki.org/devel:coding_style>
155
156
157
158 VI. Other notes
159
160 If you like this free project, you might buy us a coffee [1], or get some
161 cool QR Code merchandise [2]. Thank you! :-)
162
163 Do not hesitate to contact ARSAVA [3] if you need professional DokuWiki
164 support, training or if you think we are the ones to get your project done.
165
166 [1] <https://donate.arsava.com/dokuwiki-template-vector/>
167 [2] <http://goqr.me/>
168 [3] <https://dev.arsava.com/>
169
170
171
172 VII. Explanatory notes about the dirs of this template
173
174 - "vector/conf"
175 Contains some configuration files (do NOT edit them!), especially
176 - default.php: default settings [1]
177 - metadata.php: configuration metadata [2]
178
179 - "vector/lang"
180 Language files (subdir names = language code). You may copy the English
181 language files and translate them if your language is missing. Simply send
182 us the translated files (cf. "V. Contact") and I will include them in the
183 next release :-D.
184
185 - "vector/static"
186 Static files (images, CSS, JavaScript). The interesting stuff is located
187 in subdirs (as described below).
188 - "3rd"
189 Static files originally taken from a third party like MediaWiki or
190 DokuWiki. The subdir "dokuwiki" contains files originally taken from the
191 DokuWiki "default" or "starter" template. The subdir "vector" contains
192 files taken from the MediaWiki "vector" skin.
193 - "css"
194 All non-3rd-party Cascading Style Sheets (CSS). See my tutorial [3] for
195 more information about how the CSS is handled.
196 - "img"
197 All non-3rd-party images files.
198 - "js"
199 All non-3rd-party JavaScript files.
200
201 - "vector/user"
202 Place for userdefined stuff. E.g. if you want use an own logo, simply copy
203 a logo.[png|gif|jpg] in here. See "III. Customizing the template" for
204 details.
205
206 [1] <https://www.dokuwiki.org/devel:configuration#default_settings>
207 [2] <https://www.dokuwiki.org/devel:configuration#configuration_metadata>
208 [3] <http://j.mp/eq8zSo>
209
210
211
212 VIII. Creation transcript
213
214 Some developers may find this interesting. Additionally, I am very oblivious
215 :-P.
216
217 - Downloaded the nightly MediaWiki build (because only the SVN version is
218 containing the vector skin as I'm writing this) from
219 <http://toolserver.org/~vvv/mw-nightly/>.
220
221 - Installed DokuWiki (Release "2009-12-25c", "Lemming") for testing purpose.
222
223 - Copied all "monobook for DokuWiki" sources because it already fits some of
224 my needs regarding config options and non-layout features. Means: I used
225 the source of the "monobook for DokuWiki" template as base for "vector for
226 DokuWiki".
227
228 - replaced "monobook" through "vector" in:
229 - /conf/*
230 - /lang/*
231 - /detail.php
232 - /inc_cite.php
233 - /inc_detail.php
234 - /inc_mediamanager.php
235 - /main.php
236 - /mediamanager.php
237
238 - After investigation, some 3rd-party files were copied into the provided
239 places within "/vector/static/3rd".
240 - The following files were copied from the original vector skin:
241 - /skins/vector/csshover.htc
242 - /skins/vector/main-ltr.css
243 - /skins/vector/main-rtl.css
244 - /skins/vector/images/*
245 - The following files were copied from Andreas Gohr's "default" template:
246 - /default/*.css (see <http://j.mp/eq8zSo> why I did that)
247 - /default/images/closed.gif
248 - /default/images/favicon.ico
249 - /default/images/open.gif
250 - /default/images/tocdot2.gif
251 - The following files were copied from Anika Henke's's "starter" template:
252 - /starter/images/external-link.png
253 - /starter/images/unc.png
254 - /starter/images/email.png
255
256 - Edited:
257 - "/vector/static/3rd/vector/main-ltr.css"
258 "/vector/static/3rd/vector/main-rtl.css"
259 All url() rules were edited (-> replaced "url(images/" through
260 "url(static/3rd/vector/", deleted "?1" and "?2 postfixes").
261 To make this clear, a comment was added at the top of the files.
262
263 - "/vector/static/3rd/dokuwiki/design.css"
264 All url() rules were edited (-> replaced "url(images/" through
265 "url(static/3rd/dokuwiki/").
266 To make this clear, a comment was added at the top of the files.
267
268 - Visited <http://en.wikipedia.org/w/index.php?title=ASCII>, copied the
269 XHTML source and let Tidy do the dirty work to get a valid clean and
270 correctly indented base markup (after core removal, for sure). This markup
271 was then compared with the current main.php and needed changes where done.
272
273 - Created new files:
274 - "vector/static/css/print.css"
275 - "vector/static/css/rtl.css"
276 - "vector/static/css/screen.css"
277 All relevant information should be found within the inline comments.
278
279 - Worked worked worked a few days.... and done! :-P
280
281 - After ~1 year, I switched the CSS base from DokuWiki's default template
282 to <https://www.dokuwiki.org/template:starter>. See <http://j.mp/f7V4ES>
283 for more information about this. I edited some files, see
284 "vector/static/3rd/dokuwiki/00_starter-tmpl-notes.txt" for details.
285
286
