Catalog

Register a website that will run within the current Interchange instance.

Synopsis

You need to have at least one Catalog directive in your global configuration.

Scope

This directive is only available for use in the global (interchange.cfg) configuration file, and will affect all websites running under the Interchange installation.  It will not work in a website's local (catalog.cfg) configuration file. 

Description

This directive registers a website that will run within the current Interchange instance.

The simplified usage, shown in the synopsis, requires three or more parameters, as follows:

1. The symbolic name of the website.  This name will used in error, warning, and informational messages and must contain only alphanumeric characters, hyphens and underscores.  It is highly recommended that the name is all lowercase. 
   
   
2. The path to the website's home directory.  If the directory does not exist or the required "catalog.cfg" file is not present (or is not readable), or Interchange detects any other problem, then the website configuration will be skipped and this particular website won't be activated for use within this Interchange instance.  at all. 
   
   
3. This is a URI path by which the website can be accessed, and can be followed by a number of optional aliases.  The "script_name" is one of the methods Interchange uses to determine which of the configured websites a page request should be sent.  If required, and if FullUrl is in force, a hostname can be specified here along with the path.  All Interchange-generated links will be called using the named link path, or one of the aliased path(s), as appropriate. 
   
   
4. Optional "script_name" aliases allow you to access the same website via another path.  For example, this is useful when using a HTTPS/SSL server, or a members-only area that requires "Basic HTTP authorisation". 
   
   

Warning The "script_name" path (and aliases, if configured) must be unique among other "script_name" paths that run under the same Interchange instance, so that the URI path from incoming requests can be mapped to an Interchange-driven website. An exception to this is made if the FullUrl directive is specified;  The FullUrl directive allows hostnames to be added to differentiate otherwise identical paths.

There is a more elaborate usage of the Catalog directive, where the individual arguments are split into multiple lines.  See the verbose directive usage example, below.

Examples

Registering a website

Using FullUrl, instead of the link program path, to differentiate websites

Verbose directive usage

A website can be verbosely registered using the following syntax: 

Defining local website directives in the global configuration

It is possible to define website-specific configuration directives from the global interchange.cfg configuration file.  This is useful when globally managing the location used by the ErrorFile and DisplayErrors directives: