-
-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 <mario*erphesfurt�de> icq95596825 (+Yah,Jab)
-main contributor: Andy Fundinger <andy*burgiss�com> 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. <note> I didn't want to
-include a LICENSE file larger than the program itself. </note>
-
-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 <html><body> tags
-around the output from ewiki. The most simple script to accomplish
-this could look like this (see also example-2.php):
-
- <HTML>
- <BODY>
- <?php
-
- mysql_connect("localhost", "DB-USER-NAME", "PASSWORD"); #[1]
- mysql_query("use DATABASE-NAME-HERE");
-
- define("EWIKI_SCRIPT", "yoursite.php?page="); #[2]
- error_reporting(0); #[3]
-
- include("ewiki.php"); #[4]
-
- echo ewiki_page(); #[5]
-
- ?>
- </BODY>
- </HTML>
-
-[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 <html> 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").
-
- <?php
- include("includes/ewiki/myconfig.php");
- ?>
- <HTML>
- <BODY>
- <?php
- echo ewiki_page();
- ?>
- </BODY>
- </HTML>
-
- 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 <HTML> 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
- mysql_connect(":/var/run/mysqld/mysqld.sock", "USER", "PW");
- mysql_query("use DBNAME");
-
- define("EWIKI_SCRIPT", "yoursite.php?page=);
- error_reporting(0);
-
- include("ewiki.php");
-
- $content = ewiki_page();
- ?>
- <HTML>
- <HEAD>
- <TITLE><?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\r
- | version: 1\r
- | flags: 1\r
- | author: 127.0.0.1:3054\r
- | created: 1046532697\r
- | lastmodified: 1046532697\r
- | refs: \nErfurtWiki\nNewestPages\n\r
- |\r
- | !! 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
-
-
