T R I K I

A lightweight flat-file Wiki system written in PHP (and Xhtml).

Version 1.0.1  2008-03-23

Based on "Giki" by Gregor Richards, 2005 - 2006; which in turn was
based on "Wiki!" by Sam Thursfield <golrien hybd.net>, August 2002 - February 2003.

Triki (c) by Tim Reeves, September 2007 - March 2008.

First of all, please read giki-readme.txt.
This file does not duplicate all of the information contained there.
However, anything contained here supercedes anything contained there :)

GETTING TRIKI RUNNING
---------------------

1. Unpack Triki
   to a directory inside the web root (i.e. viewable via HTTP)
	e.g. (/foo/bar) /htdocs/mywiki

2. FCKeditor
   If you want to use the FCK WYSIWYG editor then it must be at
	e.g. (/foo/bar) /htdocs/mywiki/FCKeditor
	Note that FCK bleats "Error loading /fckstyles.xml" upon being called
	when your server is not configured to serve Triki directly as a domain
	(e.g. if you call it as "http://localhost/mywiki"). So make a domain :)

3. Create the directory where Triki should store the Wiki pages.
   For security this should be a directory OUTSIDE the web root directory,
	as it has to be world writable (chmod'ed to 777).
   You may have an issue with php open_basedir here, it can also be set from Apache
   via: php_admin_value open_basedir "<path1>:<path2>:/tmp"
	If you decide to put it "next to" the Webserver, using above example:
	e.g. (/foo/bar) /mywikidocs

4. Triki is configured in the file "config.php".
   Depending on your operating system, copy config-example-unix.php or
	config-example-win.php to config.php and edit it according to your
	paths chosen above and to the comments contained in that file.

	BTW that's where - among many other things - you select the language to use.
	Tip: The only essential things to have Triki "come up" are $rootdir and $nodedir,
	but it'll probably be more appealing if you also do $wikiname and $language.
	The rest you can do later, as you get a feel for Triki.

5. Assuming your webserver is running and will serve an "index.php", then
   when you now call "http://mywiki" (or whatever you've set up)
	you should see something like the picture: triki-install-1.gif

6. IF you have (left) "UserPermissions" configured as a plugin in config.php
   then you'll see the warning "WARNING: UserPermissions are unconfigured!".
	Note that the word "UserPermissions" is a LINK which you can click on!
	Do so, you'll see the page title change from "Home" to "UserPermissions",
	i.e. you are now "on" the not-yet-existing page "UserPermissions". So hit
	the menu button "Edit this page". Below the FCK edit box you'll find four
	links to help files, which each open in a popup window. One is called
	"Help on UserPermissions", click it for a popup where you can copy the
	approbated content of "UserPermissions" and paste it right into FCK.
	But notice the line "Admins (Guest)". You'll probably want to change this,
	to a blank-separated (quoted) list of logins with administration privilege,
	e.g. Admins ('Tim Reeves' 'Bill Smith')
	BTW logins named here need not exist (yet) but the privilege will of course
	only work when exactly such a login has been registered with Triki.

7. Now you can play around a bit, add some (privileged) users and create the
   home page, etc.

8. Once you have Triki working to this level, you'll probably want to edit the
   template you have chosen to your own layout (size, proportions, colors, logo etc.)

HTML or XHTML?
--------------

I strongly recommend the use of XHTML, and if possible, FCKeditor. Together these
produce valid and optically pleasing output. If you can't use FCK then you'll need
to use the plugins GWS and noHTML, which work, but since there is as yet no support
for turning newlines into <p>...</p> the output is not very pretty. The files for
XHTML are all those beginning with "x".

The standard Xhtml template "xtemplate.html" implements a somewhat unusual but
useful layout: there is only one navigation bar, on the left (most Wikis also have
one at the top). The navigation bar is fixed top left in the browser window, which
only shows a vertical scroller if the page content is higher than the browser
window, so you get the maximum available height for your content. The scroller is
a feature of <body>. There is also a variant "xscroller-..." which puts the scroller
into a fixed-height <div>, and has smallish default widths - I use this in an <iframe>
and it works fine.


STOP HTTP CACHING!
------------------

You MUST prevent the browser from caching any php-pages from the Wiki, or the user
will see old content, or for example a lock message which is no longer valid. The
".htaccess" supplied with Triki should do the trick for Apache, assuming that it
allows overrriding from .htaccess and has mod_expires and mod_headers loaded.


SUMMARY FOR ADDING LINKS TO A PAGE
----------------------------------

- [PageName] will link to PageName with PageName as the visible link text.
- [VisText|PageName] will link to PageName but display VisText as the link text.
- [VisText|cond:PageName] will link to PageName only if it exists.
- [VisText|file:filename] will link to the given file in a new browser tab or window. *
- [VisText|down:filename] will create a download link to the given file. *
- [AltText|image:filename] will be replaced by the image file *
- [VisText|http://www.google.com/] will create a normal external link to that URL

- [:upload.php] will create a relative link within the Wiki Website (to upload.php)
- [:help:filename] inserts file "help/<filename>.<language>.html" in place of the link

* See below for more details

The last two link types are "exotic" i.e. for webmasters instantiating a Triki and
are therefore not mentioned in the normal user help files. To insert a helpfile on
the page, you should put it in a <div> if you are using FCKeditor.

Page and file names are case sensitive, so if you've got a page named cheese you've
got to write [cheese] and not [Cheese]. You can still put [Cheese|cheese], though.

Note that regexp is used to match the links, so if your link "doesn't work" then
it probably contains a character that isn't listed (some are deliberately disallowed
to avoid invalid filenames and such). Currently available, as well as all letters and
numbers, are the following symbols: !-=+\"$%^()@_


HOW CAN I LET THE USER CREATE A NEW WIKI PAGE?
----------------------------------------------

Well, anyone can, by first creating a link to it (before it exists) on an
existing page, and then when viewing that page by clicking on the link.
Then you are "on" the non-existing page and create it by editing it.
Easy, but perhaps not very intuitive. So here's a way to do it explicitly:
The following snippet of code was sent in by "Walk" <walk ifrance.com>:
<form name="edit"> <input type="text" name="title"> <input
type="submit" value="Create a page"> </form>


FILE UPLOADS - WHERE THEY GO AND HOW TO USE THEM ON A WIKI PAGE
---------------------------------------------------------------

There are two possible ways for users to upload files to the Wiki:
1. Via the Upload-Button in the navigation bar
2. Via the inbuilt resources browser of FCKeditor, if your Wiki uses it.

In either case, for the file to be displayable on the Website, it must be in
the Webspace (not in the Wikis data storage space, which should NOT be within
the Webspace for security reasons).

FCKeditor uploads files to a path specified as in:
FCKeditor/editor/filemanager/browser/default/connectors/php/config.php
as $Config['UserFilesPath'] = '/userfiles/'. If you specify a $rootdir
in Trikis config.php you'll need to prepend it here. Note that FCKeditor
puts the files in a subdirectory "image" for images and "file" for others.

Trikis Up- and Downloader use a location specified in config.php as
$userpath = '/userfiles/', and duplicate FCKeditor subdirectories, if that plugin
is used, see below. These values ensure that however the user uploads, the file
arrives in the same directory. There is one difference: Trikis Uploader prepends
the name of the logged in user to the file name.

Upload Filetypes and Subdirectories:
Files of type ".tgz", ".tar.gz", ".tar.bz2", ".zip" and ".pdf" are uploaded
to a subdirectory "file" of the upload path; files of type ".jpg", ".jpeg",
".png" and ".gif" to a subdirectory "image". I have modified Trikis uploader
to this algorithm to match that of FCK (which I saw no easy way to change, nor
any reason to do so).

Including an Image on the Wiki Page
-----------------------------------

1. Via Wiki-Link: [AltText|image:Fmypic.jpg]
   where "F" is a placeholder and may be missing, or one of (without "")
	"(" for css-style float-left, or ")" for css-style float-right.

2. Via FCKeditor: Click on the "Insert/Edit Image" Symbol (top row, third from right).
   In the ensuing "Image Properties" Dialog click the URL / Browse Server Button to
	choose an uploaded image (or on the Upload tab to upload one). After choosing an
	image file add an "Alternative Text" and click the rounded arrow "Reset Size" to
	the right of the Width / Height fields, finally click OK. Experts can use the
	additional fields / tabs of this dialog to position or size the image.

Linking to an uploaded PDF (or other file) on the Wiki Page
-----------------------------------------------------------

- [VisText|file:filename] will link to the given file in a new browser tab or window.
- [VisText|down:filename] will create a download link to the given file.

In both cases you only write the name of the file - Triki assumes that the file is
located in the upload path (see above). If the FCKeditor plugin is used, Triki will
also infer the correct subdirectory ('file' or 'image') according to the file name
extension. A "file:" link creates a link with target "_blank", so that the user does
not "lose" the Wiki. A "down:" link creates a call to Trikis downloader package, which
sends a reply with HTTP-Header "Content-Disposition: attachment", so that again the
user does not lose his current position in the Wiki (see downloader/download-readme.txt).

Admin-Interface to delete old versions
--------------------------------------

The programm "cleanup.php" takes 2 Get-Parameters, "title=" is the node to return to
(gets put in the navigation), and "keep=" says how many history versions of each page
to retain. All older history versions are deleted, assuming the caller has the user
write permission for the pseudo-page ":cln". It can be called (for convenience) via
a link from any other page, like this: [Cleanup|:cleanup.php#&keep=6]

The default value to keep is 7; less than three is silently changed to three, to prevent
any disasters. This is not exactly a large and flexible solution, but all I could manage
for now. If anyone wants to write an all-singing, all-dancing admin component, I'll be
glad to have it (don't complain - get hacking! :)

Configuring the FCKeditor
-------------------------

The plugin file plugin-edit-FCKeditor.php contains various runtime settings and
a lot of comment. The version of FCKeditor contained in the Triki distribution
(Version 2.4.3) already contains the further changes detailed here:

a) in FCKeditor/fckconfig.js
   - Added a new own toolbar set as FCKConfig.ToolbarSets["Xwiki"]
	  This loads all the toolbar symbols which are sensible to have in Twiki.
	  The order of symbols matches MS Word as closely as possible.
	- var _FileBrowserLanguage	= 'php' ;
   - var _QuickUploadLanguage	= 'php' ;
	- FCKConfig.ProcessHTMLEntities	= true ;   // leave this true
	- FCKConfig.IncludeLatinEntities	= false ;  // change this to false
	  This prevents for example "ö" being converted to "&ouml;", thus allowing
	  latin-1 characters in Page Names (which must be url-encoded, not entities)

b) in FCKeditor/editor/filemanager/browser/default/connectors/php/config.php
   => this enables the Upload-Tab of the "Insert Image" Dialog
	- disable the security setting
	- following that include any SubDir und docRoot here:
	  $Config['UserFilesPath'] = '{/AnySubdirUnderDocroot}/userfiles' ;

c) in FCKeditor/editor/filemanager/upload/php/config.php
   => if you want to allow Upload via the "Link" Dialog / Upload-Tab
	- disable the security setting
	- following that include any SubDir und docRoot here:
	  $Config['UserFilesPath'] = '{/AnySubdirUnderDocroot}/userfiles' ;


THE STATE OF PLUGINS
====================

I "inherited" a number of plugins from Giki, and the more I was working with the code
the more I had to correct errors, adding a lot of comment on the way. In places I
completely recoded things to (a) work at all, or (b) work with Xhmtl and CSS, or
(c) to work reliably for all modern browsers. I have not done this (yet) for all
the exising plugins, here is the state of affairs:

Available Prefixes for use by Plugins:
--------------------------------------

db          A database implementation (to replace default-db.php)
user        A user management implementation (to replace default-user.php)
perm        A user permission implementation (to replace default-perm.php)
lang        Called in language.php after language is set (good place for session_start)
reg         Registration (used in adduser.php)
render      Extension / modification of node display (in parse.php)

Editing:
edit        At end of edit form display - several plugins write help texts here.
            plugin-edit-FCKeditor.php also overwrites the <textarea> with FCK stuff.
pre         At edit form submission, BEFORE the new text is saved to the DB
post        At edit form submission, AFTER  the new text is saved to the DB

Pseudo:
inc / lib   are not used AS plugins but rather BY some plugins
            (to provide the same functions in more than one place)

Available Plugins:
------------------

Name             What it does           Author     Triki Status

GWS *            Implements WikiSyntax  Richards   Works OK (but \n not made to <p>)
noHTML *         Strip HTML from Input  Richards   Works OK
FCKeditor *      Use a WYSIWYG editor   Richards   Complete Overhaul, Great!
UserPermissions  Check if user allowed  Richards   Polished, OK

TOC              Add TOC at page head   Richards   Polished, OK
RecentChanges    Maintain such a Node   Richards   Polished, OK
diff             Add a "diff" to Menu   Richards   Ported to Drupal "Diff" code, OK
                                                   Many thanks to Drupal and PHPWiki!
Talk (1)         Comments to each page  Richards   Polished, OK

subnodes         Show nested nodes      Richards   Major Overhaul, Fine
subwins          Onpage text in a box   Richards   Major Overhaul, Fine
popwins          Text in popup window   Reeves     New, Great!
lockpage         Lock page while edit   Reeves     New, Great!

* Use EITHER GWS (optionally with noHTML) OR FCKeditor
  but never both, or noHTML with FCKeditor!

(1) A "Talk" - when the plugin is loaded - is automatically offered for EVERY
    Wiki Page via an extra item in the navigation bar. The first user to click
    it creates the Talk-Page. Every call to the talk page shows all the entries
    previously posted and offers the user a form after the last entry to post a
    new entry. A maximum of ten entries per talk-page are displayed, with a link
    list to the various pages at the bottom.

User management (registration and login and -out) are provided in user.inc.php, which
either loads a -user- plugin, if one is set, otherwise default-user.php. If you create
a user plugin then it MUST contain all the functions detailed in user.inc.php. User
permission management is provided in a similar way via perm.inc.php.

Untested:
BBCode, CamelCase, NT, pwauth, redir, SF, hiero


TRANSLATIONS
============

Select the language for your wiki by including the appropriate language file in
language.php. Currently available are english, german, spanish, italian and finnish
translations, whereby the last three are not yet completely translated - wherever
a translation is missing you will see the english text.

The bulk of the language-specific texts are contained in language.XX.php, but some
longer texts for plugins are contained at the head of (one of) the plugin files, or
even longer ones are in extra files in the "help" subdirectory, so if you translate,
please do these as well:

- edit.php
- plugin-edit-subnodes.php
- plugin-edit-subwins.php
- plugin-edit-popwins.php         (these four contain help texts)
- plugin-edit-lockpage.php        (messages about locked pages)
- plugin-edit-FCKeditor.php       (and the included texts in the help directory)
- plugin-edit-GWS.php             (and the included texts in the help directory)
- plugin-render-diff.php          (a line on how to use the diff list)
- plugin-render-TOC.php           (just the caption for the TOC box)
- display.php / addLoginToBar()   (tooltips for the extra buttons)


CALL HIERARCHY WHEN index.php IS CALLED TO DISPLAY A NORMAL NODE (Page)
-----------------------------------------------------------------------

A. Minimal Version (plugins not elaborated)
------------------

1 parse($title)  [aus parse.php]

  1.1 getNodeContents($title)  [aus db.php / default-db.php]
  1.2 parsecontents($title, $node, $linkmethod, $wrevhist, $perm)  [aus parse.php]

      1.2.1 Execute (via include) any defined render plugins
		      NOTE: Execution happens in the order of (configured) $plugins!
		1.2.2 Find and replace the [...] links in the otherwise completed node (see above)

2. display($title, $node, $bar, $template)  [aus display.php]

B. With SubNodes Plugin
-----------------------

1 parse($title)  [aus parse.php]

  1.1 getNodeContents($title)  [aus db.php / default-db.php]
  1.2 parsecontents($title, $node, $linkmethod, $wrevhist, $perm)  [aus parse.php]

      1.2.1 SubNodes Plugin: $node = stdParse("subnode", "parseSubNode", $node);

		      1.2.1.1 parseSubNode() is called for each "subnode" found
				1.2.1.2 It in turn calls GPSN_makeContents($title, $returnto)
				1.2.1.3 GPSN_makeContents() in turn calls parse($title,...)

		1.2.2 Find and replace the [...] links in the otherwise completed node (see above)

2. display($title, $node, $bar, $template)  [aus display.php]

Regarding 1.2.1 - including render-plugins:
  Since SubNodes will involve recursive calling of parse(), we must use
  "include()" here, and NOT "include_once()", so that render processing
  happens equally to included SubNodes (and also to any Nodes subsequently
  included directly in the template). This in turn means that render
  plugins must be able to be called more than once - use if (!function_exists...
  as required to make sure functions are only defined once.
  NOTE that therefore any variables declared in render plugins will be local
  to the context of parsecontents, unless you explicitly declare them global!