unit tests MDL-22017 made test_usergetdate() work on machines in different timezones
[moodle.git] / mod / wiki / ewiki / README
CommitLineData
39fcb981 1
2ErfurtWiki - a fast, user-friendly, highly configurable Wiki engine in PHP
3==========================================================================
4
5
6README
14a960ac 7������
39fcb981 8This is the documentation for ewiki. I tries to describe nearly everything,
9but therefore has now grown to long to be read at once. However it is often
10sufficient to just read the first few paragraphs to set it up (plugins can be
11activated at any later time). If you have the Wiki running, then you can also
12read this file in hypertext format.
13
14
15 1 What is this?
16 1.1 Why "ErfurtWiki"?
17 1.2 WikiAlternatives
18 1.3 Authors
19 1.4 Project pages
20 1.5 Obtaining support
21 1.6 License
22 1.7 Known Bugs
23
24 2 HowTo
25 2.1 Integration with yoursite.php
26 2.1.1 Creating a "config.php"
27 2.1.2 Generation of a "monsterwiki.php" script
28 2.1.3 What to do if images don't work
29 2.2 Supplying the WikiPageName
30 2.2.1 mod_rewrite or PATH_INFO
31 2.2.2 use with the 404 trick
32 2.3 Security considerations
33 2.3.1 PHP settings (register_globals)
34 2.3.2 _protected_mode
35 2.4 simple usage restrictions via wrappers
36 2.5 PhpWiki compatibility
37 2.5.1 Transition from another WikiWare
38 2.6 Idea Collection
39 2.6.1 Multiple Wikis / InterWiki feature abuse
40
41 3 Internals
42 3.1 the ewiki_ functions
43 3.2 $GLOBALS pollution
44 3.3 the EWIKI_ constants
45 3.4 $ewiki_config array
46 3.5 internal coding explained
47 3.5.1 how ewiki operates
48 3.5.2 used variables
49
50 4 Tweaking
51 4.1 Using the wiki source transformation only
52 4.2 Customizing ewiki_format()
53 4.3 Customization using CSS
54 4.3.1 user style classes in pages
55 4.3.2 rendered page content
56 4.3.3 pages enclosed in style classes
57 4.3.4 plugin output styling
58
59 5 Explanations
60 5.1 Binary and text support
61 5.1.1 Image uploading
62 5.1.2 Image caching
63 5.1.3 Image WikiMarkup
64 5.1.4 binary_store, direct access
65 5.1.5 Arbitrary binary content
66 5.2 $action and $id
67 5.2.1 ewiki URLs
68
69 6 Everything in one script
70 6.1 database plugins
71 6.1.1 MySQL support
72 6.1.2 plugins/db/flat_files (IMPORTANT)
73 6.1.3 plugins/db/fast_files
74 6.1.4 plugins/db/any
75 6.1.5 plugins/db/adodb
76 6.1.6 plugins/db/dba
77 6.1.7 plugins/db/phpwiki13
78 6.1.8 plugins/db/binary_store
79 6.2 core enhancements
80 6.2.1 plugins/patchsaving
81 6.2.2 plugins/notify
82 6.2.3 plugins/jump
83 6.2.4 plugins/email_protect
84 6.2.5 plugins/spages (StaticPages)
85 6.2.6 plugins/pluginloader
86 6.2.7 plugins/init
87 6.2.8 plugins/feature/appendonly.php
88 6.2.9 plugins/feature/imgresize_gd.php
89 6.2.A plugins/feature/imgresize_magick.php
90 6.2.B plugins/feature/spellcheck.php
91 6.3 action/ plugins
92 6.3.1 plugins/action/diff.php
93 6.3.2 plugins/action/translation.php
94 6.3.3 plugins/action/like_pages.php
95 6.3.4 plugins/action/raw.php
96 6.4 plugins related to hypertext links
97 6.4.1 plugins/linking/tcn
98 6.4.2 plugins/linking/plural
99 6.4.3 plugins/linking/autolinking
100 6.4.4 plugins/linking/link_css
101 6.4.5 plugins/linking/link_icons
102 6.4.6 plugins/linking/link_target_blank
103 6.4.7 plugins/linking/linkexcerpts
104 6.4.8 plugins/linking/linkdatabase
105 6.4.9 plugins/linking/instanturls
106 6.4.A plugins/linking/titlefix
107 6.4.B plugins/interwiki/intermap
108 6.5 appearance/ tweaks
109 6.5.1 plugins/appearance/listpages_br
110 6.5.2 plugins/appearance/listpages_ul
111 6.5.3 plugins/appearance/listpages_tbl
112 6.5.4 plugins/appearance/fancy_list_dict
113 6.5.5 plugins/appearance/title_calendar.php
114 6.6 page/ plugins
115 6.6.1 plugins/page/powersearch
116 6.6.2 plugins/page/pageindex
117 6.6.3 plugins/page/wordindex
118 6.6.4 plugins/page/imagegallery
119 6.6.5 plugins/page/aboutplugins
120 6.6.6 plugins/page/orphanedpages
121 6.6.7 plugins/page/wantedpages
122 6.6.8 plugins/page/since_updates
123 6.6.9 plugins/page/textupload
124 6.6.A plugins/page/wikidump
125 6.6.B plugins/page/interwikimap
126 6.6.C plugins/page/hitcounter
127 6.6.D plugins/page/scandisk
128 6.6.E plugins/page/wikinews
129 6.6.F plugins/page/wikiuserlogin
130 6.6.G plugins/page/randompage
131 6.6.H plugins/page/fortune
132 6.6.J plugins/page/ewikilog
133 6.6.J plugins/page/phpinfo
134 6.6.K plugins/page/README
135 6.7 markup/ plugins
136 6.7.1 Other WikiWares markup
137 6.7.2 plugins/markup/css
138 6.7.3 plugins/markup/css_singleat
139 6.7.4 plugins/markup/footnotes
140 6.7.5 plugins/markup/asciitbl
141 6.7.6 plugins/markup/complextbl
142 6.7.7 plugins/markup/htmltbl
143 6.7.8 plugins/markup/rescuehtml
144 6.7.9 plugins/markup/rendering_phpwiki12
145 6.7.A plugins/markup/rendering_null
146 6.8 mpi
147 6.8.1 mpi_backlinks
148 6.8.2 mpi_multimedia
149 6.8.3 mpi_syndicate
150 6.8.4 mpi_insert
151 6.8.5 mpi_localsitemap
152 6.9 visual extensions
153 6.9.1 plugins/aview/backlinks
154 6.9.2 plugins/aview/linktree
155 6.9.3 plugins/aview/toc
156 6.9.4 plugins/aview/posts
157 6.9.5 plugins/aview/threads
158 6.9.6 plugins/aview/subpages
159 6.9.7 plugins/aview/downloads
160 6.9.8 plugins/aview/imgappend
161 6.9.9 plugins/aview/piclogocntrl
162 6.9.A plugins/aview/aedit_pageimage
163 6.9.B plugins/aview/control2
164 6.9.C plugins/aview/aedit_authorname
165 6.9.D plugins/aview/aedit_deletebutton.js
166 6.A page filters
167 6.A.1 plugins/filter/f_fixhtml
168 6.A.2 plugins/filter/search_highlight
169 6.A.3 plugins/filter/fun_chef
170 6.A.4 plugins/filter/fun_upsidedown
171 6.A.5 plugins/filter/fun_wella
172 6.A.6 plugins/filter/fun_screamomatic
173 6.A.7 plugins/filter/f_msiepng
174 B.9 BloatWiki extensions
175 6.B.1 plugins/module/calendar
176 6.B.2 plugins/module/downloads
177 6.B.3 plugins/module/tour
178 6.C utility code
179 6.C.1 plugins/lib/cache
180 6.C.2 plugins/lib/speed
181 6.C.3 plugins/lib/mime_magic
182 6.C.4 plugins/lib/navbar
183 6.C.5 plugins/lib/protmode
184 6.C.6 plugins/lib/save_storevars
185 6.D admin/ plugins
186 6.D.1 control
187 6.D.2 SearchAndReplace
188 6.D.3 SearchCache
189 6.E other plugins
190 6.E.1 plugins/debug/
191 6.E.2 plugins/auth/
192 6.E.3 plugins/auth-liveuser/
193 6.F separate "extra" tarball
194
195 7 More separate files
196 7.1 Pages in init-pages/
197 7.2 Additional tools/ (IMPORTANT)
198 7.2.1 tools/t_flags
199 7.2.2 tools/t_backup
200 7.2.3 tools/t_restore
201 7.2.4 tools/t_remove
202 7.2.5 tools/t_holes
203 7.2.6 tools/t_textinsert
204 7.2.7 tools/t_transfer
205 7.2.8 tools/t_revert
206 7.2.9 tools/ewikictl
207 7.2.A tools/wiki2html
208 7.2.B tools/mkhuge
209 7.2.C tools/mkpluginmap
210 7.2.D tools/mkpageplugin
211 7.3 examples/
212 7.3.1 examples/homepage.php
213 7.4 Nice things in fragments/
214 7.4.1 strip_wonderful_slashes.php (IMPORTANT)
215 7.4.2 strike_register_globals.php
216 7.4.3 404finder.php
217 7.4.4 htaccess
218 7.4.5 binary.php
219 7.5 fragments/funcs/*
220 7.5.1 fragments/funcs/wiki_format.inc
221 7.5.2 fragments/funcs/auth.php
222 7.6 fragments/css/*
223 7.7 fragments/blocks/*
224 7.8 fragments/patches/*
225 7.9 How to deal with tweaked code
226
227 8 Extension HowTo
228 8.1 the PlugInterface
229 8.2 plugin tasks
230 8.2.1 mpi plugins
231 8.2.2 authentication/permission plugins
232 8.3 writing your own plugin
233 8.4 format_* / rendering plugins
234 8.4.1 ewiki_format() internals
235 8.4.2 the format_ plugin hooks
236 8.4.3 $iii[] and $ooo[] block flags
237
238
239
240
241
242
243
244 -------------------------------------------------------------------- 1 --
245
246
247
248What is this?
14a960ac 249�������������
39fcb981 250This is a WikiWikiWeb engine implemented in the PHP web scripting
251language. A WikiWiki is a web site which can be edited by everybody
252who visits it (most commonly without requiring that user to register
253before).
254
255It should allow easy integration into an existing web site (portal
256or homepage / CMS-like software), as it is more a library and does
257not output a full .html page but instead just the formatted wiki
258text for inclusion in your pages` body/content area.
259
260
261
262Why "ErfurtWiki"?
14a960ac 263�����������������
39fcb981 264My home town (Btw, Erfurt is next to Weimar.de) and really that's
265just a name (you're allowed to rename, extend it and to finally
266ship it GPLifyed). You'll soon see the internal name is "ewiki",
267and it is also sometimes called 'EmbeddableWiki'.
268
269
270If you asked - Why you should I use it?
271
14a960ac 272 - It is contained within a single file. It does not require 20 other
39fcb981 273 files to lie around between your own scripts.
274
275 - It does not impose a pre-defined layout, and you do not need
276 to customize it either as it nicely integrates with your sites`
277 layout.
278
279 - I think it's rather fast. It uses regexs too, but most of the
280 ewiki_format() uses the simple and quick string functions.
281
282 - It got rather featureful, the final release seems near :)
283
284
285
286WikiAlternatives
14a960ac 287����������������
39fcb981 288If you don't like ewiki, then try at least one of these:
289
290* PhpWiki has a more complete approach than this WikiWare,
291 get it from http://freshmeat.net/projects/phpwiki,
292 it has support for different database types, features localization
293 and comes with an integrated admin area.
294
295* WakkaWiki by Hendrik Mans is also a very powerful PHP implementation,
296 see http://www.wakkawiki.com/
297
298* Miki is another nice (small) implementation in PHP from Jukka
299 Zitting. Get it from http://miki.sourceforge.net/
300
301* Finally sfWiki - the sourceforge Wiki (therefore can be found on
302 http://sfwiki.sourceforge.net/). Some of its wiki syntax looks
303 a bit weird (other parts were inspiring), but it features complex
304 user authentication.
305
306* coWiki - completely OOP and the source code layout is great; looks
307 very featureful, but is more a CMS than a Wiki (authentication bloat)
308 and has also a little weird markup,
14a960ac 309 but better check it out yourself on http://cowiki.org/
39fcb981 310
311* And of course there are Wikis in other scripting languages (and yes,
312 there is still demand for an implementation in assembler or C !!)
313 http://www.freshmeat.net/search/?q=wiki&section=projects or just
314 have a look at http://www.google.com/search?q=wiki
315
316* However, the BEST PLACE to look for evil concurrent implementations is
317 http://c2.com/cgi/wiki?WikiEngines
318
319
320
321Authors
14a960ac
PS
322�������
323current maintainer: Mario Salzer <mario*erphesfurt�de> icq95596825 (+Yah,Jab)
324main contributor: Andy Fundinger <andy*burgiss�com> from http://burgiss.com/
39fcb981 325
326For the complete list of authors and contributors please see the CREDITS
327file.
328
329This project is still in an early stage, to improve it further we need
330to know what doesn't work or what could be enhanced. Every mail is a
331contribution (yep, that is not measured in lines of source code).
332
333
334
335Project Pages
14a960ac
PS
336�������������
337official freshmeat project page:
39fcb981 338- http://freshmeat.net/projects/ewiki
339
340demo site:
341- http://erfurtwiki.sourceforge.net/
342
343newest versions (unstable development releases):
344- http://erfurtwiki.sourceforge.net/downloads/
345
346mailing list archive
347- http://www.freelists.org/archives/ewiki/
348
349
350
351Obtaining Support
14a960ac 352�����������������
39fcb981 353Getting support for problems with ewiki is possible, but please read this
354README first. The author is thankful for BugReports, and of course would
355like to know were this documentation is not detailed enough and fails to
356explain things clearly.
357However, before you send requests to anyone, please visit following site
358(this is necessary to get FREE support):
359
360http://www.catb.org/~esr/faqs/smart-questions.html
361
362Then please feel free to contact the author or leave notes on the BugReports
363or UserSuggestion pages on our project site.
364Joining our http://erfurtwiki.sourceforge.net/?MailingList would allow you
365to reach a larger audience for your questions (and you can unsubscribe as
366soon as your problems are solved).
367
368
369
370License
14a960ac 371�������
39fcb981 372This "program" is "distributed" as "Public Domain". Public Domain
373is like "FreeWare", but a bit more free ;-> You can think of it
374as the GPL without being bound to the GPL. <note> I didn't want to
375include a LICENSE file larger than the program itself. </note>
376
377As this is a free (beer) piece of software, you cannot make me
378responsible for any BUGS or all the REALLY BAD HARD DISK DAMAGES ;-P
379it may lead to.
380
381Additional note: a few plugins contain GPL code, and therefore must be
382downloaded separately (mime_magic.php, rendering_phpwiki12.php).
383
384
385
386Known Bugs
14a960ac 387����������
39fcb981 388Currently none. But this note is just here to encourage you to visit
389http://erfurtwiki.sourceforge.net/?BugReports
390
391
392
393
394
395 -------------------------------------------------------------------- 2 --
396
397
398
399
400HowTo
14a960ac 401�����
39fcb981 402the ewiki script requires:
403
404- Webserver (Apache, Nanoweb, ...)
405- PHP 4.1 or later
406- a SQL database (works faster if you have one)
407- your existing web site layout
408- older PHP's wonderful magic slashes should really be disabled
409
410If you don't have the database, there is an add-on for flat-file
411usage (search this document for "db_flat_files" for notes on how to
412get this running).
413
414
415
416Integration with yoursite.php
14a960ac 417�����������������������������
39fcb981 418For the next few paragraphs the "yoursite.php" refers to whatever
419files and/or scripts belong to your already existing website. This
420hypothetical script should at least output the <html><body> tags
421around the output from ewiki. The most simple script to accomplish
422this could look like this (see also example-2.php):
14a960ac 423
39fcb981 424 <HTML>
425 <BODY>
426 <?php
427
428 mysql_connect("localhost", "DB-USER-NAME", "PASSWORD"); #[1]
429 mysql_query("use DATABASE-NAME-HERE");
430
431 define("EWIKI_SCRIPT", "yoursite.php?page="); #[2]
432 error_reporting(0); #[3]
433
434 include("ewiki.php"); #[4]
435
436 echo ewiki_page(); #[5]
437
438 ?>
439 </BODY>
440 </HTML>
14a960ac 441
39fcb981 442[1] The first two commands open a connection to your MySQL database,
443usually one saves the result of mysql_connect() in a variable named
444$db or so, but as PHP does not depend on it if there is only one
445single database connection, it is not used in "ewiki.php" at all.
446
447[2] The define line tells ewiki about the hyperlinks it shall
448create.
449
450[3] The error_reporting(0) is highly encouraged (but something similar
451is already built into the ewiki.php script).
452
453[4] The include("ewiki.php") finally loads the ewiki "library" and sets
454any EWIKI_ constants that have not already been defined here.
455
456[5] The final call to the ewiki_page() function returns the wiki page
457which was requested by the browser. You must prepend it with
458"echo" because the ewiki_page() function just returns a <html> enhanced
459string but does not output that one itself.
460
461
462
463 Creating a "config.php"
14a960ac 464 �����������������������
39fcb981 465 Instead of including the plain "ewiki.php" script as shown in the
466 example above, many people may find it more useful to include()
467 a more customized Wiki yoursite.
468
469 Customization of ewiki takes place, by pre-defining() some of the
470 EWIKI_ configuration settings and loading extension plugins. To
471 not move that work and code into yoursite it is recommended to
472 create some sort of "config.php" script, which then contained the
473 various define() and include() commands.
474 It is sometimes even senseful to establish the database connection
475 (if you use SQL and not the flat_files backend) inside of such a
476 config script, if there wasn't already established in yoursite.
477
478 So such a config.php script could contain:
479 - multiple define() commands, setting ewiki behaviour constants
480 - include() comands to load extension plugins
481 - evtl. some include() and define() for the db_flat_files plugin
482 (if you don't have a SQL database)
483 - and last but not least, the include("ewiki.php") script
484
485 If you then include() such a config.php, you get a fully functional
486 and preconfigured Wiki to include into yoursite. By using this
487 approach, you still could override some of the EWIKI_ settings with
488 additional define() constants right before the include("config.php").
489
490 <?php
491 include("includes/ewiki/myconfig.php");
492 ?>
493 <HTML>
494 <BODY>
495 <?php
496 echo ewiki_page();
497 ?>
498 </BODY>
499 </HTML>
500
501 Note: Please don't get confused by the path names, you of course
502 needed to use a subdirectory specification like "ewiki/" before
503 every filename specified in these include() commands, if this was
504 the dir you put all the ewiki scripts.
505
506
507
508 Generation of a "monsterwiki.php" script
14a960ac 509 ����������������������������������������
39fcb981 510 ewiki over the time grow larger, and nowadays isn't anymore the
511 single script it once was. The distribution ships with over hundreds
512 of extension plugins. But nevertheless it is still possible to build
513 a single script from it all!
514
515 That being said, the "ewiki.php" script still implements a fully
516 functional Wiki (and just only lacks the advanced features supplied
517 the plugins). - You could still just include() the "ewiki.php"
518 script into yoursite and delete everything else the ewiki tarball
519 contained.
14a960ac 520
39fcb981 521 However, it is also possible to MERGE all wanted plugins and the
522 core script together to built a customized (feature enhanced) Wiki
523 script from it. All you needed to do was:
524
525 /unix/$ cat ewiki.php plugins/*.* > monsterwiki.php
526 C:/dos/ type ewiki.php plugins/*.* > monsterwiki.php
527
528 This way you'd get the "monsterwiki.php" file, which contained the
529 ewiki core script plug all plugins - but of course, you should only
530 copy the ones in, you really need and want (but not "*.*" all as
531 shown in the example above)!
532
533 The UNIX shell script "tools/mkhuge" will do exactly that for you;
534 it accepts a parameter from 0 to 3, which will merge a custom set
535 of useful plugins into the then generated "monsterwiki.php" script.
536
537 If you have built a "monsterwiki.php" script, you can include() this
538 instead of the minimal "ewiki.php" into yoursite to integrate a Wiki.
539
540 Eventually you'd also want to merge some configuration settings into
541 this monsterwiki script, so you wouldn't have to put the define(...)
542 commands into yoursite.php before you include("monsterwiki.php");
543 The define() commands however need to be the very first part merged
544 into that monsterwiki script, so it's best to edit the monsterscript
545 after generation and insert the appropriate settings then at the
546 very beginning.
547 You could also merge a (reduced!) "config.php" into the script,
548 using the above "cat" (or "type" for DOS/Win) method. But beware,
549 that this "config.php" then does not contain any include() command;
550 because else the resulting "monsterwiki.php" script would then try
551 to load the "ewiki.php" core script and plugins which were probably
552 already merged in. Even if you merge such a minimal config script
553 at the start of this monsterwiki script, you still could override
554 some settings (at least establishing the database connection) from
555 within yoursite, if you think it's useful.
556
557 Additional note: You could still include() plugins, if you included()
558 such a monsterwiki script into yoursite, provided that the plugin
559 you try to include() wasn't already merged into that monsterwiki.php
560 script before (else it would crash the PHP interpreter, because
561 loading it twice is once too much).
562
563 StaticPages (read about "spages" plugin) can also be included, if
14a960ac 564 you first convert them into ordinary ["page"] plugins using the
39fcb981 565 'mkpageplugin' commandline tool.
566
567
568
569 What to do if images don't work
14a960ac 570 �������������������������������
39fcb981 571 The first example, as well as the "example-2.php" have problems with
572 binary content, because: the <HTML> is output before the 'ewiki.php'
573 library was loaded and got the chance to output pictures.
574
575 So one should better rewrite the above example yoursite.php script to:
576
577 <?php
578 mysql_connect(":/var/run/mysqld/mysqld.sock", "USER", "PW");
579 mysql_query("use DBNAME");
580
581 define("EWIKI_SCRIPT", "yoursite.php?page=);
582 error_reporting(0);
583
584 include("ewiki.php");
585
586 $content = ewiki_page();
587 ?>
588 <HTML>
589 <HEAD>
590 <TITLE><?php echo $ewiki_title; ?>
591 </HEAD>
592 <BODY>
593 <?php
594 echo $content;
595 ?>
596 </BODY>
597 </HTML>
598
599 Please again, note the initial <?php part before the very first plain
600 HTML output - yoursite.php must really start with it, or else binary
601 content (uploaded images) won't work!
602
603 You could, of course write a "binary.php" besides "yoursite.php", to
604 get around this problem; please see fragments/ for an example.
605
606
607
608Supplying the WikiPageName
14a960ac 609��������������������������
39fcb981 610If you just call ewiki_page() as shown in the first example, it will
611try to get the name of the requested WikiPage either from the
612$_SERVER["PATH_INFO"] variable or from one of the GET-variables '?id='
14a960ac 613or '?name=' or '?page=' or '?file=' (available as $_REQUEST["name"]).
39fcb981 614If yoursite.php however uses another way or another varname to receive
615the WikiPageName you can just give it as first parameter:
616
617 ewiki_page( $id = "WikiPageName" );
618
619example-4.php shows how this can be used to list a second WikiPage
620(the list of newest pages) somewhere else on yoursite.php.
621
622
623
624 mod_rewrite or PATH_INFO
14a960ac 625 ������������������������
39fcb981 626 If you dedicate a complete directory for your wiki, you should keep
627 in mind, that some of the generated URLs contain slashes (for
628 example "edit/WikiPage"), and will look like subdirectories and thus
629 confuse browsers.
630
631 So you should either set EWIKI_SCRIPT to the absolute directory
632 containing your wiki wrapper script: define(EWIKI_SCRIPT,
633 "http://myserver/wiki/"); or else put a <BASE HREF="..."> into the
634 generated pages. Take this precaution because some of the generated
635 links contain additional slashes (like "edit/ThisPage") and thus may
636 make browsers believe in a changed subdirectory.
637
638 This applies to mod_rewrite usage and if you call your wiki wrapper
639 with the page name as PATH_INFO (like "/wiki/index.php/WikiPage").
640
641 Do not forget to enable EWIKI_USE_PATH_INFO, as it is per default
642 disabled for Apache servers! Also check, if EWIKI_URLENCODE and
643 _URLDECODE suit your needs, else you will find it useful to have URL
644 generation encapsulated in the ewiki_script() function.
645
646
647
648 use with the 404 trick
14a960ac 649 ����������������������
39fcb981 650 Once I implemented a way to run a web server below another one
651 (actually Nanoweb below Apache, for more details see
652 http://nanoweb.si.kz/), because the Apache on one of my providers
653 servers was heavily misconfigured - so I handed work over to a
654 secondary WebServer.
655
656 This trick also works without mod_rewrite support, and is therefore
657 also well suited for cheap WebSpace. Put following into the
658 .htaccess of the dedicated wiki directory:
659
660 #-- handle "not found" pages by ewiki
661 ErrorDocument 404 /wiki/index.php
662 DirectoryIndex 404 index.php
663
664 This will allow the "yoursite.php/ewiki.php" script to catch all
665 missed files, which would usually trigger a 404 error. Inside your
666 ewiki wrapper script, you must then however decode the originally
667 requested URL:
668
669 $url = $_SERVER["REQUEST_URL"]; # Apache often uses this one
670 $url = preg_replace("#^/wiki#", "", $url); # strip wiki subdir name
671 $_SERVER["PATH_INFO"] = $url; # make ewiki see it
672
673 The second step is very important, it strips the name of the
674 dedicated subdirectory from the URL, which cannot be done inside
675 ewiki.php.
676
677 The $url from the above example could also be used as $id
14a960ac 678 parameter to ewiki_page().
39fcb981 679
680 It should be noted, that some Apache implementations are garbaging
681 POST requests in case of a triggered 404 error - but you can simply
682 test this by saving a changed WikiPage.
683
684 See also the "fragments/404finder.php" example on this.
685
686 Do not forget to enable EWIKI_USE_PATH_INFO, as it is per default
687 disabled for Apache servers!
688
689
690
691
692
693
694Security considerations
14a960ac 695�����������������������
39fcb981 696ewiki was developed using a PHP5 interpreter, but with limitations of PHP4.3
697in mind. There are huge differences (a rather instable, bug-prone and still
698unfinished language) across the 4.x versions of PHP. The 4.0 series is not
699enough to run ewiki, you'll need at least a PHP 4.1 (4.07) to make it work
700reliable.
701
702One must also know, that there are also differences between the settings of
703providers. Some for example enforce users to run their scripts in so called
704"safe mode" (crippled mode) in place of real server security guidelines.
705Other still use pre-4.3 settings for the PHP interpreter (the Win4 php.ini
706still is outdated). So take care, and adjust settings using .htaccess`
707php_option for Apache servers.
14a960ac 708
39fcb981 709
710
711 PHP settings (register_globals)
14a960ac 712 �������������������������������
39fcb981 713 Because ewiki was developed on later PHP versions (at least 4.3), it
714 heavily uses the $_REQUEST array and assumes a deactivated
715 "register_globals" setting in php.ini
716 If this is not the case for your setup / WebServer. or with your
717 provider the ewiki.php script may expose a lot security leaks
718 (because of uninitialized variables).
719
720 ewiki in general does only use a few global variables, but especially
721 the $ewiki_ring variable (which is used for PROTECTED_MODE) can lead
722 to problems, if you use it without an existing authentication
723 concept. The $ewiki_plugins is also a very complex task, and I
724 cannot safely state that it won't be able to produce exploits, if
725 the variable is tweaked externally (pushed into by a client).
726
727 So the best thing you could do is to disable register_globals (this
728 can be done from inside a directories .htaccess file by inserting
729 the line "php_option register_globals off").
730
731 A fragments/ include will be added to strike against variables which
732 got set from outside (this is rather easy for variables used by
733 ewiki, because their names all start with "$ewiki_").
734
735
736
737 The two modes of operation (_protected_mode and _flat_real_mode)
14a960ac 738 ��������������������������
39fcb981 739 While this wiki was originally developed as a real wiki, many people
740 use it for different things now, like private HomePages, easy CMS on
741 commercial web sites.
742
743 This fact lead to the support of a restricted operation mode, now
744 known as the _PROTECTED_MODE. It is often used to require people to
745 log in before they can edit pages or upload things. In this README
746 this mode of operation will often be referred to also as the
747 'crippled mode'. It is completely optional, and doesn't have any
748 impact on speed, when left disabled.
749
750 Btw, the standard ewiki operation mode is
751 now known as the _FLAT_REAL_MODE.
752
753 If you'd like to use authentication, you'll probably want to chain
754 some plugins which enable you to use the user database from
755 yoursite.php, so you do not need a separate .htaccess or an
756 additional relational database for passwords. Please see the section
757 on auth plugins.
758
759 See also the EWIKI_PROTECTED_MODE configuration constant and the
760 separate "plugins/auth/README.auth" file for further and more
761 detailed informations on this feature.
762
763
764
765simple usage restrictions via wrappers
14a960ac 766��������������������������������������
39fcb981 767The easiest way to cripple a Wiki setup to be browseable-only for the larger
768public, and to allow only a small subset of users to edit pages is to write
769two wrapper scripts around the ewiki.php library.
770
771One of the wrapper scripts should include and use ewiki as described in the
772"Integration with yoursite.php" paragraph. You may want to move this wrapper
773script into a password protected subdirectory (say "/wikiadmin/index.php").
774
775Another wrapper script should then be provided for the users that are only
776allowed to view pages. To disallow editing you'll just have to enrich it
777with commands like:
778
779 unset($ewiki_plugins["action"]["edit"]); # disables editing
780 unset($ewiki_plugins["action"]["info"]); # no info/ action
781 unset($ewiki_plugins["page"]["SearchPages"]); # no search function
782 unset($ewiki_plugins["action"]["view"]); # kill wiki completely
783
784This code must occur after you have 'included("ewiki.php");' the library,
785but before you call the 'ewiki_page();' function, so the unwanted actions
786and pages really do not get activated.
787
788So far the basic approach. If you however have real user authentication
789code behind the scenes you probably don't want to maintain two different
790wrapper scripts. You'll then just put the functionality stripping code
791from above into an if-clause in "yoursite.php" like:
792
793 if (! $user_is_logged_in) {
794 unset($ewiki_plugins["action"]); # (do it less destructive ;)
795 }
796
797Note: this is again an example, DO NOT copy&paste examples and assume
798they'll work for you!
799
800
801
802PhpWiki compatibility
14a960ac 803���������������������
39fcb981 804The MySQL database table is partially compatible to PhpWiki versions 1.2.x,
805but not with the current PhpWiki 1.3.x versions. There is however now the
806db_phpwiki13 plugin which allows to access those (rw).
807
808
809
810 Transition from another WikiWare
14a960ac 811 ��������������������������������
39fcb981 812 If you choosed ewiki to replace an already existing wiki script on
813 your site, you should first think about, that the syntax/WikiMarkup
814 isn't equal across all Wikis. There are a few markup extension
815 plugins, that may help you around this, but beware that transition
816 with a larger collection of WikiPages won't be very easy.
817
818 The best way to import the old WikiPages to ewiki, is to first
819 export it using the tools of the previous WikiWare. You can then
820 just put the produced text/plain PageSource into "init-pages/",
821 because all files found therein (note, that there shouldn't be any
822 file name extension like .txt) are feed directly into the ewiki
823 database, when ewiki is run for the very first time (when the
824 EWIKI_PAGE_INDEX is not found in the db).
825
826 There is a "plugins/db_phpwiki13.php" which may be useful in first
14a960ac 827 trying ewiki, but it is not recommended to use it for daily work.
39fcb981 828 Speaking of PhpWiki you could also use the "tools/t_convertdb.php"
829 to import (and markup convert) all pages from PhpWiki to the ewiki
830 database format.
831
832
833
834
835
836
837 -------------------------------------------------------------------- 3 --
838
839
840
841
842Internals
14a960ac 843���������
39fcb981 844The MySQL database table structure is to a certain degree compatible
14a960ac 845with that of the well known �PHPWiki� v1.2.x (you only need to change
39fcb981 846EWIKI_DB_TABLE_NAME to "wiki" to use it). This is the MySQL statement
847which creates our database table (you can find it at the bottom of the
848"ewiki.php" script):
849 CREATE TABLE ewiki (
850 pagename VARCHAR(160) NOT NULL,
851 version INTEGER UNSIGNED NOT NULL DEFAULT 0,
852 flags INTEGER UNSIGNED DEFAULT 0,
853 content MEDIUMTEXT,
854 author VARCHAR(100) DEFAULT 'ewiki',
855 created INTEGER UNSIGNED DEFAULT 0,
856 lastmodified INTEGER UNSIGNED DEFAULT 0,
857 refs MEDIUMTEXT,
858 meta MEDIUMTEXT,
859 hits INTEGER UNSIGNED DEFAULT 0,
860 PRIMARY KEY id (pagename, version)
861 )
862
863I didn't like the column name {pagename} but as I've seen this was
864the only difference I renamed it, therefore now the ewiki_database()
865function translates it from "pagename" to "id" and vice versa most of
866the time - else this would be really slim and nice code :)
867
868The columns {version} holds the different saved page versions. Other
869Wikis require a secondary "backup" or "history" table for old versions,
870but as I couldn't imagine what this is for, there is just one table
871in ewiki; and it seems this is really enough. The first {version} of
872a wiki page is always numbered 1. An existing page {version} will
873never get overwritten => very secure MySQL usage.
874
875For what's in the {flags}, see the README section about constants. The
876{content} of course holds the wiki pages source. The {created} and
877{lastmodified} should be clear too.
878
879{refs} contains a "\n" separated list of referenced WikiPages. The
880code to generate that list is rather unclean, so it often contains
881GhostPages. However this does not hurt ewiki and the few functions
882that utilize {refs}, so there is currently no need to slow it down
883by fixing this.
884
885{meta} can hold additional informations, which allows to extend ewiki
886without requiring to ALTER and convert the ewiki database table. It
887currently holds some mime headers for binary content and some other
888useful informations for images and uploaded files.
889
890{hits} should have gone into {meta} really. But having it separate
891allows us to use the very fast mysql UPDATE function.
892
893Note, that the ewiki database table can hold other things than wiki
894pages - binary content (images) for example, depending on the setting
895of the {flags} field.
896
897And last comment about this, the one-table-concept also made it really easy
898to implement the flat file based "database backend".
899
900
901
902ewiki_ functions
14a960ac 903����������������
39fcb981 904Some of the core functions of ewiki.php can be used separate from the
905others and some of them were designed to be replaced by different
906implementations.
907Btw, all the functions, constants and variables start with "ewiki_"
908to make it easier to mix it into other projects (reduces function name
909conflicts and similar problems, that usually arise if you join two
910or more scripts into one program).
911
912
913 ewiki_page($id)
914 ---------------
915 This is the main function which fetches the selected WikiPage
916 (or the one given with $id) via ewiki_database to transform
917 with ewiki_format().
918 If the requested page does not exist it returns the edit
919 screen.
920 It also includes some virtual pages (InfoAboutThisPage,
921 NewestPages, SearchPage, ReferencesToThisPage, ...).
922
923
924 ewiki_page_...()
925 ----------------
926 These functions were separated out from the main ewiki_page()
927 to make it more readable.
928 Most of them contain code to generate the few special/internal
929 WikiPages (Search, Newest, Info, and the Edit <FORM>, ...)
930
931
932 ewiki_control_links($id, $data)
933 -------------------------------
934 Prints the line with the EditThisPage and PageInfo, ... links.
935
936
937 ewiki_format($wiki_source, $params)
938 ----------------------------------------------------------
939 This returns the formatted (HTML) output for the given WikiSource
940 (with all the WikiMarkup in it).
941
942 The second param is an array with various config overrides. An entry
943 of "scan_links"=>1 for example tells ewiki_format to lookup the
944 referenced WikiPages in the database (see ewiki_scan_wikiwords) for
945 filling up $ewiki_links. Another $params entry is "html"=>0, which
946 controls interpetation of the <html>...</html> page content blocks.
947
948
949 ewiki_render_wiki_links(&$o)
950 ----------------------------
951 Transforms WikiLinks and square brackets in a page into html links.
952
953
954 ewiki_scan_wikiwords(&$wiki_source, &$ewiki_links)
955 --------------------------------------------------
956 work with regex on the wiki source text, to find valid WikiWords,
957 the $ewiki_links will be filled with informations if the found page
958 names exist in the DB.
959
960
961 ewiki_link_regex_callback()
962 ---------------------------
963 Called from ewiki_format(). To separate the ewiki_format() from
964 the database this function will utilize the global $ewiki_links
965 (generated on demand by ewiki_format) to output either a normal
966 link or a question-mark after the WikiPageName to signal a
967 non-existent page.
968
969
970 ewiki_script()
971 --------------
972 Builds the complete URL needed to access the given resource. This
973 function replaces/enhances the static EWIKI_SCRIPT constant and
974 unifies the generated URLs (less bugs). It also helps around
975 various design flaws (like nice looking URL strings), that made
976 some parts of ewiki a bit weird and unreliable in the past. Btw,
977 now the base URL is stored in $ewiki_config["script"].
978
979
980 ewiki_script_binary()
981 ---------------------
982 Is just a ewiki_script() wrapper, but can additionally distinguish
983 between binary download and upload URLs, which could be utilized by
984 (database external) plain file storages (see plugins/binary_store).
14a960ac 985
39fcb981 986
987 ewiki_binary()
988 --------------
989 Gets called automatically for requests with the ?binary= trailer
990 which is used to reference cached and uploaded images (or not
14a960ac 991 yet cached ones).
39fcb981 992
993
994 ewiki_author()
995 --------------
996 returns a string with REMOTE_ADDR and the $ewiki_author or a default
997 string incorporated
998
999
1000 ewiki_auth()
1001 ------------
1002 Is a simple interface to a probably large collection of plugins,
1003 which should to actual user and permission management. Support for
1004 this in the core is however still sporadic.
1005
1006
1007 ewiki_auth_user()
1008 -----------------
1009 Queries all registered user databases, and is usually itself called
1010 from within an auth_method/auth_query plugin.
1011
1012
1013 ewiki_t()
1014 ---------
1015 Fetches a text string from the $ewiki_t[] array and additionally adds
1016 some text pieces into it (given as second param). It can retrieve
1017 translations for registered abbreviations, or searches for complete
1018 text fragment replacements. It also understands _{...} to recursively
1019 translate a text snippet inside of larger text blocks.
1020 This is probably a bit slower and less readable than the previous usage
1021 of EWIKI_T_ constants, but it saves some memory and allows to extend
1022 translations or additional text constants (of plugins) a lot more
1023 easier (previously one had to edit inside a function, which is almost
1024 impossible to do from outside / per configuration).
1025
1026
1027 ewiki_make_title()
1028 ------------------
1029 Returns a string enclosing (the generated) page title (as link) into
1030 the html title markup "<h2>". The $class parameter actually tells from
1031 which plugin sort it was called, and this decides if a link will be
1032 generated or the title will be unclickable plain text (the setting in
1033 $ewiki_config["print_title"] is used to determine that). $go_action tells
1034 which action to link the title to.
1035
1036
1037 ewiki_chunked_page(...)
1038 -----------------------
1039 Is a helper function to split large results into multiple click-through
1040 pages, and is used by info/ and some search functions/plugins. It only
1041 produces the click-through links for inclusion on other dynamic pages,
1042 allows overlapping of page chunk ranges.
1043
14a960ac 1044
39fcb981 1045 ewiki_in_array($value, &$array, $dn=0)
1046 --------------------------------------
1047 Case-insensitive variant of PHPs` in_array(), returns the $value if
1048 found. The $array will be all-lowercased afterwards (except when $dn
1049 was set).
1050
1051
1052 ewiki_array($array, $index=false, $am=1)
1053 ----------------------------------------
1054 Returns input-array lowercased (indices), or just the entry for the
1055 $index if searched for. The $am decides if multiple entries should be
1056 merged together (uppercase+lowercase merging produces overlaps).
1057
1058
1059 ewiki_database($FUNCTION, $args=array() )
1060 ------------------------------------------
1061 This function is the "database abstraction" in ewiki. It contains
1062 ''only'' eight SQL statements which must be replaced if you'd like
1063 to use another database server. It is very stupid, and does not know
1064 much about its database (keeping it extensible on the other hand),
1065 therefore one must be careful when passing database entries to it.
1066 The individual "atomic" functions are:
1067
1068 "GET", $args = array( "id"=>STRING, ["version"=>NUM] )
1069 Fetches the newest wiki page incarnation from the database,
1070 or alternatively the one given by version.
1071
1072 "WRITE", $args = array( COLUMN-NAME => VALUE, ... )
1073 Saves the contents of the given data array in the database,
1074 does _never_ overwrite an existing entry (you must keep track
1075 of the {version} yourself).
1076
1077 "GETALL", $args = array( "COLUMN-1", "COLUMN-2", ... )
1078 Fetches an array of all existing pages in the database, but
1079 returns it as ewiki_dbquery_result object, which will throw
1080 the requested columns on ->get(), where the entries 'id',
1081 'version' and 'flags' are always present.
1082
1083 "FIND", $args = array( "WikiPage1", "WikiPageName2", ... )
1084 Searches the database for the queried page names, returns an
1085 array which associates the boolean value (if pages found) with
1086 their names
1087
1088 "SEARCH", $args = array( "COLUMN" => "CONTENT" )
1089 Returns only those pages, where the database COLUMN has a content
1090 that matches the requested value; the list of pages is returned
1091 as ewiki_dbquery_result object, where you can access the
1092 individual entries using the ->get() call, which will return the
1093 columns 'id', 'version', 'flags' and the scanned COLUMN of course
1094 unless you ->get("_ALL=1").
1095
1096 The following three actions are not required for correct operation,
1097 but provide additional functionality for some plugins or tools.
1098
1099 "HIT", $args = array( "id"=>STRING )
1100 Increases the hit counter of the given wiki page by 1,
1101 what is not implemented in db_flat_file.
1102
1103 "OVERWRITE"
1104 Is a wrapper to "WRITE" and does replace existing entries.
1105
1106 "DELETE", $args = array( "id"=>STRING, "version"=>NUM )
1107 Removes the specified page (only the given version) from the
1108 database; implemented in all database plugins but should be used
1109 from within the tools/ only.
1110
1111 Other functions are usually used internally only, as for example the
1112 "ALLFILES" command in dbff or dba/dbm plugins.
1113
1114
1115 ewiki_dbquery_result
1116 --------------------
1117 Has the member variables $keys and $entries, where the latter
1118 contains an array of page names that where triggered by your GETALL
1119 or SEARCH request, and the $keys array contains the column names that
1120 each subsequent "$result->get()" will return.
1121
1122 get()
1123 Returns the database entry array (see GET above), but only the
1124 fields the database query should return (at minimum these are
1125 'id', 'version' and 'flags' and the searched column for SEARCH).
1126
1127 get("_ALL=1")
1128 Instead returns the complete entry.
1129
1130 count()
1131 Returns the number of found database entries.
1132
1133 add($row)
1134 [internal] This is used by the ewiki_database() core functions
1135 to initialize the $result object with the found entries.
1136
1137
1138
1139$GLOBALS pollution
14a960ac 1140������������������
39fcb981 1141At least the ewiki_page() function produces variables in the
1142global namespace. Of course they also were named to not interfere
1143with anything from yoursite.php:
1144
1145 $ewiki_id - Contains the current page name, after ewiki_page()
1146 was called.
1147
1148 $ewiki_action - Contains the $action/ForTheCurrentPage.
1149
1150 $ewiki_title - Will be set after the first call to ewiki_page(),
1151 it is most useful to be printed inside the <TITLE>
1152 tags inside <HEAD>. So if you want to use it you
1153 should call ewiki_page() very early, but save its
1154 output into a variable for later use. This way
1155 you can make the current wiki pages` title available
1156 (the _title may be different from the pages _id).
1157
1158 $ewiki_errmsg - Sometimes used to pass error notices back (ewiki_auth
1159 does so for example).
1160
1161 $ewiki_links - Is an array produced by ewiki_format() that associates
1162 all found WikiPageNames with a value of 0 or 1,
1163 depending on if the referred page exists in the
1164 database.
1165
1166 $ewiki_author - The content of this variable is saved in the author
1167 field of newly created wiki pages (it will be filled
1168 with IP:PORT if not set from outside). This is only an
1169 informational setting, and does not directly correspond
1170 to the _PROTECTED_MODE.
1171 You should set it, whenever yoursite.php notes a logged in
1172 user (so his login gets saved in the wiki pages 'author'
1173 column). But you should REALLY NOT SPAM IT with your own
1174 name or ad words.
1175
1176 $ewiki_auth_user - Is set by ewiki_auth_user() whenever it successfully
1177 authenticates a user in _PROTECTED_MODE. This variable
1178 is then used as reliable state setting, which affects
14a960ac 1179 permission granting.
39fcb981 1180
1181 $ewiki_ring - Holds the permission level ('ring') of the currently
1182 authenticated user (or else will be unset). This value
1183 tells only about the user, many plugin functions have
1184 built-in requirements which will be compared against
1185 this value (no value or zero means full permissions).
1186 While this is the built-in way to grant permissions
1187 and often also suits the needs to do it, the _auth()
1188 plugin interface allows to work at a much finer degree
1189 of access granting.
1190 values: 0=administrator, 1=moderator, 2=editor, 3=guest
1191 See also plugins/auth/README.auth for more informations.
1192
1193 $ewiki_plugins - Is an array which connects task names (say "database"
1194 or "image_resize" for example) to function names.
1195 You can utilize this if you decide to extend ewiki.
1196 There is an own chapter on this.
1197
1198 $ewiki_config - Imports some configuration settings from older constants,
1199 and introduces newer ones, which can then be overridden at
1200 runtime. Also holds some work and markup transform data.
1201
1202 $ewiki_t - Text definitions and translations for all possible
1203 messages.
1204
1205 Things that disappeared again, and which are now part of the $ewiki_config
1206 array instead include:
1207
1208 $ewiki_data - May reappear by setting a _config[] variable.
1209
1210 $ewiki_interwiki - Was errornously part of _plugins[] for some time.
1211
1212 $ewiki_script - Was a global var for a short period of time, but now is
1213 a subentry in $ewiki_config.
1214
14a960ac 1215
39fcb981 1216
1217
1218EWIKI_ constants
14a960ac 1219����������������
39fcb981 1220This chapter explains some of the constants and how you can utilize
1221them to tweak some of ewiki's behaviour.
1222
1223The recommended way to change settings is to copy the define() commands
1224from "ewiki.php" into "yoursite.php" (see our example "config.php"). This
1225is a good idea, because then your settings won't get lost if you upgrade
1226to a newer version by overwriting your tweaked "ewiki.php".
1227
1228 [Note: constants in PHP can be defined() once only, so
1229 pre-defining them in "yoursite.php" or a "config.php"
1230 script is nearly like a 'configuration']
1231
1232To define() some of those constants in 'yoursite.php' is especially a good
1233thing, because some of them are more used like state variables and it may
1234be more senseful to set them depending on informations only available in
1235the scripts of yoursite.php (for example if yourscripts provide a way to
1236authenticate and login a user you may give him additional rights within
1237ewiki by pre-defining one of the following constants).
1238
1239
1240 EWIKI_SCRIPT
1241 This is the most important setting. It is used by ewiki.php
1242 to generate links to other WikiPages.
1243
1244 It needs the name of yourscript.php which itself includes
1245 ewiki.php.
1246 The name of the linked WikiPage is just appended to the string
1247 defined here, so you must ensure that it either ends in "/"
1248 or "?id=" or "?name=" or "?page=" so it constructs a valid
1249 URL after concatenation (or %s replaced) with the WikiPageName.
1250
1251 If you utilize mod_rewrite on your server, you may wish to
1252 make it blank when all requests to http://wiki.example.com/
1253 are redirected to the correct script by your WebServer.
1254
1255 If your wrapper script for example is called 'index.php' then you
1256 can just set EWIKI_SCRIPT to "?page=" (which then refers to the
1257 index.php of the current directory).
1258 You should preferrably set it absolute to the servers DocumentRoot,
1259 which gets a requirement if you'd like to give page names and actions
1260 via PATH_INFO "/wiki.php/WikiPage" and not as QUERY_STRING "?id=".
1261
1262 Update: this constant will stay, but the core script now utilizes
1263 the ewiki_script() function (which itself additionally respects
1264 the $ewiki_config["script"] config variable in favour).
1265
1266 ewiki_script() introduces use of the "%s" placeholder inside
1267 EWIKI_SCRIPT, which will be replaced by pagename and action, when
1268 URLs are generated.
1269
1270 EWIKI_SCRIPT_URL
1271 Some parts of ewiki require the absolute URL of the ewiki wrapper
1272 script. So in contrast to the (often) short EWIKI_SCRIPT, this
1273 constant MUST contain the protocol and server name, like:
1274 "http://www.example.com/wiki/index.php?id="
1275
1276 If you do not set this constant, it will be guessed by the
1277 ewiki_script_url() funciton, what often works but may be suboptimal
1278 and could also lead to security problems.
14a960ac 1279
39fcb981 1280
1281 EWIKI_DB_TABLE_NAME
1282 Sets the name of the MySQL database table name to be created
1283 and used to store all WikiPages.
1284
1285 EWIKI_DBQUERY_BUFFER
1286 When set to a value>0 then SQL database buffering will be enabled
1287 for SEARCH and GETALL queries. This is mostly like the old (R1.00)
1288 behaviour (memory exhaustive), but instead is limited to the size
1289 defined by this configuration constant (for example 384K).
1290
1291 EWIKI_DBFILES_DIRECTORY
1292 Defines where db_flat_files puts the database (made up of files).
1293 There is a separate paragraph about this,
1294
1295 EWIKI_DBFILES_ENCODE
1296 If set to 1 will generate urlencoded() filenames even on UNIX
1297 systems, so the dbff database 'files' get exchangeable across
1298 DOS/Win and UNIX filesystems. Not recommended, and will make
1299 ewiki run bogus, if you switch it after there already entries
1300 in the database.
1301 It may however be useful to enable this per default, if you want to
1302 "backup" (this is the wrong way) from a Unix server to a Win box via
1303 an ordinary FTP program (more professional tools could however handle
1304 this more easily).
1305
1306 EWIKI_INIT_PAGES
1307 Names the directory from which the basic pages should be read and
1308 then written into the database, when ewiki is run the very first
1309 time (or the FrontPage - EWIKI_PAGE_INDEX) is still empty.
1310 Btw, you could use the 'ewikictl' utility to export all your Wiki
1311 pages into this directory as auto-reinit-backup.
1312
1313
1314 EWIKI_NAME
1315 Defines the name of your Wiki. (This is not used currently, but
1316 is required, as _PAGE_INDEX is often just set to "FrontPage".)
1317
1318 EWIKI_PAGE_INDEX
1319 This defines the name of the WikiPage which shall be displayed
1320 when no value is received within the URL. Often this is called
1321 the "FrontPage" of the Wiki.
1322
1323 The mysql error message "Table 'ewiki' already exists" will appear
1324 until you create (and fill) the page specified herein.
1325
1326 If you'd like to have a wiki without FrontPage, you can set this
1327 constant to 0 or "" - you must then however ensure, that the ewiki
1328 script is never activated without a page name!
1329
1330 EWIKI_PAGE_NEWEST
1331 This defined the name of the virtual (internally generated) page
1332 containing a list of the lately added WikiPages.
1333 EWIKI_PAGE_SEARCH
1334 Holds the WikiPageName for the search function.
1335
1336
1337 EWIKI_CONTROL_LINE
1338 Pre-define this with 0 before including("ewiki.php") if you
1339 don't want that "<HR><A HREF>EditThisPage</A> ..." to be shown
1340 at the bottom of each page.
1341
1342 You must then generate the EditThisPage link yourself somewhere
1343 else on yoursite.php
1344
1345 It is often easier to edit the ewiki_control_links() function
1346 to match the layout/design of yoursite.php.
1347
1348 EWIKI_AUTO_EDIT
1349 If set to 1 (default) will automatically bring up the edit box
1350 for non-existent pages. Else a page in between will appear ("please
1351 edit me!") like in PhpWiki.
1352
1353 EWIKI_LIST_LIMIT
1354 Number of pages to show up in search queries (and other generated
1355 pages).
1356
1357
1358 EWIKI_PRINT_TITLE
1359 If set to 0 will prevent the page title from being shown on many
1360 pages (generated and database content ones).
1361
1362 EWIKI_SPLIT_TITLE
1363 If changed to 1 will separate WikiPages titles into its different
1364 word parts (only on top of each page).
1365
1366
1367 EWIKI_ALLOW_HTML
1368 Usually you do not want that users are able to add <HTML> tags
1369 inside the WikiPages as this allows for corruption of your page
1370 layout or creation of harmful JavaScript areas.
1371
1372 This is however one of the few constants which could be set by
1373 yoursite.php for logged-in users. If it is set while a user
1374 saves a changed page, then the special EWIKI_DB_F_HTML will
1375 be set for the newly created version, so <HTML> won't be
1376 garbaged by ewiki_format() if another (not logged-in) user
1377 requests the WikiPage next time.
1378
1379 You must start a line with a "|" to actually make the HTML
1380 work within a WikiPage.
1381
1382 If a not logged-in user however re-saves the page this flag
1383 won't be set anymore, so you should be careful about that.
1384 {{edit ewiki.php and define(_DB_F_HTML with 8+16) to change}}
14a960ac 1385
39fcb981 1386 EWIKI_RESCUE_HTML
1387 Was replaced by "plugins/markup_rescuehtml.php", which now allows
1388 for certain 'safe' HTML tags within the wiki source to be used.
1389
1390 EWIKI_HTML_CHARS
1391 If set the rendering function will backconvert html entities which
1392 represent non-latin characters, like &#4234; or &#1324;
1393
1394
1395 EWIKI_HTTP_HEADERS
1396 Allows ewiki to throw HTTP headers, where appropriate. You should keep
1397 it enabled, as it allows for things like RedirectionAfterEdit (when
1398 a page gets saved), and many other useful things.
1399 headers() can often only be sent, if your wiki/yoursite.php is binary
1400 safe, or uses PHPs output buffering (less reliable).
1401
1402 EWIKI_HTTP_HEADERS
1403 Instructs browsers not to cache delivered pages at all. This is often
1404 a good thing, because otherwise unclever caches will prevent the most
1405 recent wikipage version to get seen by users.
1406
1407
1408 EWIKI_CASE_INSENSITIVE
1409 Was only recently implemented, but ewiki is fully configurable now in
1410 regards to WikiLink case. It is enabled per default, and thus allows
1411 referencing any "WikiPage" using strings like "WiKipAgE". This is
1412 believed to be more user-friendly than case-dependency.
1413 Reverting to "binary" page name matching is not fully complete now (our
1414 database scheme was designed for case-insensitivity from the very start
1415 and thus the DB code first needs tweaking before links in ewiki really
1416 get case-dependent.
1417
1418
1419 EWIKI_ESCAPE_AT
1420 Encodes the "@" sign into a html entities, which in the past helped
1421 a little bit against address rippers. But please check out the new
1422 plugins/email_protect.php, which is more effective against email
1423 harvesters.
1424
1425
1426 EWIKI_URLENCODE
1427 EWIKI_URLDECODE
1428 You shouldn't disable both unless you know, you don't need to encode
1429 WikiPageNames (else almost always necessary for sanity and security
1430 reasons).
1431
1432
1433 EWIKI_USE_PATH_INFO
1434 If you have a broken Webserver (like many Apache versions), you may
1435 wish to disable the use of PATH_INFO.
1436 If you ever happen to see "Edit page '/wiki/example-1.php'", you
1437 probably need to disable it.
1438
1439
1440 EWIKI_USE_ACTION_PARAM
1441 Allows the page action command to be given as '&action=...' within
1442 an URL (else only "action/WikiPage" allowed).
1443 If you set this constant to 2, ewiki will also create such URLs
1444 (instead of the usual "edit/PageName" prefix).
1445
1446 EWIKI_ACTION_SEP_CHAR
1447 Defines the character that separates the page name from the action
1448 name in generated URLs. Per default this is the slash, but you
1449 could use something else (like the ":" colon), which however may
1450 have a few drawbacks somewhere else.
1451
1452
1453 EWIKI_DB_F_TEXT
1454 This flag is set for every WikiPage inside the database. Usually
1455 the only flag set on creation of a new page.
1456 Starting from R1.00b previous flags will be copied after applying
1457 EWIKI_DB_F_COPYMASK.
1458
1459 EWIKI_DB_F_BINARY
1460 Used for cached/uploaded images. Prevents a page from getting
1461 shown.
14a960ac 1462
39fcb981 1463 EWIKI_DB_F_DISABLED
1464 If set will prevent the page from being shown. Not useful.
1465 You could more easily unset the TEXT flag to disable page view.
1466
1467 EWIKI_DB_F_HTML
1468 Special flag to allow the current version to include <HTML>
1469 tags regardless of the global EWIKI_ALLOW_HTML setting.
1470
1471 EWIKI_DB_F_READONLY
1472 Prevents a new version to be saved, and thus disallows
1473 editing of the WikiPage.
1474
1475 EWIKI_DB_F_WRITEABLE
1476 Is the reversal of READONLY but only useful if you crippled
1477 ewiki by setting EWIKI_EDIT_AUTHENTICATE, as this flag is only
1478 intended to reallow editing of a page if you disallowed it before
1479 with _EDIT_AUTH (which denies access to _all_ pages).
1480
1481 EWIKI_DB_F_APPENDONLY
1482 Gets implemented by the plugins/append*.php, and allows to lock
1483 a page, in that users can only append to edit (or edit parts of
1484 it). See the plugin description for more details.
1485
1486 EWIKI_DB_F_SYSTEM
1487 Is used to mark internally used data holders (usually serialized()
1488 variables).
1489
1490 EWIKI_DB_F_TYPE
1491 Used internally to separate TEXT, BINARY, DISABLED and SYSTEM entries.
1492
1493 EWIKI_DB_F_COPYMASK
1494 When a new page is created, the flags of the previous version
1495 are ANDed with this value to strip off some unsafe settings.
1496 It could be possible to add the _DB_F_HTML setting to here, but
1497 this would allow HTML to be used by all users if the READONLY
1498 isn't set.
1499 Always keep in mind, that flags could be reimported from previous
1500 versions as well (I'm usure if this could happen).
1501
1502
1503 EWIKI_PROTECTED_MODE
1504 Is an operation mode of ewiki, which activates ewiki_auth() function,
1505 that is utilized from many places to require a permission level (from
1506 authenticated users). Set this constant to 1 to enable this mode.
1507 You'll also need some plugins from plugins/auth/ to make this useful.
1508
1509 If this constant is set to 2, then you don't need a permission plugin,
1510 but can control access to the edit/ function, by setting $ewiki_ring
1511 to 2 (to allow) from within yoursite.php scripts. This setting is also
1512 sometimes referred to as the "ClassicProtectedMode".
1513
1514 EWIKI_FLAT_REAL_MODE
1515 Not a configuration directive, but the opposite to _PROTECTED_MODE ;)
1516
1517 EWIKI_AUTH_DEFAULT_RING
1518 Is the permission level which is to be set, if no user is logged in
1519 currently (defaults to 3 - which means "browsing only").
1520
1521 EWIKI_AUTO_LOGIN
1522 If this is enabled, then ewiki_page() automatically requests for
1523 (re-)presenting the login <form> on startup, if current authentication
1524 isn't sufficient to go any further. Leave this enabled, it helps around
1525 some problems.
1526
1527 EWIKI_EDIT_AUTHENTICATE
1528 EWIKI_ALLOW_OVERWRITE
1529 Outdated (were present in older ewiki versions). See
1530 'plugins/auth/auth_perm_old.php' to get them back.
1531
1532
1533 EWIKI_TMP
1534 Tells ewiki which directory to use for temporary files. The default
1535 value is "/tmp" or whatever the environment variable $TEMP or %TEMP
1536 tells (often "C:\\Windoze\\Temp" or "C:\\Trashcan" on DOS systems).
1537
1538
1539 EWIKI_LOGLEVEL
1540 Log messages are internally separated into four categories:
1541 0=evil errors, 1=warnings, 2=notices, 3=annoying debug stuff.
1542 If you do not want a log at all, just set this constant
1543 to -1 or 357. If you set it to 1 for example, you will see
1544 error and warning messages in EWIKI_LOGFILE.
1545
1546
1547 EWIKI_SCRIPT_BINARY
1548 This requires the REAL absolute address of the ewiki.php
1549 library script (but the database must already be opened).
1550 Needed for the function for cached/uploaded images.
1551 You can set it to almost the same value as EWIKI_SCRIPT if it
1552 is ensured that there is yet no output made, and the headers()
1553 are not already sent.
1554
1555 Usually just "?binary=" works fine (if you use the index.php
1556 way of including ewiki.php).
1557
1558 If you don't want ewiki to use image caching and uploading
1559 functions you would define this to "" or 0, because this disables
1560 the <img href> redirection through ewiki_binary(). You should then
1561 also disable the following two constants:
1562
1563 EWIKI_CACHE_IMAGES
1564 Allow caching of images.
1565 To disable all the image functions (uploading, caching) set this to 0,
1566 as well as EWIKI_SCRIPT_BINARY and:
1567
1568 EWIKI_IMAGE_MAXSIZE
1569 ewiki will scale down images until they get smaller than
1570 the absolute size (bytes) given here. This is true for cached
1571 and uploaded images.
1572 Your database may grow really fast, if you set it too high!
1573 (even if .BMP and .XWD files are discarded normally ;-)
1574
1575 EWIKI_IMAGE_MAXALLOC
1576 Maximum size of image while uploading and resizing it (memory
1577 limits).
1578
1579 EWIKI_IMAGE_RESIZE
1580 Enables the internal resizing functions.
1581
1582 EWIKI_IDF_INTERNAL
1583 Is used to identify uploaded images and data files. Usually you do
1584 not want to change it, especially if there are already uploaded
1585 files; however "chrome://" or "file://localhost/tmp/" could be
1586 funny alternatives to the default "internal://".
1587
1588 Note that the renderer relies only on some unique string to detect
1589 binary references, but the database functions in fact depend upon
1590 "://" to return image sizes on "FIND" calls.
14a960ac 1591
39fcb981 1592 EWIKI_ACCEPT_BINARY
1593 Allows users to upload arbitrary binary files through the image upload
1594 function. You should now rather use the downloads plugin, which adds
1595 a lot of functionality missing better suited for such purposes.
1596 This feature depends on the image upload and cache function.
1597
1598
1599 EWIKI_ADDPARAMDELIM
1600 Automatically defined, holds either "?" or "&" depending on what
1601 is in EWIKI_SCRIPT. You shouldn't change this unless you know what
1602 you are doing.
1603
1604
1605 EWIKI_T_*
1606 These were replaced by the $ewiki_t[] array and ewiki_t() function.
1607
1608
1609 EWIKI_CHARS_U
1610 EWIKI_CHARS_L
1611 Allowed chars in WikiPageNames (uppercase and lowercase chars). Use
1612 this to localize your wiki (standard Wikis only allow A-Z, think of
1613 that when it comes to InterWiki).
1614
1615
1616 EWIKI_UP_*
1617 URL parameters. Changing these may only be necessary, if one is already
1618 evaluated within yoursite.php for other purposes (incompatibilities).
1619 You could also change these just to make some of the generated URLs
1620 look a bit nicer ;)
1621
1622
1623 EWIKI_DEFAULT_LANG
1624 This value is used by a few plugins, that must guess the desired
1625 language of visitors, or the language of a pages content.
1626
1627 EWIKI_CHARSET
1628 ewiki currently only supports the Latin-1 charset, but UTF-8
1629 support is underway. So you should only specify "ISO-8859-1"
1630 or "UTF-8" herein (while most other "ISO-8859-*" are believed
1631 to work too).
1632
1633
1634 UNIX_MILLENNIUM
1635 Ey, don't tell me you're using Windoze ;)
1636
1637
1638 EWIKI_VERSION
1639 Is not used at all. It is just placed on top of every ewiki.php to tell
1640 you, which version you are running currently.
1641 Major releases have a version number like 'R1.00a', while testing and
1642 unstable releases have another number appended 'R1.00a7'.
14a960ac 1643
39fcb981 1644
1645See the tools/ subdir for a small utility to change the mentioned flags
1646in the ewiki database table.
1647
1648
1649
1650$ewiki_config array
14a960ac 1651�������������������
39fcb981 1652As it turned out not all configuration settings are as everlasting that
1653they can be constants (this mainly applies to "look&feel"-settings). So
1654some of the above mentioned EWIKI_ constants can now be overridden by
1655settings in the more flexible $ewiki_config[] array.
1656
1657Usually this array contains index=>value pairs with simple boolean
1658meanings, but often there are more complex entries and some of its contents
1659are data/behaviour entries (that were previously/falsely in $ewiki_plugins).
1660
1661You can override settings by just setting $ewiki_config["..."]="...";
1662because the entries in ewiki.php are defaults that do not overwrite any
1663existing var. So it is really not important if you change things after or
1664before the 'ewiki.php' script gets included().
1665
1666["script"] Replaced EWIKI_SCRIPT, and is used to define the
1667 path/URL of the ewiki wrapper script (yoursite.php,
1668 which at least included the ewiki.php script and
1669 runs the ewiki_page() function).
1670
1671["script_url"] Should contain an absolute URL to the ewiki wrapper
1672 script. (replaces EWIKI_SCRIPT_URL)
1673
1674["script_binary"] like EWIKI_SCRIPT_BINARY
1675
1676["print_title"] replaces EWIKI_PRINT_TITLE, but also allows finer
1677 grained control:
1678 a 1 says that titles should be added at top of pages
1679 a 2 states that titles should also link for internal
1680 and generated pages
1681 a 3 will make linked titles even for pages, that
1682 should normally not have them
1683
1684["split_title"] replaces EWIKI_SPLIT_TITLE, defines if pages` titles
1685 WikiWords should be separated by spaces when displayed
1686
1687["wiki_pre_scan_regex"] Is the regular expression used to separate out links
1688 from a pages` content to query the database for
1689 existence of all mentioned WikiPages.
1690
1691["wiki_link_regex"] Is the actual link search regular expression. It is
1692 responsible for finding WikiWords and things in square
1693 brackets and ordinary http:// or internal:// WWW-links
1694 and even email addresses.
1695
1696["action_links"][$ACTION1][$ACTION2] Holds title for $ACTION2 when shown
1697 on a page activated with $ACTION1 (only "view" and
1698 "info" get other actions` titles associated currently).
1699 This is used for the _control_links() for example to
1700 entitle/show action links.
1701
1702["idf"][$TYPE] Associates arrays with identification (search) strings
1703 into classes (we have "url" and "img", "obj" for
1704 example associated with proto:// prefixes or filename
1705 extension lists).
1706
1707["interwiki"][$PREFX] Connects other Wikis` script URLs to WikiLinkPrefixes.
1708
1709
1710["format_block"][$BTYPE] Defines "block" types, which are scanned for in
1711 WikiPages (using the given search strings), and then
1712 handled by specialized ["format_block"] plugins
1713 (instead of the core ewiki_format() function code).
1714
1715["format_params"][] Contains the default $params, the ewiki_format()
1716 function will assume, if they weren't overridden
1717 by the second paramater given to it.
1718
1719["wm_..."] WikiMarkup definitions.
1720
1721["htmlentities"] Used by ewiki_format() to pre-escape <html> in
1722 wikipages (later some of the escaped html is
1723 often reactivated).
1724
1725
1726
1727internal coding explained
14a960ac 1728�������������������������
39fcb981 1729This section is to explain some of the coding style of ewiki, and how some
1730things work. While many parts of ewiki carry good source code comments, it
1731is always difficult to quickly understand larger scripts like the ewiki one
1732by just reading it.
1733
1734
1735
1736 how ewiki operates
14a960ac 1737 ������������������
39fcb981 1738 ewiki_page()
1739 - decodes the $id and $action from the GET or POST parameters
1740 - tries to load the page from ewiki_database()
1741 - if this failed then it calls the database init function
1742 - calls some init plugins, calls the _auth() interface
1743 - chains to ["page"] plugins which activate for registered $id's
1744 - alternatively calls a plugin that was registered for $action
1745 - the default however is to render the current page via _page_view()
1746 - adds a page title
1747 - sends the generated output (view page or plugin output) back to
1748 caller (for output into yoursite.php)
1749
1750 ewiki_page_view()
1751 - feeds the current page $data's ["content"] into ewiki_format()
1752 - also decodes paramters (html allowed)
1753 - returns the gererated html back
1754
1755 ewiki_format()
1756 - beatifies the source code (unifies to plain UNIX newlines)
1757 - calls init plugins (wiki source mangling)
1758 - splits source into blocks, calls block plugins
1759 - then goes through each line of the wiki source to generate html
1760 - there is line-start, in-line and complete-markup
1761 - afterwards everything went from source into the $ooo-output var
1762 - first calls the link pre scan regex (which searches for
1763 wikiwords and stores that information into $ewiki_links)
1764 - then calls the wiki-link transformation regex function
1765 - then calls post plugins and returns generated <html>
1766
1767 ewiki_render_wiki_links()
1768 - searches for all (pre-fetched) $ewiki_links in the
1769 ewiki_database ("FIND")
1770 - transforms the wikiwords into html-links
1771 - with the regex and callback func: returns output back to
1772 - ewiki_format()
1773
1774 ewiki_link_regex_callback()
1775 - transform the wiki source snippet returned from the
1776 preg_replace() call into a html link string
1777 - (complicated)
1778
1779 ewiki_$page_plugin_*()
1780 - page plugins return html output, which usually is hardcoded as
1781 strings into them
1782 - provide some interactivity
14a960ac 1783
39fcb981 1784 ewiki_$action_plugins_*()
1785 - activate on pages with special registered $action's
1786 - provide some interactivity (for page editing for example)
1787
1788
1789
1790 used variables
14a960ac 1791 ��������������
39fcb981 1792 Variables in ewiki often have similar names, and are also
1793 regularily passed by reference from one function to another (so it
1794 is in fact the same variable).
1795
1796 $id - Is often the name of the current page (which is to be shown
1797 returned as output. The content of this variable is
1798 also available via the global $ewiki_id [[for plugins
1799 that do not have the common ($id,$data,$action)
1800 interface parameters]].
1801
1802 $data - Contains the entry fetched with the initial
1803 ewiki_database() call. This is an array of the form:
1804 array(
1805 "id" => "CurrentPageName",
1806 "version" => 1, # 1 is the lowest possible
1807 "flags" => 1,
1808 "created" => 1002056301,
1809 "lastmodified" => 1002171711,
1810 "hits" => 235,
1811 "author" => "localhost (127.0.0.1:4981),
1812 "meta" => array("Http-Header"=>"X", "setting"=>"val"),
1813 "content" => "wiki source...",
1814 )
1815
1816 $action - The $action with wich the current page was requested
1817 (most often "view", but everybody also knows "edit").
1818
1819 $uu - Short for "unused". Is used as temporary variable, especially
1820 with preg_match() and string functions.
1821
1822 $result - Used for database queries SEARCH and GETALL.
1823
1824 $row - Holds temporarily fetched entries from the databases
1825 (like $data), if page lists are to be generated.
1826
1827
1828
1829
1830
1831 -------------------------------------------------------------------- 4 --
1832
1833
1834
1835
1836
1837Tweaking
14a960ac 1838��������
39fcb981 1839(this part of the README is also just a collection of random notes)
1840
1841
1842
1843Just using the wiki source transformation
14a960ac 1844�����������������������������������������
39fcb981 1845The ewiki_format function was designed to be used independently from the
1846ewiki database.
1847
1848 ewiki_format($wiki_source, 0);
1849
1850It just needs the "wiki_source" as argument and generates a nicely
1851formatted page from it. All you need to take care about is the
1852$ewiki_links variable.
1853Set the $ewiki_links=true ("true" and not "1" or anything else) to
1854enforce ewiki_format() to treat all references as existing.
1855
1856To separate the ewiki_format() function out of recent ewiki versions,
1857you'll also need ewiki_script(), ewiki_link_regex_callback(), ... and
1858a lot of constants to take with. It is often much easier to just
1859include("ewiki.php") for using ewiki_format(). You then should however
1860take care, that the _binary part doesn't get activated by accident. To
1861prevent this, just put following before the include() statement:
1862
1863 unset($_REQUEST["binary"]);
1864 include("ewiki.php");
1865
1866If you need it more quickly, or don't want to load the whole ewiki.php
1867file, then just try the fragments/wiki_format.inc, which is a stripped
1868down version of an older rendering core function (no WikiLinks, no binary
1869stuff). Contributed by Frank Luithle.
1870
1871
1872
1873Customizing ewiki_format()
14a960ac 1874��������������������������
39fcb981 1875There are various markup extension plugins available for ewiki, which
1876allow you to use BBCode or the syntax of another WikiWare. But if you
1877have a closer look at $ewiki_config (the defaults are in 'ewiki.php'
1878around line 200), you'll notice, that you can configure the WikiMarkup
1879that is to be used.
1880Various "wm_..." entries map our obscure markup to html <tags> (or at
1881least fragments of them). So in order to add a feature you could insert
1882an own rule there. (But keep in mind, that every new WikiMarkup slows
1883down the transformation function.)
1884
1885Often you want to append an entry to "wm_style", for example:
1886
1887 $ewiki_config["wm_style"]["==="] = array("<h1>", "</h1>");
1888
1889Would allow you to write "===SomeText===" in a WikiPage, which then would
1890display as an far-too-large headline.
1891
1892You can also add markup with different 'start' and 'end' characters, using
1893the "wm_start_end" entry in $ewiki_config. For example the following would
1894render "... ((((some text)))) ..." in a page using the html <kbd> tag:
1895
1896 $ewiki_config["wm_start_end"][] = array(
1897 "((((", "))))", "<kbd>", "</kbd>",
1898 );
1899
1900Please see the section on "ewiki_format() internals" on how to write a
1901["format_..."] or markup plugin.
1902
1903
1904
1905Customization using CSS
14a960ac 1906�����������������������
39fcb981 1907There are now some interesting ways to style ewiki output, just read on.
1908
1909Please note, that it in your stylesheets you just write ".wiki" and
1910REALLY NOT ".ewiki" this time.
1911
1912Also important is, that we discourage use of the underscore in CSS class
1913names, because it is simply forbidden there, even if current browsers do
1914not complain as loudly as the w3c does. (That's just why you'll now see
1915lots of class names with minus dashes instead of underscores.)
1916
1917
1918
1919user style classes in pages
14a960ac 1920���������������������������
39fcb981 1921The plugins/markup_css allows you to use CSS classes and style definitions
1922in WikiPages. With the double at @@ followed by a css classname or command
1923you start styling a paragraph or parts of the text.
1924
1925 @@classname at the start of a paragraph will
1926 enclose it into a <div class="classname">
1927 completely
1928
1929 But inside of some text, the @@styledef only
1930 affects the part until the next @@ everything
1931 that comes later won't be enclosed in a <span>
1932
1933While the css style classes must be defined in your sites` global stylesheet
1934to take effect, you could also use direct CSS style commands instead. These
1935also must follow the @@ immediately and may not contain spaces. So something
1936like @@color:#ff0000; will work, while specifying font names may not always.
1937
1938
1939
1940rendered page content
14a960ac 1941���������������������
39fcb981 1942If you are not interested in walking around the "ewiki.php" script
1943when you want to tune how the output looks, you should try to
1944utilize the (few) CSS classes ewiki defines (it does not include
1945even one color setting or <font> tag):
1946
1947<style type="text/css">
1948
1949 p { font: ... } // almost every part of the generated
1950 // wiki pages is inside a <p>...</p>
1951
1952 em { ... } // you could encolour this, if the browsers
1953 strong { ... } // usual italic is not emphasized enough
1954
1955 .indent // to specify a different space-indentation
1956
14a960ac 1957</style>
39fcb981 1958
1959
1960
1961pages enclosed in style classes
14a960ac 1962�������������������������������
39fcb981 1963The most powerful way to style the content ewiki includes into your site
1964is to use the generic style class names which enclose every page that comes
1965from ewiki:
1966
1967 <div class="wiki view ThatPage">
1968 ...
1969 </div>
1970
1971This <div> is always the outermost tag around the html content that returns
1972from ewiki_page(). It will always contain the class "wiki", after this
1973the current page action/ and PageName (the action is usually "view", but
1974can be also "edit", "info", "links" or something similar).
1975
1976Keeping this in mind you can easily style all, a few or even just a single
1977page from ewiki in your stylesheet. (We'll explain it here, because the word
1978of multiple class names and the cascading way of using CSS is not very
1979widespread.)
1980
1981.wiki { // this affects every page ewiki returns
1982 background-color: #ccccff;
1983 font-family: "WikiFont";
1984 ...
1985}
1986
1987.wiki.view { ... } // only applies to pages that are "view"ed
1988.wiki.links { ... } // BackLinks
1989.wiki.edit { ... } // when a page gets edited
1990
1991.wiki.PageIndex { // this rule affects only a __single__ page
1992 ... // regardless what the "action/" is now;
1993} // useful for "PowerSearch" or "PageIndex"
1994
1995.wiki.edit.ThisVerySpecialPage { // this css section applies to just one
1996 ... // page again, and this time only when
1997} // it gets edited
1998
1999
2000
2001plugin output styling
14a960ac 2002���������������������
39fcb981 2003There often appear special 'pieces' within a rendered page that ewiki
2004returns, because not everything in the returned html code belongs to the
2005requested pages` content.
2006
2007For example the current pages` title needs its own css class, like does
2008the block of action links ("EditThisPage, PageInfo, ...") below every page,
2009so it can be distinguished from the pages` text.
2010
2011Also note again the use of the '.wiki' selector within the following
2012stylesheet guide and ewiki CSS class overview:
2013
2014
2015.wiki h2.page.title { // all titles now have it, while many
2016 ... // of them include links as well
2017}
2018
2019.wiki.view .action-links { // "EditThisPage, PageInfo, ..." links
2020 ... // are inside such a block, like are two
2021} // <hr>'s
2022
2023.wiki.info .chunked-result { // some generated pages (like the history
2024 ... // info/ ones) may need to split their
2025} // results; this matches those links
2026
2027 //-- the edit/ pages are separated into
2028 // following blocks:
2029.wiki.edit .edit-box { ... }
2030.wiki.edit .image-upload { ... }
2031.wiki.edit .preview { ... }
2032
2033 //-- info/ pages contain a history of page versions, each enclosed in
2034 // a <table class="version-info">, the <tr>s inside can be selected
2035 // separately:
2036.wiki.info table.version-info { ... }
2037.wiki.info .version-info .action-links { ... }
2038.wiki.info .version-info .page-author { ... }
2039.wiki.info .page-refs { ... }
2040.wiki.info .page-flags { ... }
2041
2042
2043The class naming across most of the extension plugins is not unified, so you
2044may often need to look it up here - or inside of the plugins source code.
2045This is at least necessary for calendar and navbar, which follow a very
2046different naming scheme.
2047
2048.wiki .download-entry { ... }
2049.wiki .download-form { ... }
2050.wiki .upload-form { ... }
2051
2052.wiki .image-append { ... }
2053
2054
2055
2056Idea Collection
14a960ac 2057���������������
39fcb981 2058Here we'll note some tricks, on how to do this and that. Some of the
2059following paragraphs also explain workarounds for currently lacking
2060features.
2061
2062
2063
2064 Multiple Wikis / InterWiki feature abuse
14a960ac 2065 ����������������������������������������
39fcb981 2066 Other WikiWare provides means to have multiple namespaces in a wiki,
2067 what if fact is contrary to the original Wiki idea suggesting a
2068 single flat namespace. ewiki does not support SubWikis or alike, to
2069 get multiple Wikis using one ewiki installation you'll need multiple
2070 layout and config wrappers (each with its own absolute URL and
2071 differen EWIKI_DB_TABLE_NAME or EWIKI_DBFILES_DIRECTORY constants).
2072
2073 This way you'd get two independent Wikis (with two different SQL
2074 database tables, or flat_files directories), and of course links
2075 between those two need a special syntax. And the best approach here
2076 was to use the InterWiki linking feature.
2077
2078 To do so, invent to InterWikiAbbreviations for each of your separate
2079 Wikis and add it to $ewiki_config["interwiki"] as follows:
2080
2081 $ewiki_config["interwiki"]["main"] = "/wiki/main/?id=";
2082 $ewiki_config["interwiki"]["office"] = "/wiki/office/?id=";
2083 $ewiki_config["interwiki"]["tech"] = "http://tech.company.com/?id=";
2084 $ewiki_config["interwiki"]["our-www"] = "http://www.company.com/";
14a960ac 2085
39fcb981 2086 The last one is an example, on how to use the InterWiki feature to
2087 generate references to arbitrary web documents, with a simple syntax
2088 like "[our-www:/customers/pub/rules.html]" - it's somehow standard to
2089 use "company-url:" or "company-www:" as InterWikiAbbreviation for this
2090 purpose.
2091
2092
2093
2094
2095
2096
2097
2098 -------------------------------------------------------------------- 5 --
2099
2100
2101
2102
2103Explanations
14a960ac 2104������������
39fcb981 2105The next few paragraphs shall enlight more detailed how some things are
2106handled in ewiki (and why it is that way).
2107
2108
2109
2110Binary and Text content
14a960ac 2111�����������������������
39fcb981 2112Because I'd like to keep it small (see also the "Everything in one
2113script" paragraph) ewiki also creates just one database table.
2114Differently from other Wikis this one has the 'flags' setting for
2115each saved page. And as I successfully used this bad trick in earlier
2116projects many times to integrate support for hundreds of different
2117functions (CMS, links, boards/forums, ...) into a single table; I
2118thought it could be funny to have something like this in ewiki too.
2119
2120While the image thingi seemed senseful to me, other binary data
2121cannot be feed into database without helper plugins, because this is
2122a Wiki script and not an almighty portal software!
2123
2124Uploading and caching of images requires the EWIKI_SCRIPT_BINARY
2125constant to be set correctly (no output may be made before "ewiki.php"
2126is included == "binary safe").
2127The ewiki_binary() function handles almost all of this, and gets
2128activated automagically (whenever required) as soon as ewiki.php is
2129included().
2130
2131I believe these functions to be rather safe, as there are many sanity checks
2132throughout the code to separate between _DB_F_BINARY and _DB_F_TEXT content.
2133
2134
2135
2136 Image Uploading
14a960ac 2137 ���������������
39fcb981 2138 The currently most important use for the BINARY flag and image
2139 functions is to upload images with the small form below every page
2140 edit box.
2141
2142 The upload/caching functions can be disabled fully if
2143 EWIKI_SCRIPT_BINARY and EWIKI_CACHE_IMAGES are set empty (or zero).
2144
2145 URLs starting with "internal://" represent the uploaded files. The
2146 string is just a md5() sum generated from the contents of the
2147 uploaded file. This way files won't get saved another time if they
2148 are uploaded twice. For uploading a JavaScript-capable browser is
2149 recommended. It will work without, but then requires the user to
2150 copy the [internal://...] text (from one window to another).
2151
2152 The color of the temporary upload info screen can only be changed
2153 inside the ewiki_binary() function, currently.
2154
2155 Beware that images usually get downscaled if they are larger than
2156 specified with EWIKI_IMAGE_MAXSIZE (per default 64K).
2157
2158
2159
2160 Images Caching
14a960ac 2161 ��������������
39fcb981 2162 Images are usually redirected through EWIKI_SCRIPT_BINARY, and ewiki
2163 tries to save them inside the database as with uploaded images. So
2164 most of the facts from the previous paragraph apply to this function
2165 too.
2166
2167 You must enable this feature with EWIKI_IMAGE_CACHING, it is shipped
2168 disabled currently.
2169 Adding a ?nocache to the image URL disables this feature for just one
2170 specific image, if _IMAGE_CACHING was otherwise enabled.
2171
2172 Images are downscaled to fit the maximum defined size in
2173 EWIKI_IMAGE_MAXSIZE (bytes) if the PHP libgd extension is available
2174 (else dropped and then always redirecting clients which request
2175 those image).
2176
2177
2178
2179 Image WikiMarkup
14a960ac 2180 ����������������
39fcb981 2181 Usually one writes image references using square brackets around the
2182 url of an image: [http://www.example.com/pics/image.png] or:
2183 [internal://md5md5md5md5md5md5md5md5md5md5md5md5.png]
2184
2185 This will include (inline) the image into the page, when rendered
2186 and viewed. Using the standard square bracket link entitling syntax
2187 also image references can be named (non-graphics / alternative
2188 text):
2189 [http://www.example.com/pics/image.png | This is an example image]
2190 [http://.../image.pic "or entitle it using double quotes"]
2191
2192 Images can also be "aligned" to either side of the screen, thus the
2193 remaining text will flow around it. To achieve this include spaces
2194 to the left or the right of the image URL:
2195
2196 * picture to the LEFT: [http://www.example.com/pics/image.png ]
2197 * picture to the RIGHT: [ http://www.example.com/pics/image.png]
2198 * CENTRED picture: [ http://www.example.com/pics/image.png ]
2199
2200 Note that you must use __two__ spaces, currently!
2201
2202 Image rescaling is possible by appending x=... and y=... as query
2203 string parameters behind the image URL:
2204 [http://www.example.com/pics/image.png?x=160&y=120]
2205 The query string parameters "width" and "height" are also accepted.
2206
2207 If you have an image URL, but you do not want to get that image
2208 inlined into the current page, then just leave out the square
2209 brackets around.
2210
2211
2212
2213 binary_store, direct access
14a960ac 2214 ���������������������������
39fcb981 2215 While storing the binary data together with text pages in the same
2216 database is most often a good thing and suits most sites, there
2217 exists also a workaround/hack to keep this binary data in plain
2218 files. The advantage is a smaller database and possibly a little
2219 speed enhancement (with a large collection of binary things in the
2220 db). However the drawback is, that use of plugins/binary_store is
2221 only transparent to the main ewiki script, but all admin tools/
2222 won't be aware of it.
2223
2224 If you choose to use the binary_store.php plugin, you can also let
2225 ewiki generate URLs directly to the then stored data files if you
2226 just set the EWIKI_DB_STORE_URL constant.
2227
2228 Please see the paragraph on this plugin for more informations on
2229 this.
2230
2231
2232
2233 Arbitrary Binary Content
14a960ac 2234 ������������������������
39fcb981 2235 Set the EWIKI_ACCEPT_BINARY constant, if you'd like to allow any
2236 binary file to be uploaded and saved in the database using the image
2237 upload function. Uploaded files will show up as ordinary (except
2238 that "internal://" href prefix) links.
2239
2240 Please also note the "plugins/download.php", which does a much
2241 better job than this constant.
2242
2243
2244
2245$action and $id
14a960ac 2246���������������
39fcb981 2247Inside of ewiki.php you'll see many occurrences of variables named $id and
2248$action. The $id refers to the current page, which usually is a string like
2249ThisPage, ThatPage, OrAnotherPage.
2250
2251Because just having pages wasn't believed to be sufficient enough, there
2252is also a way to do something with them. That is what the $action tells.
2253The most often used $action is "view" and is automatically assumed when
2254no other $action was specified in the current ewiki URL. For non-existent
2255pages alternatively the "edit" $action may get used instead.
2256
2257So the $action now delegates control about a requested page to a subfunc
2258or plugin of ewiki, so the stored data of the page can be used for
2259something (viewing being again the most common thing to do with it).
2260
2261"action/ForTheCurrentPage" is how both often looks in conjunction (again:
2262if there is no "$action/" then "view/" will be assumed). Here the $action
2263appears in front of the page name separated by a slash. A pagename now can
2264contain slashes too, because ewiki can figure out, that "view/That/Page"
2265separates into the $action being "view" and $id is "That/Page" in this
2266example (the "view" gets mandatory in such cases).
2267
2268
2269
2270 ewiki URLs
14a960ac 2271 ����������
39fcb981 2272 "$action/$id" is most commonly appended as "GET parameter" to an
2273 ewiki URL, after a string like "?id=" or "?page=" - you've already
2274 noticed that!
2275
2276 There are of course other ways to design the URLs ewiki produces
2277 and uses, the PATH_INFO being one of the most favoured alternatives.
2278 (we had a paragraph on this earlier, see on top of this README)
2279
2280 Other Wikis use different URLs too, but you can tweak ewiki easily
2281 to a different behaviour, because you have the chance to pass your
2282 $action and $id to ewiki_page() from different sources. And because
2283 URL generation is encapsulated into the function ewiki_script()
2284 you could easily change just a few lines to make them look like you
2285 desire.
2286
2287 The $action can be passed as "?action=" parameter already (this is
2288 core support), so URLs could for example look like
2289 ".../my/wiki.php?id=ThisPage&action=view" ... or something alike.
2290
2291
2292
2293
2294
2295
2296
2297 -------------------------------------------------------------------- 6 --
2298
2299
2300
2301
2302
2303
2304Everything in one script
14a960ac 2305������������������������
39fcb981 2306I think its handy to have one script for one task, and as ewiki is not
2307intended to be used as portal script I think it's senseless to have
2308always thousands of libs/scripts surrounding it.
2309
14a960ac 2310However as time went on, it turned out, that it would either slow down
39fcb981 2311the core 'library' when everything was included into it, or that there
2312couldn't be much further development at some point.
2313
2314So packaging useful but non-essential extensions into separate files was
2315a good decision. Most of the plugin code can however still be inserted
2316into or appended to the main "ewiki.php" script easily.
2317
2318As I realized that it really takes some time to edit the source when
2319including non-standard things I decided to add that simple extension
2320mechanism. Internally it is represented by the "$ewiki_plugins" array,
2321which holds an list of alternative functions for various tasks.
2322This allows to just include("a/plugin.php") for additional functionality
2323inside ewiki.
2324
2325 Note: if you're going to use almost all plugins, you should think about
2326 merging them altogether into one .php file:
2327 cat plugins/*.php > all-plugins.php
2328 It is much faster to include() just one big .php script, than it is to
2329 let the PHP parser run over twenty small ones (PHP is not interpreted,
2330 but memory-compiled).
2331
2332
2333
2334database plugins
14a960ac 2335����������������
39fcb981 2336The ewiki.php core script contains a database request function which is
2337tailored to a MySQL database. However that function is already prepared
2338to chain to another "database abstraction" function if desired.
2339
2340
2341
2342 MySQL support
14a960ac 2343 �������������
39fcb981 2344 The first implemented, and still most recommended way to use
2345 ewiki is with a MySQL (3.21 or later) database. RDBMS work more
2346 reliably and of course much faster than any other of the ewiki
2347 database backends.
2348
2349 As the core ewiki_database() inside ewiki.php already includes
2350 the MySQL database calls, there is usually nothing to do, but
2351 opening a database connection before ewiki.php is included()
2352 from yoursite.php
2353 Please look at the top of this README for an example.
2354
2355 As PHPs mysql_() functions don't require a db resource link to
2356 be given anymore, the ewiki_database() function does not pass
2357 and thus does not require it too. (If you use more than one MySQL
2358 database, you should take care, that ewiki accesses the one you
2359 accesses least.)
2360
2361
2362
2363 plugins/db_flat_files
14a960ac 2364 ���������������������
39fcb981 2365 If you don't have access to a MySQL database, then just include()
2366 this plugin to save your wiki pages into simple text files (editable,
2367 often called "flat files") inside a dedicated subdirectory. You
2368 must set EWIKI_DBFILES_DIRECTORY in the 'ewiki.php' script to the
2369 correct dirname. Don't forget, that it must be given either relative
2370 to where the ewiki.php script is run from (like "./pages") or
2371 absolute to the servers filesystem root (for example
2372 "/export/htdocs/user528742/www.example.com/ewiki/pages") but NOT
2373 relative to your WebSpaces DocumentRoot!.
2374
2375 Usually "/tmp" will work, but this one is purged on every boot; and
2376 therefore you should create a new sub directory (" mkdir ./pages ")
2377 where all files go into. This newly created subdir must be made
14a960ac 2378 �world-writeable� using the command "chmod 777 ./pages", because the
39fcb981 2379 WebServers user id counts when accessing it.
2380
2381 Usually you can do both from within your ftp client (the commands
2382 are the same if you have a shell account):
2383 ftp> cd .../ewiki
2384 ftp> mkdir pages
2385 ftp> chmod 777 pages
2386 ftp> ls
2387 -rw----r-- 1 yourname yourname 57024 01. Jan 00:00 ewiki.php
2388 -rw----r-- 1 yourname yourname 512 01. Jan 00:00 index.php
2389 drwx---r-x 2 yourname yourname 4096 01. Jan 00:00 init-pages
2390 drwxrwxrwx 2 yourname yourname 4096 25. Feb 23:59 pages
2391 drwx---r-x 2 yourname yourname 4096 01. Jan 00:00 plugins
2392 -rw----r-- 1 yourname yourname 33010 01. Jan 00:00 README
2393 ftp> quit
2394
2395 In graphical FTP clients there is usually a menu entry to set
2396 "access mode" or "access rights" (sometimes "file permissions") of
2397 files and directories equally.
2398
2399 Again: don't forget to set the EWIKI_DBFILES_DIRECTORY constant to
2400 the correct value!
2401 If you create a subdirectory for the page files in the same directory
2402 the main 'ewiki.php' script resides, you usually want to set the
2403 config constant to just "./thesubdirectory" - here you could leave
2404 out the "./" (not required as it only refers to the current path).
2405 Btw, the slash character will work in directory specifications on
2406 windoze systems too (mr. bill once had to introduce a hierarchical
2407 filesystem in DOS 2.0, but choosed the bad backslashes, so no one
2408 should notice where that idea was borought from).
2409
2410 The saved pages are in a format usually referred to as
2411 "message/http" (like www service request) or "message/rfc822"
2412 (internet mail). They usually look like:
2413 +-----------------------------------------------
2414 | id: WikiPageName\r
2415 | version: 1\r
2416 | flags: 1\r
2417 | author: 127.0.0.1:3054\r
2418 | created: 1046532697\r
2419 | lastmodified: 1046532697\r
2420 | refs: \nErfurtWiki\nNewestPages\n\r
14a960ac 2421 |\r
39fcb981 2422 | !! WikiSourceContent
2423 | <more-text>...
2424
2425 This file format can be exported by the "backup" tool, so you could
2426 easily change from the MySQL database to the flat-files one, if
2427 desired. Each page file exists in different versions, where the
2428 version number is always appended to the saved pages` file name.
2429
2430 EWIKI_DBFILES_NLR converts newlines into the string "\n", but just
2431 for the values of the metadata. So there shouldn't occur much
2432 inconsistency, because the wiki content is saved binary safe in
2433 those "flat files".
2434
2435 Filenames will be heavily converted on Win32 (urlencoded), while on
2436 state of the art UNIX/Linux systems only a few characters are
2437 replaced (slashes into backslashes) to match filesystem requirements.
2438
2439 Problems: dbff WikiPageNames are currently not case-insensitive on
2440 UNIX-filesystems (while the MySQL-table is).
2441 Hits won't get counted; I don't think it is that essential, and it
2442 would take too much effort and time (file accesses) to support this.
2443
2444 Note: You cannot do a "backup" from a Unix server to a Win box by
2445 using a plain FTP program, because many characters are allowed in
2446 Unix filenames but not on Win partitions. If you really want and
2447 need to do so regularily, you could then setup ewiki with
2448 EWIKI_DBFILES_ENCODE enabled from the very beginning. - The better
2449 aproach was to use 'ewikictl' or 't_backup' or 't_transfer' for the
2450 backup task.
2451
2452
2453
2454 plugins/db_fast_files
14a960ac 2455 ���������������������
39fcb981 2456 NOTE: The db_fast_files has been merged into db_flat_files, so both
2457 formats can be read now - at the same time! Updated or new pages will
2458 however always be written in the file format determined by
2459 EWIKI_DB_FAST_FILES (defaults to 0), edit the "db_flat_files.php"
2460 script to change that constant setting, or even add it to your
2461 "config.php" so it was always present.
2462
2463 While "db_flat_files" allows you to edit the WikiPage files (using
2464 any simple text editor), the "db_FAST_files" plugin saves the pages
2465 in a binary&compressed format (utilizing PHP's serialize function).
2466
2467 This generally leads to a speed enhancement. Additionally this also
2468 allowed the PageHit counting to be activated (which is off in plain
2469 flat files).
2470
2471 So you may wish to use this plugin in favour of the older
2472 db_flat_files. And as now both methods are available at the same
2473 time, you can switch whenever you want.
2474
2475 Most of the setup guide from above is true for this one, too.
2476
2477 An additional configuration constant introduced here is
2478 EWIKI_DBFILES_GZLEVEL, which tells the PHP internal zlib how much
2479 time to spend on compression of the saved pages. Usually the zlib
2480 uses a default of 5, but for speed purposes it is set to 2 here. You
2481 can also set the constant to 0 so the files will get saved
2482 uncompressed (but still in 'binary' format). A value of 9 will give
2483 you the smallest possible files, but this takes a little more CPU
2484 cycles (a bit slower).
2485
2486 This plugin was contributed by Carsten Senf.
2487
2488
2489
2490 plugins/db_any
14a960ac 2491 ��������������
39fcb981 2492 If you use a relational SQL database other than MySQL, then you
2493 may want to give this plugin a try. It itself provides a wrapper
2494 for the PHP database access wrapper libraries ADOdb, PEAR::DB and
2495 dbx().
2496 These wrappers themselves provide unified access to various SQL
2497 databases in contrast to the many highly different db access
2498 functions of PHP. Each of these db access wrappers has advantages
2499 and disadvantages and so none of them is really widespread and many
2500 users of course only jump on one of these trains. Because ewiki now
2501 tries to be 'library' it will use whatever database access wrapper
2502 you already have running on your site or container CMS, and the
2503 highly simplified anydb_*() now tries to make use of it.
2504
2505 The plugin is based upon the current MySQL database backend, and
2506 thus may not be compatible to all proprietary SQL variants other
2507 vendors usually enforce.
2508
2509 Before you can use the db_any plugin you must ensure that you
2510 either already have the PHP dbx extension dll loaded or the PEAR::DB
2511 or ADOdb include files loaded. db_any will like to see an opened
2512 database connection inside of the global '$db' variable. If
2513 yoursite.php hasn't already a connection opened when ewiki.php
2514 gets included, then you should preferably choose to use the
2515 anydb_connect() function to do so (it will choose from PEAR::DB,
2516 ADOdb and PHP dbx interfaces).
2517 The '$db' connection handle can be shared between your site and
2518 ewiki as long as it is a handle for one of the mentioned database
2519 access wrapper libraries.
2520
2521
2522
2523 plugins/db_adodb
14a960ac 2524 ����������������
39fcb981 2525 obsoleted by plugins/db_any
2526
2527
2528
2529 plugins/db_dba
14a960ac 2530 ��������������
39fcb981 2531 including() this plugin enables ewiki to store the WikiPages in the
2532 Berkeley DB file given with the EWIKI_DBA constant. Your PHP binary
2533 must be compiled with either the "dba" or the "dbm" extension to use
2534 this (and the dba extension requires at least one other database
2535 type to be enabled).
2536
2537 The plugin has a built-in list of preferred dba database types, but
2538 it respects the filename extension of EWIKI_DBA. For example
2539 "wiki.db3" would create a DB3 database file, while "wiki.gdbm"
2540 resulted in a GDBM file, if that php extension was available.
2541
2542 The PHP dba extension can support the db types (if compiled for):
2543 .gdbm
2544 .ndbm
2545 .db2
2546 .db3
2547 .db4
2548 .flatfile
2549 .dbm
2550
2551 If you have the PHP "dbm" extension enabled, wrapper functions will
2552 get enabled, so this works even if the "dba" extension is not there.
2553
2554 The .flatfile is often available even if you haven't compiled your
2555 PHP binary for anything else than "dba". This may also often be
2556 faster than one of the db_flat_files plugins.
2557
2558 If EWIKI_DBFILES_GZLEVEL is set to a value from 1 (fast) till 9
2559 (very good compression, but slow), the saved pages will get
2560 compressed inside the dba database. With 0 this feature gets
2561 disabled.
2562
2563
2564
2565 plugins/db_phpwiki13
2566 --------------------
2567 The original ewiki database table structure was compatible with the
2568 one used in PhpWiki version 1.2.x, however it turned out that the
2569 PhpWiki project has yet not stopped completely and choosed to
2570 implement a more relational table structure with version 1.3
2571
2572 This plugin is only meant for transition __from__ PhpWiki v1.3.x to
2573 ewiki, it should NOT be used to connect ewiki with PhpWiki forever.
2574
2575 Write access is disabled per default, but available. However it is
2576 probably not fully compatible with the database abstraction and usage
2577 of PhpWiki, so it is likely to corrupt your database if you use it
2578 for a longer period of time. This warning is mainly because the
2579 'latestmajor', 'latestminor and 'minor_edit' rows in the PhpWiki
2580 database, because such stuff is not used by ewiki at all. ewiki also
2581 tries to put some of the pages meta data into places where it could
2582 eventually confuse PhpWiki.
2583 Write access is however done nearly as safe as within the ewiki
2584 database access layer (INSERT statement to not overwrite existing
2585 entries).
2586
2587 Again: this plugin is in no way meant to encourage you to keep your
2588 old PhpWiki database! ;>
2589 Please see also "tools/ewiki_convertdb.php".
2590
2591 If you temporarily enable this plugin within the default/example
2592 "config.php" or the "tools/ewiki_tools_config.php" you can also
2593 utilize the very powerful 'ewikictl' cmdline utility to generate a
2594 copy of your PhpWiki database in one of the backup formats suitable
2595 for later use with ewiki.
2596
2597
2598
2599 plugins/binary_store
14a960ac 2600 ��������������������
39fcb981 2601 Is a hack into the ewiki core, which will store binary/uploaded
2602 files outside of the default ewiki database (as plain files in a
2603 data directory).
2604
2605 Please also see the documentation on top of the plugin file.
2606
2607 Per default ewiki can store "binary" entries beside ordinary text
2608 pages in the database. If you'd like to keep uploaded files/images
2609 out of the db, then this plugin/hack will help. It intercepts ewiki
2610 and saves uploaded data into a plain data file, and instead creates
2611 a "binary symlink" in the database for it (just the binary meta
2612 data will get stored, with a hint on where to later access the plain
2613 data file).
2614
2615 This may sometimes be a speed enhancement and reduces size of the
2616 database, however it has the drawback that only the main ewiki
2617 script can handle this transparently and all admin tools/ fail to
2618 deal with the stored plain data files (no backup support and so on).
14a960ac 2619
39fcb981 2620 By setting the EWIKI_DB_STORE_URL constant correctly (corresponding
2621 to your wiki setup and where you store the data files, compare with
2622 EWIKI_DB_STORE_DIRECTORY) you can make ewiki create URLs directly
2623 to where the stored plain data files reside (they do not contain
2624 ewiki database meta data, and thus could be accessed directly by
2625 http clients/browsers).
2626
2627 Please be sure to configure this plugin by setting _DB_STORE_DIRECTORY
2628 to something more useful than "/tmp", so your uploaded files will
2629 still be there after a reboot.
2630
2631
2632
2633core enhancements
14a960ac 2634�����������������
39fcb981 2635Some really cool features are put into extension plugins, and the most
2636important, recommended and most often used ones are listed in this section:
2637
2638
2639
2640 plugins/patchsaving
14a960ac 2641 �������������������
39fcb981 2642 If two users concurrently edit a page, then only the first saving
2643 attempt will succeed; which the second user is told by the "This
2644 page version was already saved" failure message.
2645
2646 This plugin works around this by passing the contents of the
2647 concurrent versions through the 'diff' and 'patch' utilities, which
2648 often merges the two different modifications in a new version that
2649 can be saved into the database so there is no need for the failure
2650 message.
2651
2652
2653
2654 plugins/notify
14a960ac 2655 ��������������
39fcb981 2656 This plugin enables users to get notified, whenever someone changes
2657 a watched page. To enable 'watching' one must just place an email
2658 address into the page with following syntax:
2659 [notify:mail@example.com]
2660
2661 This bracket will be invisible, when a page is viewed, so it can be
2662 placed anywhere. The notifications will be sent to this address
2663 as long as the tag is there.
2664
2665 If one wishes to receive notification messages in another language,
2666 this just needs to be added after a comma or semicolon, like:
2667 [notify:pop3@example.net,de]
2668 This is often only necessary for the generic TLDs .com .org .net,
2669 or where language code and TLD differ.
2670
2671
2672
2673 plugins/jump
14a960ac 2674 ������������
39fcb981 2675 Introduces magic markup for page redirection (switching to another
2676 page). Possible notations are:
2677
2678 [jump:OtherPage]
2679 [goto:SwitchToThere]
2680
2681 The EWIKI_JUMP_HTTP setting tells this plugin to send a Location:
2682 and redirect HTTP status when encountering a page [jump:]. Else
2683 this plugin will show up the JumpDestination page without notifying
2684 the browser about it.
2685
2686 It is also possible to perform InterWiki jumps, just be using the
2687 common InterWikiMoniker: syntax. [jump:WardsWiki:WelcomeVisitors]
2688
2689
2690
2691 plugins/email_protect
14a960ac 2692 ���������������������
39fcb981 2693 This plugin 'ciphers' all valid email addresses inside a WikiPage
2694 for protection against automated spambots. Additionally it
2695 throws fake/trap email addresses to spam spammers databases :>
2696
2697 It ist not integrated into the core script, because some people
2698 may prefer to have email addresses visible (intranet usage).
2699 However it is HIGHLY RECOMMENDED to enable this plugin. Despite
2700 its file size it is rather fast.
2701
2702
2703
2704 plugins/spages (StaticPages)
14a960ac 2705 ����������������������������
39fcb981 2706 The "StaticPages"-plugin allows ewiki to access files in a given
2707 directory. If these files are in text format, ewiki will parse them
2708 as WikiPages. But if you put files with an extension .html, .htm or
2709 .php into one of the specified StaticPages` directories they will
2710 be returned as is from ewiki_page() - the .php files will of course
2711 get executed and their output is returned.
2712
14a960ac 2713 The basename of the files in the directories to be used by spages
39fcb981 2714 will make up the WikiPageName with which the files will be
14a960ac 2715 accessible.
39fcb981 2716
2717 Any given directory (see on top of plugins/spages.php) will be read
2718 recursively. So files in a subdirectory will get available as a
2719 page with a name like "subdir/FileName". If the name of the
2720 subdirectory contains a dot at the end, then the slash will be left
2721 out in favour of a dot: resulted in "subdir.FileName" for example.
2722
2723 PHP scripts in a spages directory however have some restrictions,
2724 like not being able to return headers() or to access most global
2725 variables without use of the $GLOBALS[] syntax. If you rely on
2726 such functionality you should rather write an ordinary page plugin
2727 (which in fact is often much easier).
2728 From the output of .html and .php scripts only the parts between
2729 <body> and </body> will be returned as page content. Any <html>
2730 head area will get stripped, as it would lead to completely invalid
2731 html code if it was returned as is by ewiki_page() into yoursite.
2732
2733 To let this plugin load pages from directories, you should either
2734 edit the array on top of this plugin file, or define() the
2735 EWIKI_SPAGES_DIR (before! including the spages.php script), which
2736 then also would be read in.
2737 Alternatively you could call the ewiki_init_spages() function
2738 yourself to register a directory for processing (after! loading the
2739 spages plugin):
2740
2741 include("plugins/spages.php");
2742 ewiki_init_spages("/var/www/wiki/staticpages/");
2743
2744 You could also use this plugin to inline the ewiki database tools/
2745 as virtual pages.
2746
2747 Btw, it is very easy to make a StaticPage from a ewiki page plugin
2748 and vice versa. Please also note the tools/mkpageplugin which can
2749 convert anything used as StaticPage into a page plugin for easy
2750 including() with other ewiki plugins.
2751
2752
2753
2754 plugins/pluginloader
14a960ac 2755 ��������������������
39fcb981 2756 The pluginloader plugin automatically loads ["action"] and ["page"]
2757 plugins, whenever necessary. This allows to skip dozens of
2758 include() statements within the config.php (which most always just
2759 slow down script startup). It is configured via a static array,
2760 which defines which plugins are allowed to be automatically invoked
2761 on request.
2762 Detailed explanaition is available within this script.
2763
2764
2765
2766 plugins/init
14a960ac 2767 ������������
39fcb981 2768 Handles database initialization using the distributed standard Wiki
2769 files from './init-pages'. Unlike the ewiki-builtin function to
2770 perform that task, this plugin first outputs informational notes
2771 to the user, prior database initialization.
2772 Once you have your SQL or ./files database initialized, you should
2773 disable this plugin (it then isn't be required anymore).
2774
2775
2776
2777 plugins/feature/appendonly
14a960ac 2778 ��������������������������
39fcb981 2779 This plugin (a family of) implements the actual support for the
2780 _DB_F_APPENDONLY page flag. When the flag is set, and this plugin
2781 active, then ordinary users can further only append text to the
2782 page, and won't be able to edit the earlier written parts of it. So
2783 this implements a much softer approach than the _READONLY page
2784 flag.
2785
2786 Also this plugin comes in three flavours, but you can often only
2787 load one of them:
2788
2789 "appendonly" - Really allows just additions to be made to the page,
2790 each new separated by a horizontal bar.
2791
2792 "appendwrite" - Allows to insert a page separator, which protects
2793 the upper part from getting edited by ordinary
2794 users. Everything below a horizontal bar (denoted
2795 by at least 16 minus signs) or a double horizontal
2796 bar remains editable by all users.
2797 This plugin activates only if the _APPENDONLY and
2798 _WRITEABLE flag is set.
2799
2800 "appendcomments" - stores page additions in an separate database
2801 entry marked with _DB_F_PART, but allows this part
2802 to get edited as whole (like "appendwrite" plugin).
2803
2804 The last one is probably not very useful, as it generates some
2805 overhead and in fact is a collection of various workarounds to
2806 accomplish the desired functionality (so it may prove little
2807 lifetime).
2808
2809
2810
2811 plugins/feature/imgresize_gd
14a960ac 2812 ����������������������������
39fcb981 2813 Was extracted from the core during the R1.00f development releases.
2814 Automatically rescales uploaded images, if they are larger than
2815 EWIKI_IMAGE_MAXSIZE.
2816 As it uses the gd2 library, there must be support for this in your
2817 PHP binary. There are a lot of problems on Win32 systems, and also
2818 some Linux binarys (-dev ones) crash constantly if you load this
2819 plugin but don't have the libgd activated or available.
2820
2821
2822
2823 plugins/feature/imgresize_magick
14a960ac 2824 ��������������������������������
39fcb981 2825 Rescales uploaded images via the ImageMagick utility "mogrify",
2826 which is usually only available on UNIX systems. It should however
2827 be fairly simple to make this plugin work with some other image
2828 manipulation tool (at least with Linux).
2829
2830
2831
2832 plugins/feature/spellcheck
14a960ac 2833 ��������������������������
39fcb981 2834 Turns the [preview] button below every page edit box into a
2835 spellcheck function.
2836
2837 You need a working 'aspell' or 'ispell' on your system, or the
2838 PHP internal aspell functions - as it is rather slow it only shows
2839 up the first 20 errors on a page
2840
2841
2842
2843action/ plugins
14a960ac 2844���������������
39fcb981 2845Action plugins are those, that can be activated ON individual pages. And
2846usually are shown as links below a page. The ewiki-builtin EditThisPage,
2847BackLinks and PageInfo are ["action"] plugins for example.
2848
2849
2850
2851 plugins/action/diff
14a960ac 2852 �������������������
39fcb981 2853 Enables to view the differences between two saved page versions
2854 (what changes somebody has done to the page), but it is rather
2855 stupid and guessworking in how it does so.
14a960ac 2856
39fcb981 2857
2858
2859 plugins/action/translation
14a960ac 2860 ��������������������������
39fcb981 2861 This plugin adds a link to the GoogleLanguageTools or AltaVista
2862 BabelFish, which then remotely translated the current page into
2863 the users preferred language. It has support to detect the lang
2864 of the current pages content, to redirect to the right service.
2865
2866
2867
2868 plugins/like_pages
14a960ac 2869 ������������������
39fcb981 2870 LikePages is a search feature of WardsWiki, which scans for
2871 WikiPages whose name is somewhat similar to the one of the current
2872 page (the pagename must be made up of the same WikiWordParts so a
2873 page gets listed).
2874
2875
2876
2877 plugins/action/raw
14a960ac 2878 ������������������
39fcb981 2879 Can be used to download the unrendered Wiki source of a page.
2880
2881
2882
2883plugins related to hypertext links
14a960ac 2884����������������������������������
39fcb981 2885The linking/ plugin group deals with how links inside the Wiki will look and
2886work. Some of them are would also fall the "core enhancements" group, while
2887others are just handy or for link beatification.
2888
2889
2890
2891 plugins/linking/tcn
14a960ac 2892 �������������������
39fcb981 2893 ewiki evaluates the Accept-Language HTTP header modern browser
2894 send with each request. This plugin now automatically brings up
2895 a variant of the current requested page if it finds a match in
2896 the database. To make it work, you need to create pages with
2897 language suffixes in their names like:
2898 ThisPage.es
2899 ThisPage
2900 ThisPage.de
2901 or
2902 OtherPage
2903 OtherPage*nl
2904
2905 Note, that there can always be one page in each name group without
2906 that suffix. This page then will be assumed to be in the default
2907 language set by EWIKI_DEFAULT_LANG.
2908
2909 If multiple page versions are available, then a list will be
2910 printed above the page title to allow users to override the
2911 prefered language guess of this plugin.
2912
2913
2914
2915 plugins/linking/plural
14a960ac 2916 ����������������������
39fcb981 2917 This plugin tries to alias plural and singular page names against
2918 each other. That is, "WikiPage" will be shown, whenever "WikiPages"
2919 was requested (and vice versa).
2920
2921
2922
2923 plugins/linking/autolinking
14a960ac 2924 ���������������������������
39fcb981 2925 The autolinking plugin allows to have automatic links inside the
2926 Wiki for words which exist in the database, but are no real
2927 WikiWords. This is made possible by the companion StaticPage
2928 admin plugin "spages/Admin/PrepareAutolinking", which must be
2929 invoked from time to time to update the db cache entry, which the
2930 autolinking plugin utilizes.
2931
2932
2933
2934 plugins/linking/link_css
14a960ac 2935 ������������������������
39fcb981 2936 Adds CSS classes to the links generated by the Wiki page formatting
2937 kernel, which then allow you to colorize (or to otherwise change
2938 appearance of links) via a style sheet.
2939
2940
2941
2942 plugins/linking/link_icons
14a960ac 2943 ��������������������������
39fcb981 2944 The link_icons plugin prepends icon <img>s before registered link
2945 types, like the link_css plugin adds class="..." attributes to the
2946 html formatted links in every page.
2947
2948
2949
2950 plugins/linking/link_target_blank
14a960ac 2951 ���������������������������������
39fcb981 2952 Adds 'target="blank"' to link tags <a>, which will result in most
2953 browsers opening pages in a new window.
2954
2955
2956
2957 plugins/linking/linkexcerpts
14a960ac 2958 ����������������������������
39fcb981 2959 Adds a short preview text (with <a title="...">) to every link of
2960 a page. This however requires multiple additonal database accesses
2961 (slower) and could enlarge delivered .html page sizes dramatically.
2962
2963
2964
2965 plugins/linking/linkdatabase
14a960ac 2966 ����������������������������
39fcb981 2967 Is a page plugin, which provides a nearly compliant implementation
2968 of the page and link structure export function known from the UseMod
2969 WikiWare and MeatBall:LinkDatabase. This is useful for contributing
2970 to the upcoming InterWikiBatabase and BorgWiki.
2971
2972
2973
2974 plugins/linking/instanturls
14a960ac 2975 ���������������������������
39fcb981 2976 Allows to specify URL abbreviations on one or more summary pages.
2977 This can be done using a table or a definition list to assign
2978 each URL a title, which then can be used on other pages as square
2979 bracket reference.
2980
2981 The 'instanturl_find' plugin in addition allows to use the [find:]
2982 moniker to perform partial searches in the list of URL
2983 abbreviations, but also in the list of interwiki monikers. As
2984 fallback it searches for matching page names or redirects to
2985 Google.
2986
2987
2988
2989 plugins/linking/titlefix
14a960ac 2990 ������������������������
39fcb981 2991 Allows to swap [title|PageName] in square brackers [Page|title],
2992 because that can easily be detected, if the page already exists.
2993
2994
2995
2996 plugins/interwiki/intermap
14a960ac 2997 ��������������������������
39fcb981 2998 This plugin (in fact only a general include) extends the list of
2999 known InterWiki: prefixes with a more complete set merged from
3000 MoinMoin and PhpWiki's interwiki.map. The links are rather
3001 untested to work at the moment.
3002
3003
3004
3005
3006appearance/ tweaks
14a960ac 3007������������������
39fcb981 3008There are various plugin hooks within ewiki, which allow to mangle text
3009strings and data immediately before it would be returned as output.
3010
3011
3012
3013 plugins/appearance/listpages_br
14a960ac 3014 �������������������������������
39fcb981 3015 This plugin will produce <br> separated lists (for SearchPages,
3016 PageIndex, MostVisitedPages, and so on).
3017
3018
3019
3020 plugins/appearance/listpages_ul
14a960ac 3021 �������������������������������
39fcb981 3022 Creates real <ul> lists (WordIndex, CreatedPages, ...) instead of
3023 the &middot; ones, ewiki core would usually return.
3024
3025
3026
3027 plugins/listpages_tbl
14a960ac 3028 ���������������������
39fcb981 3029 The listpages_tbl plugin outputs a table instead of the ordinary
3030 page lists (PageIndex, UpdatedPages, ...). You need to edit its
3031 source to set colours to fit your site layout.
3032
3033
3034
3035 plugins/appearance/fancy_list_dict
14a960ac 3036 ����������������������������������
39fcb981 3037 The WordIndex and PageIndex plugins (unlike the other page list
3038 returning ones like SearchPages and UpdatedPages) can utlize this
3039 plugin to output a pretty dictionary like listing of pages.
3040
3041
3042
3043 plugins/appearance/title_calendar
14a960ac 3044 ���������������������������������
39fcb981 3045 Changes the titles of calendar plugin entries in the database into
3046 a more readable format for page lists (PageIndex, PowerSearch,
3047 UpdatedPages, and so on).
3048
3049
3050
3051page plugins
14a960ac 3052������������
39fcb981 3053The page plugins provide additional "generated/internal" pages, which have
3054a standard WikiWordPageName and can thus be referenced easily from within
3055ordingary WikiPages. But they are of course uneditable (because their
3056content is 'hardcoded' as PHP code) and most action/ plugins cannot perform
3057any function on them.
3058
3059With the rise of the StaticPages plugin, the page plugins are almost
3060outdated, because all their code could now be extracted into a StaticPage
3061file, so their code had to be loaded only on request (instead of including()
3062them regardless if they're needed or not, how it currently is done).
3063
3064
3065
3066 plugins/page/powersearch
14a960ac 3067 ������������������������
39fcb981 3068 This plugins provides a (probably) better search function
3069 with the default page name "PowerSearch". It tries to guess
3070 a value, which tells something about how good a page matches
3071 the searched words and orders the found pages list by this
3072 (possibly not very useful) value. It prints the top 10 results
3073 more verbose.
3074
3075
3076
3077 plugins/page/pageindex
14a960ac 3078 ����������������������
39fcb981 3079 Lists all pages found in the database alphabetically.
3080
3081
3082
3083 plugins/page/wordindex
14a960ac 3084 ����������������������
39fcb981 3085 Lists the word parts of all wiki pages, but requires the
3086 powersearch plugin to be present, because the result is redirected
3087 to there as usually many of the listed words belong to multiple
3088 page names.
3089
3090
3091
3092 plugins/page/imagegallery
14a960ac 3093 �������������������������
39fcb981 3094 Outputs a page containing all cached/uploaded images. The
3095 images are currently not rescaled to fit on the page; this
3096 work is left to the browser.
3097 Needs enhancement.
3098
3099
3100
3101 plugins/page/aboutplugins
14a960ac 3102 �������������������������
39fcb981 3103 Lists all registered plugins (mpi, page, action, task/core). The
3104 name refers to the "about:plugins" page present in recent browsers.
14a960ac 3105
39fcb981 3106
3107
3108 plugins/page/orphanedpages
14a960ac 3109 ��������������������������
39fcb981 3110 Shows up a list of pages, that exist, but are not linked from any
3111 other pages. These is often also called dead pages.
3112
3113 Note that this plugin does not take into account, if any page
3114 can be reached from the frontpage - such a hypertext tree test
3115 would require much more work than realized in here.
3116
3117
3118
3119 plugins/page/wantedpages
14a960ac 3120 ������������������������
39fcb981 3121 Returns a list of pages to which QuestionMarkLinks? currently
3122 exist.
3123
3124
3125
3126 plugins/page/since_updates
14a960ac 3127 ��������������������������
39fcb981 3128 Provides a list of pages with actualization times.
3129
3130
3131
3132 plugins/page/textupload
14a960ac 3133 �����������������������
39fcb981 3134 The virtual TextUpload plugin allows to insert new WikiPages by
3135 uploading text files. It can convert from various formats into Wiki
3136 content, including some proprietary Office file formats, if one of
3137 the possibile filters is avaiable (Unix style file piping).
3138 It also can extract multiple files from a Tarball or ZIP archive
3139 if the according utilities are available (even on DOS/Win systems).
3140
3141
3142
3143 plugins/page/wikidump
14a960ac 3144 ���������������������
39fcb981 3145 Allows to download a gzipped tarball containing all readily
3146 rendered pages as .html files and also images.
3147
3148
3149
3150 plugins/page/interwikimap
14a960ac 3151 �������������������������
39fcb981 3152 Shows up the currently in use InterWikiMap.
3153
3154
3155
3156 plugins/page/hitcounter
14a960ac 3157 �����������������������
39fcb981 3158 Sums up the individual {hits} count of all pages and returns the
3159 overall count.
3160
3161
3162
3163 plugins/page/scandisk
14a960ac 3164 ���������������������
39fcb981 3165 Presents an unserious statistic.
3166
3167
3168
3169 plugins/page/wikinews
14a960ac 3170 ���������������������
39fcb981 3171 Returns the most recently added pages in an overview, that
3172 incorporates a small fragment from the content of those newly added
3173 pages.
3174
3175
3176
3177 plugins/page/wikiuserlogin
14a960ac 3178 ��������������������������
39fcb981 3179 Allows to set a free-form username, which then would be stored into
3180 the database whenever a page was edited.
3181
3182
3183
3184 plugins/page/randompage
14a960ac 3185 �����������������������
39fcb981 3186 Shows up a randomly choosen page from the database.
3187
3188
3189
3190 plugins/page/fortune
14a960ac 3191 ��������������������
39fcb981 3192 Calls the Unix /usr/games/fortune program and prints out returned
3193 content.
3194
3195
3196
3197 plugins/page/ewikilog
14a960ac 3198 ���������������������
39fcb981 3199 Allows to review the content of the 'ewiki.log' file.
3200
3201
3202
3203 plugins/page/phpinfo
14a960ac 3204 ��������������������
39fcb981 3205 Shows the settings of your PHP interpreter.
3206
3207
3208
3209 plugins/page/README
14a960ac 3210 �������������������
39fcb981 3211 Can parse the distributed README file and make a hypertext
3212 presentation from it, for easier reading of the Wiki documentation.
3213 It is printed in <pre> text, but with WikiLinking enabled (which
3214 however is rarely used in the README file). It additionally
3215 presents the README.de and README.auth files.
3216
3217
3218
3219 plugins/page/wikiuserlogin
14a960ac 3220 ��������������������������
39fcb981 3221 Allows to post a username (Note: this one does not do any sort of
3222 real authentication), which is saved in the http client as cookie,
3223 but can afterwards be evaluated as $ewiki_author, so the according
3224 field in the database entries contains a bit more than just
3225 the IP address when a changed page gets saved.
14a960ac 3226
39fcb981 3227
3228
3229markup plugins
14a960ac 3230��������������
39fcb981 3231The ewiki rendering core is rather fast and consolidated, that was the goal.
3232However if you ever happen to need more functionality, this can be added
3233easily by the use of plugins.
3234
3235Several are already available to emulate the WikiMarkup of other commonly
3236used WikiWare.
3237
3238
3239
3240 Other WikiWares markup
14a960ac 3241 ����������������������
39fcb981 3242 The WikiWorld still lacks a unified markup (and thus also the
3243 interchangeablity that made html THE standard it today is), and
3244 while ewiki usues nearly MeatBall:WikiMarkupStandard, you may want
3245 to reuse existing pages from another Wiki.
3246
3247 Currently we provide emulation for:
3248 * PhpWiki
3249 * sfWiki
3250 * miki
3251 * bbcode (BulletinBoard, not a Wiki)
3252
3253 But please see the individual files on which (additional) markup
3254 they introduce.
3255
3256 These plugins on occasion only register their markup within
3257 $ewiki_config["wm_*"] settings, but often just perfrom
3258 pre-conversion of foreign markup by utilizing the ["format_src"]
3259 plugin hook (they then pre-convert page content to use ewiki
3260 markup rules before the ewiki_format() kernel performs
3261 transformation).
3262
3263
3264
3265 plugins/markup/css
14a960ac 3266 ������������������
39fcb981 3267 CSS markup allows you to assign visual styles (or semantic CSS
3268 class names) to a block of text (paragraph) or to pieces of text.
3269 @@ is used to start a styled area. The @@ must be immediately
3270 followed by either a CSS class name (without the dot) or with
3271 CSS instructions without any whitespaces.
3272 The following text (after the @@, the class name and a space) will
3273 then be assigned the class until a (possible) next @@ without
3274 attached classname or style definition.
3275
3276 If the @@ occurs at the start of a paragraph it will enclose it
3277 in a <div> with the according style assignment, otherwise (in the
3278 text) a @@ will become a <span>.
3279
3280 See also the explanation and examples in this plugins` comments.
3281
3282
3283
3284 plugins/markup/css_singleat
14a960ac 3285 ���������������������������
39fcb981 3286 This plugin allows you (like the markup_css plugin) to attach CSS
3287 classes to a paragraph of text with just a single @ character:
3288
3289 @JAVADOCLIKE paragraphs text...
3290 ... ... ... .... ... ... ... ...
3291
3292
3293
3294 plugins/markup/footnotes
14a960ac 3295 ������������������������
39fcb981 3296 Introduces the ability to generate footnotes by placing an
3297 explanation into double curly brackets {{footnote text}}.
3298
3299 You should activate this only if you really need it. Sometimes this
3300 may be useful, but it is rather bad wiki style; because if someone
3301 would like to explain something in more detail he should create a
3302 WikiLink to a new page. So this should be used for very short
3303 explanations, say incomplete sentences or a book reference and
3304 other things where it really seems bloat to create a new page.
3305
3306 USE THIS RARELY or better not at all!
3307 (this is a feature copied from MS` EvilWiki)
3308
3309
3310
3311 plugins/markup/asciitbl
14a960ac 3312 �����������������������
39fcb981 3313 Allows to use ASCII-Art tables as outputed by lynx and other
3314 console programs inside of WikiPages, which eases life, when
3315 dealing with multiline table cell content.
3316
3317
3318
3319 plugins/markup_complextbl
14a960ac 3320 �������������������������
39fcb981 3321 ewiki allows you to use tables with the || | characters in the wiki
3322 page source. However the html code for the table layout is
3323 hardcoded and cannot be changed on a per-page basis.
3324 This plugin intercepts the wiki source formation process to allow
3325 you to specify html tag attributes inside a table definition like:
3326
3327 |{ border=0 cellspacing=10} here is | the table | content |
3328 | 2nd line | 2nd line |{ rowspan=2} fills two table rows |
3329 |{ colspan=2} 3rd line |
3330
3331 Note, the opening "{" must follow the "|" character immediately.
3332
3333 This code was provided by Hans B Pufal.
3334
3335 It may be a security risk to include it per default, as this allows
3336 to add SomethingScript references as well.
3337
3338
3339
3340 plugins/markup/htmltbl
14a960ac 3341 ����������������������
39fcb981 3342 Provides a block escape to use the standard html <table> code
3343 instead of the limited pipe syntax provided by ewiki. It will parse
3344 for <tr> and <td> tags and strip any not registered attributes to
3345 defend against harm that could be caused by EvilScript additions.
3346
3347 The common html <table> syntax then allows easily to include
3348 multiline table cell content, which is nearly impossible (to edit)
3349 for the "|...|..|" table syntax.
3350
3351
3352
3353 plugins/markup_rescuehtml
14a960ac 3354 �������������������������
39fcb981 3355 Allows to use some 'safe' HTML tags within the WikiPage. This
3356 plugin replaces the previous EWIKI_RESCUE_HTML constant.
3357
3358 Note that those 'safe' HTML tags may also lead to some confusion,
3359 especially if you have a wiki about HTML, because then you cannot
3360 write text about the <STRONG> tag because it will actually always
3361 be interpolated as itself and not as the text string "<STRONG>".
3362
3363
3364
3365 plugins/contrib/rendering_phpwiki12
3366 -----------------------------------
3367 This is the rendering kernel of PhpWiki 1.2 which was made compatible
3368 with the ewiki function set.
3369 It may be useful to reuse old WikiPages, but anyhow most of its
3370 features are supported by the standard ewiki rendering kernel, so
3371 this is just a fun and proof-of-concept plugin.
3372 ..................................................................
3373 : The code of this module is covered by the GPL license, as it :
3374 : was copied verbatim from the PhpWiki project. :
14a960ac 3375 ������������������������������������������������������������������
39fcb981 3376
3377
3378
3379 plugins/rendering_null
3380 ----------------------
3381 If someone would like to use ewiki for a personal homepage, but
3382 prefers HTML over WikiSyntax, then this rendering core replacement
3383 may suit his needs. It allows HTML to be used, but still renders
3384 WikiWords into valid hyperlinks (a few other features from the
3385 original ewiki_format function are also supported, but you can
3386 strip even those).
3387
3388
3389
3390mpi
14a960ac 3391���
39fcb981 3392The so called "mpi" plugins can be embedded into pages, and produce their
3393output there. They are loaded on demand (only if it appears that they should
3394be invoked), but it is possible to include() the individual files regardless
3395if they would be used or not.
3396
3397In order to have the mpi plugins available, you must however first load the
3398mpi dispatcher:
3399 include("plugins/mpi/mpi.php");
3400Which then takes care of the markup and loading of the requested plugins.
3401
3402The syntax for calling a mpi plugin is (write this inside of a WikiPage,
3403when editing it):
3404
3405 <?plugin PluginName arg="..." arg2=DDD ?>
3406
3407Where args are often optional or could even be written without the 'argname='
3408if only one was required. The name of the mpi plugin is case-insensitive
3409here.
3410
3411It is often possible to invoke mpi plugins like ["page"] plugins, if you
3412create a link inside of the page using the syntax <?plugin-link PluginName ?>
3413
3414
3415
3416 mpi_backlinks
14a960ac 3417 �������������
39fcb981 3418 Prints a list of BackLinks to the current page (the same as when
3419 clicking on the title of a page or on the BackLinks action link).
3420 <?plugin BackLinks ?>
3421 <?plugin BackLinks page=ForThatPage ?>
3422
3423
3424
3425 mpi_multimedia
14a960ac 3426 ��������������
39fcb981 3427 Allows to <embed> multimedia files into a page.
3428
3429
3430
3431 mpi_syndicate
14a960ac 3432 �������������
39fcb981 3433 Embeds remote RSS feeds (abbrv. for "ReallySimpleSyndication" or
3434 "RichSiteSummary") into the current page. It caches the fetched
3435 data for quite some time in a pre-parsed _BINARY database entry.
3436
3437
3438
3439 mpi_insert
14a960ac 3440 ����������
39fcb981 3441 Allows to insert another readily rendered WikiPage into the current
3442 one, usually inside of a <table border="1">.
3443
3444
3445
3446 mpi_localsitemap
14a960ac 3447 ����������������
39fcb981 3448 Is a mix of BackLinks and LinkTree features, and prints the tree of
3449 pages backreferencing to the current one.
3450
3451
3452
3453visual extensions
14a960ac 3454�����������������
39fcb981 3455The hook following plugins utilize is called "append-view". It allows to put
3456content below a pages contents (after the action links).
3457
3458
3459
3460 plugins/aview/backlinks
14a960ac 3461 �����������������������
39fcb981 3462 Adds the list of BackLinks (references from others to the current
3463 page) to the current page below it (this list is also available,
3464 when a user clicks on the title of a page).
3465
3466
3467
3468 plugins/aview/linktree
14a960ac 3469 ����������������������
39fcb981 3470 Prints the possible (shortest) paths to the FrontPage (determined
3471 by the EWIKI_PAGE_INDEX constant) starting from the current one
3472 below. Calculations and database access required by this plugin
3473 often means a slowdown up to 2 seconds before the page is readily
3474 rendered.
3475
3476
3477
3478 plugins/aview/toc
14a960ac 3479 �����������������
39fcb981 3480 Analyzes a pages headlines and generates a list of contents box
3481 from it, which is inserted as float box on top of it then. Use the
3482 following CSS selector to style it:
3483
14a960ac 3484 .wiki .page-toc {
39fcb981 3485 ...
3486 }
3487
3488
3489
3490 plugins/aview/posts
14a960ac 3491 �������������������
39fcb981 3492 Allows to add separate comment pages, which will then always be
3493 displayed below the current one, but remain editable as standalone
3494 pages. (So the page they are appended to could be marked as
3495 _READONLY).
3496
14a960ac 3497
39fcb981 3498
3499 plugins/aview/threads
14a960ac 3500 ���������������������
39fcb981 3501 Allows to group the pages created using the "posts" plugin into
3502 threads.
3503
3504
3505
3506 plugins/aview/subpages
14a960ac 3507 ����������������������
39fcb981 3508 Adds the list of pages, which appear to be SubPages of the current
3509 one, below it.
3510
3511
3512
3513 plugins/aview/downloads
14a960ac 3514 �����������������������
39fcb981 3515 Shows the uploaded files, which appear to belong to the current
3516 page (individual pages can be treated as upload sections).
3517
3518
3519
3520 plugins/aview/imgappend
14a960ac 3521 �����������������������
39fcb981 3522 Prints an image uploading box below every page, which allows to
3523 append an image without prior clicking EditThisPage (the image
3524 will be automatically appended to the bottom of the page).
3525
3526
3527
3528 plugins/aview/piclogocntrl
14a960ac 3529 ��������������������������
39fcb981 3530 This plugin allows users to select a logo graphic which will be
3531 made available for use in the site template as
3532 $ewiki_config["page_logo"]. Configureable through the internal
3533 image list array.
3534
3535
3536
3537 plugins/aview/aedit_pageimage
14a960ac 3538 �����������������������������
39fcb981 3539 This plugin allows users to select a page image graphic, and is a
3540 mix of the aview/piclogocntrl and page/imagegallery plugins.
14a960ac 3541
39fcb981 3542
3543
3544 plugins/aview/control2
14a960ac 3545 ����������������������
39fcb981 3546 Shows examplarily how to replace the standard "action-links" box,
3547 and adds it on top of the page (including the page title).
3548
3549
3550
3551 plugins/aview/aedit_authorname
14a960ac 3552 ������������������������������
39fcb981 3553 Adds a text <input> field below the edit/ box, which allows to
3554 set the AuthorName which then will get stored, when the page is
3555 saved. This name is then also stored client-side as cookie for
3556 at least 45 minutes.
3557
3558 Before using this plugin, you must consider, that it eventually
3559 allows to override the correct username that ProtectedMode plugins
3560 already provided. And there is no way to prevent users from using
3561 faked names (because this plugin cannot check if a username was
3562 already 'registered' and thus can't initiate a password query).
3563
3564
3565
3566 plugins/aview/aedit_deletebutton.js
14a960ac 3567 �����������������������������������
39fcb981 3568 Adds a JavsScript snippet to allow users to quickly mark a page
3569 for deleterequest, by inserting the link to "DeleteMe" into the
3570 contents, when editing it.
3571
3572
3573
3574page filters
14a960ac 3575������������
39fcb981 3576A few plugin hooks exist to completely rework generate page output. These
3577are often used to insert content into the otherwise readily rendered .html
3578pages (some of the above aview plugins do so, too).
3579
3580
3581
3582 plugins/filter/f_fixhtml
14a960ac 3583 ������������������������
39fcb981 3584 Is a minimal tag balancer (a highly simplified HTML tidy) and can
3585 work around various html code problems that the ewiki_format()
3586 html rendering function has. It is for example specialized to
3587 correct broken html that resulted from WikiMarkupAbuse as for
3588 example nesting text style attributes like this: __''text__''
3589
3590
3591
3592 plugins/filter/search_highlight
14a960ac 3593 �������������������������������
39fcb981 3594 Evaluates the Referer header sent by many browsers to detect if
3595 a visitor came from a search engine (even the internal PowerSearch
3596 or SearchPages ones) and highlights the searched words in the
3597 current pages body (using CSS).
3598
3599
3600
3601 plugins/filter/fun_chef
14a960ac 3602 �����������������������
39fcb981 3603 Borg, Borg, Borg!
3604
3605
3606
3607 plugins/filter/fun_upsidedown
14a960ac 3608 �����������������������������
39fcb981 3609 Transforms a pages content using letter transformation to make
3610 them readibly from upside down with certain fonts. This however
3611 is a bit tricky for html pages and thus will always wrongly
3612 intermix sentence order.
3613
3614
3615
3616 plugins/filter/fun_wella
14a960ac 3617 ������������������������
39fcb981 3618 Adds a little CSS to make text swirrling on both sides.
3619
3620
3621
3622 plugins/filter/fun_screamomatic
14a960ac 3623 �������������������������������
39fcb981 3624 Detects if someone entered a FULL LINE OF YELLING into a page
3625 when editing it, and then sets a persistent cookie. That cookie
3626 will result in all pages contents to be converted into uppercase
3627 characters.
3628
3629
3630
3631 plugins/filter/f_msiepng
14a960ac 3632 ������������������������
39fcb981 3633 Converts .png <img> references in the WhateverX code required by
14a960ac 3634 all current IE versions to display .png images according to the
39fcb981 3635 specification (which currently only an IE external plugin can handle
3636 correctly).
3637
3638
3639
3640BloatWiki extensions
14a960ac 3641��������������������
39fcb981 3642ewiki slowly evolves into a well-bloated portal software, and some plugins
3643already extend it far beyond the scope of an ordinary Wiki.
3644
3645
3646
3647 plugins/module/calendar
14a960ac 3648 �����������������������