+++ /dev/null
-
-ewiki code fragments/ and tools/
-================================
-
-Unlike the plugins/ the code snippets and asorted data files in fragments/
-can be included() directly into yoursite.php and are sometimes also
-unspecific to ewiki. And the init-pages/ for example are required only once
-and can be removed after initialization.
-The tools/ is a separate bundle of administration tools for the ewiki
-database. They are separate from the main Wiki (even comes with a different
-'config.php') to enhance safety and reliability.
-
-
- 1 fragments/
- 1.1 strip_wonderful_slashes.php
- 1.2 strike_register_globals
- 1.3 404finder.php
- 1.4 htaccess
- 1.5 binary.php
- 1.6 force_lang_de.php
- 1.7 fragments/funcs/*
- 1.8 fragments/css/*
- 1.9 fragments/blocks/*
- 1.a fragments/patches/*
- 1.b fragments/php-patches/*
- 2 Additional tools/
- 2.1 tools/t_flags
- 2.2 tools/t_backup
- 2.3 tools/t_restore
- 2.4 tools/t_remove
- 2.5 tools/t_holes
- 2.6 tools/t_textinsert
- 2.7 tools/t_transfer
- 2.8 tools/t_revert
- 3 commandline tools/
- 3.0 tools/setup
- 3.1 tools/ewikictl
- 3.2 tools/wiki2html
- 3.3 tools/mkhuge
- 3.4 tools/mkpluginmap
- 3.5 tools/mkpageplugin
- 3.6 tools/mkxpi
- 3.7 tools/php5fix
- 4 examples/
- 4.1 examples/homepage.php
- 5 Pages in init-pages/
-
-
-
-
- -------------------------------------------------------------------- 7 --
-
-
-
-
-fragments/
-¯¯¯¯¯¯¯¯¯¯
-This directory holds some files to integrate ewiki.php within some
-other web projects (for example PhpNuke) or some helper and extension
-code, but even data files, code patches.
-
-Most stuff is grouped into subdirs:
-
- blocks/ plugin extractions to get included() somewhere into yoursite
- (onto left or right side, like in one of those portal scripts)
- head/ also output html snippets, for inclusion into the html <head>
- area of pages
- css/ for sample .css files and per-page .css definitions (for use
- with 'fragments/css.php')
- funcs/ code snippets of varying usefulness
- parent-cms/ samples on how to integrate ewiki into CMS or portal scripts
- patches/ code/feature tweaks
- php-patches/ PHP interpreter bugfixes
- ./ assorted stuff, described below:
-
-
-
- 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
-
- It does not hurt a well configured PHP interpreter setup.
-
- Newer ewiki versions come with a "plugins/lib/fix.php", which does
- basically the same, but also incorporates:
-
-
-
- strike_register_globals
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- Tries to secure the $GLOBALS environment for PHP setups with the
- register_globals still turned on (which is a bad thing!).
-
-
-
- 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.
-
- +++
-
- Shows how to use mod_rewrite with ewiki.
-
- * old style: http://www.example.com/wiki.php?page=WikiPage
- * PATH_INFO: http://www.example.com/WikiPage
-
- Remember to enable EWIKI_USE_PATH_INFO inside ewiki.php - this was
- disabled once, because of the many broken Apache implementations (they
- seem to support that broken CGI/1.1 specification, which was for good
- reasons and luckily never blessed to become an official RFC).
-
-
-
- binary.php
- ¯¯¯¯¯¯¯¯¯¯
- If yoursite.php (ewiki wrapper) is not designed carefully enough
- (=not binary safe, because <html> or text is written before the
- ewiki.php core script got included) or EWIKI_SCRIPT_BINARY cannot be
- set correctly, you may want to use this wrapper script to allow for
- uploading and retrieval of binary content (images) via ewiki.
-
- Copy it to where the main ewiki.php script is, and set the
- EWIKI_SCRIPT_BINARY constant to the correct absolute position
- (possibly including http://server.name/) of "binary.php". (this
- constant must be set on top of ewiki.php)
-
- You must set the database access params in here, too.
-
- It may also be useful if you'd like to divide the database into its
- two parts again - text content and binary content. You could even
- let it save binary content in a flat file database, while WikiPages
- remain in a RDBMS.
-
-
-
- force_lang_de.php
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- Sample pre-config script for "de_DE" lang to preset the language
- appearance of ewiki. If you just are too lazy to set up your
- browser correctly, then this line usually fixes your language
- setting problem:
-
- $_SERVER["HTTP_ACCEPT_LANGUAGE"] = "de";
-
- (must be written before ewiki.php gets included)
-
-
-
- fragments/funcs/*
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- The funcs/ subdirectory contains code snippets, that provide
- additional interface functions.
-
-
-
- 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/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.
-
-
-
- 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).
-
- The 'fragments/css.php' script can be included into yoursites`
- page html <head> part and inserts all *.css files from this
- directory which match the current page or action name. This allows
- for restyling certain pages and helps in keeping a sites main
- stylesheet small.
-
-
-
- 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.
-
-
-
- fragments/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.
-
-
-
- fragments/php-patches/*
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- If bugs in the PHP language interpreter prevent running of ewiki
- under certain versions, a patchfix will appear in the php-patches/
- directory.
-
-
-
-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/index.html
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- If this page looks ugly, it is because you are using IE prior
- version 7 - it works fine with Mozilla, Opera and even text-only
- browsers like w3m.
-
-
-
-commandline tools/
-¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
-As opposed to the web based tools/ mentioned above, a few scripts in tools/
-must be run from the commandline. That is, you need a standalone PHP
-interpreter (/usr/local/bin/php) and shell access to your web server.
-
-If you don't have shell access, you could write temporary wrapper scripts
-(see the note for ewikictl), or use one of the emulation packages (or start
-up a xterm on the server in absence of ssh access). A detailed description
-is out of scope of this document.
-
-UNIX users will find those tools very useful and handy, while they effort
-additional work from Windows users. But then all those tools/ should run
-on Win32 systems too, but you often want to create additional .bat files
-to make this more user-friendly. There is for example a 'ewikictl.bat'
-demonstrating this.
-
-
-
- tools/setup
- ¯¯¯¯¯¯¯¯¯¯¯
- Using this console or X11 tool, you can create a custom "ewiki.ini"
- or "config.php" script by choosing plugins and settings through a
- nice interface. It even allows generation of a MonsterWiki script.
-
- Works only under Linux. Read [doc/SetupTool] for more informations.
-
-
-
- tools/ewikictl
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- ewikictl 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>
- --writable <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).
-
-
-
- tools/mkxpi
- ¯¯¯¯¯¯¯¯¯¯¯
- The new .xpi plugins can be installed at runtime (password required),
- if the plugins/feature/xpi extension is loaded. This type of plugins
- however must be prepared first using the 'mkxpi' tool from their
- source scripts.
-
- A detailed description is available in the comment part of this
- commandline tool.
-
-
-
- tools/php5fix
- ¯¯¯¯¯¯¯¯¯¯¯¯¯
- If you want to test ewiki with recent PHP5 beta versions, you
- either need to apply the fragments/php-patches/ or mangle the ewiki
- core script using the 'php5fix' commandline utility.
-
- It adds a few explicit typecasts, where this is known to be
- necessary to keep PHP5 versions happy.
-
-
-
- tools/collectplugins
- ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
- Allows you to make a 'monsterplugin' script by analyzing your
- config.php script. It will output a combination of all activated
- plugins merged into one file, which you could afterwards glue
- together with the core script to get a real monsterwiki script.
-
-
-
-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.
-
-
-
-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
-very first time.
-You can create these files with the tools/ewiki_backup.php script
-or the 'ewikictl' commandline utility, what is very handy for backup
-purposes or partial mirroring of all your content.
-
-Using the "TextUpload" plugin/spage you can upgrade all of those
-files that are already existing on your setup. You could also get
-the latest tarball containing all default pages from
-[http://ewiki.berlios.de/initpages/?MiniDump] to do so (TextUpload
-can directly use that page tarball).
-
-