The GopherPHP configuration file

The structure of a GopherPHP site is defined in a simple XML configuration file. This configuration file consists of three main sections, which may be listed in any order and must be wrapped in a top-level <gopher> element. Details for each configuration section are given below. You can find a complete configuration file example at the bottom of this page.

Global settings: <config>

The <config> section contains some basic configuration settings for the site, which are specified as individual XML elements (containing the respective option value as body text) and can be listed in any order. The following configuration settings are currently available:

<id> ID code for the Web site (used e.g. in cookie names)
<css> CSS stylesheet — only a single URL is allowed here
(usually a relative path to one of the top-level GOPHER stylesheets)
<name> Name of the Web site
(used as HTML page title and site banner in the default page header)

Site navigation: <site>

The <site> section describes the structure of a GopherPHP site. It is used to generate the automatic navigation bar and (optionally) a complete site map. All pages of the site must be listed here. They are collected into page groups, which correspond to entries in the top row of the navigation bar. The individual pages belonging to the currently active group are shown in the bottom row of the navigation bar. Each page group is described by a <page> element as shown in the following example.

<group name="Documentation" root="documentation.php">
    <page file="documentation.php" name="User Manuals"/>
    <page file="doc_faq.php" name="FAQ"/>
    <link url="http://wiki.myproject.org/" name="Project Wiki"/>
</group>

The group name is shown in the top row of the navigation bar. It links to the specified root page, which must be one of the pages listed in this group. Each individual page is described by an empty <page> element with attributes file (the filename of the Web page) and name (the page name shown in the bottom row of the navigation bar when the group is active). In the navigation bar, groups and pages are listed in the same order as given in the configuration file. Groups can also contain external links, which are included in the navigation bar and are specified by empty <link> elements with attributes url and name. Empty groups (<group/>) can be used as “spacers” to adjust the layout of the navigation bar.

NB: All pages of a GopherPHP Web site have to be in the same directory! In particular, the file and root attributes must be plain filenames without subdirectories. It is probably a good idea to use a common filename prefix for all pages in a group, but this is not enforced by GopherPHP. The sample configuration file below uses “short names” without prefix for some important pages such as copyright.php or download.php.

User display preferences: <options>

The <options> section enables users to set display preferences for this site (provided that cookies have been enabled). Usually, the global preferences dialogue is enabled by setting <options button="yes">, and can be accessed by clicking on the preferences icon Display Preferences Icon in the top right corner of the navigation bar (see special features if you prefer to offer a regular Web page for the preferences dialogue).

Each preference item is described by a separate XML element, which contains <option> elements for the invidual options that can be selected. The name attribute is shown in the preferences dialogue, while value specifies the internal value for this option. One of the options can be marked as a default by setting default="yes". Currently, only two preference items are supported:

GopherPHP sites should offer both preference items whenever possible, so that users can choose their preferred display settings. It is usually sufficient to copy the <options> entry from the configuration file example below.

Configuration file example

<?xml version="1.0" encoding="UTF-8"?>
<gopher_config>
    <!-- Global configuration settings -->
    <config>
        <id>gopher_homepage</id>
        <css>css/gopher_web_rgb.css</css>
        <name>GopherPHP: A simple site framework for GOPHER</name>
    </config>
    <!-- User display preferences: global icon enabled with button="yes" -->
    <options button="yes"> 
        <css>
            <option name="Web fonts, RGB colour scheme (default)" value="css/gopher_web_rgb.css" default="yes"/>
            <option name="Web fonts, purple colour scheme" value="css/gopher_web_purple.css"/>
            <option name="Office fonts, RGB colour scheme" value="css/gopher_office_rgb.css"/>
            <option name="Office fonts, purple colour scheme" value="css/gopher_office_purple.css"/>
            <option name="Mac OS X fonts, RGB colour scheme" value="css/gopher_mac_rgb.css"/>
            <option name="Mac OS X fonts, purple colour scheme" value="css/gopher_mac_purple.css"/>
        </css>
        <fontsize>
            <option name="tiny" value="xx-small"/>
            <option name="small" value="x-small"/>
            <option name="normal (default)" value="small" default="yes"/>
            <option name="medium" value="medium"/>
            <option name="large" value="large"/>
        </fontsize>
    </options>
    <!-- Site navigation: sections and pages -->
    <site>
        <group name="Introduction" root="index.php">
            <page file="index.php" name="Welcome to GOPHER"/>
            <page file="copyright.php" name="Author &amp; Copyright"/>
            <link url="http://purl.org/stefan.evert/GOPHER/" name="GOPHER Homepage"/>
        </group>
        <group name="Documentation" root="doc_page_skeleton.php">
            <page file="doc_page_skeleton.php" name="Page skeleton"/>
            <page file="doc_config_file.php" name="Configuration files"/>
            <page file="doc_headers_and_footers.php" name="Header &amp; Footers"/>
            <page file="doc_specials.php" name="Special features"/>
            <page file="doc_gopher.php" name="GOPHER layout"/>
        </group>
        <group name="Download" root="download.php">
            <page file="download.php" name="Download GOPHER"/>
            <page file="install.php" name="Installation instructions"/>
        </group>
        <group/> <!-- empty groups are used as spacers -->
        <group/>
    </site>
</gopher_config>