This is an old revision of the document!
How to install and configure
DIRECTORY STRUCTURE
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.).
CONFIGURATION
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.
INSTALLATION
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.
MULTIPLE TARGET FILES
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.