How to install and configure

This directory is divided into one subdirectory for each module (base, search, upload and quest), and one directory (common) for files shared between the modules.

In addition, one subdirectory (app) contains all the applications. The inclusion of the app directory in the source directory stucture for the generic METAMOD2 software is just a practical solution for short term needs. In the long run, applications should not reside inside this directory structure, but be located as separate entities.

The module directories shares a common structure. In each module directory there is a htdocs subdirectory. During installation of an application, the htdocs directories for all the selected modules are merged into one htdocs directory on the target location. To avoid name collisions, the actual HTML and PHP files etc. are contained within subdirectories of the htdocs directory. For example, all such files are contained in the directory htdocs/sch for the METAMODSEARCH module, and htdocs/upl for the METAMODUPLOAD module. On the target directory (where an application is installed), there will be a htdocs directory containing both the sch and the upl subdirectories. Some subdirectories may be shared among several modules. For example, the METAMODBASE module and the METAMODQUEST module both have files in the adm subdirectory. Special care must be taken for these files to avoid name collisions.

Each module directory must also contain a file 'filelist.txt' which lists all files comprising the module.

The app directory contains one subdirectory for each application. In each of these subdirectories there must be a configuration file called master_config.txt, and a filelist.txt file containing a list of files that are specific for the application (image files, style sheets etc.).

The source files within the METAMOD2 directories contain a variety of file types (PHP, Perl, HTML/XHTML, CSS and shell-script files, some of them with embedded SQL). The source files are not intended to be used directly, but must be modified and copied to a target directory tree before the application can run. The reason for this is to apply a unified configuration method for all the different file types.

The following file is the master configuration file for one application:

    master_config.txt

This file contains lines as follows:

VARNAME = VALUE

VARNAME must be all uppercase letters [A-Z], underline or digits. Any number of white space characters may separate VARNAME and =, and also = and VALUE. VALUE starts with the first non-whitespace character and ends with the last non-whitespace character on the line. Additional lines may be appended to VALUE immediately after the initial VARNAME = … line. Such lines must start with a space character. No whitespace are removed from such appended lines.

In addition, comment lines, starting with #, may be found. Blank lines are ignored.

In the source files, all text strings like:

[==VARNAME==]

will be substituted with the corresponding value when the files are modified and moved to the target directory. Such text strings may alo be found within VALUE strings, and they will be substituted as appropriate.

One variable is mandatory in master_config.txt: TARGET_DIRECTORY. This is the directory name of the top level of the target directory tree.

The following variables are used to select the modules that will comprise the application. They also identify the absolute path of the source directory for each module:

METAMODBASE_DIRECTORY     
METAMODSEARCH_DIRECTORY 
METAMODUPLOAD_DIRECTORY 
METAMODQUEST_DIRECTORY 

If any of these variables are missing, the corresponding modules will not be part of the application.

Each application delivering data to a database (an application with the METAMODUPLOAD and/or the METAMODQUEST module) must have a short acronym that uniquely identify the application for the database. This acronym is included in the master_config.txt file as the value of variable APPLICATION_ID.

To install an application, the following installation script (located in the top METAMOD2 directory) should be run with one argument:

update_target.pl application_directory

The argument is the absolute or relative path of the directory containing the master_config.txt file for the application.

For each module selected by the configuration file, there is a filelist.txt list of files in the corresponding module directory. The installation script will copy all the files in these lists to the target directory tree (given by TARGET_DIRECTORY in the configuration file). In the same way, files in the application specific filelist.txt file (located in the application directory) will be copied to the target directory tree. If any file name collision occur between the module file lists and the application file list, the file in the application file list is used. Thus, it is possible to substitute any file in any module with an application specific file, although this mechanism is primarily meant for image files, style sheets etc. Name collisions between files from different modules are supposed not to occur.

While copying the files, the script will perform all substitutions prescribed in the configuration file. The script will only copy files that are modified later than the corresponding target files (or the target file does not exist). Directories will be created as needed.

If any of these files should not be substituted according to the configuration file (e.g. a binary file), the file name must be prepended with = in filelist.txt.

The file pathes in each filelist.txt file must all be relative to the corresponding top module directory (or the application directory). The copied files will keep these relative pathes on the the target directory.

It is possible to use the configuration file to produce several target files from a single source file. This is done using the special directives:

!substitute_to_file_with_new_name sourcefilepath => targetfilepath
!end_substitute_to_file_with_new_name

The sourcefilepath must be a relative file path found in one of the filelist.txt files, and targetfilepath must also be a relative file path, but it is not required to exist in any filelist.txt file. The source file (given by sourcefilepath) will be modified and copied to the target file (given by targetfilepath) using the ordinary substitution directives in the configuration file. In addition to these substitutions, any substitution directive between the !substitute_to_file_with_new_name directive and the corresponding !end_substitute_to_file_with_new_name directive will be performed. Note that these substitution directives will not affect any of the other files produced by the installation script.

By using these special directives several times for the same source file, and varying the target file name between each use, several target files are produced from the same source file, and they will have different content depending on the in-between substitution directives found for each target file.