CWIS Developer Documentation

- Home
- Main Page
- Namespaces
- Classes
- Files

Implementing CWIS Interfaces

CWIS is designed to allow the look and feel of a CWIS-based site to be customized with a minimum of effort, and for those customizations to be able to be applied on a per-user basis. Toward this end the PHP internals of the software have been carefully separated out from the HTML, PHP, and CSS code that produces the rendered web pages. This section attempts to outline some of the steps and considerations in modifying the appearance of your CWIS site.

A working knowledge of HTML, and (depending on the extent of the customization desired) CSS and/or PHP is assumed.

Before continuing you may want to review the CWIS Directory Structure section for an overview of the different groups of files and where they are stored.

# Loading Precedence

A fundamental aspect of CWIS interface handling is how the software decides which files to load. Because interfaces can be selected on a per-user basis (i.e. different users can have different interfaces shown to them) and an interface can be customized without modifying the CWIS distribution files, interface (HTML and image) files can be loaded from a number of different locations.

The software searches for interface files in these locations, in this order:

- `local/interface/`CurrentInterface
- `interface/`CurrentInterface
- `local/interface/default`
- `interface/default`

where CurrentInterface is the directory for the currently active interface. So, for example, if the Horizons interface is currently active, the first directory where the software would look for interface files would be `local/interface/Horizons` (if that directory exists).

Searching in this order means that if you want to customize something that appears on a specific page, you put your version of the HTML file for that page in the appropriate location under the `local` tree, and CWIS will use that file instead of the file found in the `interface` tree that is distributed with the software.

The search order also applies for most other interface files in subdirectories of the directories listed above. So, for example, you could create your own version of `CWIS.css` and put it in `local/interface/default/include`, and it will be used instead of `interface/default/include/CWIS.css`.

# Standard Page Segments

For the sake of consistency (and to make site maintenance easier) most web sites have a standard menu or navigation area that appears on most of their pages. CWIS supports this by breaking pages down into three sections: the standard page start, the content area, and the standard page end. This allows you to make modifications that will affect the entire site (e.g. adding your logo to the top of the page) by changing only one file.

In the default CWIS interface, the standard page start contains the top header area and search box and the main navigation bar (Home, Browse Resources, etc), and the standard page end contains the login box, the secondary navigation area (Preferences, Accessibility, etc), the other boxes and links in that column, and the page footer. The HTML header code is also contained in the standard page start file.

Code for the standard page start can be found in the file `StdPageStart.html` (AKA `SPT–StandardPageStart.html`). The standard page end code can be found in `StdPageEnd.html` (AKA `SPT–StandardPageEnd.html`). CWIS looks for both of these files in the `include` subdirectories under the interface paths discussed in Loading Precedence above.

# Adding a New Interface Step-by-Step

Adding a new interface to a CWIS site is a fairly straightforward process. The steps below assume you're working from the command line, though the same operations can be accomplished via FTP and (optionally) a text editor.

1 - Decide on a name for your new interface. The interface name will be displayed in the System Configuration page and on the Preferences page if users are allowed to change their interface.

2 - Create an interface subdirectory under `local/interface`. The subdirectory should be the interface name with all punctuation and spaces removed. For example, if your new interface is named My New Interface #1 you would create the directory `local/interface/MyNewInterface1`:

mkdir local/interface/MyNewInterface1

If you're modifying the standard page start or end, CSS, or any of the images, you'll also need to create the appropriate subdirectories under your new directory:

mkdir local/interface/MyNewInterface1/include
mkdir local/interface/MyNewInterface1/images

3 - Set the interface name. (optional) The interface name that's displayed is read from the text file `NAME` in the interface subdirectory if that file is present. If the file is not present, the interface subdirectory name will be displayed. From the command line you might set the name like this:

echo 'My New Interface #1' > local/interface/MyNewInterface1/NAME

4 - Determine the name of the HTML file for the page you want to modify. The HTML file name is simply the value displayed after `P=` in the URL with `.html` added to the end. So, for example, since the URL for the Advanced Search page is `index.php?P=Advanced`, the HTML file would be `Advanced.html`.

5 - Copy the distribution HTML file into your new interface subdirectory.

cp interface/default/Advanced.html local/interface/MyNewInterface1/Advanced.html

In the above example the file is being copied from the `default` interface directory, but it could also be taken from the `LowVision` directory, or the directory for any interface that has a version you want to use as a starting point for your modifications.
This also applies to the standard page start and end, CSS files, or any of the other files in the `include` subdirectory. So if you wanted to modify the standard page start, you would copy the distribution file for that instead:

cp interface/default/include/StdPageStart.html local/interface/MyNewInterface1/include/StdPageStart.html

6 - Edit the HTML file to make your desired changes or additions.

7 - Repeat steps 4-6 for each page to be modified.

8 - Switch CWIS to use your new interface via System Configuration. (optional) The Default User Interface option on the System Configuration page determines what interface is displayed to users when they're not logged in and what interface they start with when they first register (if Allow Multiple User Interfaces is enabled) or what interface they always see when logged in (if multiple interfaces are disabled).

The Allow Multiple User Interfaces option on the System Configuration page determines whether non-privileged users are allowed to change their interface.

IMPORTANT: Which interface is displayed is dependent on two values: the Default User Interface setting on the System Configuration page, which is a global value that applies to the whole system, and the Active User Interface setting on the Preferences page, which is individual to each user. The global setting is used when a user is not logged in and as the initial value for the individual setting for new users. If you change the global Default User Interface setting it will not change the interface displayed to existing users unless you check Set All Users to This Interface on the System Configuration page and click the Save Changes button.

# Common Functions

There are a handful of interface constructs that appear in a variety of contexts (e.g. resource summaries). These are encapsulated in PHP functions which may be found in the `include` subdirectories in the interface trees, one function per file. The files are named `F-`FunctionName`.html` where FunctionName is the name of the function contained therein. For example, the default version of `PrintResource()` function can be found in `interface/default/include/F-PrintResource.html`.

(These functions were formerly all contained in `SPT–Common.html` in the same directory.)