ErfurtWiki - a fast, user-friendly, highly configurable Wiki engine in PHP ========================================================================== README ŻŻŻŻŻŻ This is the documentation for ewiki. I tries to describe nearly everything, but therefore has now grown to long to be read at once. However it is often sufficient to just read the first few paragraphs to set it up (plugins can be activated at any later time). If you have the Wiki running, then you can also read this file in hypertext format. 1 What is this? 1.1 Why "ErfurtWiki"? 1.2 WikiAlternatives 1.3 Authors 1.4 Project pages 1.5 Obtaining support 1.6 License 1.7 Known Bugs 2 HowTo 2.1 Integration with yoursite.php 2.1.1 Creating a "config.php" 2.1.2 Generation of a "monsterwiki.php" script 2.1.3 What to do if images don't work 2.2 Supplying the WikiPageName 2.2.1 mod_rewrite or PATH_INFO 2.2.2 use with the 404 trick 2.3 Security considerations 2.3.1 PHP settings (register_globals) 2.3.2 _protected_mode 2.4 simple usage restrictions via wrappers 2.5 PhpWiki compatibility 2.5.1 Transition from another WikiWare 2.6 Idea Collection 2.6.1 Multiple Wikis / InterWiki feature abuse 3 Internals 3.1 the ewiki_ functions 3.2 $GLOBALS pollution 3.3 the EWIKI_ constants 3.4 $ewiki_config array 3.5 internal coding explained 3.5.1 how ewiki operates 3.5.2 used variables 4 Tweaking 4.1 Using the wiki source transformation only 4.2 Customizing ewiki_format() 4.3 Customization using CSS 4.3.1 user style classes in pages 4.3.2 rendered page content 4.3.3 pages enclosed in style classes 4.3.4 plugin output styling 5 Explanations 5.1 Binary and text support 5.1.1 Image uploading 5.1.2 Image caching 5.1.3 Image WikiMarkup 5.1.4 binary_store, direct access 5.1.5 Arbitrary binary content 5.2 $action and $id 5.2.1 ewiki URLs 6 Everything in one script 6.1 database plugins 6.1.1 MySQL support 6.1.2 plugins/db/flat_files (IMPORTANT) 6.1.3 plugins/db/fast_files 6.1.4 plugins/db/any 6.1.5 plugins/db/adodb 6.1.6 plugins/db/dba 6.1.7 plugins/db/phpwiki13 6.1.8 plugins/db/binary_store 6.2 core enhancements 6.2.1 plugins/patchsaving 6.2.2 plugins/notify 6.2.3 plugins/jump 6.2.4 plugins/email_protect 6.2.5 plugins/spages (StaticPages) 6.2.6 plugins/pluginloader 6.2.7 plugins/init 6.2.8 plugins/feature/appendonly.php 6.2.9 plugins/feature/imgresize_gd.php 6.2.A plugins/feature/imgresize_magick.php 6.2.B plugins/feature/spellcheck.php 6.3 action/ plugins 6.3.1 plugins/action/diff.php 6.3.2 plugins/action/translation.php 6.3.3 plugins/action/like_pages.php 6.3.4 plugins/action/raw.php 6.4 plugins related to hypertext links 6.4.1 plugins/linking/tcn 6.4.2 plugins/linking/plural 6.4.3 plugins/linking/autolinking 6.4.4 plugins/linking/link_css 6.4.5 plugins/linking/link_icons 6.4.6 plugins/linking/link_target_blank 6.4.7 plugins/linking/linkexcerpts 6.4.8 plugins/linking/linkdatabase 6.4.9 plugins/linking/instanturls 6.4.A plugins/linking/titlefix 6.4.B plugins/interwiki/intermap 6.5 appearance/ tweaks 6.5.1 plugins/appearance/listpages_br 6.5.2 plugins/appearance/listpages_ul 6.5.3 plugins/appearance/listpages_tbl 6.5.4 plugins/appearance/fancy_list_dict 6.5.5 plugins/appearance/title_calendar.php 6.6 page/ plugins 6.6.1 plugins/page/powersearch 6.6.2 plugins/page/pageindex 6.6.3 plugins/page/wordindex 6.6.4 plugins/page/imagegallery 6.6.5 plugins/page/aboutplugins 6.6.6 plugins/page/orphanedpages 6.6.7 plugins/page/wantedpages 6.6.8 plugins/page/since_updates 6.6.9 plugins/page/textupload 6.6.A plugins/page/wikidump 6.6.B plugins/page/interwikimap 6.6.C plugins/page/hitcounter 6.6.D plugins/page/scandisk 6.6.E plugins/page/wikinews 6.6.F plugins/page/wikiuserlogin 6.6.G plugins/page/randompage 6.6.H plugins/page/fortune 6.6.J plugins/page/ewikilog 6.6.J plugins/page/phpinfo 6.6.K plugins/page/README 6.7 markup/ plugins 6.7.1 Other WikiWares markup 6.7.2 plugins/markup/css 6.7.3 plugins/markup/css_singleat 6.7.4 plugins/markup/footnotes 6.7.5 plugins/markup/asciitbl 6.7.6 plugins/markup/complextbl 6.7.7 plugins/markup/htmltbl 6.7.8 plugins/markup/rescuehtml 6.7.9 plugins/markup/rendering_phpwiki12 6.7.A plugins/markup/rendering_null 6.8 mpi 6.8.1 mpi_backlinks 6.8.2 mpi_multimedia 6.8.3 mpi_syndicate 6.8.4 mpi_insert 6.8.5 mpi_localsitemap 6.9 visual extensions 6.9.1 plugins/aview/backlinks 6.9.2 plugins/aview/linktree 6.9.3 plugins/aview/toc 6.9.4 plugins/aview/posts 6.9.5 plugins/aview/threads 6.9.6 plugins/aview/subpages 6.9.7 plugins/aview/downloads 6.9.8 plugins/aview/imgappend 6.9.9 plugins/aview/piclogocntrl 6.9.A plugins/aview/aedit_pageimage 6.9.B plugins/aview/control2 6.9.C plugins/aview/aedit_authorname 6.9.D plugins/aview/aedit_deletebutton.js 6.A page filters 6.A.1 plugins/filter/f_fixhtml 6.A.2 plugins/filter/search_highlight 6.A.3 plugins/filter/fun_chef 6.A.4 plugins/filter/fun_upsidedown 6.A.5 plugins/filter/fun_wella 6.A.6 plugins/filter/fun_screamomatic 6.A.7 plugins/filter/f_msiepng B.9 BloatWiki extensions 6.B.1 plugins/module/calendar 6.B.2 plugins/module/downloads 6.B.3 plugins/module/tour 6.C utility code 6.C.1 plugins/lib/cache 6.C.2 plugins/lib/speed 6.C.3 plugins/lib/mime_magic 6.C.4 plugins/lib/navbar 6.C.5 plugins/lib/protmode 6.C.6 plugins/lib/save_storevars 6.D admin/ plugins 6.D.1 control 6.D.2 SearchAndReplace 6.D.3 SearchCache 6.E other plugins 6.E.1 plugins/debug/ 6.E.2 plugins/auth/ 6.E.3 plugins/auth-liveuser/ 6.F separate "extra" tarball 7 More separate files 7.1 Pages in init-pages/ 7.2 Additional tools/ (IMPORTANT) 7.2.1 tools/t_flags 7.2.2 tools/t_backup 7.2.3 tools/t_restore 7.2.4 tools/t_remove 7.2.5 tools/t_holes 7.2.6 tools/t_textinsert 7.2.7 tools/t_transfer 7.2.8 tools/t_revert 7.2.9 tools/ewikictl 7.2.A tools/wiki2html 7.2.B tools/mkhuge 7.2.C tools/mkpluginmap 7.2.D tools/mkpageplugin 7.3 examples/ 7.3.1 examples/homepage.php 7.4 Nice things in fragments/ 7.4.1 strip_wonderful_slashes.php (IMPORTANT) 7.4.2 strike_register_globals.php 7.4.3 404finder.php 7.4.4 htaccess 7.4.5 binary.php 7.5 fragments/funcs/* 7.5.1 fragments/funcs/wiki_format.inc 7.5.2 fragments/funcs/auth.php 7.6 fragments/css/* 7.7 fragments/blocks/* 7.8 fragments/patches/* 7.9 How to deal with tweaked code 8 Extension HowTo 8.1 the PlugInterface 8.2 plugin tasks 8.2.1 mpi plugins 8.2.2 authentication/permission plugins 8.3 writing your own plugin 8.4 format_* / rendering plugins 8.4.1 ewiki_format() internals 8.4.2 the format_ plugin hooks 8.4.3 $iii[] and $ooo[] block flags -------------------------------------------------------------------- 1 -- What is this? ŻŻŻŻŻŻŻŻŻŻŻŻŻ This is a WikiWikiWeb engine implemented in the PHP web scripting language. A WikiWiki is a web site which can be edited by everybody who visits it (most commonly without requiring that user to register before). It should allow easy integration into an existing web site (portal or homepage / CMS-like software), as it is more a library and does not output a full .html page but instead just the formatted wiki text for inclusion in your pages` body/content area. Why "ErfurtWiki"? ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ My home town (Btw, Erfurt is next to Weimar.de) and really that's just a name (you're allowed to rename, extend it and to finally ship it GPLifyed). You'll soon see the internal name is "ewiki", and it is also sometimes called 'EmbeddableWiki'. If you asked - Why you should I use it? - It is contained within a single file. It does not require 20 other files to lie around between your own scripts. - It does not impose a pre-defined layout, and you do not need to customize it either as it nicely integrates with your sites` layout. - I think it's rather fast. It uses regexs too, but most of the ewiki_format() uses the simple and quick string functions. - It got rather featureful, the final release seems near :) WikiAlternatives ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you don't like ewiki, then try at least one of these: * PhpWiki has a more complete approach than this WikiWare, get it from http://freshmeat.net/projects/phpwiki, it has support for different database types, features localization and comes with an integrated admin area. * WakkaWiki by Hendrik Mans is also a very powerful PHP implementation, see http://www.wakkawiki.com/ * Miki is another nice (small) implementation in PHP from Jukka Zitting. Get it from http://miki.sourceforge.net/ * Finally sfWiki - the sourceforge Wiki (therefore can be found on http://sfwiki.sourceforge.net/). Some of its wiki syntax looks a bit weird (other parts were inspiring), but it features complex user authentication. * coWiki - completely OOP and the source code layout is great; looks very featureful, but is more a CMS than a Wiki (authentication bloat) and has also a little weird markup, but better check it out yourself on http://cowiki.org/ * And of course there are Wikis in other scripting languages (and yes, there is still demand for an implementation in assembler or C !!) http://www.freshmeat.net/search/?q=wiki§ion=projects or just have a look at http://www.google.com/search?q=wiki * However, the BEST PLACE to look for evil concurrent implementations is http://c2.com/cgi/wiki?WikiEngines Authors ŻŻŻŻŻŻŻ current maintainer: Mario Salzer icq95596825 (+Yah,Jab) main contributor: Andy Fundinger from http://burgiss.com/ For the complete list of authors and contributors please see the CREDITS file. This project is still in an early stage, to improve it further we need to know what doesn't work or what could be enhanced. Every mail is a contribution (yep, that is not measured in lines of source code). Project Pages ŻŻŻŻŻŻŻŻŻŻŻŻŻ official freshmeat project page: - http://freshmeat.net/projects/ewiki demo site: - http://erfurtwiki.sourceforge.net/ newest versions (unstable development releases): - http://erfurtwiki.sourceforge.net/downloads/ mailing list archive - http://www.freelists.org/archives/ewiki/ Obtaining Support ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Getting support for problems with ewiki is possible, but please read this README first. The author is thankful for BugReports, and of course would like to know were this documentation is not detailed enough and fails to explain things clearly. However, before you send requests to anyone, please visit following site (this is necessary to get FREE support): http://www.catb.org/~esr/faqs/smart-questions.html Then please feel free to contact the author or leave notes on the BugReports or UserSuggestion pages on our project site. Joining our http://erfurtwiki.sourceforge.net/?MailingList would allow you to reach a larger audience for your questions (and you can unsubscribe as soon as your problems are solved). License ŻŻŻŻŻŻŻ This "program" is "distributed" as "Public Domain". Public Domain is like "FreeWare", but a bit more free ;-> You can think of it as the GPL without being bound to the GPL. I didn't want to include a LICENSE file larger than the program itself. As this is a free (beer) piece of software, you cannot make me responsible for any BUGS or all the REALLY BAD HARD DISK DAMAGES ;-P it may lead to. Additional note: a few plugins contain GPL code, and therefore must be downloaded separately (mime_magic.php, rendering_phpwiki12.php). Known Bugs ŻŻŻŻŻŻŻŻŻŻ Currently none. But this note is just here to encourage you to visit http://erfurtwiki.sourceforge.net/?BugReports -------------------------------------------------------------------- 2 -- HowTo ŻŻŻŻŻ the ewiki script requires: - Webserver (Apache, Nanoweb, ...) - PHP 4.1 or later - a SQL database (works faster if you have one) - your existing web site layout - older PHP's wonderful magic slashes should really be disabled If you don't have the database, there is an add-on for flat-file usage (search this document for "db_flat_files" for notes on how to get this running). Integration with yoursite.php ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ For the next few paragraphs the "yoursite.php" refers to whatever files and/or scripts belong to your already existing website. This hypothetical script should at least output the tags around the output from ewiki. The most simple script to accomplish this could look like this (see also example-2.php): [1] The first two commands open a connection to your MySQL database, usually one saves the result of mysql_connect() in a variable named $db or so, but as PHP does not depend on it if there is only one single database connection, it is not used in "ewiki.php" at all. [2] The define line tells ewiki about the hyperlinks it shall create. [3] The error_reporting(0) is highly encouraged (but something similar is already built into the ewiki.php script). [4] The include("ewiki.php") finally loads the ewiki "library" and sets any EWIKI_ constants that have not already been defined here. [5] The final call to the ewiki_page() function returns the wiki page which was requested by the browser. You must prepend it with "echo" because the ewiki_page() function just returns a enhanced string but does not output that one itself. Creating a "config.php" ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Instead of including the plain "ewiki.php" script as shown in the example above, many people may find it more useful to include() a more customized Wiki yoursite. Customization of ewiki takes place, by pre-defining() some of the EWIKI_ configuration settings and loading extension plugins. To not move that work and code into yoursite it is recommended to create some sort of "config.php" script, which then contained the various define() and include() commands. It is sometimes even senseful to establish the database connection (if you use SQL and not the flat_files backend) inside of such a config script, if there wasn't already established in yoursite. So such a config.php script could contain: - multiple define() commands, setting ewiki behaviour constants - include() comands to load extension plugins - evtl. some include() and define() for the db_flat_files plugin (if you don't have a SQL database) - and last but not least, the include("ewiki.php") script If you then include() such a config.php, you get a fully functional and preconfigured Wiki to include into yoursite. By using this approach, you still could override some of the EWIKI_ settings with additional define() constants right before the include("config.php"). Note: Please don't get confused by the path names, you of course needed to use a subdirectory specification like "ewiki/" before every filename specified in these include() commands, if this was the dir you put all the ewiki scripts. Generation of a "monsterwiki.php" script ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewiki over the time grow larger, and nowadays isn't anymore the single script it once was. The distribution ships with over hundreds of extension plugins. But nevertheless it is still possible to build a single script from it all! That being said, the "ewiki.php" script still implements a fully functional Wiki (and just only lacks the advanced features supplied the plugins). - You could still just include() the "ewiki.php" script into yoursite and delete everything else the ewiki tarball contained. However, it is also possible to MERGE all wanted plugins and the core script together to built a customized (feature enhanced) Wiki script from it. All you needed to do was: /unix/$ cat ewiki.php plugins/*.* > monsterwiki.php C:/dos/ type ewiki.php plugins/*.* > monsterwiki.php This way you'd get the "monsterwiki.php" file, which contained the ewiki core script plug all plugins - but of course, you should only copy the ones in, you really need and want (but not "*.*" all as shown in the example above)! The UNIX shell script "tools/mkhuge" will do exactly that for you; it accepts a parameter from 0 to 3, which will merge a custom set of useful plugins into the then generated "monsterwiki.php" script. If you have built a "monsterwiki.php" script, you can include() this instead of the minimal "ewiki.php" into yoursite to integrate a Wiki. Eventually you'd also want to merge some configuration settings into this monsterwiki script, so you wouldn't have to put the define(...) commands into yoursite.php before you include("monsterwiki.php"); The define() commands however need to be the very first part merged into that monsterwiki script, so it's best to edit the monsterscript after generation and insert the appropriate settings then at the very beginning. You could also merge a (reduced!) "config.php" into the script, using the above "cat" (or "type" for DOS/Win) method. But beware, that this "config.php" then does not contain any include() command; because else the resulting "monsterwiki.php" script would then try to load the "ewiki.php" core script and plugins which were probably already merged in. Even if you merge such a minimal config script at the start of this monsterwiki script, you still could override some settings (at least establishing the database connection) from within yoursite, if you think it's useful. Additional note: You could still include() plugins, if you included() such a monsterwiki script into yoursite, provided that the plugin you try to include() wasn't already merged into that monsterwiki.php script before (else it would crash the PHP interpreter, because loading it twice is once too much). StaticPages (read about "spages" plugin) can also be included, if you first convert them into ordinary ["page"] plugins using the 'mkpageplugin' commandline tool. What to do if images don't work ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The first example, as well as the "example-2.php" have problems with binary content, because: the is output before the 'ewiki.php' library was loaded and got the chance to output pictures. So one should better rewrite the above example yoursite.php script to: <?php echo $ewiki_title; ?> </HEAD> <BODY> <?php echo $content; ?> </BODY> </HTML> Please again, note the initial <?php part before the very first plain HTML output - yoursite.php must really start with it, or else binary content (uploaded images) won't work! You could, of course write a "binary.php" besides "yoursite.php", to get around this problem; please see fragments/ for an example. Supplying the WikiPageName ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you just call ewiki_page() as shown in the first example, it will try to get the name of the requested WikiPage either from the $_SERVER["PATH_INFO"] variable or from one of the GET-variables '?id=' or '?name=' or '?page=' or '?file=' (available as $_REQUEST["name"]). If yoursite.php however uses another way or another varname to receive the WikiPageName you can just give it as first parameter: ewiki_page( $id = "WikiPageName" ); example-4.php shows how this can be used to list a second WikiPage (the list of newest pages) somewhere else on yoursite.php. mod_rewrite or PATH_INFO ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you dedicate a complete directory for your wiki, you should keep in mind, that some of the generated URLs contain slashes (for example "edit/WikiPage"), and will look like subdirectories and thus confuse browsers. So you should either set EWIKI_SCRIPT to the absolute directory containing your wiki wrapper script: define(EWIKI_SCRIPT, "http://myserver/wiki/"); or else put a <BASE HREF="..."> into the generated pages. Take this precaution because some of the generated links contain additional slashes (like "edit/ThisPage") and thus may make browsers believe in a changed subdirectory. This applies to mod_rewrite usage and if you call your wiki wrapper with the page name as PATH_INFO (like "/wiki/index.php/WikiPage"). Do not forget to enable EWIKI_USE_PATH_INFO, as it is per default disabled for Apache servers! Also check, if EWIKI_URLENCODE and _URLDECODE suit your needs, else you will find it useful to have URL generation encapsulated in the ewiki_script() function. use with the 404 trick ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Once I implemented a way to run a web server below another one (actually Nanoweb below Apache, for more details see http://nanoweb.si.kz/), because the Apache on one of my providers servers was heavily misconfigured - so I handed work over to a secondary WebServer. This trick also works without mod_rewrite support, and is therefore also well suited for cheap WebSpace. Put following into the .htaccess of the dedicated wiki directory: #-- handle "not found" pages by ewiki ErrorDocument 404 /wiki/index.php DirectoryIndex 404 index.php This will allow the "yoursite.php/ewiki.php" script to catch all missed files, which would usually trigger a 404 error. Inside your ewiki wrapper script, you must then however decode the originally requested URL: $url = $_SERVER["REQUEST_URL"]; # Apache often uses this one $url = preg_replace("#^/wiki#", "", $url); # strip wiki subdir name $_SERVER["PATH_INFO"] = $url; # make ewiki see it The second step is very important, it strips the name of the dedicated subdirectory from the URL, which cannot be done inside ewiki.php. The $url from the above example could also be used as $id parameter to ewiki_page(). It should be noted, that some Apache implementations are garbaging POST requests in case of a triggered 404 error - but you can simply test this by saving a changed WikiPage. See also the "fragments/404finder.php" example on this. Do not forget to enable EWIKI_USE_PATH_INFO, as it is per default disabled for Apache servers! Security considerations ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewiki was developed using a PHP5 interpreter, but with limitations of PHP4.3 in mind. There are huge differences (a rather instable, bug-prone and still unfinished language) across the 4.x versions of PHP. The 4.0 series is not enough to run ewiki, you'll need at least a PHP 4.1 (4.07) to make it work reliable. One must also know, that there are also differences between the settings of providers. Some for example enforce users to run their scripts in so called "safe mode" (crippled mode) in place of real server security guidelines. Other still use pre-4.3 settings for the PHP interpreter (the Win4 php.ini still is outdated). So take care, and adjust settings using .htaccess` php_option for Apache servers. PHP settings (register_globals) ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Because ewiki was developed on later PHP versions (at least 4.3), it heavily uses the $_REQUEST array and assumes a deactivated "register_globals" setting in php.ini If this is not the case for your setup / WebServer. or with your provider the ewiki.php script may expose a lot security leaks (because of uninitialized variables). ewiki in general does only use a few global variables, but especially the $ewiki_ring variable (which is used for PROTECTED_MODE) can lead to problems, if you use it without an existing authentication concept. The $ewiki_plugins is also a very complex task, and I cannot safely state that it won't be able to produce exploits, if the variable is tweaked externally (pushed into by a client). So the best thing you could do is to disable register_globals (this can be done from inside a directories .htaccess file by inserting the line "php_option register_globals off"). A fragments/ include will be added to strike against variables which got set from outside (this is rather easy for variables used by ewiki, because their names all start with "$ewiki_"). The two modes of operation (_protected_mode and _flat_real_mode) ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ While this wiki was originally developed as a real wiki, many people use it for different things now, like private HomePages, easy CMS on commercial web sites. This fact lead to the support of a restricted operation mode, now known as the _PROTECTED_MODE. It is often used to require people to log in before they can edit pages or upload things. In this README this mode of operation will often be referred to also as the 'crippled mode'. It is completely optional, and doesn't have any impact on speed, when left disabled. Btw, the standard ewiki operation mode is now known as the _FLAT_REAL_MODE. If you'd like to use authentication, you'll probably want to chain some plugins which enable you to use the user database from yoursite.php, so you do not need a separate .htaccess or an additional relational database for passwords. Please see the section on auth plugins. See also the EWIKI_PROTECTED_MODE configuration constant and the separate "plugins/auth/README.auth" file for further and more detailed informations on this feature. simple usage restrictions via wrappers ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The easiest way to cripple a Wiki setup to be browseable-only for the larger public, and to allow only a small subset of users to edit pages is to write two wrapper scripts around the ewiki.php library. One of the wrapper scripts should include and use ewiki as described in the "Integration with yoursite.php" paragraph. You may want to move this wrapper script into a password protected subdirectory (say "/wikiadmin/index.php"). Another wrapper script should then be provided for the users that are only allowed to view pages. To disallow editing you'll just have to enrich it with commands like: unset($ewiki_plugins["action"]["edit"]); # disables editing unset($ewiki_plugins["action"]["info"]); # no info/ action unset($ewiki_plugins["page"]["SearchPages"]); # no search function unset($ewiki_plugins["action"]["view"]); # kill wiki completely This code must occur after you have 'included("ewiki.php");' the library, but before you call the 'ewiki_page();' function, so the unwanted actions and pages really do not get activated. So far the basic approach. If you however have real user authentication code behind the scenes you probably don't want to maintain two different wrapper scripts. You'll then just put the functionality stripping code from above into an if-clause in "yoursite.php" like: if (! $user_is_logged_in) { unset($ewiki_plugins["action"]); # (do it less destructive ;) } Note: this is again an example, DO NOT copy&paste examples and assume they'll work for you! PhpWiki compatibility ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The MySQL database table is partially compatible to PhpWiki versions 1.2.x, but not with the current PhpWiki 1.3.x versions. There is however now the db_phpwiki13 plugin which allows to access those (rw). Transition from another WikiWare ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you choosed ewiki to replace an already existing wiki script on your site, you should first think about, that the syntax/WikiMarkup isn't equal across all Wikis. There are a few markup extension plugins, that may help you around this, but beware that transition with a larger collection of WikiPages won't be very easy. The best way to import the old WikiPages to ewiki, is to first export it using the tools of the previous WikiWare. You can then just put the produced text/plain PageSource into "init-pages/", because all files found therein (note, that there shouldn't be any file name extension like .txt) are feed directly into the ewiki database, when ewiki is run for the very first time (when the EWIKI_PAGE_INDEX is not found in the db). There is a "plugins/db_phpwiki13.php" which may be useful in first trying ewiki, but it is not recommended to use it for daily work. Speaking of PhpWiki you could also use the "tools/t_convertdb.php" to import (and markup convert) all pages from PhpWiki to the ewiki database format. -------------------------------------------------------------------- 3 -- Internals ŻŻŻŻŻŻŻŻŻ The MySQL database table structure is to a certain degree compatible with that of the well known ğPHPWikiĞ v1.2.x (you only need to change EWIKI_DB_TABLE_NAME to "wiki" to use it). This is the MySQL statement which creates our database table (you can find it at the bottom of the "ewiki.php" script): CREATE TABLE ewiki ( pagename VARCHAR(160) NOT NULL, version INTEGER UNSIGNED NOT NULL DEFAULT 0, flags INTEGER UNSIGNED DEFAULT 0, content MEDIUMTEXT, author VARCHAR(100) DEFAULT 'ewiki', created INTEGER UNSIGNED DEFAULT 0, lastmodified INTEGER UNSIGNED DEFAULT 0, refs MEDIUMTEXT, meta MEDIUMTEXT, hits INTEGER UNSIGNED DEFAULT 0, PRIMARY KEY id (pagename, version) ) I didn't like the column name {pagename} but as I've seen this was the only difference I renamed it, therefore now the ewiki_database() function translates it from "pagename" to "id" and vice versa most of the time - else this would be really slim and nice code :) The columns {version} holds the different saved page versions. Other Wikis require a secondary "backup" or "history" table for old versions, but as I couldn't imagine what this is for, there is just one table in ewiki; and it seems this is really enough. The first {version} of a wiki page is always numbered 1. An existing page {version} will never get overwritten => very secure MySQL usage. For what's in the {flags}, see the README section about constants. The {content} of course holds the wiki pages source. The {created} and {lastmodified} should be clear too. {refs} contains a "\n" separated list of referenced WikiPages. The code to generate that list is rather unclean, so it often contains GhostPages. However this does not hurt ewiki and the few functions that utilize {refs}, so there is currently no need to slow it down by fixing this. {meta} can hold additional informations, which allows to extend ewiki without requiring to ALTER and convert the ewiki database table. It currently holds some mime headers for binary content and some other useful informations for images and uploaded files. {hits} should have gone into {meta} really. But having it separate allows us to use the very fast mysql UPDATE function. Note, that the ewiki database table can hold other things than wiki pages - binary content (images) for example, depending on the setting of the {flags} field. And last comment about this, the one-table-concept also made it really easy to implement the flat file based "database backend". ewiki_ functions ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Some of the core functions of ewiki.php can be used separate from the others and some of them were designed to be replaced by different implementations. Btw, all the functions, constants and variables start with "ewiki_" to make it easier to mix it into other projects (reduces function name conflicts and similar problems, that usually arise if you join two or more scripts into one program). ewiki_page($id) --------------- This is the main function which fetches the selected WikiPage (or the one given with $id) via ewiki_database to transform with ewiki_format(). If the requested page does not exist it returns the edit screen. It also includes some virtual pages (InfoAboutThisPage, NewestPages, SearchPage, ReferencesToThisPage, ...). ewiki_page_...() ---------------- These functions were separated out from the main ewiki_page() to make it more readable. Most of them contain code to generate the few special/internal WikiPages (Search, Newest, Info, and the Edit <FORM>, ...) ewiki_control_links($id, $data) ------------------------------- Prints the line with the EditThisPage and PageInfo, ... links. ewiki_format($wiki_source, $params) ---------------------------------------------------------- This returns the formatted (HTML) output for the given WikiSource (with all the WikiMarkup in it). The second param is an array with various config overrides. An entry of "scan_links"=>1 for example tells ewiki_format to lookup the referenced WikiPages in the database (see ewiki_scan_wikiwords) for filling up $ewiki_links. Another $params entry is "html"=>0, which controls interpetation of the <html>...</html> page content blocks. ewiki_render_wiki_links(&$o) ---------------------------- Transforms WikiLinks and square brackets in a page into html links. ewiki_scan_wikiwords(&$wiki_source, &$ewiki_links) -------------------------------------------------- work with regex on the wiki source text, to find valid WikiWords, the $ewiki_links will be filled with informations if the found page names exist in the DB. ewiki_link_regex_callback() --------------------------- Called from ewiki_format(). To separate the ewiki_format() from the database this function will utilize the global $ewiki_links (generated on demand by ewiki_format) to output either a normal link or a question-mark after the WikiPageName to signal a non-existent page. ewiki_script() -------------- Builds the complete URL needed to access the given resource. This function replaces/enhances the static EWIKI_SCRIPT constant and unifies the generated URLs (less bugs). It also helps around various design flaws (like nice looking URL strings), that made some parts of ewiki a bit weird and unreliable in the past. Btw, now the base URL is stored in $ewiki_config["script"]. ewiki_script_binary() --------------------- Is just a ewiki_script() wrapper, but can additionally distinguish between binary download and upload URLs, which could be utilized by (database external) plain file storages (see plugins/binary_store). ewiki_binary() -------------- Gets called automatically for requests with the ?binary= trailer which is used to reference cached and uploaded images (or not yet cached ones). ewiki_author() -------------- returns a string with REMOTE_ADDR and the $ewiki_author or a default string incorporated ewiki_auth() ------------ Is a simple interface to a probably large collection of plugins, which should to actual user and permission management. Support for this in the core is however still sporadic. ewiki_auth_user() ----------------- Queries all registered user databases, and is usually itself called from within an auth_method/auth_query plugin. ewiki_t() --------- Fetches a text string from the $ewiki_t[] array and additionally adds some text pieces into it (given as second param). It can retrieve translations for registered abbreviations, or searches for complete text fragment replacements. It also understands _{...} to recursively translate a text snippet inside of larger text blocks. This is probably a bit slower and less readable than the previous usage of EWIKI_T_ constants, but it saves some memory and allows to extend translations or additional text constants (of plugins) a lot more easier (previously one had to edit inside a function, which is almost impossible to do from outside / per configuration). ewiki_make_title() ------------------ Returns a string enclosing (the generated) page title (as link) into the html title markup "<h2>". The $class parameter actually tells from which plugin sort it was called, and this decides if a link will be generated or the title will be unclickable plain text (the setting in $ewiki_config["print_title"] is used to determine that). $go_action tells which action to link the title to. ewiki_chunked_page(...) ----------------------- Is a helper function to split large results into multiple click-through pages, and is used by info/ and some search functions/plugins. It only produces the click-through links for inclusion on other dynamic pages, allows overlapping of page chunk ranges. ewiki_in_array($value, &$array, $dn=0) -------------------------------------- Case-insensitive variant of PHPs` in_array(), returns the $value if found. The $array will be all-lowercased afterwards (except when $dn was set). ewiki_array($array, $index=false, $am=1) ---------------------------------------- Returns input-array lowercased (indices), or just the entry for the $index if searched for. The $am decides if multiple entries should be merged together (uppercase+lowercase merging produces overlaps). ewiki_database($FUNCTION, $args=array() ) ------------------------------------------ This function is the "database abstraction" in ewiki. It contains ''only'' eight SQL statements which must be replaced if you'd like to use another database server. It is very stupid, and does not know much about its database (keeping it extensible on the other hand), therefore one must be careful when passing database entries to it. The individual "atomic" functions are: "GET", $args = array( "id"=>STRING, ["version"=>NUM] ) Fetches the newest wiki page incarnation from the database, or alternatively the one given by version. "WRITE", $args = array( COLUMN-NAME => VALUE, ... ) Saves the contents of the given data array in the database, does _never_ overwrite an existing entry (you must keep track of the {version} yourself). "GETALL", $args = array( "COLUMN-1", "COLUMN-2", ... ) Fetches an array of all existing pages in the database, but returns it as ewiki_dbquery_result object, which will throw the requested columns on ->get(), where the entries 'id', 'version' and 'flags' are always present. "FIND", $args = array( "WikiPage1", "WikiPageName2", ... ) Searches the database for the queried page names, returns an array which associates the boolean value (if pages found) with their names "SEARCH", $args = array( "COLUMN" => "CONTENT" ) Returns only those pages, where the database COLUMN has a content that matches the requested value; the list of pages is returned as ewiki_dbquery_result object, where you can access the individual entries using the ->get() call, which will return the columns 'id', 'version', 'flags' and the scanned COLUMN of course unless you ->get("_ALL=1"). The following three actions are not required for correct operation, but provide additional functionality for some plugins or tools. "HIT", $args = array( "id"=>STRING ) Increases the hit counter of the given wiki page by 1, what is not implemented in db_flat_file. "OVERWRITE" Is a wrapper to "WRITE" and does replace existing entries. "DELETE", $args = array( "id"=>STRING, "version"=>NUM ) Removes the specified page (only the given version) from the database; implemented in all database plugins but should be used from within the tools/ only. Other functions are usually used internally only, as for example the "ALLFILES" command in dbff or dba/dbm plugins. ewiki_dbquery_result -------------------- Has the member variables $keys and $entries, where the latter contains an array of page names that where triggered by your GETALL or SEARCH request, and the $keys array contains the column names that each subsequent "$result->get()" will return. get() Returns the database entry array (see GET above), but only the fields the database query should return (at minimum these are 'id', 'version' and 'flags' and the searched column for SEARCH). get("_ALL=1") Instead returns the complete entry. count() Returns the number of found database entries. add($row) [internal] This is used by the ewiki_database() core functions to initialize the $result object with the found entries. $GLOBALS pollution ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ At least the ewiki_page() function produces variables in the global namespace. Of course they also were named to not interfere with anything from yoursite.php: $ewiki_id - Contains the current page name, after ewiki_page() was called. $ewiki_action - Contains the $action/ForTheCurrentPage. $ewiki_title - Will be set after the first call to ewiki_page(), it is most useful to be printed inside the <TITLE> tags inside <HEAD>. So if you want to use it you should call ewiki_page() very early, but save its output into a variable for later use. This way you can make the current wiki pages` title available (the _title may be different from the pages _id). $ewiki_errmsg - Sometimes used to pass error notices back (ewiki_auth does so for example). $ewiki_links - Is an array produced by ewiki_format() that associates all found WikiPageNames with a value of 0 or 1, depending on if the referred page exists in the database. $ewiki_author - The content of this variable is saved in the author field of newly created wiki pages (it will be filled with IP:PORT if not set from outside). This is only an informational setting, and does not directly correspond to the _PROTECTED_MODE. You should set it, whenever yoursite.php notes a logged in user (so his login gets saved in the wiki pages 'author' column). But you should REALLY NOT SPAM IT with your own name or ad words. $ewiki_auth_user - Is set by ewiki_auth_user() whenever it successfully authenticates a user in _PROTECTED_MODE. This variable is then used as reliable state setting, which affects permission granting. $ewiki_ring - Holds the permission level ('ring') of the currently authenticated user (or else will be unset). This value tells only about the user, many plugin functions have built-in requirements which will be compared against this value (no value or zero means full permissions). While this is the built-in way to grant permissions and often also suits the needs to do it, the _auth() plugin interface allows to work at a much finer degree of access granting. values: 0=administrator, 1=moderator, 2=editor, 3=guest See also plugins/auth/README.auth for more informations. $ewiki_plugins - Is an array which connects task names (say "database" or "image_resize" for example) to function names. You can utilize this if you decide to extend ewiki. There is an own chapter on this. $ewiki_config - Imports some configuration settings from older constants, and introduces newer ones, which can then be overridden at runtime. Also holds some work and markup transform data. $ewiki_t - Text definitions and translations for all possible messages. Things that disappeared again, and which are now part of the $ewiki_config array instead include: $ewiki_data - May reappear by setting a _config[] variable. $ewiki_interwiki - Was errornously part of _plugins[] for some time. $ewiki_script - Was a global var for a short period of time, but now is a subentry in $ewiki_config. EWIKI_ constants ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This chapter explains some of the constants and how you can utilize them to tweak some of ewiki's behaviour. The recommended way to change settings is to copy the define() commands from "ewiki.php" into "yoursite.php" (see our example "config.php"). This is a good idea, because then your settings won't get lost if you upgrade to a newer version by overwriting your tweaked "ewiki.php". [Note: constants in PHP can be defined() once only, so pre-defining them in "yoursite.php" or a "config.php" script is nearly like a 'configuration'] To define() some of those constants in 'yoursite.php' is especially a good thing, because some of them are more used like state variables and it may be more senseful to set them depending on informations only available in the scripts of yoursite.php (for example if yourscripts provide a way to authenticate and login a user you may give him additional rights within ewiki by pre-defining one of the following constants). EWIKI_SCRIPT This is the most important setting. It is used by ewiki.php to generate links to other WikiPages. It needs the name of yourscript.php which itself includes ewiki.php. The name of the linked WikiPage is just appended to the string defined here, so you must ensure that it either ends in "/" or "?id=" or "?name=" or "?page=" so it constructs a valid URL after concatenation (or %s replaced) with the WikiPageName. If you utilize mod_rewrite on your server, you may wish to make it blank when all requests to http://wiki.example.com/ are redirected to the correct script by your WebServer. If your wrapper script for example is called 'index.php' then you can just set EWIKI_SCRIPT to "?page=" (which then refers to the index.php of the current directory). You should preferrably set it absolute to the servers DocumentRoot, which gets a requirement if you'd like to give page names and actions via PATH_INFO "/wiki.php/WikiPage" and not as QUERY_STRING "?id=". Update: this constant will stay, but the core script now utilizes the ewiki_script() function (which itself additionally respects the $ewiki_config["script"] config variable in favour). ewiki_script() introduces use of the "%s" placeholder inside EWIKI_SCRIPT, which will be replaced by pagename and action, when URLs are generated. EWIKI_SCRIPT_URL Some parts of ewiki require the absolute URL of the ewiki wrapper script. So in contrast to the (often) short EWIKI_SCRIPT, this constant MUST contain the protocol and server name, like: "http://www.example.com/wiki/index.php?id=" If you do not set this constant, it will be guessed by the ewiki_script_url() funciton, what often works but may be suboptimal and could also lead to security problems. EWIKI_DB_TABLE_NAME Sets the name of the MySQL database table name to be created and used to store all WikiPages. EWIKI_DBQUERY_BUFFER When set to a value>0 then SQL database buffering will be enabled for SEARCH and GETALL queries. This is mostly like the old (R1.00) behaviour (memory exhaustive), but instead is limited to the size defined by this configuration constant (for example 384K). EWIKI_DBFILES_DIRECTORY Defines where db_flat_files puts the database (made up of files). There is a separate paragraph about this, EWIKI_DBFILES_ENCODE If set to 1 will generate urlencoded() filenames even on UNIX systems, so the dbff database 'files' get exchangeable across DOS/Win and UNIX filesystems. Not recommended, and will make ewiki run bogus, if you switch it after there already entries in the database. It may however be useful to enable this per default, if you want to "backup" (this is the wrong way) from a Unix server to a Win box via an ordinary FTP program (more professional tools could however handle this more easily). EWIKI_INIT_PAGES Names the directory from which the basic pages should be read and then written into the database, when ewiki is run the very first time (or the FrontPage - EWIKI_PAGE_INDEX) is still empty. Btw, you could use the 'ewikictl' utility to export all your Wiki pages into this directory as auto-reinit-backup. EWIKI_NAME Defines the name of your Wiki. (This is not used currently, but is required, as _PAGE_INDEX is often just set to "FrontPage".) EWIKI_PAGE_INDEX This defines the name of the WikiPage which shall be displayed when no value is received within the URL. Often this is called the "FrontPage" of the Wiki. The mysql error message "Table 'ewiki' already exists" will appear until you create (and fill) the page specified herein. If you'd like to have a wiki without FrontPage, you can set this constant to 0 or "" - you must then however ensure, that the ewiki script is never activated without a page name! EWIKI_PAGE_NEWEST This defined the name of the virtual (internally generated) page containing a list of the lately added WikiPages. EWIKI_PAGE_SEARCH Holds the WikiPageName for the search function. EWIKI_CONTROL_LINE Pre-define this with 0 before including("ewiki.php") if you don't want that "<HR><A HREF>EditThisPage</A> ..." to be shown at the bottom of each page. You must then generate the EditThisPage link yourself somewhere else on yoursite.php It is often easier to edit the ewiki_control_links() function to match the layout/design of yoursite.php. EWIKI_AUTO_EDIT If set to 1 (default) will automatically bring up the edit box for non-existent pages. Else a page in between will appear ("please edit me!") like in PhpWiki. EWIKI_LIST_LIMIT Number of pages to show up in search queries (and other generated pages). EWIKI_PRINT_TITLE If set to 0 will prevent the page title from being shown on many pages (generated and database content ones). EWIKI_SPLIT_TITLE If changed to 1 will separate WikiPages titles into its different word parts (only on top of each page). EWIKI_ALLOW_HTML Usually you do not want that users are able to add <HTML> tags inside the WikiPages as this allows for corruption of your page layout or creation of harmful JavaScript areas. This is however one of the few constants which could be set by yoursite.php for logged-in users. If it is set while a user saves a changed page, then the special EWIKI_DB_F_HTML will be set for the newly created version, so <HTML> won't be garbaged by ewiki_format() if another (not logged-in) user requests the WikiPage next time. You must start a line with a "|" to actually make the HTML work within a WikiPage. If a not logged-in user however re-saves the page this flag won't be set anymore, so you should be careful about that. {{edit ewiki.php and define(_DB_F_HTML with 8+16) to change}} EWIKI_RESCUE_HTML Was replaced by "plugins/markup_rescuehtml.php", which now allows for certain 'safe' HTML tags within the wiki source to be used. EWIKI_HTML_CHARS If set the rendering function will backconvert html entities which represent non-latin characters, like ႊ or Ԭ EWIKI_HTTP_HEADERS Allows ewiki to throw HTTP headers, where appropriate. You should keep it enabled, as it allows for things like RedirectionAfterEdit (when a page gets saved), and many other useful things. headers() can often only be sent, if your wiki/yoursite.php is binary safe, or uses PHPs output buffering (less reliable). EWIKI_HTTP_HEADERS Instructs browsers not to cache delivered pages at all. This is often a good thing, because otherwise unclever caches will prevent the most recent wikipage version to get seen by users. EWIKI_CASE_INSENSITIVE Was only recently implemented, but ewiki is fully configurable now in regards to WikiLink case. It is enabled per default, and thus allows referencing any "WikiPage" using strings like "WiKipAgE". This is believed to be more user-friendly than case-dependency. Reverting to "binary" page name matching is not fully complete now (our database scheme was designed for case-insensitivity from the very start and thus the DB code first needs tweaking before links in ewiki really get case-dependent. EWIKI_ESCAPE_AT Encodes the "@" sign into a html entities, which in the past helped a little bit against address rippers. But please check out the new plugins/email_protect.php, which is more effective against email harvesters. EWIKI_URLENCODE EWIKI_URLDECODE You shouldn't disable both unless you know, you don't need to encode WikiPageNames (else almost always necessary for sanity and security reasons). EWIKI_USE_PATH_INFO If you have a broken Webserver (like many Apache versions), you may wish to disable the use of PATH_INFO. If you ever happen to see "Edit page '/wiki/example-1.php'", you probably need to disable it. EWIKI_USE_ACTION_PARAM Allows the page action command to be given as '&action=...' within an URL (else only "action/WikiPage" allowed). If you set this constant to 2, ewiki will also create such URLs (instead of the usual "edit/PageName" prefix). EWIKI_ACTION_SEP_CHAR Defines the character that separates the page name from the action name in generated URLs. Per default this is the slash, but you could use something else (like the ":" colon), which however may have a few drawbacks somewhere else. EWIKI_DB_F_TEXT This flag is set for every WikiPage inside the database. Usually the only flag set on creation of a new page. Starting from R1.00b previous flags will be copied after applying EWIKI_DB_F_COPYMASK. EWIKI_DB_F_BINARY Used for cached/uploaded images. Prevents a page from getting shown. EWIKI_DB_F_DISABLED If set will prevent the page from being shown. Not useful. You could more easily unset the TEXT flag to disable page view. EWIKI_DB_F_HTML Special flag to allow the current version to include <HTML> tags regardless of the global EWIKI_ALLOW_HTML setting. EWIKI_DB_F_READONLY Prevents a new version to be saved, and thus disallows editing of the WikiPage. EWIKI_DB_F_WRITEABLE Is the reversal of READONLY but only useful if you crippled ewiki by setting EWIKI_EDIT_AUTHENTICATE, as this flag is only intended to reallow editing of a page if you disallowed it before with _EDIT_AUTH (which denies access to _all_ pages). EWIKI_DB_F_APPENDONLY Gets implemented by the plugins/append*.php, and allows to lock a page, in that users can only append to edit (or edit parts of it). See the plugin description for more details. EWIKI_DB_F_SYSTEM Is used to mark internally used data holders (usually serialized() variables). EWIKI_DB_F_TYPE Used internally to separate TEXT, BINARY, DISABLED and SYSTEM entries. EWIKI_DB_F_COPYMASK When a new page is created, the flags of the previous version are ANDed with this value to strip off some unsafe settings. It could be possible to add the _DB_F_HTML setting to here, but this would allow HTML to be used by all users if the READONLY isn't set. Always keep in mind, that flags could be reimported from previous versions as well (I'm usure if this could happen). EWIKI_PROTECTED_MODE Is an operation mode of ewiki, which activates ewiki_auth() function, that is utilized from many places to require a permission level (from authenticated users). Set this constant to 1 to enable this mode. You'll also need some plugins from plugins/auth/ to make this useful. If this constant is set to 2, then you don't need a permission plugin, but can control access to the edit/ function, by setting $ewiki_ring to 2 (to allow) from within yoursite.php scripts. This setting is also sometimes referred to as the "ClassicProtectedMode". EWIKI_FLAT_REAL_MODE Not a configuration directive, but the opposite to _PROTECTED_MODE ;) EWIKI_AUTH_DEFAULT_RING Is the permission level which is to be set, if no user is logged in currently (defaults to 3 - which means "browsing only"). EWIKI_AUTO_LOGIN If this is enabled, then ewiki_page() automatically requests for (re-)presenting the login <form> on startup, if current authentication isn't sufficient to go any further. Leave this enabled, it helps around some problems. EWIKI_EDIT_AUTHENTICATE EWIKI_ALLOW_OVERWRITE Outdated (were present in older ewiki versions). See 'plugins/auth/auth_perm_old.php' to get them back. EWIKI_TMP Tells ewiki which directory to use for temporary files. The default value is "/tmp" or whatever the environment variable $TEMP or %TEMP tells (often "C:\\Windoze\\Temp" or "C:\\Trashcan" on DOS systems). EWIKI_LOGLEVEL Log messages are internally separated into four categories: 0=evil errors, 1=warnings, 2=notices, 3=annoying debug stuff. If you do not want a log at all, just set this constant to -1 or 357. If you set it to 1 for example, you will see error and warning messages in EWIKI_LOGFILE. EWIKI_SCRIPT_BINARY This requires the REAL absolute address of the ewiki.php library script (but the database must already be opened). Needed for the function for cached/uploaded images. You can set it to almost the same value as EWIKI_SCRIPT if it is ensured that there is yet no output made, and the headers() are not already sent. Usually just "?binary=" works fine (if you use the index.php way of including ewiki.php). If you don't want ewiki to use image caching and uploading functions you would define this to "" or 0, because this disables the <img href> redirection through ewiki_binary(). You should then also disable the following two constants: EWIKI_CACHE_IMAGES Allow caching of images. To disable all the image functions (uploading, caching) set this to 0, as well as EWIKI_SCRIPT_BINARY and: EWIKI_IMAGE_MAXSIZE ewiki will scale down images until they get smaller than the absolute size (bytes) given here. This is true for cached and uploaded images. Your database may grow really fast, if you set it too high! (even if .BMP and .XWD files are discarded normally ;-) EWIKI_IMAGE_MAXALLOC Maximum size of image while uploading and resizing it (memory limits). EWIKI_IMAGE_RESIZE Enables the internal resizing functions. EWIKI_IDF_INTERNAL Is used to identify uploaded images and data files. Usually you do not want to change it, especially if there are already uploaded files; however "chrome://" or "file://localhost/tmp/" could be funny alternatives to the default "internal://". Note that the renderer relies only on some unique string to detect binary references, but the database functions in fact depend upon "://" to return image sizes on "FIND" calls. EWIKI_ACCEPT_BINARY Allows users to upload arbitrary binary files through the image upload function. You should now rather use the downloads plugin, which adds a lot of functionality missing better suited for such purposes. This feature depends on the image upload and cache function. EWIKI_ADDPARAMDELIM Automatically defined, holds either "?" or "&" depending on what is in EWIKI_SCRIPT. You shouldn't change this unless you know what you are doing. EWIKI_T_* These were replaced by the $ewiki_t[] array and ewiki_t() function. EWIKI_CHARS_U EWIKI_CHARS_L Allowed chars in WikiPageNames (uppercase and lowercase chars). Use this to localize your wiki (standard Wikis only allow A-Z, think of that when it comes to InterWiki). EWIKI_UP_* URL parameters. Changing these may only be necessary, if one is already evaluated within yoursite.php for other purposes (incompatibilities). You could also change these just to make some of the generated URLs look a bit nicer ;) EWIKI_DEFAULT_LANG This value is used by a few plugins, that must guess the desired language of visitors, or the language of a pages content. EWIKI_CHARSET ewiki currently only supports the Latin-1 charset, but UTF-8 support is underway. So you should only specify "ISO-8859-1" or "UTF-8" herein (while most other "ISO-8859-*" are believed to work too). UNIX_MILLENNIUM Ey, don't tell me you're using Windoze ;) EWIKI_VERSION Is not used at all. It is just placed on top of every ewiki.php to tell you, which version you are running currently. Major releases have a version number like 'R1.00a', while testing and unstable releases have another number appended 'R1.00a7'. See the tools/ subdir for a small utility to change the mentioned flags in the ewiki database table. $ewiki_config array ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ As it turned out not all configuration settings are as everlasting that they can be constants (this mainly applies to "look&feel"-settings). So some of the above mentioned EWIKI_ constants can now be overridden by settings in the more flexible $ewiki_config[] array. Usually this array contains index=>value pairs with simple boolean meanings, but often there are more complex entries and some of its contents are data/behaviour entries (that were previously/falsely in $ewiki_plugins). You can override settings by just setting $ewiki_config["..."]="..."; because the entries in ewiki.php are defaults that do not overwrite any existing var. So it is really not important if you change things after or before the 'ewiki.php' script gets included(). ["script"] Replaced EWIKI_SCRIPT, and is used to define the path/URL of the ewiki wrapper script (yoursite.php, which at least included the ewiki.php script and runs the ewiki_page() function). ["script_url"] Should contain an absolute URL to the ewiki wrapper script. (replaces EWIKI_SCRIPT_URL) ["script_binary"] like EWIKI_SCRIPT_BINARY ["print_title"] replaces EWIKI_PRINT_TITLE, but also allows finer grained control: a 1 says that titles should be added at top of pages a 2 states that titles should also link for internal and generated pages a 3 will make linked titles even for pages, that should normally not have them ["split_title"] replaces EWIKI_SPLIT_TITLE, defines if pages` titles WikiWords should be separated by spaces when displayed ["wiki_pre_scan_regex"] Is the regular expression used to separate out links from a pages` content to query the database for existence of all mentioned WikiPages. ["wiki_link_regex"] Is the actual link search regular expression. It is responsible for finding WikiWords and things in square brackets and ordinary http:// or internal:// WWW-links and even email addresses. ["action_links"][$ACTION1][$ACTION2] Holds title for $ACTION2 when shown on a page activated with $ACTION1 (only "view" and "info" get other actions` titles associated currently). This is used for the _control_links() for example to entitle/show action links. ["idf"][$TYPE] Associates arrays with identification (search) strings into classes (we have "url" and "img", "obj" for example associated with proto:// prefixes or filename extension lists). ["interwiki"][$PREFX] Connects other Wikis` script URLs to WikiLinkPrefixes. ["format_block"][$BTYPE] Defines "block" types, which are scanned for in WikiPages (using the given search strings), and then handled by specialized ["format_block"] plugins (instead of the core ewiki_format() function code). ["format_params"][] Contains the default $params, the ewiki_format() function will assume, if they weren't overridden by the second paramater given to it. ["wm_..."] WikiMarkup definitions. ["htmlentities"] Used by ewiki_format() to pre-escape <html> in wikipages (later some of the escaped html is often reactivated). internal coding explained ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This section is to explain some of the coding style of ewiki, and how some things work. While many parts of ewiki carry good source code comments, it is always difficult to quickly understand larger scripts like the ewiki one by just reading it. how ewiki operates ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewiki_page() - decodes the $id and $action from the GET or POST parameters - tries to load the page from ewiki_database() - if this failed then it calls the database init function - calls some init plugins, calls the _auth() interface - chains to ["page"] plugins which activate for registered $id's - alternatively calls a plugin that was registered for $action - the default however is to render the current page via _page_view() - adds a page title - sends the generated output (view page or plugin output) back to caller (for output into yoursite.php) ewiki_page_view() - feeds the current page $data's ["content"] into ewiki_format() - also decodes paramters (html allowed) - returns the gererated html back ewiki_format() - beatifies the source code (unifies to plain UNIX newlines) - calls init plugins (wiki source mangling) - splits source into blocks, calls block plugins - then goes through each line of the wiki source to generate html - there is line-start, in-line and complete-markup - afterwards everything went from source into the $ooo-output var - first calls the link pre scan regex (which searches for wikiwords and stores that information into $ewiki_links) - then calls the wiki-link transformation regex function - then calls post plugins and returns generated <html> ewiki_render_wiki_links() - searches for all (pre-fetched) $ewiki_links in the ewiki_database ("FIND") - transforms the wikiwords into html-links - with the regex and callback func: returns output back to - ewiki_format() ewiki_link_regex_callback() - transform the wiki source snippet returned from the preg_replace() call into a html link string - (complicated) ewiki_$page_plugin_*() - page plugins return html output, which usually is hardcoded as strings into them - provide some interactivity ewiki_$action_plugins_*() - activate on pages with special registered $action's - provide some interactivity (for page editing for example) used variables ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Variables in ewiki often have similar names, and are also regularily passed by reference from one function to another (so it is in fact the same variable). $id - Is often the name of the current page (which is to be shown returned as output. The content of this variable is also available via the global $ewiki_id [[for plugins that do not have the common ($id,$data,$action) interface parameters]]. $data - Contains the entry fetched with the initial ewiki_database() call. This is an array of the form: array( "id" => "CurrentPageName", "version" => 1, # 1 is the lowest possible "flags" => 1, "created" => 1002056301, "lastmodified" => 1002171711, "hits" => 235, "author" => "localhost (127.0.0.1:4981), "meta" => array("Http-Header"=>"X", "setting"=>"val"), "content" => "wiki source...", ) $action - The $action with wich the current page was requested (most often "view", but everybody also knows "edit"). $uu - Short for "unused". Is used as temporary variable, especially with preg_match() and string functions. $result - Used for database queries SEARCH and GETALL. $row - Holds temporarily fetched entries from the databases (like $data), if page lists are to be generated. -------------------------------------------------------------------- 4 -- Tweaking ŻŻŻŻŻŻŻŻ (this part of the README is also just a collection of random notes) Just using the wiki source transformation ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The ewiki_format function was designed to be used independently from the ewiki database. ewiki_format($wiki_source, 0); It just needs the "wiki_source" as argument and generates a nicely formatted page from it. All you need to take care about is the $ewiki_links variable. Set the $ewiki_links=true ("true" and not "1" or anything else) to enforce ewiki_format() to treat all references as existing. To separate the ewiki_format() function out of recent ewiki versions, you'll also need ewiki_script(), ewiki_link_regex_callback(), ... and a lot of constants to take with. It is often much easier to just include("ewiki.php") for using ewiki_format(). You then should however take care, that the _binary part doesn't get activated by accident. To prevent this, just put following before the include() statement: unset($_REQUEST["binary"]); include("ewiki.php"); If you need it more quickly, or don't want to load the whole ewiki.php file, then just try the fragments/wiki_format.inc, which is a stripped down version of an older rendering core function (no WikiLinks, no binary stuff). Contributed by Frank Luithle. Customizing ewiki_format() ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ There are various markup extension plugins available for ewiki, which allow you to use BBCode or the syntax of another WikiWare. But if you have a closer look at $ewiki_config (the defaults are in 'ewiki.php' around line 200), you'll notice, that you can configure the WikiMarkup that is to be used. Various "wm_..." entries map our obscure markup to html <tags> (or at least fragments of them). So in order to add a feature you could insert an own rule there. (But keep in mind, that every new WikiMarkup slows down the transformation function.) Often you want to append an entry to "wm_style", for example: $ewiki_config["wm_style"]["==="] = array("<h1>", "</h1>"); Would allow you to write "===SomeText===" in a WikiPage, which then would display as an far-too-large headline. You can also add markup with different 'start' and 'end' characters, using the "wm_start_end" entry in $ewiki_config. For example the following would render "... ((((some text)))) ..." in a page using the html <kbd> tag: $ewiki_config["wm_start_end"][] = array( "((((", "))))", "<kbd>", "</kbd>", ); Please see the section on "ewiki_format() internals" on how to write a ["format_..."] or markup plugin. Customization using CSS ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ There are now some interesting ways to style ewiki output, just read on. Please note, that it in your stylesheets you just write ".wiki" and REALLY NOT ".ewiki" this time. Also important is, that we discourage use of the underscore in CSS class names, because it is simply forbidden there, even if current browsers do not complain as loudly as the w3c does. (That's just why you'll now see lots of class names with minus dashes instead of underscores.) user style classes in pages ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The plugins/markup_css allows you to use CSS classes and style definitions in WikiPages. With the double at @@ followed by a css classname or command you start styling a paragraph or parts of the text. @@classname at the start of a paragraph will enclose it into a <div class="classname"> completely But inside of some text, the @@styledef only affects the part until the next @@ everything that comes later won't be enclosed in a <span> While the css style classes must be defined in your sites` global stylesheet to take effect, you could also use direct CSS style commands instead. These also must follow the @@ immediately and may not contain spaces. So something like @@color:#ff0000; will work, while specifying font names may not always. rendered page content ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you are not interested in walking around the "ewiki.php" script when you want to tune how the output looks, you should try to utilize the (few) CSS classes ewiki defines (it does not include even one color setting or <font> tag): <style type="text/css"> p { font: ... } // almost every part of the generated // wiki pages is inside a <p>...</p> em { ... } // you could encolour this, if the browsers strong { ... } // usual italic is not emphasized enough .indent // to specify a different space-indentation </style> pages enclosed in style classes ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The most powerful way to style the content ewiki includes into your site is to use the generic style class names which enclose every page that comes from ewiki: <div class="wiki view ThatPage"> ... </div> This <div> is always the outermost tag around the html content that returns from ewiki_page(). It will always contain the class "wiki", after this the current page action/ and PageName (the action is usually "view", but can be also "edit", "info", "links" or something similar). Keeping this in mind you can easily style all, a few or even just a single page from ewiki in your stylesheet. (We'll explain it here, because the word of multiple class names and the cascading way of using CSS is not very widespread.) .wiki { // this affects every page ewiki returns background-color: #ccccff; font-family: "WikiFont"; ... } .wiki.view { ... } // only applies to pages that are "view"ed .wiki.links { ... } // BackLinks .wiki.edit { ... } // when a page gets edited .wiki.PageIndex { // this rule affects only a __single__ page ... // regardless what the "action/" is now; } // useful for "PowerSearch" or "PageIndex" .wiki.edit.ThisVerySpecialPage { // this css section applies to just one ... // page again, and this time only when } // it gets edited plugin output styling ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ There often appear special 'pieces' within a rendered page that ewiki returns, because not everything in the returned html code belongs to the requested pages` content. For example the current pages` title needs its own css class, like does the block of action links ("EditThisPage, PageInfo, ...") below every page, so it can be distinguished from the pages` text. Also note again the use of the '.wiki' selector within the following stylesheet guide and ewiki CSS class overview: .wiki h2.page.title { // all titles now have it, while many ... // of them include links as well } .wiki.view .action-links { // "EditThisPage, PageInfo, ..." links ... // are inside such a block, like are two } // <hr>'s .wiki.info .chunked-result { // some generated pages (like the history ... // info/ ones) may need to split their } // results; this matches those links //-- the edit/ pages are separated into // following blocks: .wiki.edit .edit-box { ... } .wiki.edit .image-upload { ... } .wiki.edit .preview { ... } //-- info/ pages contain a history of page versions, each enclosed in // a <table class="version-info">, the <tr>s inside can be selected // separately: .wiki.info table.version-info { ... } .wiki.info .version-info .action-links { ... } .wiki.info .version-info .page-author { ... } .wiki.info .page-refs { ... } .wiki.info .page-flags { ... } The class naming across most of the extension plugins is not unified, so you may often need to look it up here - or inside of the plugins source code. This is at least necessary for calendar and navbar, which follow a very different naming scheme. .wiki .download-entry { ... } .wiki .download-form { ... } .wiki .upload-form { ... } .wiki .image-append { ... } Idea Collection ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Here we'll note some tricks, on how to do this and that. Some of the following paragraphs also explain workarounds for currently lacking features. Multiple Wikis / InterWiki feature abuse ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Other WikiWare provides means to have multiple namespaces in a wiki, what if fact is contrary to the original Wiki idea suggesting a single flat namespace. ewiki does not support SubWikis or alike, to get multiple Wikis using one ewiki installation you'll need multiple layout and config wrappers (each with its own absolute URL and differen EWIKI_DB_TABLE_NAME or EWIKI_DBFILES_DIRECTORY constants). This way you'd get two independent Wikis (with two different SQL database tables, or flat_files directories), and of course links between those two need a special syntax. And the best approach here was to use the InterWiki linking feature. To do so, invent to InterWikiAbbreviations for each of your separate Wikis and add it to $ewiki_config["interwiki"] as follows: $ewiki_config["interwiki"]["main"] = "/wiki/main/?id="; $ewiki_config["interwiki"]["office"] = "/wiki/office/?id="; $ewiki_config["interwiki"]["tech"] = "http://tech.company.com/?id="; $ewiki_config["interwiki"]["our-www"] = "http://www.company.com/"; The last one is an example, on how to use the InterWiki feature to generate references to arbitrary web documents, with a simple syntax like "[our-www:/customers/pub/rules.html]" - it's somehow standard to use "company-url:" or "company-www:" as InterWikiAbbreviation for this purpose. -------------------------------------------------------------------- 5 -- Explanations ŻŻŻŻŻŻŻŻŻŻŻŻ The next few paragraphs shall enlight more detailed how some things are handled in ewiki (and why it is that way). Binary and Text content ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Because I'd like to keep it small (see also the "Everything in one script" paragraph) ewiki also creates just one database table. Differently from other Wikis this one has the 'flags' setting for each saved page. And as I successfully used this bad trick in earlier projects many times to integrate support for hundreds of different functions (CMS, links, boards/forums, ...) into a single table; I thought it could be funny to have something like this in ewiki too. While the image thingi seemed senseful to me, other binary data cannot be feed into database without helper plugins, because this is a Wiki script and not an almighty portal software! Uploading and caching of images requires the EWIKI_SCRIPT_BINARY constant to be set correctly (no output may be made before "ewiki.php" is included == "binary safe"). The ewiki_binary() function handles almost all of this, and gets activated automagically (whenever required) as soon as ewiki.php is included(). I believe these functions to be rather safe, as there are many sanity checks throughout the code to separate between _DB_F_BINARY and _DB_F_TEXT content. Image Uploading ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The currently most important use for the BINARY flag and image functions is to upload images with the small form below every page edit box. The upload/caching functions can be disabled fully if EWIKI_SCRIPT_BINARY and EWIKI_CACHE_IMAGES are set empty (or zero). URLs starting with "internal://" represent the uploaded files. The string is just a md5() sum generated from the contents of the uploaded file. This way files won't get saved another time if they are uploaded twice. For uploading a JavaScript-capable browser is recommended. It will work without, but then requires the user to copy the [internal://...] text (from one window to another). The color of the temporary upload info screen can only be changed inside the ewiki_binary() function, currently. Beware that images usually get downscaled if they are larger than specified with EWIKI_IMAGE_MAXSIZE (per default 64K). Images Caching ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Images are usually redirected through EWIKI_SCRIPT_BINARY, and ewiki tries to save them inside the database as with uploaded images. So most of the facts from the previous paragraph apply to this function too. You must enable this feature with EWIKI_IMAGE_CACHING, it is shipped disabled currently. Adding a ?nocache to the image URL disables this feature for just one specific image, if _IMAGE_CACHING was otherwise enabled. Images are downscaled to fit the maximum defined size in EWIKI_IMAGE_MAXSIZE (bytes) if the PHP libgd extension is available (else dropped and then always redirecting clients which request those image). Image WikiMarkup ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Usually one writes image references using square brackets around the url of an image: [http://www.example.com/pics/image.png] or: [internal://md5md5md5md5md5md5md5md5md5md5md5md5.png] This will include (inline) the image into the page, when rendered and viewed. Using the standard square bracket link entitling syntax also image references can be named (non-graphics / alternative text): [http://www.example.com/pics/image.png | This is an example image] [http://.../image.pic "or entitle it using double quotes"] Images can also be "aligned" to either side of the screen, thus the remaining text will flow around it. To achieve this include spaces to the left or the right of the image URL: * picture to the LEFT: [http://www.example.com/pics/image.png ] * picture to the RIGHT: [ http://www.example.com/pics/image.png] * CENTRED picture: [ http://www.example.com/pics/image.png ] Note that you must use __two__ spaces, currently! Image rescaling is possible by appending x=... and y=... as query string parameters behind the image URL: [http://www.example.com/pics/image.png?x=160&y=120] The query string parameters "width" and "height" are also accepted. If you have an image URL, but you do not want to get that image inlined into the current page, then just leave out the square brackets around. binary_store, direct access ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ While storing the binary data together with text pages in the same database is most often a good thing and suits most sites, there exists also a workaround/hack to keep this binary data in plain files. The advantage is a smaller database and possibly a little speed enhancement (with a large collection of binary things in the db). However the drawback is, that use of plugins/binary_store is only transparent to the main ewiki script, but all admin tools/ won't be aware of it. If you choose to use the binary_store.php plugin, you can also let ewiki generate URLs directly to the then stored data files if you just set the EWIKI_DB_STORE_URL constant. Please see the paragraph on this plugin for more informations on this. Arbitrary Binary Content ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Set the EWIKI_ACCEPT_BINARY constant, if you'd like to allow any binary file to be uploaded and saved in the database using the image upload function. Uploaded files will show up as ordinary (except that "internal://" href prefix) links. Please also note the "plugins/download.php", which does a much better job than this constant. $action and $id ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Inside of ewiki.php you'll see many occurrences of variables named $id and $action. The $id refers to the current page, which usually is a string like ThisPage, ThatPage, OrAnotherPage. Because just having pages wasn't believed to be sufficient enough, there is also a way to do something with them. That is what the $action tells. The most often used $action is "view" and is automatically assumed when no other $action was specified in the current ewiki URL. For non-existent pages alternatively the "edit" $action may get used instead. So the $action now delegates control about a requested page to a subfunc or plugin of ewiki, so the stored data of the page can be used for something (viewing being again the most common thing to do with it). "action/ForTheCurrentPage" is how both often looks in conjunction (again: if there is no "$action/" then "view/" will be assumed). Here the $action appears in front of the page name separated by a slash. A pagename now can contain slashes too, because ewiki can figure out, that "view/That/Page" separates into the $action being "view" and $id is "That/Page" in this example (the "view" gets mandatory in such cases). ewiki URLs ŻŻŻŻŻŻŻŻŻŻ "$action/$id" is most commonly appended as "GET parameter" to an ewiki URL, after a string like "?id=" or "?page=" - you've already noticed that! There are of course other ways to design the URLs ewiki produces and uses, the PATH_INFO being one of the most favoured alternatives. (we had a paragraph on this earlier, see on top of this README) Other Wikis use different URLs too, but you can tweak ewiki easily to a different behaviour, because you have the chance to pass your $action and $id to ewiki_page() from different sources. And because URL generation is encapsulated into the function ewiki_script() you could easily change just a few lines to make them look like you desire. The $action can be passed as "?action=" parameter already (this is core support), so URLs could for example look like ".../my/wiki.php?id=ThisPage&action=view" ... or something alike. -------------------------------------------------------------------- 6 -- Everything in one script ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ I think its handy to have one script for one task, and as ewiki is not intended to be used as portal script I think it's senseless to have always thousands of libs/scripts surrounding it. However as time went on, it turned out, that it would either slow down the core 'library' when everything was included into it, or that there couldn't be much further development at some point. So packaging useful but non-essential extensions into separate files was a good decision. Most of the plugin code can however still be inserted into or appended to the main "ewiki.php" script easily. As I realized that it really takes some time to edit the source when including non-standard things I decided to add that simple extension mechanism. Internally it is represented by the "$ewiki_plugins" array, which holds an list of alternative functions for various tasks. This allows to just include("a/plugin.php") for additional functionality inside ewiki. Note: if you're going to use almost all plugins, you should think about merging them altogether into one .php file: cat plugins/*.php > all-plugins.php It is much faster to include() just one big .php script, than it is to let the PHP parser run over twenty small ones (PHP is not interpreted, but memory-compiled). database plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The ewiki.php core script contains a database request function which is tailored to a MySQL database. However that function is already prepared to chain to another "database abstraction" function if desired. MySQL support ŻŻŻŻŻŻŻŻŻŻŻŻŻ The first implemented, and still most recommended way to use ewiki is with a MySQL (3.21 or later) database. RDBMS work more reliably and of course much faster than any other of the ewiki database backends. As the core ewiki_database() inside ewiki.php already includes the MySQL database calls, there is usually nothing to do, but opening a database connection before ewiki.php is included() from yoursite.php Please look at the top of this README for an example. As PHPs mysql_() functions don't require a db resource link to be given anymore, the ewiki_database() function does not pass and thus does not require it too. (If you use more than one MySQL database, you should take care, that ewiki accesses the one you accesses least.) plugins/db_flat_files ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you don't have access to a MySQL database, then just include() this plugin to save your wiki pages into simple text files (editable, often called "flat files") inside a dedicated subdirectory. You must set EWIKI_DBFILES_DIRECTORY in the 'ewiki.php' script to the correct dirname. Don't forget, that it must be given either relative to where the ewiki.php script is run from (like "./pages") or absolute to the servers filesystem root (for example "/export/htdocs/user528742/www.example.com/ewiki/pages") but NOT relative to your WebSpaces DocumentRoot!. Usually "/tmp" will work, but this one is purged on every boot; and therefore you should create a new sub directory (" mkdir ./pages ") where all files go into. This newly created subdir must be made ğworld-writeableĞ using the command "chmod 777 ./pages", because the WebServers user id counts when accessing it. Usually you can do both from within your ftp client (the commands are the same if you have a shell account): ftp> cd .../ewiki ftp> mkdir pages ftp> chmod 777 pages ftp> ls -rw----r-- 1 yourname yourname 57024 01. Jan 00:00 ewiki.php -rw----r-- 1 yourname yourname 512 01. Jan 00:00 index.php drwx---r-x 2 yourname yourname 4096 01. Jan 00:00 init-pages drwxrwxrwx 2 yourname yourname 4096 25. Feb 23:59 pages drwx---r-x 2 yourname yourname 4096 01. Jan 00:00 plugins -rw----r-- 1 yourname yourname 33010 01. Jan 00:00 README ftp> quit In graphical FTP clients there is usually a menu entry to set "access mode" or "access rights" (sometimes "file permissions") of files and directories equally. Again: don't forget to set the EWIKI_DBFILES_DIRECTORY constant to the correct value! If you create a subdirectory for the page files in the same directory the main 'ewiki.php' script resides, you usually want to set the config constant to just "./thesubdirectory" - here you could leave out the "./" (not required as it only refers to the current path). Btw, the slash character will work in directory specifications on windoze systems too (mr. bill once had to introduce a hierarchical filesystem in DOS 2.0, but choosed the bad backslashes, so no one should notice where that idea was borought from). The saved pages are in a format usually referred to as "message/http" (like www service request) or "message/rfc822" (internet mail). They usually look like: +----------------------------------------------- | id: WikiPageName | version: 1 | flags: 1 | author: 127.0.0.1:3054 | created: 1046532697 | lastmodified: 1046532697 | refs: \nErfurtWiki\nNewestPages\n | | !! WikiSourceContent | <more-text>... This file format can be exported by the "backup" tool, so you could easily change from the MySQL database to the flat-files one, if desired. Each page file exists in different versions, where the version number is always appended to the saved pages` file name. EWIKI_DBFILES_NLR converts newlines into the string "\n", but just for the values of the metadata. So there shouldn't occur much inconsistency, because the wiki content is saved binary safe in those "flat files". Filenames will be heavily converted on Win32 (urlencoded), while on state of the art UNIX/Linux systems only a few characters are replaced (slashes into backslashes) to match filesystem requirements. Problems: dbff WikiPageNames are currently not case-insensitive on UNIX-filesystems (while the MySQL-table is). Hits won't get counted; I don't think it is that essential, and it would take too much effort and time (file accesses) to support this. Note: You cannot do a "backup" from a Unix server to a Win box by using a plain FTP program, because many characters are allowed in Unix filenames but not on Win partitions. If you really want and need to do so regularily, you could then setup ewiki with EWIKI_DBFILES_ENCODE enabled from the very beginning. - The better aproach was to use 'ewikictl' or 't_backup' or 't_transfer' for the backup task. plugins/db_fast_files ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ NOTE: The db_fast_files has been merged into db_flat_files, so both formats can be read now - at the same time! Updated or new pages will however always be written in the file format determined by EWIKI_DB_FAST_FILES (defaults to 0), edit the "db_flat_files.php" script to change that constant setting, or even add it to your "config.php" so it was always present. While "db_flat_files" allows you to edit the WikiPage files (using any simple text editor), the "db_FAST_files" plugin saves the pages in a binary&compressed format (utilizing PHP's serialize function). This generally leads to a speed enhancement. Additionally this also allowed the PageHit counting to be activated (which is off in plain flat files). So you may wish to use this plugin in favour of the older db_flat_files. And as now both methods are available at the same time, you can switch whenever you want. Most of the setup guide from above is true for this one, too. An additional configuration constant introduced here is EWIKI_DBFILES_GZLEVEL, which tells the PHP internal zlib how much time to spend on compression of the saved pages. Usually the zlib uses a default of 5, but for speed purposes it is set to 2 here. You can also set the constant to 0 so the files will get saved uncompressed (but still in 'binary' format). A value of 9 will give you the smallest possible files, but this takes a little more CPU cycles (a bit slower). This plugin was contributed by Carsten Senf. plugins/db_any ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you use a relational SQL database other than MySQL, then you may want to give this plugin a try. It itself provides a wrapper for the PHP database access wrapper libraries ADOdb, PEAR::DB and dbx(). These wrappers themselves provide unified access to various SQL databases in contrast to the many highly different db access functions of PHP. Each of these db access wrappers has advantages and disadvantages and so none of them is really widespread and many users of course only jump on one of these trains. Because ewiki now tries to be 'library' it will use whatever database access wrapper you already have running on your site or container CMS, and the highly simplified anydb_*() now tries to make use of it. The plugin is based upon the current MySQL database backend, and thus may not be compatible to all proprietary SQL variants other vendors usually enforce. Before you can use the db_any plugin you must ensure that you either already have the PHP dbx extension dll loaded or the PEAR::DB or ADOdb include files loaded. db_any will like to see an opened database connection inside of the global '$db' variable. If yoursite.php hasn't already a connection opened when ewiki.php gets included, then you should preferably choose to use the anydb_connect() function to do so (it will choose from PEAR::DB, ADOdb and PHP dbx interfaces). The '$db' connection handle can be shared between your site and ewiki as long as it is a handle for one of the mentioned database access wrapper libraries. plugins/db_adodb ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ obsoleted by plugins/db_any plugins/db_dba ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ including() this plugin enables ewiki to store the WikiPages in the Berkeley DB file given with the EWIKI_DBA constant. Your PHP binary must be compiled with either the "dba" or the "dbm" extension to use this (and the dba extension requires at least one other database type to be enabled). The plugin has a built-in list of preferred dba database types, but it respects the filename extension of EWIKI_DBA. For example "wiki.db3" would create a DB3 database file, while "wiki.gdbm" resulted in a GDBM file, if that php extension was available. The PHP dba extension can support the db types (if compiled for): .gdbm .ndbm .db2 .db3 .db4 .flatfile .dbm If you have the PHP "dbm" extension enabled, wrapper functions will get enabled, so this works even if the "dba" extension is not there. The .flatfile is often available even if you haven't compiled your PHP binary for anything else than "dba". This may also often be faster than one of the db_flat_files plugins. If EWIKI_DBFILES_GZLEVEL is set to a value from 1 (fast) till 9 (very good compression, but slow), the saved pages will get compressed inside the dba database. With 0 this feature gets disabled. plugins/db_phpwiki13 -------------------- The original ewiki database table structure was compatible with the one used in PhpWiki version 1.2.x, however it turned out that the PhpWiki project has yet not stopped completely and choosed to implement a more relational table structure with version 1.3 This plugin is only meant for transition __from__ PhpWiki v1.3.x to ewiki, it should NOT be used to connect ewiki with PhpWiki forever. Write access is disabled per default, but available. However it is probably not fully compatible with the database abstraction and usage of PhpWiki, so it is likely to corrupt your database if you use it for a longer period of time. This warning is mainly because the 'latestmajor', 'latestminor and 'minor_edit' rows in the PhpWiki database, because such stuff is not used by ewiki at all. ewiki also tries to put some of the pages meta data into places where it could eventually confuse PhpWiki. Write access is however done nearly as safe as within the ewiki database access layer (INSERT statement to not overwrite existing entries). Again: this plugin is in no way meant to encourage you to keep your old PhpWiki database! ;> Please see also "tools/ewiki_convertdb.php". If you temporarily enable this plugin within the default/example "config.php" or the "tools/ewiki_tools_config.php" you can also utilize the very powerful 'ewikictl' cmdline utility to generate a copy of your PhpWiki database in one of the backup formats suitable for later use with ewiki. plugins/binary_store ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is a hack into the ewiki core, which will store binary/uploaded files outside of the default ewiki database (as plain files in a data directory). Please also see the documentation on top of the plugin file. Per default ewiki can store "binary" entries beside ordinary text pages in the database. If you'd like to keep uploaded files/images out of the db, then this plugin/hack will help. It intercepts ewiki and saves uploaded data into a plain data file, and instead creates a "binary symlink" in the database for it (just the binary meta data will get stored, with a hint on where to later access the plain data file). This may sometimes be a speed enhancement and reduces size of the database, however it has the drawback that only the main ewiki script can handle this transparently and all admin tools/ fail to deal with the stored plain data files (no backup support and so on). By setting the EWIKI_DB_STORE_URL constant correctly (corresponding to your wiki setup and where you store the data files, compare with EWIKI_DB_STORE_DIRECTORY) you can make ewiki create URLs directly to where the stored plain data files reside (they do not contain ewiki database meta data, and thus could be accessed directly by http clients/browsers). Please be sure to configure this plugin by setting _DB_STORE_DIRECTORY to something more useful than "/tmp", so your uploaded files will still be there after a reboot. core enhancements ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Some really cool features are put into extension plugins, and the most important, recommended and most often used ones are listed in this section: plugins/patchsaving ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If two users concurrently edit a page, then only the first saving attempt will succeed; which the second user is told by the "This page version was already saved" failure message. This plugin works around this by passing the contents of the concurrent versions through the 'diff' and 'patch' utilities, which often merges the two different modifications in a new version that can be saved into the database so there is no need for the failure message. plugins/notify ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin enables users to get notified, whenever someone changes a watched page. To enable 'watching' one must just place an email address into the page with following syntax: [notify:mail@example.com] This bracket will be invisible, when a page is viewed, so it can be placed anywhere. The notifications will be sent to this address as long as the tag is there. If one wishes to receive notification messages in another language, this just needs to be added after a comma or semicolon, like: [notify:pop3@example.net,de] This is often only necessary for the generic TLDs .com .org .net, or where language code and TLD differ. plugins/jump ŻŻŻŻŻŻŻŻŻŻŻŻ Introduces magic markup for page redirection (switching to another page). Possible notations are: [jump:OtherPage] [goto:SwitchToThere] The EWIKI_JUMP_HTTP setting tells this plugin to send a Location: and redirect HTTP status when encountering a page [jump:]. Else this plugin will show up the JumpDestination page without notifying the browser about it. It is also possible to perform InterWiki jumps, just be using the common InterWikiMoniker: syntax. [jump:WardsWiki:WelcomeVisitors] plugins/email_protect ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin 'ciphers' all valid email addresses inside a WikiPage for protection against automated spambots. Additionally it throws fake/trap email addresses to spam spammers databases :> It ist not integrated into the core script, because some people may prefer to have email addresses visible (intranet usage). However it is HIGHLY RECOMMENDED to enable this plugin. Despite its file size it is rather fast. plugins/spages (StaticPages) ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The "StaticPages"-plugin allows ewiki to access files in a given directory. If these files are in text format, ewiki will parse them as WikiPages. But if you put files with an extension .html, .htm or .php into one of the specified StaticPages` directories they will be returned as is from ewiki_page() - the .php files will of course get executed and their output is returned. The basename of the files in the directories to be used by spages will make up the WikiPageName with which the files will be accessible. Any given directory (see on top of plugins/spages.php) will be read recursively. So files in a subdirectory will get available as a page with a name like "subdir/FileName". If the name of the subdirectory contains a dot at the end, then the slash will be left out in favour of a dot: resulted in "subdir.FileName" for example. PHP scripts in a spages directory however have some restrictions, like not being able to return headers() or to access most global variables without use of the $GLOBALS[] syntax. If you rely on such functionality you should rather write an ordinary page plugin (which in fact is often much easier). From the output of .html and .php scripts only the parts between <body> and </body> will be returned as page content. Any <html> head area will get stripped, as it would lead to completely invalid html code if it was returned as is by ewiki_page() into yoursite. To let this plugin load pages from directories, you should either edit the array on top of this plugin file, or define() the EWIKI_SPAGES_DIR (before! including the spages.php script), which then also would be read in. Alternatively you could call the ewiki_init_spages() function yourself to register a directory for processing (after! loading the spages plugin): include("plugins/spages.php"); ewiki_init_spages("/var/www/wiki/staticpages/"); You could also use this plugin to inline the ewiki database tools/ as virtual pages. Btw, it is very easy to make a StaticPage from a ewiki page plugin and vice versa. Please also note the tools/mkpageplugin which can convert anything used as StaticPage into a page plugin for easy including() with other ewiki plugins. plugins/pluginloader ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The pluginloader plugin automatically loads ["action"] and ["page"] plugins, whenever necessary. This allows to skip dozens of include() statements within the config.php (which most always just slow down script startup). It is configured via a static array, which defines which plugins are allowed to be automatically invoked on request. Detailed explanaition is available within this script. plugins/init ŻŻŻŻŻŻŻŻŻŻŻŻ Handles database initialization using the distributed standard Wiki files from './init-pages'. Unlike the ewiki-builtin function to perform that task, this plugin first outputs informational notes to the user, prior database initialization. Once you have your SQL or ./files database initialized, you should disable this plugin (it then isn't be required anymore). plugins/feature/appendonly ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin (a family of) implements the actual support for the _DB_F_APPENDONLY page flag. When the flag is set, and this plugin active, then ordinary users can further only append text to the page, and won't be able to edit the earlier written parts of it. So this implements a much softer approach than the _READONLY page flag. Also this plugin comes in three flavours, but you can often only load one of them: "appendonly" - Really allows just additions to be made to the page, each new separated by a horizontal bar. "appendwrite" - Allows to insert a page separator, which protects the upper part from getting edited by ordinary users. Everything below a horizontal bar (denoted by at least 16 minus signs) or a double horizontal bar remains editable by all users. This plugin activates only if the _APPENDONLY and _WRITEABLE flag is set. "appendcomments" - stores page additions in an separate database entry marked with _DB_F_PART, but allows this part to get edited as whole (like "appendwrite" plugin). The last one is probably not very useful, as it generates some overhead and in fact is a collection of various workarounds to accomplish the desired functionality (so it may prove little lifetime). plugins/feature/imgresize_gd ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Was extracted from the core during the R1.00f development releases. Automatically rescales uploaded images, if they are larger than EWIKI_IMAGE_MAXSIZE. As it uses the gd2 library, there must be support for this in your PHP binary. There are a lot of problems on Win32 systems, and also some Linux binarys (-dev ones) crash constantly if you load this plugin but don't have the libgd activated or available. plugins/feature/imgresize_magick ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Rescales uploaded images via the ImageMagick utility "mogrify", which is usually only available on UNIX systems. It should however be fairly simple to make this plugin work with some other image manipulation tool (at least with Linux). plugins/feature/spellcheck ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Turns the [preview] button below every page edit box into a spellcheck function. You need a working 'aspell' or 'ispell' on your system, or the PHP internal aspell functions - as it is rather slow it only shows up the first 20 errors on a page action/ plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Action plugins are those, that can be activated ON individual pages. And usually are shown as links below a page. The ewiki-builtin EditThisPage, BackLinks and PageInfo are ["action"] plugins for example. plugins/action/diff ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Enables to view the differences between two saved page versions (what changes somebody has done to the page), but it is rather stupid and guessworking in how it does so. plugins/action/translation ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin adds a link to the GoogleLanguageTools or AltaVista BabelFish, which then remotely translated the current page into the users preferred language. It has support to detect the lang of the current pages content, to redirect to the right service. plugins/like_pages ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ LikePages is a search feature of WardsWiki, which scans for WikiPages whose name is somewhat similar to the one of the current page (the pagename must be made up of the same WikiWordParts so a page gets listed). plugins/action/raw ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Can be used to download the unrendered Wiki source of a page. plugins related to hypertext links ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The linking/ plugin group deals with how links inside the Wiki will look and work. Some of them are would also fall the "core enhancements" group, while others are just handy or for link beatification. plugins/linking/tcn ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewiki evaluates the Accept-Language HTTP header modern browser send with each request. This plugin now automatically brings up a variant of the current requested page if it finds a match in the database. To make it work, you need to create pages with language suffixes in their names like: ThisPage.es ThisPage ThisPage.de or OtherPage OtherPage*nl Note, that there can always be one page in each name group without that suffix. This page then will be assumed to be in the default language set by EWIKI_DEFAULT_LANG. If multiple page versions are available, then a list will be printed above the page title to allow users to override the prefered language guess of this plugin. plugins/linking/plural ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin tries to alias plural and singular page names against each other. That is, "WikiPage" will be shown, whenever "WikiPages" was requested (and vice versa). plugins/linking/autolinking ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The autolinking plugin allows to have automatic links inside the Wiki for words which exist in the database, but are no real WikiWords. This is made possible by the companion StaticPage admin plugin "spages/Admin/PrepareAutolinking", which must be invoked from time to time to update the db cache entry, which the autolinking plugin utilizes. plugins/linking/link_css ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds CSS classes to the links generated by the Wiki page formatting kernel, which then allow you to colorize (or to otherwise change appearance of links) via a style sheet. plugins/linking/link_icons ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The link_icons plugin prepends icon <img>s before registered link types, like the link_css plugin adds class="..." attributes to the html formatted links in every page. plugins/linking/link_target_blank ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds 'target="blank"' to link tags <a>, which will result in most browsers opening pages in a new window. plugins/linking/linkexcerpts ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds a short preview text (with <a title="...">) to every link of a page. This however requires multiple additonal database accesses (slower) and could enlarge delivered .html page sizes dramatically. plugins/linking/linkdatabase ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is a page plugin, which provides a nearly compliant implementation of the page and link structure export function known from the UseMod WikiWare and MeatBall:LinkDatabase. This is useful for contributing to the upcoming InterWikiBatabase and BorgWiki. plugins/linking/instanturls ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to specify URL abbreviations on one or more summary pages. This can be done using a table or a definition list to assign each URL a title, which then can be used on other pages as square bracket reference. The 'instanturl_find' plugin in addition allows to use the [find:] moniker to perform partial searches in the list of URL abbreviations, but also in the list of interwiki monikers. As fallback it searches for matching page names or redirects to Google. plugins/linking/titlefix ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to swap [title|PageName] in square brackers [Page|title], because that can easily be detected, if the page already exists. plugins/interwiki/intermap ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin (in fact only a general include) extends the list of known InterWiki: prefixes with a more complete set merged from MoinMoin and PhpWiki's interwiki.map. The links are rather untested to work at the moment. appearance/ tweaks ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ There are various plugin hooks within ewiki, which allow to mangle text strings and data immediately before it would be returned as output. plugins/appearance/listpages_br ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin will produce <br> separated lists (for SearchPages, PageIndex, MostVisitedPages, and so on). plugins/appearance/listpages_ul ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Creates real <ul> lists (WordIndex, CreatedPages, ...) instead of the · ones, ewiki core would usually return. plugins/listpages_tbl ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The listpages_tbl plugin outputs a table instead of the ordinary page lists (PageIndex, UpdatedPages, ...). You need to edit its source to set colours to fit your site layout. plugins/appearance/fancy_list_dict ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The WordIndex and PageIndex plugins (unlike the other page list returning ones like SearchPages and UpdatedPages) can utlize this plugin to output a pretty dictionary like listing of pages. plugins/appearance/title_calendar ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Changes the titles of calendar plugin entries in the database into a more readable format for page lists (PageIndex, PowerSearch, UpdatedPages, and so on). page plugins ŻŻŻŻŻŻŻŻŻŻŻŻ The page plugins provide additional "generated/internal" pages, which have a standard WikiWordPageName and can thus be referenced easily from within ordingary WikiPages. But they are of course uneditable (because their content is 'hardcoded' as PHP code) and most action/ plugins cannot perform any function on them. With the rise of the StaticPages plugin, the page plugins are almost outdated, because all their code could now be extracted into a StaticPage file, so their code had to be loaded only on request (instead of including() them regardless if they're needed or not, how it currently is done). plugins/page/powersearch ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugins provides a (probably) better search function with the default page name "PowerSearch". It tries to guess a value, which tells something about how good a page matches the searched words and orders the found pages list by this (possibly not very useful) value. It prints the top 10 results more verbose. plugins/page/pageindex ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Lists all pages found in the database alphabetically. plugins/page/wordindex ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Lists the word parts of all wiki pages, but requires the powersearch plugin to be present, because the result is redirected to there as usually many of the listed words belong to multiple page names. plugins/page/imagegallery ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Outputs a page containing all cached/uploaded images. The images are currently not rescaled to fit on the page; this work is left to the browser. Needs enhancement. plugins/page/aboutplugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Lists all registered plugins (mpi, page, action, task/core). The name refers to the "about:plugins" page present in recent browsers. plugins/page/orphanedpages ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Shows up a list of pages, that exist, but are not linked from any other pages. These is often also called dead pages. Note that this plugin does not take into account, if any page can be reached from the frontpage - such a hypertext tree test would require much more work than realized in here. plugins/page/wantedpages ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Returns a list of pages to which QuestionMarkLinks? currently exist. plugins/page/since_updates ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Provides a list of pages with actualization times. plugins/page/textupload ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The virtual TextUpload plugin allows to insert new WikiPages by uploading text files. It can convert from various formats into Wiki content, including some proprietary Office file formats, if one of the possibile filters is avaiable (Unix style file piping). It also can extract multiple files from a Tarball or ZIP archive if the according utilities are available (even on DOS/Win systems). plugins/page/wikidump ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to download a gzipped tarball containing all readily rendered pages as .html files and also images. plugins/page/interwikimap ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Shows up the currently in use InterWikiMap. plugins/page/hitcounter ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Sums up the individual {hits} count of all pages and returns the overall count. plugins/page/scandisk ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Presents an unserious statistic. plugins/page/wikinews ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Returns the most recently added pages in an overview, that incorporates a small fragment from the content of those newly added pages. plugins/page/wikiuserlogin ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to set a free-form username, which then would be stored into the database whenever a page was edited. plugins/page/randompage ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Shows up a randomly choosen page from the database. plugins/page/fortune ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Calls the Unix /usr/games/fortune program and prints out returned content. plugins/page/ewikilog ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to review the content of the 'ewiki.log' file. plugins/page/phpinfo ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Shows the settings of your PHP interpreter. plugins/page/README ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Can parse the distributed README file and make a hypertext presentation from it, for easier reading of the Wiki documentation. It is printed in <pre> text, but with WikiLinking enabled (which however is rarely used in the README file). It additionally presents the README.de and README.auth files. plugins/page/wikiuserlogin ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to post a username (Note: this one does not do any sort of real authentication), which is saved in the http client as cookie, but can afterwards be evaluated as $ewiki_author, so the according field in the database entries contains a bit more than just the IP address when a changed page gets saved. markup plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The ewiki rendering core is rather fast and consolidated, that was the goal. However if you ever happen to need more functionality, this can be added easily by the use of plugins. Several are already available to emulate the WikiMarkup of other commonly used WikiWare. Other WikiWares markup ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The WikiWorld still lacks a unified markup (and thus also the interchangeablity that made html THE standard it today is), and while ewiki usues nearly MeatBall:WikiMarkupStandard, you may want to reuse existing pages from another Wiki. Currently we provide emulation for: * PhpWiki * sfWiki * miki * bbcode (BulletinBoard, not a Wiki) But please see the individual files on which (additional) markup they introduce. These plugins on occasion only register their markup within $ewiki_config["wm_*"] settings, but often just perfrom pre-conversion of foreign markup by utilizing the ["format_src"] plugin hook (they then pre-convert page content to use ewiki markup rules before the ewiki_format() kernel performs transformation). plugins/markup/css ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ CSS markup allows you to assign visual styles (or semantic CSS class names) to a block of text (paragraph) or to pieces of text. @@ is used to start a styled area. The @@ must be immediately followed by either a CSS class name (without the dot) or with CSS instructions without any whitespaces. The following text (after the @@, the class name and a space) will then be assigned the class until a (possible) next @@ without attached classname or style definition. If the @@ occurs at the start of a paragraph it will enclose it in a <div> with the according style assignment, otherwise (in the text) a @@ will become a <span>. See also the explanation and examples in this plugins` comments. plugins/markup/css_singleat ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin allows you (like the markup_css plugin) to attach CSS classes to a paragraph of text with just a single @ character: @JAVADOCLIKE paragraphs text... ... ... ... .... ... ... ... ... plugins/markup/footnotes ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Introduces the ability to generate footnotes by placing an explanation into double curly brackets {{footnote text}}. You should activate this only if you really need it. Sometimes this may be useful, but it is rather bad wiki style; because if someone would like to explain something in more detail he should create a WikiLink to a new page. So this should be used for very short explanations, say incomplete sentences or a book reference and other things where it really seems bloat to create a new page. USE THIS RARELY or better not at all! (this is a feature copied from MS` EvilWiki) plugins/markup/asciitbl ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to use ASCII-Art tables as outputed by lynx and other console programs inside of WikiPages, which eases life, when dealing with multiline table cell content. plugins/markup_complextbl ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewiki allows you to use tables with the || | characters in the wiki page source. However the html code for the table layout is hardcoded and cannot be changed on a per-page basis. This plugin intercepts the wiki source formation process to allow you to specify html tag attributes inside a table definition like: |{ border=0 cellspacing=10} here is | the table | content | | 2nd line | 2nd line |{ rowspan=2} fills two table rows | |{ colspan=2} 3rd line | Note, the opening "{" must follow the "|" character immediately. This code was provided by Hans B Pufal. It may be a security risk to include it per default, as this allows to add SomethingScript references as well. plugins/markup/htmltbl ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Provides a block escape to use the standard html <table> code instead of the limited pipe syntax provided by ewiki. It will parse for <tr> and <td> tags and strip any not registered attributes to defend against harm that could be caused by EvilScript additions. The common html <table> syntax then allows easily to include multiline table cell content, which is nearly impossible (to edit) for the "|...|..|" table syntax. plugins/markup_rescuehtml ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to use some 'safe' HTML tags within the WikiPage. This plugin replaces the previous EWIKI_RESCUE_HTML constant. Note that those 'safe' HTML tags may also lead to some confusion, especially if you have a wiki about HTML, because then you cannot write text about the <STRONG> tag because it will actually always be interpolated as itself and not as the text string "<STRONG>". plugins/contrib/rendering_phpwiki12 ----------------------------------- This is the rendering kernel of PhpWiki 1.2 which was made compatible with the ewiki function set. It may be useful to reuse old WikiPages, but anyhow most of its features are supported by the standard ewiki rendering kernel, so this is just a fun and proof-of-concept plugin. .................................................................. : The code of this module is covered by the GPL license, as it : : was copied verbatim from the PhpWiki project. : ·································································· plugins/rendering_null ---------------------- If someone would like to use ewiki for a personal homepage, but prefers HTML over WikiSyntax, then this rendering core replacement may suit his needs. It allows HTML to be used, but still renders WikiWords into valid hyperlinks (a few other features from the original ewiki_format function are also supported, but you can strip even those). mpi ŻŻŻ The so called "mpi" plugins can be embedded into pages, and produce their output there. They are loaded on demand (only if it appears that they should be invoked), but it is possible to include() the individual files regardless if they would be used or not. In order to have the mpi plugins available, you must however first load the mpi dispatcher: include("plugins/mpi/mpi.php"); Which then takes care of the markup and loading of the requested plugins. The syntax for calling a mpi plugin is (write this inside of a WikiPage, when editing it): <?plugin PluginName arg="..." arg2=DDD ?> Where args are often optional or could even be written without the 'argname=' if only one was required. The name of the mpi plugin is case-insensitive here. It is often possible to invoke mpi plugins like ["page"] plugins, if you create a link inside of the page using the syntax <?plugin-link PluginName ?> mpi_backlinks ŻŻŻŻŻŻŻŻŻŻŻŻŻ Prints a list of BackLinks to the current page (the same as when clicking on the title of a page or on the BackLinks action link). <?plugin BackLinks ?> <?plugin BackLinks page=ForThatPage ?> mpi_multimedia ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to <embed> multimedia files into a page. mpi_syndicate ŻŻŻŻŻŻŻŻŻŻŻŻŻ Embeds remote RSS feeds (abbrv. for "ReallySimpleSyndication" or "RichSiteSummary") into the current page. It caches the fetched data for quite some time in a pre-parsed _BINARY database entry. mpi_insert ŻŻŻŻŻŻŻŻŻŻ Allows to insert another readily rendered WikiPage into the current one, usually inside of a <table border="1">. mpi_localsitemap ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is a mix of BackLinks and LinkTree features, and prints the tree of pages backreferencing to the current one. visual extensions ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The hook following plugins utilize is called "append-view". It allows to put content below a pages contents (after the action links). plugins/aview/backlinks ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds the list of BackLinks (references from others to the current page) to the current page below it (this list is also available, when a user clicks on the title of a page). plugins/aview/linktree ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Prints the possible (shortest) paths to the FrontPage (determined by the EWIKI_PAGE_INDEX constant) starting from the current one below. Calculations and database access required by this plugin often means a slowdown up to 2 seconds before the page is readily rendered. plugins/aview/toc ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Analyzes a pages headlines and generates a list of contents box from it, which is inserted as float box on top of it then. Use the following CSS selector to style it: .wiki .page-toc { ... } plugins/aview/posts ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to add separate comment pages, which will then always be displayed below the current one, but remain editable as standalone pages. (So the page they are appended to could be marked as _READONLY). plugins/aview/threads ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to group the pages created using the "posts" plugin into threads. plugins/aview/subpages ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds the list of pages, which appear to be SubPages of the current one, below it. plugins/aview/downloads ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Shows the uploaded files, which appear to belong to the current page (individual pages can be treated as upload sections). plugins/aview/imgappend ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Prints an image uploading box below every page, which allows to append an image without prior clicking EditThisPage (the image will be automatically appended to the bottom of the page). plugins/aview/piclogocntrl ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin allows users to select a logo graphic which will be made available for use in the site template as $ewiki_config["page_logo"]. Configureable through the internal image list array. plugins/aview/aedit_pageimage ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin allows users to select a page image graphic, and is a mix of the aview/piclogocntrl and page/imagegallery plugins. plugins/aview/control2 ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Shows examplarily how to replace the standard "action-links" box, and adds it on top of the page (including the page title). plugins/aview/aedit_authorname ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds a text <input> field below the edit/ box, which allows to set the AuthorName which then will get stored, when the page is saved. This name is then also stored client-side as cookie for at least 45 minutes. Before using this plugin, you must consider, that it eventually allows to override the correct username that ProtectedMode plugins already provided. And there is no way to prevent users from using faked names (because this plugin cannot check if a username was already 'registered' and thus can't initiate a password query). plugins/aview/aedit_deletebutton.js ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds a JavsScript snippet to allow users to quickly mark a page for deleterequest, by inserting the link to "DeleteMe" into the contents, when editing it. page filters ŻŻŻŻŻŻŻŻŻŻŻŻ A few plugin hooks exist to completely rework generate page output. These are often used to insert content into the otherwise readily rendered .html pages (some of the above aview plugins do so, too). plugins/filter/f_fixhtml ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is a minimal tag balancer (a highly simplified HTML tidy) and can work around various html code problems that the ewiki_format() html rendering function has. It is for example specialized to correct broken html that resulted from WikiMarkupAbuse as for example nesting text style attributes like this: __''text__'' plugins/filter/search_highlight ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Evaluates the Referer header sent by many browsers to detect if a visitor came from a search engine (even the internal PowerSearch or SearchPages ones) and highlights the searched words in the current pages body (using CSS). plugins/filter/fun_chef ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Borg, Borg, Borg! plugins/filter/fun_upsidedown ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Transforms a pages content using letter transformation to make them readibly from upside down with certain fonts. This however is a bit tricky for html pages and thus will always wrongly intermix sentence order. plugins/filter/fun_wella ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Adds a little CSS to make text swirrling on both sides. plugins/filter/fun_screamomatic ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Detects if someone entered a FULL LINE OF YELLING into a page when editing it, and then sets a persistent cookie. That cookie will result in all pages contents to be converted into uppercase characters. plugins/filter/f_msiepng ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Converts .png <img> references in the WhateverX code required by all current IE versions to display .png images according to the specification (which currently only an IE external plugin can handle correctly). BloatWiki extensions ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewiki slowly evolves into a well-bloated portal software, and some plugins already extend it far beyond the scope of an ordinary Wiki. plugins/module/calendar ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The calendar plugin enables you to add an editable calendar to every WikiPage. It is not a fully integral part of ewiki, and needs additional calls from yoursite.php to integrate nicely into your sites layout. You even don't need to allow a calendar to be added to every page, you can just include the plugin file and use the _one_ page called "Calendar" or "YearCalendar", where everybody can make additions. The coolest about this plugin is, that it nicely integrates into the common WikiNameSpace. Just include("plugins/calendar.php"); so it gets available. In yoursite.php integrate it as follows: <?php ... echo ewiki_page(); // print current pages content, as usual ... if ( calendar_exists() ) { ... echo calendar(); // print calendar for current page } else { ... // else only a link to the cal. page echo "<a href=\"?id=calendar/$ewiki_id\">ShowCalendar</a>"; } ?> The calendar() function call emits the html for the calendar of the currently viewed page (see ewiki_page() call). The function calendar_exists() only checks for already existing event entries in the calendar, so the calendar won't show up, if there isn't yet anything inside (so only the "ShowCalendar" link at the bottom of the page will link to the still empty calendar). You can of course leave out this function call or alternatively call it with calendar_exists($always=true) if you want the calendar to appear most of the time / or for all pages. Please note the "fragments/calendar.css" file, which illustrates how to tweak layout and look of the generated calendars. This plugin was contributed by Carsten Senf (originally implemented for good old PhpWiki). plugins/module/downloads ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ From the very beginning the ewiki core supported uploading image files into the database. As time and discussions went on, there came the idea to allow arbitrary binary files to be inserted too. The old EWIKI_ALLOW_BINARY way should now be avoided, because the download plugin adds more functionality and more features, and is easier and more intuitive to use. It adds the virtual page FileUpload to insert a file into the database, and the page FileDownload, which lists all available and uploaded binary files from the db. Please note, that due to the use of the database interface, the file sizes are usually limited to 1-2M (depending on PHP and MySQL settings), so there may still be some need to reimplement this, using the antique world-writable incoming/ directory method. The mime_magic plugin should be used together with this one, and you should change the icon file names (use the ones from the Apache distribution for example). (It may also be a good idea to run a secondary database if you use it. Have a look at fragments/binary.php, and set up a secondary ewiki database using it and the db_flat_files plugin. This is useful, because you then can more easily delete uploaded files as they don't get saved into a SQL database.) Different download sections can be defined. The "*" merges all allowed sections into one list again, and the "**" section even lists the files attached to pages. The page attachment link (to append download functionality to each page) can be revoked by unsetting the $ewiki_plugins["action"] line in the downloads.php file; so only the default sections are accepted (and page names rejected). The plugins/downloads_view.php brings up the list of uploaded attachments below each page (if existing). It works rather fast due to an improved database search call, and should therefore be activated whenever you use the per-page attachments feature. See also plugins/binary_store.php to keep your SQL database small, but note its limitations. plugins/module/tour ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Provides a shortened view of the current page and all linked ones (even the backlinked ones). This eases navigation and page content "scanning" (getting a quick overview). utility code ŻŻŻŻŻŻŻŻŻŻŻŻ The plugins/lib/ directory contains code and functionality, which often is required by some of the other plugins (they depend on it then), but which was too specialized to get part of the ewiki.php core script. Other extensions in the lib/ subdir didn't match in any of the other plugin categories. plugins/lib/cache ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This plugin stores readily rendered Wiki page content (already in html format) either into a dedicated directory, or into specially named _BINARY wiki database entries. This then allows to satisfy further requests to a page with the saved content. You should set EWIKI_CACHE_DIR to a useful value (a so called "chmod 777" directory, so your webserver process can write into it), or alternatively unset this constant and instead define EWIKI_CACHE_DB so cache entries get stored into the ewiki database. The _CACHE_DB constant is just prepended to the name of the current page to get the name for the database entry for the cache data. plugins/lib/speed ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Evaluates the "conditional HTTP request headers" to tell a client if it could reuse its existing cache entry for a requested page. This is believed to reduce traffic and also speed up some applications. However it is still rather untested and could anyhow lead to some problems (never updating pages for some broken browsers). The evaluated headers include "If-Unmodified-Since:" which corresponds to the "Last-Modified:" answer header ewiki always sends. However this will only work, if you disable EWIKI_NOCACHE - but then some browsers will never see updated pages, if they were misconfigured to not refetch pages, once they got into the internal browser cache. (But on the other hand, that is users fault ;) plugins/lib/mime_magic ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Implements the mime_magic feature absent from some (older and misconfigured current) PHP interpreter versions (check your phpinfo and /etc/mime.types). This is recommended in conjunction with the downloads plugin to store correct mime type data, for proper use of icons beside download links. Also the correct Content-Type header should always be available, when binary content is delivered. .................................................................. : The data of this plugin is covered by the GNU General Public : : License. : ·································································· plugins/lib/navbar ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Provides a configureable menu for the contents of your Wiki for inclusion in your site template, which changes depending on which site area you're currently inside (determined partially by the linktree plugin). plugins/lib/protmode ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is an extension package (currently in development) with various helper functions for ProtectedMode plugins. Especailly useful in conjunction with the auth-liveuser framework. plugins/lib/save_storevars ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ An example script on how to store additional vars into page entries of the ewiki database (session like). admin/ plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Collects plugins for ewiki / database administration. Often these depend upon $ewiki_ring==0 (superuser authentication level in EWIKI_PROTECTED_MODE), otherwise refuse to work for security reasons (some functions are however available to moderators too, ring level 1). Some of these plugins may be reimplementation of stuff from the tools/ directory (integrated database tools). control ŻŻŻŻŻŻŻ Allows changing per-page settings, and adds a easily accessible "page control" action link below every page. You can use this to immediately change per-page flags (_READONLY, _HTML, _DISABLED and so on). Or you can delete a unwanted page as soon as you discover it. It also enables you to edit any entries in the {meta} field of database entries (which sometimes contain HTTP headers, or page "class" settings). And the fourth possible action is to easily rename the page (with letting ewiki adjust all links to it without further intervention). SearchAndReplace ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is a powerful text/content replacement tool. It features regular expression matching, but can also be used as any other simple string replace-all tool. SearchCache ŻŻŻŻŻŻŻŻŻŻŻ This tool is intended to create 'shadow pages' (or 'ghost pages') for ewiki internal/generated pages (the ["page"] plugins), which usually weren't found by the PageSearch and PowerSearch. This admin plugin just innovocates those page plugins and puts their html output into the database (which then can is found by the search functions, but is never displayed, because the page plugins still have precedence over that faked database content). other plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻ These plugins actually implement some stuff, one usually should do inside of the yoursite.php ewiki wrapper script. plugins/debug/ ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Eventually contains debug plugins. plugins/auth/ ŻŻŻŻŻŻŻŻŻŻŻŻŻ Contains various (example and ready to use) plugins for the ewiki_auth() interfaces. This directory contains its own README.auth, which describes the _PROTECTED_MODE, the _auth API and available sample plugins in detail. plugins/auth-liveuser/ ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Contains the more advanced authentication and permission plugin bundle for chaining ewiki with the PEAR LiveUser authentication framework. There is detailed documentation within the README in this subdirectory. separate "extra" tarball ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ There are a few plugins and extensions, which are not packaged into the distributed ewiki tarball for size reasons. You can obtain it from your favourite dealer, or from our downloads/ directory as "extra-CVS-*" tarball. http://erfurtwiki.sourceforge.net/downloads/ The package currently just contains a minimal spam filter (which after all isn't very useful for a Wiki site), but in the future will also provide additional example/ layouts and some image/graphics/icons for layout beatification purposes. -------------------------------------------------------------------- 7 -- More separate files ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Even if one of the project goals was to have everything in one script, there are now some support scripts around it, but those are normally only required for setup (init-pages for example). With some others you need to take a lot of care before installing on a public WebServer (the tools/ for example). Pages in init-pages/ ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This directory just contains text-files with the wiki_source of the initial pages, which are inserted if you start ewiki.php for the first time. You can create these files with the tools/ewiki_backup.php script or the 'ewikictl' commandline utility. Additional tools/ ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This directory holds some (external) add-ons, which are intended to supply "admin functions" for the ewiki database. It is strongly discouraged to integrate this with ewiki, as it could be dangerous to have them always around and usually such stuff just complicates things (wiki's should be easy to use). Per default you will be presented a HTTP Basic AUTH login dialog box by your browser if you try to use one of the www tools. This is made to prevent other people from doing any harm to the setup. In the "tools/t_config.php" script you'll see a link (include) to "fragments/funcs/auth.php", which is responsible for this integrated security feature. Just insert a username and a password here to start using one of the tools/. Please keep in mind, that the $passwords array of that ".../auth.php" script has nothing to do with the _auth API or EWIKI_PROTECTED_MODE. Because the www tools (all stuff named "t_*.php") use the "ewiki.php" script and the sample "config.php", you eventually need to configure these tools separately (they don't need any ewiki plugins, but the database ones, if necessary). So if there are problems (for example if your ewiki setup is configured with ewiki_auth, which then could overlap with the ".../auth.php" script), you may need to edit the www tools own "t_config.php" accordingly. (Note: This is not required for the default setup.) If you'd like to integrate the tools/ as virtual pages into ewiki, then the StaticPages plugin will help. You then needed to remove the line that tries to re-include() your config.php and ewiki.php from the tools/ "t_config.php" script (else you'll break ewiki). To load your tools/ as static pages into the wiki, you then just needed a call to ewiki_init_spages() with the "./tools/" directory as parameter. tools/t_flags ŻŻŻŻŻŻŻŻŻŻŻŻŻ WikiPages usually have the page flag TEXT assigned. Other possible flags are DISABLED, SYSTEM, BINARY or HTML, READONLY, WRITEABLE. Usually page flags are copied from one page version to the next. tools/t_backup ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Use this to make backup files from the WikiPages. This www script is a wrapper around the ewikictl commandline utility and library, and therefore supports almost the same options. tools/t_restore ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to reinsert the files generated with the backup utility into the database. It is also a www wrapper around ewikictl and thus also supports the "plain", "flat" and "fast" file formats. tools/t_remove ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Use this to delete a page from the database (including all saved versions). You should always prefer to set a page DISABLED with the ewiki_flags tool to hide unwanted content. -- make love() not unlink() tools/t_holes ŻŻŻŻŻŻŻŻŻŻŻŻŻ If pages are edited often / regularly you will soon get hundreds of saved page versions. As this slows down (particularly the db_flat_file ones) and enlarges the database content size, you may want to strip old versions. This tool suggests you to remove a few page versions. You should however NOT DELETE the page VERSION ONE and the very last (newest) page version (of course). The page version 1 often contains control data, not found in newer versions, when db_flat_files or db_dba is used, so please keep aware of this. There were some changes necessary in db_flat_files to support those "version holes", but it currently seems to work stable. tools/t_textinsert ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Can insert plain text files into the database. This is much the same, what usually happens to the files inside init-pages/ tools/t_transfer ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Allows to download all pages in one big "binary" file, and to reinsert it on the same way. This allows for quick moving of the whole database content. tools/t_revert ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Can undo mass changes caused by a script attack (specifically designed to spam or corrupt a Wiki) or someone who put enourmous energy into garbaging multiple pages. The {auther} field always contains at least an IP address to allow easy tracking of such activity, and this plugin just enables you to remove page versions whose {author} field matches a certain string (the attackers IP address). tools/ewikictl ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ewikictl is a commandline based utility - as opposed to the www/http based scripts mentioned above. UNIX people will find it very useful and handy, while it is believed to work on Win32 systems too. It integrates a lot functionality of the web based tools/, some of them less flexible and others more powerful than in the other tools. It, for example, allows to generate database backups automatically and is often easier to use. On the other hand it will be of little use if you don't have a shell account on the WebServer running your wiki (because most times one cannot make remote mysql server connections). The most important feature is to make backups using the --backup switch: All pages from the database will be saved into backup files in the directory given by --dest (or if not given into './backup-<currentdate>'). The --format of the backup files can be: plain, fast, flat or xml, meta, xmlmeta, sql, mysql. But remember that only the first three mentioned formats can be reinserted using the ewikictl utility. You really should give the --all parameter too, whenever you make a backup, because else only the very last version of each page will get saved (and think of a garbaged last version, this would be a bad idea). So USE --all ALLWAYS! Backups can be reread into the database using the --insert switch: The --dest or --source parameter says where to search for the save page files, and the --format option again tells the correct backup format (you will get a garbaged database if you get it wrong). The --all option is of course necessary again if you gave it when doing the --backup, and ewikictl will complain if it believes the --all option was required. You can also use --insert to initially fill a database, or to add just a few new pages, as pages inside the database will never be overwritten by the ones added with --insert. The --insert switch also allows to be used to load just one file into the database. --insert <WikiPageFileName> Another function is to speed up the database, by creating version --holes: If you utilize the db_flat_files and you have hundreds of versions for one page, things may get slow at some point of time, so you may wish to remove some of the unneeded versions. That is what the --holes is for, it strips some of the page versions from the database. Please keep in mind, that the very first version of each page may contain special control data, which is not available in the following ones (this is especially true for db_flat_files). Per default the 2nd version of a page until the 10th before the last page version will be removed. You can however specify this range yourself: --holes 2..-10 (default) --holes 5..-5 (5th until 5th before last version) Please also keep some versions at the end, as the very last one may contain mangled text (if someone backspaced around). The --all option is implied for --holes, but you can and you should combine --holes also with --backup. This special feature will save a backup into the --dest directory ('./holes' per default) before the page version is removed from the database. --format The default backup/insert format is the 'plain' one - which means just a pages content will be saved into the files. It is however recommended to use the "--format flat" or "--format fast" instead, as both can contain the complete meta data of a page. --ls Will print a directory-listing like list of all pages from the database. You can add a pagename as parameter, so only that one will get shown. --reset <pagename> --disable <pagename> --enable <pagename> --html <pagename> --readonly <pagename> --writeable <pagename> Will set the according page flags for the given page. You can give the page name also by using the --page or --file or --id switch. --chmod <flags> Will set the page flags to the given decimal value. The pagename must be given using --page, --file or --id. This option of course requires knowledge of the flag/option values and their numeric/decimal representations. --unlink <filepattern> Can be used to delete a page. You can use the asterisk to remove more than one page, just an '*' would for example delete all pages. NOTE that you can also use this utility without a shell account on your WebServer, if you create temporary .php wrapper scripts, that contain nothing more than: <pre><?php echo `./tools/ewikictl -ll`; ?></pre> Please search google or freshmeat.net for one of those shell faking CGI scripts, to ease this, so can get the most out of ewikictl. tools/wiki2html ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Renders the WikiPages and saves the resulting <HTML> bodies into files. It currently cannot deal with images and binary content correctly. tools/mkhuge ŻŻŻŻŻŻŻŻŻŻŻŻ For lazy people - if for some reason your text editor does not allow to enter the correct include() commands for the files from the plugins/ directory you may find this shell script useful to create a monster version of ewiki (plugins and core script merged together into one file). See the paragraph about "monsterwiki.php" for more detailed infos. tools/mkpluginmap ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Is the companion tool for the new ewiki pluginloader extension. It traverses the plugins/ directories and generates a list which allows automatical loading of ["page"] and ["action"] plugins. Use the output of this script to replace the list of available plugins inside of the "pluginloader.php" script. But don't forget to disable that extensions, that you wouldn't like to be available. tools/mkpageplugin ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Can convert any StaticPage file (from the spages/ directory) into a standard ewiki page plugin (to get included() like all the others then). It detects automatically the type of the given StaticPage input files - Wiki source (.txt), ready HTML content, or even PHP code. It's intended as help for the unexperienced PHP user, or if you needed to mass convert StaticPage files into plugins. But please note, that including() hundreds of page plugins slows down the PHP interpreter and eats a large amount of memory (and this was the reason for extracting some page plugins into StaticPages). examples/ ŻŻŻŻŻŻŻŻŻ The file "examples-1.php" is the default layout, which you will see, when you first run ewiki. The examples/ subdirectories now holds further example 'ewiki wrappers' or 'layout scripts' (commonly referred to as "yoursite.php" scripts in the README). There is not much further interesting stuff in here. If you can make a contribution, just do (however, in the ewiki core tarball, we don't want an image or graphics directory). examples/homepage.php ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This is an example on how to use ewiki.php with an authentication frontend. Note that this is not the recommended way to use a wiki (adding authentication can be considered "crippling" a wiki). "Authentication" means just a JavaScript based password query dialogue (the password is however checked server-side inside the homepage.src script). You should install it preferably as index.php as described on top of the file, the ewiki.php script must be there too. Edit the source and colours to suit your needs. Guess, it needs some images as well. Nice things in fragments/ ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This directory holds some files to integrate ewiki.php within some other web projects (for example PhpNuke) or some helper and extension code, or just other example layouts. Please have a look at the fragments/README - and as usual into the files itself!! strip_wonderful_slashes.php ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you have a PHP 4.1 or a provider using the annoying factory-default settings of such a version, you may find this tiny script helpful. It removes the just-for-security-reasons-added-backslashes from the $_REQUEST variables. I wasn't very interested in adding hundreds of stripslashes() calls inside ewiki.php, so this is the workaround for __your__ providers broken php.ini fragments/funcs/wiki_format.inc ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ This php include() file contains just the reduced wiki_format() function, the code to generate internal WikiLinks and the binary data stuff has been removed. It is best suited to allow rendering of WikiSource with other php projects. The script was contributed by Frank Luithle. 404finder.php ŻŻŻŻŻŻŻŻŻŻŻŻŻ Simple example on how to use "ErrorDocumet 404" rediriction to activate the ewiki page search function automatically, which is the poor mans mod_rewrite. htaccess ŻŻŻŻŻŻŻŻ To make a Wiki installation look more profession you should try to use your Webservers mod_rewrite module to get nicer looking URLs. This file is an example to be installed as ".htaccess" (Web server per-directory configuration file), which allows to call your ewiki wrapper using URLs like: http://www.example.de/wiki/SomePage http://www.example.de/wiki/edit/OneOfThePages (For this example, you needed to set EWIKI_SCRIPT to "/wiki/"). This example '.htaccess' script shows how to instruct mod_rewrite to catch above URLs and to transform them into ".../index.php?id=Page" again before calling the script. binary.php ŻŻŻŻŻŻŻŻŻŻ If your ewiki wrapper script is not binary safe (that is, eventually printing some <html> or text output to stdout before you include() the core ewiki script and called the ewiki_page() function) - then you may need to place a secondary ewiki wrapper besides the one dedicated to pages. The "fragments/binary.php" gives an example and further instructions on this issue. fragments/funcs/auth.php ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Include this script wherever you need authentication. It uses the HTTP Basic Authentication scheme, but the passwords are inside the script in the $passwords array (so no need for .htpasswd setup). Note that this script needs to be called before any body output is made (else it would be too late for http header() output). fragments/css/* ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Please understand the *.css as examples that illustrate which style classes are defined inside ewiki.php and its companion plugins. Remember, you could insert those files with PHPs` include(), too - if desired (and if a <style> area is currently to be written to stdout). fragments/blocks/* ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Contains small include() scripts to be loaded into "yoursite.php" as "sidebars" and the like for beatification purposes. Oftens these are reduced but useful ["page"] or ["action"] plugins, performing common tasks, like printing the list of newest pages or some sort of menu, or even random page links. Other patches/ ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ In the patches/ directory some code tweaking tips are collected that are either not worth a new plugin or to uncommon and unsafe and unsupported to get into fragments/ or plugins/. Please see the README and the files therein for more informations. I often like to refer to that subdir as the "recoding FAQ". Updates + How to deal with tweaked code ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ If you ever happen to recode parts of a plugin, WHICH WE STRONGLY ENCOURAGE TO DO (to match it better to your needs) - then there is always the risk of losing your changes as soon as you upgrade and overwrite everything inside of plugins/ Therefore it is recommended to create a subdirectory like "local/" where you copy changed plugins into, then include() them from there instead of the distributed default from plugins/. So you won't lose your changes and enhancements if you upgrade to a newer version. You of course should then check (after updates) if the newer version of a plugin contained enhancements you'd like to merge with your cutomized version of the earlier plugin incarnation. For the main "ewiki.php" script, things are of course more difficult, as you will probably always overwrite it when you update your installation. Best approach is to keep a NOTES file, where you store your patches for later reinclusion with newer releases, or even to keep always a second copy of your tweaked "ewiki.php". Much better was of course to send your changes to the ewiki -dev people so they could merge them into the CVS, so everybody could enjoy your ideas. -------------------------------------------------------------------- 8 -- Extension HowTo ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Best way to extend it is to read the man page on vi or emacs ;-> However the tool that made this all possible was joe. the PlugInterface ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The $ewiki_plugins array holds an array of "task names" connected to function names (that of course should do something senseful). As an example: $ewiki_plugins["image_resize"][0] = "ewiki_binary_image_resize_gd"; connects the task name "image_resize" to function already inside ewiki.php, and the task "image_resize" will be called for every uploaded or to be cached image. The function name here does not say anything about the parameters the function will be called with later. You have to look up the original function implementation in ewiki.php to see which parameters will be passed; so you could write your own task plugin. The [0] in the example above shows that this is the very first registered function for the task "image_resize", there could be others as well. So if you write a plugin you should take care to add your function name using $ewiki_plugins["task"][] = "my_func" so you won't overwrite a previous function name ''registration''. There are of course tasks like ["database"] where only one of the plugin functions will be called, in this case you should of course overwrite [0]. Two special case "tasks" are ["page"] and ["action"], because they aren't counted with numerical indices, but instead carry WikiPageNames or other idf strings as array/hash index. plugin tasks ŻŻŻŻŻŻŻŻŻŻŻŻ Here's a short summary of current PlugInterface "tasks" and (recommended) function interface definitions (the "= function (..." lines). A plugin hook with [] means there can be multiple, and each one would be tried. basic ----- ["page"][$PageName] - called for requests to page "$PageName" (like "SearchPage", "NewestPages") = function ( $id, $data, $action ) ["action"][$ACTION] - called for requests with url "?id=$ACTION/pagename" (core actions are "edit", "links", "info", "view") = function ( $id, &$data, $action ) ["handler"][] - called from ewiki_page() on start-up, if it returns a string the page was handled and no further processing takes place, the plugins output is used = function ( $id, &$data, $action ) rendering --------- ["render"][0] - alias for ewiki_format() - our "WikiKernel" ["format_source"][] - called inside the format function for the wiki source, implement this or the following ones to use complex wiki markup = function ( &$wiki_source ) ["format_line"][] - generic call from inside wiki format engine for every line, you may need to use static vars inside your plugin function = function ( &$o, &$line, &$post ) ["format_tbl"][0] - called to handle "wiki|table|markup" (the first and last | are already stripped) = function ( &$o, &$line, &$post, $tbl_open=0 ) ["format_final"][] - call after wiki source was transformed into html (WikiPageLinks were already interpolated too) = function ( &$html ) ["format_block"][] - called, with the page fragment extracted using the string patterns of the according $ewiki_config["format_block"] entry = function (&$currbuf, &$in, &$iii, &$s, $btype); ["format_para"][] - called, if the $para (text enclosed in <p></p>) is to be written into the output stream $ooo[$in][0] = function (&$para, &$ooo, &$s); ["link_url"][] - called to transform wiki source references = function ( $href, $title ) ["link_final"][] - called from ewiki_link_regex_callback to transform the final <a href> = function ( &$str,, $type, $href, $title ) special tasks ------------- ["database"][0] - only [0] will be called in favour of the ewiki.php internal ewiki_database_mysql() = function ( $action, $args=array() ) ["image_resize"][] - all [] registered functions will be invoked = function ( &$content, &$mime, $return=0 ) ["mime_magic"][0] - hooks before save_binary/image to fetch the correct mime type for non-image files; nowadays just an always-available get_content_type() = function ( &$content ) ["binary_get"][0] - the binary_repository handles large/binary content (to separate it out of the standard sql-database), usually just sending it to stdout = function ( $id, $meta ) page lists ---------- ["list_pages"][0] - <li>st generating callback function = function ( $lines ) ["list_dict"][0] - special variant of the above one (called just for / from within PageIndex and WordIndex listings) = ??? ["list_transform"][] - works on the given list of links (text transformations) = function ( &$lines ) ["make_title"][0] - allows to chain a replacement function for ewiki_make_title() = function ($title, $class, $action, $go_action, $may_split) ["title_transform"] - changing the currently linked title (called from within _make_title) = function ($id, &$title, &$go_action) page transform / additions -------------------------- ["view_append"][] - output will be printed below a rendered page = function ( $id, $data, $action ) ["view_final"][] - can rework the full html of the rendered page = function ( &$html, $id, $data, $action ) ["view_append"][] - add <html> code at the end of the currently viewed page = function ($id, $data, $action) ["view_final"][] - filter hook for final processing of "view/"ed pages = function ($o, $id, $data, $action) ["page_final"][] - filter hook for final processing of any shown page (any action: edit/, view/, info/, ...) = function ($o, $id, $data, $action) edit/ hooks ----------- ["edit_preview"][] - called if edit pages [preview] button pressed = function ( $data ) ["edit_form_final"][] - add <html>/<form>s to the edit/ page = function (&$o, $id, &$data, $action) ["edit_form_append"][] - insert other <input> fields between <textarea> and <submit> button on the edit/ page = function ($id, &$data, $action) ["edit_hook"][] - chains into before the edit box is printed (to allow security checks, pre-edit-tweaking, ...) any output terminates the current edit/ attemp = function (&$id, &$data, &$hidden_postdata) ["edit_save"][] - immediately called before saving the currently "edit/"ed page into the database, allows last transformations or rejection (unsetting $data) = function (&$data, &$old_data) ["edit_patch"][0] - special hook for the patchsaving plugin = function ($id, &$data) bloat extensions ---------------- ["auth_*"][] - plugin tasks used with ewiki_auth() = see the plugins/auth/README.auth ["mpi"][...] - markup plugins, see next paragraph ["init"][] - run once, when the main script is included() ["page_init"][...] - init functions, called when ewiki_page() is called the very first time aliases and variants -------------------- ["action_always"][$ACTION] - are called with precedence over ["page"] plugins (for example "links" which also works for registered page plugins) ["action_binary"][$ACTION] - action/admin plugins which do not care, if the current page actually is binary data Some other entries have been re-extracted into $ewiki_config, because they were falsely in $ewiki_plugins. See the paragraph at the start of the README on the $ewiki_config array. This list will probably not stay up-to-date, so please grep the ewiki.php script for all occurrences of 'ewiki_plugins["', and you can of course invent some new and tell the author how it helped you to implement something very different. mpi plugins ŻŻŻŻŻŻŻŻŻŻŻ Plugins of the class "mpi" extend the wiki markup with html like calls to dynamic content generating functions. They were taken from the ewiki adaption of Hans B Pufal and are very similar to the plugins found in PhpWiki. In order to use them you must first load their generic PlugInterface file using include("plugins/mpi.php"); Afterwards you could include all the wanted mpi extension modules, using include() again: include("plugins/mpi_calendar.php") You can then call those plugins from the wiki markup like: <plugin: calendar> <ewiki: calendar> <mpi: calendar> <?plugin calendar?> There are many different plugins available (not all included with this ewiki distribution), and the allowed arguments differ widely (must all be noted inside the < > and are written in arg=value style separated by semicolon): <plugin: plugins> <plugin: calendar year=2005; month=7;> month_offset=0; start_wday=0; wday_color=#999999; today_color=#ffcccc; wend_color=#bbbbbb; <plugin: environment> info=45 <plugin: insert !WikiPageName> # this includes the referenced WikiPage in a box # into the current one, Note the ! to prevent that # WikiWord from getting rendered (before mpi sees # it) <plugin: page_flags> # I strongly discourage this mpi plugin to be # loaded as it allows such easily to spy page # security settings authentication/permission plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The paragraph and descriptions about the _auth interfaces have gone into plugins/auth/README.auth writing your own plugin ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Using the list of current plugin tasks, you could (hopefully) write your own extension with ease. It is probably most simple to write a dynamic ["page"] plugin, so we start with this as example. All you need is a function definition like: function my_page_plugin($id, $data, $action) { return("This is the returned page <b>content</b>."); } And then just register it as ["page"] plugin, using your defined function name (yes, this does NOT need to start with the usual "ewiki_" prefix!). You also need to tell ewiki about the WikiPageName under which your plugin should be made available: $ewiki_plugins["page"]["MyPagePlugin"] = "my_page_plugin"; That's it. But of course your function should do something more useful, than just returning a hardcoded html string - even if this all, what's necessary here. The parameters to your ["page"] plugin function you'll often just want to ignore, and implement your plugin functionality (hard disk formation e.g.) independently from such things. It is likewise easy to write an ["action"] plugin; but this type of plugin should then process some parts of the $data entry and work for nearly any page (extracting contents or presenting the current page differently). So this kind of plugin could be used to initialize a download for the current page or to allow to email it to someone else (beware of the spammers!). format_* / rendering plugins ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ It is rather simple to add WikiMarkup using the $ewiki_config["wm_..."] settings, but for some tasks you need stronger weapons like rendering and markup plugins. The ewiki_format() function (often blatantly referred to as "rendering kernel") recently got rather complicated to add support for the 'block' plugins. Therefore we'll first need to discuss the variables structures and names used inside of it: ewiki_format() internals ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ When the function receives the input string (WikiSource), it first escapes all html tags using & < > to replace the & < > chars (because HTML is not allowed within Wiki, initially). Then it runs optional ["format_source"] plugins on the whole wiki page (still one source string). Afterwards ewiki_format() starts to split that wikisource into fragments meant to get handled by ["format_block"] plugins AND/OR the Wiki -> HTML transformation code inside of it. It creates an array called $iii[] from it - each fragment being an array on its own: $iii[0] = array( 0 => "WikiSource ...", 1 => 0x0FFF, 2 => "core", ); Initially we here just have one fragment [0] - and often this remains the only one (if no block plugin activates for the current WikiPage). The 0=> entry contains the body (wiki source) of a fragment, while at the 1=> index you'll find the block flags and 2=> is just the name of the block plugin to handle that fragment. If there is some block code, like <htm>...</htm> or <pre>...</pre> in the WikiPage, you'll end up with a larger $iii[] input array: $iii[0] = array("WikiSource...",0xFFFF,"core"), $iii[1] = array("<b>....",0x0002,"html"), $iii[2] = array("text",0x0FFF,""), Besides the $iii[] input array, we'll also have an array containing rendering status variables called $s[]. The most important entry there is $s["in"], which is the index into the currently accessed $iii[] wiki page source or block fragment. And ewiki_format() then uses various alias variable names for entries of the status var $s[] array - for example $in and $s["in"] are the same index number. After ewiki_format() separated the input source into the block fragments of $iii[], it will then run the actual ["fragment_block"] plugins on it. These can then apply regexs on them, or strip the fragments completely out of $iii[] or transform then into regular wiki source. Then the large wiki transform loop comes into action, but only for $iii[] fragments, whose flags (in the $iii[...][1] number) have the bit 0x0001 set. Other blocks/fragments of $iii[] remain untouched. While transforming the $iii[] arrays WikiSource a new fragments array will be created, called $ooo[] - the output array, which has exactly the same layout. And every $iii[$in] directly maps to the $ooo[$in] - same index number! But the later then already contains <html> instead of wiki source. Inside of the transformation loop, two other plugin types are activated (besides applying the $ewiki_config["wm_..."] ruleset): the ["format_line"] and ["format_para"] plugin groups. After all $iii[] blocks have been transformed into $ooo[], a second loop will check the flags (this time $ooo[...][1]) for the bit 0x0002 which tells, if WikiWords should be transformed into html <a href=> links. After link conversion (on the selected fragments), all blocks (the content entries $ooo[...][0] of course) of $ooo[] are merged together into one <html> string. After the ["format_final"] plugins run over this, ewiki_format() returns the resulting <html> page. the format_ plugin hooks ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ As denoted above, the ["format_source"] and ["format_final"] plugin hooks are the simplest to work with, as both only get one parameter (passed by reference) containing either the full WikiPage source text or the already fully rendered <html> output. The ["format_line"] and ["format_tbl"] hooks are also rather simple, lookup their interface to know which variables you could modify. The ["format_para"] and ["format_block"] plugins both recieve either the $iii[] or $ooo[] and status $s[] array variables (plus a few aliases and shortcomings). This makes these hooks look a bit more complicated, but allows great flexibility - a "_block" plugin could for example merge its $iii[] fragment with another one, or replace itself with nothing. To write a markup plugin, you should lookup the actual interface in the 'ewiki.php' script or in this README. And don't forget that most parameters are meant to be passed by reference to be useful! $iii[] and $ooo[] block flags ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The $iii[...][1] and $ooo[...][1] hold the flags (as defined by $ewiki_config["format_block"][...][2]) for each fragment of the WikiPage. The "core" blocks (plain WikiSource) always have the default 0x0FFF assigned. Currently used bit values are: 0x0001 - render WikiMarkup 0x0002 - render WikiLinks 0x0004 - international character &#htmlentities; allowed 0x0100 - fragment further (other block plugins can split it) pseudo-values (OR checks): 0x0011 - consider to be inline block between WikiSourceBlocks (prevents paragraph breaks between plugin and wiki block) 0x0022 - scan for WikiWords in this paragraph