2 ewiki code fragments/ and tools/
3 ================================
5 Unlike the plugins/ the code snippets and asorted data files in fragments/
6 can be included() directly into yoursite.php and are sometimes also
7 unspecific to ewiki. And the init-pages/ for example are required only once
8 and can be removed after initialization.
9 The tools/ is a separate bundle of administration tools for the ewiki
10 database. They are separate from the main Wiki (even comes with a different
11 'config.php') to enhance safety and reliability.
15 1.1 strip_wonderful_slashes.php
16 1.2 strike_register_globals
23 1.9 fragments/blocks/*
24 1.a fragments/patches/*
25 1.b fragments/php-patches/*
32 2.6 tools/t_textinsert
41 3.5 tools/mkpageplugin
45 4.1 examples/homepage.php
46 5 Pages in init-pages/
51 -------------------------------------------------------------------- 7 --
58 This directory holds some files to integrate ewiki.php within some
59 other web projects (for example PhpNuke) or some helper and extension
60 code, but even data files, code patches.
62 Most stuff is grouped into subdirs:
64 blocks/ plugin extractions to get included() somewhere into yoursite
65 (onto left or right side, like in one of those portal scripts)
66 head/ also output html snippets, for inclusion into the html <head>
68 css/ for sample .css files and per-page .css definitions (for use
69 with 'fragments/css.php')
70 funcs/ code snippets of varying usefulness
71 parent-cms/ samples on how to integrate ewiki into CMS or portal scripts
72 patches/ code/feature tweaks
73 php-patches/ PHP interpreter bugfixes
74 ./ assorted stuff, described below:
78 strip_wonderful_slashes.php
79 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
80 If you have a PHP 4.1 or a provider using the annoying factory-default
81 settings of such a version, you may find this tiny script helpful.
82 It removes the just-for-security-reasons-added-backslashes from the
83 $_REQUEST variables. I wasn't very interested in adding hundreds of
84 stripslashes() calls inside ewiki.php, so this is the workaround for
85 __your__ providers broken php.ini
87 It does not hurt a well configured PHP interpreter setup.
89 Newer ewiki versions come with a "plugins/lib/fix.php", which does
90 basically the same, but also incorporates:
94 strike_register_globals
95 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
96 Tries to secure the $GLOBALS environment for PHP setups with the
97 register_globals still turned on (which is a bad thing!).
103 Simple example on how to use "ErrorDocumet 404" rediriction to
104 activate the ewiki page search function automatically, which is the
105 poor mans mod_rewrite.
111 To make a Wiki installation look more profession you should try to
112 use your Webservers mod_rewrite module to get nicer looking URLs.
113 This file is an example to be installed as ".htaccess" (Web server
114 per-directory configuration file), which allows to call your ewiki
115 wrapper using URLs like:
117 http://www.example.de/wiki/SomePage
118 http://www.example.de/wiki/edit/OneOfThePages
120 (For this example, you needed to set EWIKI_SCRIPT to "/wiki/").
121 This example '.htaccess' script shows how to instruct mod_rewrite
122 to catch above URLs and to transform them into ".../index.php?id=Page"
123 again before calling the script.
127 Shows how to use mod_rewrite with ewiki.
129 * old style: http://www.example.com/wiki.php?page=WikiPage
130 * PATH_INFO: http://www.example.com/WikiPage
132 Remember to enable EWIKI_USE_PATH_INFO inside ewiki.php - this was
133 disabled once, because of the many broken Apache implementations (they
134 seem to support that broken CGI/1.1 specification, which was for good
135 reasons and luckily never blessed to become an official RFC).
141 If yoursite.php (ewiki wrapper) is not designed carefully enough
142 (=not binary safe, because <html> or text is written before the
143 ewiki.php core script got included) or EWIKI_SCRIPT_BINARY cannot be
144 set correctly, you may want to use this wrapper script to allow for
145 uploading and retrieval of binary content (images) via ewiki.
147 Copy it to where the main ewiki.php script is, and set the
148 EWIKI_SCRIPT_BINARY constant to the correct absolute position
149 (possibly including http://server.name/) of "binary.php". (this
150 constant must be set on top of ewiki.php)
152 You must set the database access params in here, too.
154 It may also be useful if you'd like to divide the database into its
155 two parts again - text content and binary content. You could even
156 let it save binary content in a flat file database, while WikiPages
163 Sample pre-config script for "de_DE" lang to preset the language
164 appearance of ewiki. If you just are too lazy to set up your
165 browser correctly, then this line usually fixes your language
168 $_SERVER["HTTP_ACCEPT_LANGUAGE"] = "de";
170 (must be written before ewiki.php gets included)
176 The funcs/ subdirectory contains code snippets, that provide
177 additional interface functions.
181 fragments/funcs/auth.php
182 ------------------------
183 Include this script wherever you need authentication. It
184 uses the HTTP Basic Authentication scheme, but the passwords
185 are inside the script in the $passwords array (so no need
186 for .htpasswd setup).
188 Note that this script needs to be called before any body
189 output is made (else it would be too late for http header()
194 fragments/funcs/wiki_format.inc
195 -------------------------------
196 This php include() file contains just the reduced
197 wiki_format() function, the code to generate internal
198 WikiLinks and the binary data stuff has been removed. It is
199 best suited to allow rendering of WikiSource with other php
202 The script was contributed by Frank Luithle.
208 Please understand the *.css as examples that illustrate which style
209 classes are defined inside ewiki.php and its companion plugins.
211 Remember, you could insert those files with PHPs` include(), too -
212 if desired (and if a <style> area is currently to be written to
215 The 'fragments/css.php' script can be included into yoursites`
216 page html <head> part and inserts all *.css files from this
217 directory which match the current page or action name. This allows
218 for restyling certain pages and helps in keeping a sites main
225 Contains small include() scripts to be loaded into "yoursite.php"
226 as "sidebars" and the like for beatification purposes.
227 Oftens these are reduced but useful ["page"] or ["action"] plugins,
228 performing common tasks, like printing the list of newest pages or
229 some sort of menu, or even random page links.
235 In the patches/ directory some code tweaking tips are collected
236 that are either not worth a new plugin or to uncommon and unsafe
237 and unsupported to get into fragments/ or plugins/. Please see the
238 README and the files therein for more informations.
242 fragments/php-patches/*
243 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
244 If bugs in the PHP language interpreter prevent running of ewiki
245 under certain versions, a patchfix will appear in the php-patches/
252 This directory holds some (external) add-ons, which are intended to
253 supply "admin functions" for the ewiki database.
254 It is strongly discouraged to integrate this with ewiki, as it could
255 be dangerous to have them always around and usually such stuff just
256 complicates things (wiki's should be easy to use).
258 Per default you will be presented a HTTP Basic AUTH login dialog box
259 by your browser if you try to use one of the www tools. This is made
260 to prevent other people from doing any harm to the setup.
261 In the "tools/t_config.php" script you'll see a link (include) to
262 "fragments/funcs/auth.php", which is responsible for this integrated
263 security feature. Just insert a username and a password here to start
264 using one of the tools/.
265 Please keep in mind, that the $passwords array of that ".../auth.php"
266 script has nothing to do with the _auth API or EWIKI_PROTECTED_MODE.
268 Because the www tools (all stuff named "t_*.php") use the "ewiki.php"
269 script and the sample "config.php", you eventually need to configure
270 these tools separately (they don't need any ewiki plugins, but the
271 database ones, if necessary). So if there are problems (for example
272 if your ewiki setup is configured with ewiki_auth, which then could
273 overlap with the ".../auth.php" script), you may need to edit the www
274 tools own "t_config.php" accordingly. (Note: This is not required for
277 If you'd like to integrate the tools/ as virtual pages into ewiki, then
278 the StaticPages plugin will help. You then needed to remove the line
279 that tries to re-include() your config.php and ewiki.php from the tools/
280 "t_config.php" script (else you'll break ewiki).
281 To load your tools/ as static pages into the wiki, you then just needed
282 a call to ewiki_init_spages() with the "./tools/" directory as parameter.
288 WikiPages usually have the page flag TEXT assigned. Other possible
289 flags are DISABLED, SYSTEM, BINARY or HTML, READONLY, WRITEABLE.
290 Usually page flags are copied from one page version to the next.
296 Use this to make backup files from the WikiPages. This www script
297 is a wrapper around the ewikictl commandline utility and library,
298 and therefore supports almost the same options.
304 Allows to reinsert the files generated with the backup utility into
305 the database. It is also a www wrapper around ewikictl and thus
306 also supports the "plain", "flat" and "fast" file formats.
312 Use this to delete a page from the database (including all saved
314 You should always prefer to set a page DISABLED with the ewiki_flags
315 tool to hide unwanted content. -- make love() not unlink()
321 If pages are edited often / regularly you will soon get hundreds of
322 saved page versions. As this slows down (particularly the
323 db_flat_file ones) and enlarges the database content size, you may
324 want to strip old versions.
326 This tool suggests you to remove a few page versions. You should
327 however NOT DELETE the page VERSION ONE and the very last (newest)
328 page version (of course).
329 The page version 1 often contains control data, not found in newer
330 versions, when db_flat_files or db_dba is used, so please keep
333 There were some changes necessary in db_flat_files to support
334 those "version holes", but it currently seems to work stable.
339 Can insert plain text files into the database. This is much the
340 same, what usually happens to the files inside init-pages/
346 Allows to download all pages in one big "binary" file, and to
347 reinsert it on the same way. This allows for quick moving of
348 the whole database content.
354 Can undo mass changes caused by a script attack (specifically
355 designed to spam or corrupt a Wiki) or someone who put enourmous
356 energy into garbaging multiple pages. The {auther} field always
357 contains at least an IP address to allow easy tracking of such
358 activity, and this plugin just enables you to remove page versions
359 whose {author} field matches a certain string (the attackers IP
366 If this page looks ugly, it is because you are using IE prior
367 version 7 - it works fine with Mozilla, Opera and even text-only
374 As opposed to the web based tools/ mentioned above, a few scripts in tools/
375 must be run from the commandline. That is, you need a standalone PHP
376 interpreter (/usr/local/bin/php) and shell access to your web server.
378 If you don't have shell access, you could write temporary wrapper scripts
379 (see the note for ewikictl), or use one of the emulation packages (or start
380 up a xterm on the server in absence of ssh access). A detailed description
381 is out of scope of this document.
383 UNIX users will find those tools very useful and handy, while they effort
384 additional work from Windows users. But then all those tools/ should run
385 on Win32 systems too, but you often want to create additional .bat files
386 to make this more user-friendly. There is for example a 'ewikictl.bat'
393 Using this console or X11 tool, you can create a custom "ewiki.ini"
394 or "config.php" script by choosing plugins and settings through a
395 nice interface. It even allows generation of a MonsterWiki script.
397 Works only under Linux. Read [doc/SetupTool] for more informations.
403 ewikictl integrates a lot functionality of the web based tools/,
404 some of them less flexible and others more powerful than in the
405 other tools. It, for example, allows to generate database backups
406 automatically and is often easier to use. On the other hand it
407 will be of little use if you don't have a shell account on the
408 WebServer running your wiki (because most times one cannot make
409 remote mysql server connections).
411 The most important feature is to make backups using the
414 All pages from the database will be saved into backup files
415 in the directory given by --dest (or if not given into
416 './backup-<currentdate>').
418 The --format of the backup files can be: plain, fast, flat
419 or xml, meta, xmlmeta, sql, mysql. But remember that only
420 the first three mentioned formats can be reinserted using the
423 You really should give the --all parameter too, whenever you
424 make a backup, because else only the very last version of each
425 page will get saved (and think of a garbaged last version, this
426 would be a bad idea). So USE --all ALLWAYS!
428 Backups can be reread into the database using the
431 The --dest or --source parameter says where to search for the
432 save page files, and the --format option again tells the
433 correct backup format (you will get a garbaged database if you
436 The --all option is of course necessary again if you gave it
437 when doing the --backup, and ewikictl will complain if it
438 believes the --all option was required.
440 You can also use --insert to initially fill a database, or to
441 add just a few new pages, as pages inside the database will
442 never be overwritten by the ones added with --insert.
444 The --insert switch also allows to be used to load just one
445 file into the database. --insert <WikiPageFileName>
447 Another function is to speed up the database, by creating version
450 If you utilize the db_flat_files and you have hundreds of
451 versions for one page, things may get slow at some point of
452 time, so you may wish to remove some of the unneeded versions.
453 That is what the --holes is for, it strips some of the page
454 versions from the database. Please keep in mind, that the
455 very first version of each page may contain special control
456 data, which is not available in the following ones (this is
457 especially true for db_flat_files).
459 Per default the 2nd version of a page until the 10th before
460 the last page version will be removed. You can however specify
462 --holes 2..-10 (default)
463 --holes 5..-5 (5th until 5th before last version)
465 Please also keep some versions at the end, as the very last
466 one may contain mangled text (if someone backspaced around).
468 The --all option is implied for --holes, but you can and you
469 should combine --holes also with --backup. This special
470 feature will save a backup into the --dest directory ('./holes'
471 per default) before the page version is removed from the
475 The default backup/insert format is the 'plain' one - which
476 means just a pages content will be saved into the files.
478 It is however recommended to use the "--format flat" or
479 "--format fast" instead, as both can contain the complete meta
483 Will print a directory-listing like list of all pages from
485 You can add a pagename as parameter, so only that one will
492 --readonly <pagename>
493 --writable <pagename>
494 Will set the according page flags for the given page. You can
495 give the page name also by using the --page or --file or --id
499 Will set the page flags to the given decimal value. The
500 pagename must be given using --page, --file or --id. This
501 option of course requires knowledge of the flag/option values
502 and their numeric/decimal representations.
504 --unlink <filepattern>
505 Can be used to delete a page. You can use the asterisk to
506 remove more than one page, just an '*' would for example delete
510 NOTE that you can also use this utility without a shell account on
511 your WebServer, if you create temporary .php wrapper scripts, that
512 contain nothing more than:
513 <pre><?php echo `./tools/ewikictl -ll`; ?></pre>
515 Please search google or freshmeat.net for one of those shell faking
516 CGI scripts, to ease this, so can get the most out of ewikictl.
522 Renders the WikiPages and saves the resulting <HTML> bodies into
523 files. It currently cannot deal with images and binary content
530 For lazy people - if for some reason your text editor does not
531 allow to enter the correct include() commands for the files from
532 the plugins/ directory you may find this shell script useful to
533 create a monster version of ewiki (plugins and core script merged
534 together into one file).
535 See the paragraph about "monsterwiki.php" for more detailed infos.
541 Is the companion tool for the new ewiki pluginloader extension. It
542 traverses the plugins/ directories and generates a list which
543 allows automatical loading of ["page"] and ["action"] plugins.
545 Use the output of this script to replace the list of available
546 plugins inside of the "pluginloader.php" script. But don't forget
547 to disable that extensions, that you wouldn't like to be available.
553 Can convert any StaticPage file (from the spages/ directory) into
554 a standard ewiki page plugin (to get included() like all the others
555 then). It detects automatically the type of the given StaticPage
556 input files - Wiki source (.txt), ready HTML content, or even PHP
558 It's intended as help for the unexperienced PHP user, or if you
559 needed to mass convert StaticPage files into plugins. But please
560 note, that including() hundreds of page plugins slows down the PHP
561 interpreter and eats a large amount of memory (and this was the
562 reason for extracting some page plugins into StaticPages).
568 The new .xpi plugins can be installed at runtime (password required),
569 if the plugins/feature/xpi extension is loaded. This type of plugins
570 however must be prepared first using the 'mkxpi' tool from their
573 A detailed description is available in the comment part of this
580 If you want to test ewiki with recent PHP5 beta versions, you
581 either need to apply the fragments/php-patches/ or mangle the ewiki
582 core script using the 'php5fix' commandline utility.
584 It adds a few explicit typecasts, where this is known to be
585 necessary to keep PHP5 versions happy.
591 Allows you to make a 'monsterplugin' script by analyzing your
592 config.php script. It will output a combination of all activated
593 plugins merged into one file, which you could afterwards glue
594 together with the core script to get a real monsterwiki script.
600 The file "examples-1.php" is the default layout, which you will see, when
601 you first run ewiki. The examples/ subdirectories now holds further example
602 'ewiki wrappers' or 'layout scripts' (commonly referred to as "yoursite.php"
603 scripts in the README).
605 There is not much further interesting stuff in here. If you can make a
606 contribution, just do (however, in the ewiki core tarball, we don't want
607 an image or graphics directory).
611 examples/homepage.php
612 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
613 This is an example on how to use ewiki.php with an authentication
614 frontend. Note that this is not the recommended way to use a wiki
615 (adding authentication can be considered "crippling" a wiki).
617 "Authentication" means just a JavaScript based password query
618 dialogue (the password is however checked server-side inside the
619 homepage.src script).
621 You should install it preferably as index.php as described on top
622 of the file, the ewiki.php script must be there too. Edit the source
623 and colours to suit your needs. Guess, it needs some images as well.
629 This directory just contains text files with the wiki_source of the
630 initial pages, which are inserted if you start ewiki.php for the
632 You can create these files with the tools/ewiki_backup.php script
633 or the 'ewikictl' commandline utility, what is very handy for backup
634 purposes or partial mirroring of all your content.
636 Using the "TextUpload" plugin/spage you can upgrade all of those
637 files that are already existing on your setup. You could also get
638 the latest tarball containing all default pages from
639 [http://ewiki.berlios.de/initpages/?MiniDump] to do so (TextUpload
640 can directly use that page tarball).
projects / atutor.git / blob