WikiFarms are a mechanism for running multiple independent wikis on the same web server from a single Pm Wiki installation. If a WikiFarm is a collection of independent wikis, then each independent wiki in the farm is commonly called a WikiField. A person who manages the Pm Wiki software installation is commonly called a farm administrator, the location of the Pm Wiki software is called the "farm directory" and any administrators of individual fields are called field administrators. Each field must have its own base URL, but can share pages and WikiGroups, uploads, page templates, passwords, and other local customizations with other fields. For a quick explanation of what goes where and what it controls, see PmWiki:QuickFarms.
The remainder of this document describes how to setup WikiFarms and individual fields of the farm, and assumes you are already somewhat familiar with the details of Pm Wiki installation.
Any Pm Wiki installation can become the WikiFarm on a particular web server.
Setting up a Pm Wiki installation to act as a WikiFarm is fairly straightforward. The farm administrator simply creates a local/farmconfig.php file in the farm's "home directory" (the directory in which pmwiki.php is installed). This file would contain any local customizations that are to be performed for every field in the farm (farmconfig.php replaces the config.php file of a typical installation). Usually, this will mean setting $FarmPubDirUrl to reasonable settings for the new field. A minimal farmconfig.php file might look like this:
<?php if (!defined('PmWiki')) exit(); $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub';
$FarmPubDirUrl is used to provide fields with the URL location of the farm's pub/ directory.
Your Pm Wiki installation is now set up for farming. Now you need to create fields to see it in action.
Once Pm Wiki has been set up for WikiFarming, a new field is created by doing the following:
1. Create a directory to hold the field. Normally the field directory goes in a web-accessible directory (e.g., under public_html), but it can be placed anywhere that a Pm Wiki installation would normally go. This could be a directory outside or inside the farm's home-directory.
2. Create a PHP script (e.g., field.php) in the field directory with the following line
<?php include('path/to/pmwiki.php'); ?>
where path/to/pmwiki.php is the file path to the farm's installation of Pm Wiki. Either an absolute file path (
/home/username/pmwiki/pmwiki.php) or relative file path (
../pmwiki/pmwiki.php) will usually work, although PHP doesn't understand ~username in file paths. Do not use a url path, i.e., there shouldn't be an '
http://' in it anywhere.
3. Change the field's directory permissions to 777.
4. Open a web browser and execute the field.php script you created in step #2. This will create the needed directories for the field and should bring up a default Pm Wiki installation (with any default settings the farm administrator may have set).
Each field administrator can create a local/ directory within the field directory for local customization to be applied to the field. This works just like a normal Pm Wiki installation--the file local/config.php holds settings for the entire field, and files of the form local/Group.php and local/Group.PageName.php are used for per-group and per-page customizations (see Per Group Customizations).
The Pm Wiki variable
$FarmD points to the "home directory" for the Pm Wiki farm installation; thus a field administrator can use
$FarmD/pub/ to refer to the farm's scripts/ and pub/ directories.
A farm administrator can use the local/farmconfig.php file for customizations to be applied to all fields within the farm. By default, farm customizations are performed before any field-customization files; however, the farm administrator can override some field-customizations by explicitly calling the field's config.php files (this effects all fields), as in:
<?php if (!defined('PmWiki')) exit(); # Settings performed before field-customizations $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub'; $Skin = 'pmwiki-farm'; # load the field's global and per-group customizations include_once('local/config.php'); include_once('local/pgcust.php'); # Override field customizations here
$EnableUpload= 0; # disable uploads ?>
If extension scripts are used farm-wide and they are located in the farm's cookbook directory they should be loaded through entries in local/farmconfig.php like:
similar includes can be done in any field's local/config.php file. Note the double quotes "..."; single quotes do not work.