Project files

From phpCMS

Contents 1 Using project files 1.1 File extension 1.2 Structure 1.3 Explanation of fields

[edit] Using project files

In phpCMS the project file plays a central role for a whole website or alternatively only for certain types of pages within your website. In this project file you set the paths to some important files. Important files within a project are the templates (menu template and main template), the menu structure and the tag file (replacement table).

[edit] File extension

The file extension for the project file can be chosen arbitrarily. However, with time a certain “standard” has been built up for the file extensions, e.g. project files normally end on '.ini', tag files on '.tag', template files on '.tpl', menu files on '.mnu', and menu templates on '.mtpl'. This provides an easier portability to other systems.

[edit] Structure

A project file doesn't only contain declarations, it can also contain comments. Comments are produced by putting a semicolon at the beginning of the line. There are no comments allowed within a content line! To assign a value to a fieldname phpCMS uses the string ':='
(This sign is also used in mathematics and has the same meaning: to define an expression.)

Here's an example for the content of a project file:

HOME         := /demo
TAGS         := $home/template/home.tag
PLUGINDIR    := /parser/plugs
TEMPLATE     := $home/template/home.tpl
MENU         := $home/template/home.mnu
MENUTEMPLATE := $home/template/home.mtpl

Remark

Following variables are allowed here:

$home 

Value of HOME

$plugindir 

Value of PLUGINDIR

These replacements are only working, if the variables are at the beginning of the value.

In the PLUGINDIR value no replacement will be done!

[edit] Explanation of fields

Directories are always given relative to the document root of the webserver.

Let us first explain that a bit:

The document root is the upper most directory that can be addressed from the Internet when calling up a web site by its domain name as URL.
Example:

If you call http://www.mydomain.net/index.html than the index.html file 
located in the document root of your web space will be displayed. 

If you call http://www.mydomain.net/mydir/index.html than it will be the index.html file
located in the directory mydir located itself directly under the document root 

The URL of the web site in the example above is composed of the following elements:

• the protocol: "http://"
• the sub domain and the domain of the web server: "www.mydomain"
• the “top level domain” of the domain name: ".net"
• the path relative to the document root of the web server: "/" or "/mydir"
• and finally the name of the file located in that path (directory): "index.html"

Now to the fields in the project file:

HOME 

The entry HOME needs to be placed as the very first entry in the project file, as path relative to the document root and thus with beginning slash, but without trailing slash.

The entry for the demo delivered with the phpCMS package would be /demo if the "demo" directory is located directly under the document root (this is the default).

This tells phpCMS that the home directory is /demo and all paths given in all files related to this project file such as content files, templates, menu files, and project files can simply be entered as "$home" instead of "/mydir".

There are three exceptions, however:

1. the HOME entry in a project file has to be given as the real path relative to the document root and cannot itself contain "$home";
2. the same goes for the PLUGINDIR entry (see below);
3. the contents for the field {PROJECT} in a content file has to be given as the path to the governing project file relative to the content file (e.g. {PROJECT} ./template/home.ini).

The advantage of this is clear: Once you want to relocate your project from let's say "/mydir" to "/myotherdir/new" you only have to adapt the HOME entry in the project files.

The above was the only way to define the home directory with phpCMS 1.1.x. In that case a project file would look like the one shown further up. There for example

  TAGS         := $home/template/home.tag

means that phpCMS will look for the tag file in document_root/demo/template/ as you had declared before that

  HOME         := /demo

In more complex web sites with sitemap, search function, forms, etc., one often has several different project files (*.ini), e.g. if one uses different template files (*.ini). That would mean one has to set - and keep track of in case of relocation - the (same) home path in every project file.

As from phpCMS 1.2.0 a new parameter "GLOBAL_PROJECT_HOME" has been introduced in the default.php, the phpCMS configuration file. This entry is also accessible via the "Configuration" in the graphic user interface (GUI). There one can centrally define the overall home path at only one place and all the HOME entries in the different project files pointing to that same home directory can be deactivated or completely omitted. When phpCMS does not find a HOME entry in a project file it will fall back onto the GLOBAL_PROJECT_HOME entry in the default.php. An active HOME entry in a project file will in turn prevail over the GLOBAL_PROJECT_HOME entry.

Please note that this and the other specific phpCMS variables don't have anything to do with PHP variables, also if they are equal in their syntax.

PLUGINDIR 

This gives the path to the directory where phpCMS plug-ins are located. Up to now the PLUGINDIR entry in project files does not support the usage of "$home". So directories in the PLUGINDIR entries have always to be entered as paths relative to the document root. This will be changed in future phpCMS versions.

TAGS 

This entry describes the path to the tag file. The tag file is a replacement table for several expressions (see How to work with tag files).

TEMPLATE 

This defines the path to the main template. If you use sub templates, you include them directly in the main template.

MENU 

With this entry you set the path to the menu file.

MENUTEMPLATE 

The menu template located in the directory entered here is used to prepare and show the menu structure which is defined in 'MENU'. At the same time it is a sub template, but it doesn't need to be called explicitly. It's automatically called by usage of the variable {MENU NAME="MAIN"} in the template.