Advanced Interchange Topics: Catalog Skeletons

7.1. Catalog Skeletons

A catalog skeleton contains an image of a configured catalog. The best way to see what the makecat program does is to configure the simple demo and then run a recursive diff on the template and configured catalog directories:

    cd /usr/local/interchange
    diff -r construct catalogs/construct

The files are mostly identical, except that certain macro strings have been replaced with the answers given to the script. For example, if www.mydomain.com was answered at the prompt for a server name, this difference would appear in the catalog.cfg file:

    # template
    Variable SERVER_NAME  __MVC_SERVERNAME__

    # configured catalog
    Variable SERVER_NAME  www.mydomain.com

The macro string __MVC_SERVERNAME__ was substituted with the answer to the question about server name. In the same way, other variables are substituted, and include:

    MVC_BASEDIR      MVC_IMAGEDIR
    MVC_CATROOT      MVC_IMAGEURL
    MVC_CATUSER      MVC_MAILORDERTO
    MVC_CGIBASE      MVC_MINIVENDGROUP
    MVC_CGIDIR       MVC_MINIVENDUSER
    MVC_CGIURL       MVC_SAMPLEHTML
    MVC_DEMOTYPE     MVC_SAMPLEURL
    MVC_DOCUMENTROOT MVC_VENDROOT
    MVC_ENCRYPTOR

Note: Not all of these variables are present in the "construct" template, and more may be defined. In fact, any environment variable that is set and begins with MVC_ will be substituted for by the makecat script. For example, to set up a configurable parameter to customize the COMPANY variable in catalog.cfg, run a pre-qualifying script that set the environment variable MVC_COMPANY and then place in the catalog.cfg file:

Variable COMPANY __MVC_COMPANY__

All files within a template directory are substituted for macros, not just the catalog.cfg file. There are two special directories named html and images. These will be recursively copied to the directories defined as SampleHTML and ImageDir.

Note: The template directory is located in the Interchange software directory, i.e., where interchange.cfg resides. Avoid editing files in the template directory. To create a new template, it is recommended that it should be named something besides 'construct' and a copy of the construct demo directory be used as a starting point. Templates are normally placed in the Interchange base directory, but can be located anywhere. The script will prompt for the location if it cannot find a template.

In addition to the standard parameters prompted for by Interchange, and the standard catalog creation procedure, four other files in the config directory of the template may be defined:

 additional_fields -- file with more parameters for macro substitution
 additional_help   -- extended description for the additional_fields
 precopy_commands  -- commands passed to the system prior to catalog copy
 postcopy_commands -- commands passed to the system after catalog copy

All files are paragraph-based. In other words, a blank line (with no spaces) terminates the individual setting.

7.1.1. Additional fields

The additional_fields file contains:

    PARAM
    The prompt. Set PARAM to?
    The default value of PARAM^IAlternate value of PARAM

This would cause a question during makecat:

    The prompt. Set PARAM to?.....[The default value of PARAM]

The default value line can contain alternate values, separated by tabs from the default value. (The default value may not contain a TAB character.) This will allow command-line editing to cycle between the different values -- usually with the UP and DOWN arrow keys.

If you wish to set the parameter to the default value in this file without a prompt, precede the parameter with an exclamation point, i.e.:

    !PARAM
    The prompt.  Set PARAM to?
    default value^Ialternate value

If you wish only to prompt for a value if a previous parameter was set, put the previous parameter to set in curly brackets before the actual parameter:

    {MYSQL}SQLDSN
    Data source name (DSN) for MySQL?
    dbi:mysql:test___MVC_CATALOGNAME__

The above will be ignored if the MYSQL parameter was not previously set to a true value.

Note that information collected in the main makecat run (in this case, the catalog name) can be inserted via macro substitution.

7.1.2. Additional help

If the additional_help file is present, additional instructions for PARAM may be provided.

    PARAM

    These are additional instructions for PARAM, and they
    may span multiple lines up to the first blank line.

The prompt would now be:

    These are additional instructions for PARAM, and they
    may span multiple lines up to the first blank line.

    The prompt. Set PARAM to?.....[The default value of PARAM]

7.1.3. Command files

If the file config/precopy_commands exists, it will be read as a command followed by the prompt/help value.

    mysqladmin create __MVC_CATALOGNAME__
    We need to create an SQL database for your Interchange
    database tables.

This will cause the prompt:

    We need to create an SQL database for your Interchange
    database tables.

    Run command "mysqladmin create simple"?

If the response is "y" or "yes," the command will be run by passing it through the Perl system() function. As with any of the additional configuration files, MVC_PARAM macro substitution is performed on the command and help. Proper permissions for the command are required.

The file config/postcopy_commands is exactly the same as <precopy_commands>, except the prompt occurs after the catalog files are copied and macro substitution is performed on all files.

There may also be SubCatalog directives:

    SubCatalog easy simple /home/catalogs/simple /cgi-bin/easy

easy

easy.cfg

simple

The name of the base configuration that will be the basis for the catalog. Parameters in the easy.cfg file that are different will override those in the catalog.cfg file for the base configuration.

The remaining parameters are similar to the Catalog directive.

Additional interchange.cfg parameters set up administrative parameters that are catalog wide. See the server configuration file for details on each of these.

Each catalog can be completely independent with different databases, or catalogs can share pages, databases, and session files. This means that several catalogs can share the same information, allowing "virtual malls."