3. Setting up henkari
3.1. Requirements
In theory where ever you can make PHP4 or better to work henkari will follow. Properly setting up an entrypoint that is separate from the place where henkari itself is located requires filesystem with symbolic links (or equivalent feature), but it's not required.
In Debian environment you need packages php4 and phplib. Phplib program files appear in /usr/lib/phplib and when creating an entrypoint (see Section 3.2.4) you can link them from there.
3.2. Installation
3.2.1. Obtain
Henkari can be obtained from http://www.math.jyu.fi/~terotil/
3.2.2. Extract
Extract the distribution package on a place where you keep your local program files.
It's recommended that when really using henkari, you don't put files under any web directory but create entrypoint separately (Section 3.2.4) and that way can share henkari program files between several websites and make updating henkari easier. For testing purposes it's perfectly OK to extract files under web directory and use the directory where henkari resides as an entrypoint.
If you have GNU tar, extracting goes with command.
bash$ tar --extract --ungzip --file=henkari.tar.gz |
3.2.3. PHPLib
 |
Currently henkari distribution includes program files from phplib-7.4-pre1. If you already have phplib on your machine, you can during entrypoint creation link you existing phplib instead of phplib-7.4-pre1 which came with henkari distribution. |
Henkari uses functionality from phplib. So if you don't already have it and it didn't come with henkari distribution, obtain it from http://sourceforge.net/projects/phplib/, extract package and copy directory containing library files (php/) to your shared php-code location. Henkari should work with any phplib from 7.x on.
Henkari assumes phplib library files reside in phplib/ when looking from the directory where entrypoint script is. Quick way is to symlink phplib library directory to entrypoint directory.
bash$ cd /dir/where/entrypoint/script/is bash$ ln -s /shared/php/code/phplib-code-dir/ phplib |
3.2.4. Create entrypoint
If you use the directory where henkari actually resides as and entrypoint too, you don't have to do anything special. Extracted henkari directory serves as an entrypoint right out-of-box. Creating entrypoint this way can make updating and local an error-prone task. It's OK for testing purposes, but creating separate entrypoint is recommended.
Creating separate entrypoint starts with creating (web)directory that will serve the entrypoint. Copy config.php to that directory. Create (symbolic) links to doc/, lib/, phplib/ directories and index.php. Create root/ and pagecache/ directories (or which ever are approppriate for you. These can be changed from configuration). Now you should have working entrypoint.
Good smoke test is to put whatever (html-)file to root/ directory and point your browser to entrypoint directory. You should see a link pointing to that file and clicking should show that file. Assume my webroot is /var/www/ and I have henkari entrypoint at /var/www/henkari/. Now I would copy my whatever.html to /var/www/henkari/root/, point my browser to http://myhost/henkari/ and see (if henkari is working) a page with single link "Whatever" pointing to http://myhost/henkari/index.php/whatever.html.
3.3. Configuration
Henkari's configuration has three levels. General settings have global defaults, which are located in lib/henkariConfig.class.php. General settings for each entrypoint reside in config.php in the entrypoint directory in question. Third level is distributed configuration under webroot.
3.3.1. General settings
General settings apply to single entrypoint. File containing those settings is config.php and it's located in the entrypoint directory. Example configuration coming with henkari distribution contains only few settings to give an example of the syntax. You can find the rest of the configuration variables from lib/henkariConfig.class.php where their global defaults are set. Setting variable in config.php overrides the global default.
3.3.2. .index
Dotindex-file contains all the exceptions to the rules (see Section 4.4.1) along which automatic navigational elements are built. If found, both .index and _index are used.
Syntax of dotindex looks like this.
# Comment map somefile Label of some file map somedir/ Label of some dir pseudo nonexisting Another label hide filenottoshow |
Lines beginning with hash are ignored (Note that hash must be the first character.). All the other lines are split on two first sequences of whitespace (sequence of only spaces and tabs). First part is interpreted as command and the rest (one or two) are parameters. Three commands (see the syntax example abow) are recognized.
- map
-
Maps file/directory to a new name. This new name is used in automatic navigational elements to represent the file/directory in question. First parameter is the name of the file/directory and the second is the name to use for that file/directory. Note that you must append a trailing slash to directory names.
- pseudo
-
Adds an entry to automatic navigational elements. First parameter is the address used in links and the second is the name to use for that entry.
- hide
-
Hides matching files/directories from navigational elements. A file/directory is not shown if a match against any hide-pattern is found from it's name. Hide-patterns apply to the directory where they appear and all subdirectories. Patterns are POSIX extended regular expressions (see The Open Group Base Specifications Issue 6, Chapter 9 http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap09.html).
Note that this only hides files from automatic navigational elements. It doesn't prevent user from requesting them. You can still link to these hidden items, but automatic table of contents (see Section 4.4.1) may behave unexpectedly.
As you may have noticed, only the second parameter may contain whitespaces. So mapping names having whitespaces is currently impossible. Take this into account in your naming conventions.
3.3.3. .henkari
Dothenkari is executed as php-code before the directory where it resides is examined. It must be a well formed php-file. If found, both .henkari and _henkari are used. Dothenkari gives you direct access to internals of henkari in the middle of it's road towards requested file. You can redefine pretty much everything.
A straightforward way to implement two alternate templates and parameter driven switching between them is to put following code in .henkari in webroot.
if ( 'print' == CGI::safeLookupGP('tpl', 'screen') ) {
global $config;
$config->templatefile = '_template_print.html';
}
|
If now in get or post variables there is variable 'tpl' having value 'print'. Configuration is altered so that _template_print.html is used as template instead of default _template.html. Now you only need the templates and links between them.
[
<a href="{this_uri}?tpl=screen">normal</a> |
<a href="{this_uri}?tpl=print">printable</a>
]
|
To lear more about the possibilities available in dothenkari you should read Section 5.