OpenETMuS (Extendable Template Markup Script)

Every website using ETMuS has the same base structure:

/
|-- example
|   |-- lib
|   |   |-- etmus.class.php
|   |-- designs
|   |   |-- default
|   |   |   |-- head.html
|   |   |   |-- body.html
|   |   |   |-- page_default.html
|   |-- pages
|   |   |-- default
|   |   |   |-- default.php
|   |-- config.inc.php
|   |-- index.php

Each page exists out of four files:

1. a head.html file which is located in the design folder (this file is ignored when using the IsDownload oder DisplayBlank option)
2. a body.html file which is located in the design folder (this file is ignored when using the IsDownload oder DisplayBlank option)
3. a html file containing the page-related design part. This file is required and must be placed into the design folder. The output of this file is saved into the Content variable
4. a php file containing the dynamic code part. This file isn't required as long as you only want a static page. This file must be placed into the pages folder.

If you don't set any designsheet (see below) the default foldername inside the "designs" and "pages" folder is named "default".

Configuring ETMuS

The global config.inc.php file contains two different parts

1. Part: Including the core class and global plugins

All classes and plugins that should be available globally have to be included in the first lines of the config.inc.php.

require_once("lib/etmus.class.php");
require_once("lib/mysql.plugin.php");

Note: To avoid including the classes twice you should only include them with include_once or require_once

2. Part: Configuring the global settings

After including the global classes and plugins you can set the global settings. Therefore you have to get the singleton of ETMuS.
Note: You will always get the same instance when using the getSingleton() function.
These settings are set on every page. Some settings are read, write or read-write only.

// get the ETMuS singleton
$ETMuS = \OutstandDesign\ETMuS\ETMuS::getSingleton();
// set the pagetitle
$ETMuS->Pagetitle = "Nice Page";
// do other settings
. . .

Note: A full list of settings can be found in the property section below.

You can change from live mode (productivity - default) to debug mode (testing) by setting the debug variable to true. By switching into debug mode you have the ability to view all notices and warnings which are thrown by ETMuS or PHP.

$ETMuS->Debug = true;

Note: Some errors are suppressed and are only active when in debug mode.

All properties can be used (some are read or write only) in your PHP code. Some can also be used as markup tags. These are described more detailed in the "Markup" section below.

Read-Write

$ETMuS->Imagefolder : string The main image folder. Default: ""
$ETMuS->Impress : string The impresstext of the page. Default: "© Outstand-Design"
$ETMuS->Language : \OutstandDesign\Language If used, the current language class. Default: null
$ETMuS->Pagetitle : string Title of the current page. Default: ""

You can further define own Read-Write properties by simply writing
$ETMuS->YourVar = VALUE This way a new property with the name YourVar will be registered and gets the value VALUE.

Write-only

$ETMuS->Designsheet : string The current designfolder to use. Default: "default"
$ETMuS->DisplayBlank : bool Set to true, if you want to only display the content area. Default: false
$ETMuS->IsDownload : bool Set to true, if you want to only display the page-related php file output. Default: false
$ETMuS->Subdesign : string The current subdesign page (php file) to parse. Allows to override the pre-set page. Default: Parameter given to the __build__ function
$ETMuS->User : object If used, the currently logged in user. Default: null
$ETMuS->Sourcedir : string Set the source directory where the designs and pages folder is located. Default: ""
$ETMuS->Debug : bool Activates the debug (testing) mode. When activated error_reporting will be turned on and ETMuS doesn't suppress notices, warnings and error messages. Default: false

Read-only

$Page : string The current page. For example: "default"

Working with ETMuS

When working with ETMuS you have to get the singleton of the script. You don't have to always instanciate a new ETMuS class. Rather you can just use the getSingleton() method if you need to manipulate some settings.

public function getSingleton ( )

Returns

\OutstandDesign\ETMuS\ETMuS The current instance of ETMuS.

Example

// set the current instance to the $ETMuS variable
$ETMuS = \OutstandDesign\ETMuS\ETMuS::getSingleton();
// do some stuff
$ETMuS->SaveMe = true;

// get the current instance again
$ETMuS = \OutstandDesign\ETMuS\ETMuS::getSingleton();
// get the saved variable
$var = $ETMuS->SaveMe; // $var = true;

Adding links to a navigation block

If you want to add a link to a navigation block (for example a main navigation) you can use the NavigationAddLink method in combination with the <> tag (see the marker section).

public function NavigationAddLink ( string $navigationname, array $link_info[, string $parentlink] )

Parameters

$navigationname string The navigationname the link should be added to.
The navigationname must start with a letter and can further only have letters and digits (minimum 4 characters / maximum 14 characters)
$link_info array The link informations you can indiviually access inside the link template.
Required keys are: url, name.
Optional keys: active, style, identifier and also all manually set keys
$parentlink string The parentlinkname (or even better the identifier if set) of the parent link. When specified the added link will be a sublink of the parentlink.

Exceptions

If the Debug mode is activated:

E_WARNING
"NAVIGATION_NAME: NAME has no identifier - automaticly set. Please view the documentation.": If the identifier isn't set. An identifier is automaticly set.

E_ERROR
"NAVIGATION_NAME does not match the requirements - Please view the documentation.": If the navigation doesn't match the restriction descripted above.

Start the parse process

The index.php file starts the parse operation by calling the __build__ method. After calling this method the PHP file with the name of the given parameter will be parsed. If the DisplayBlank and IsDownload property is set to false the doctype will be set and the head and body part will be parsed too.
At last the method outputs the content and stopps the execution of the script. Therefore you should call the __build__ method after doing all operations.

public function __build__ ( string $page )

Parameters

$page string The page to parse. The pagename should be named without the "page_" prefix.

Example

// parses the page_example.html / example.php file
$ETMuS->__build__ ( "example" );
echo "hello"; // this echo will be never reached

Note: The design file is always needed. The PHP - file is optional.

Format

The markup tags are build up really simple. All normal tags start with << and end with >>. This way they cannot be injected by user inputs as long as you replace html special entities such as < with the html entity equivalent < and > with >. See the [htmlspecialchars][1] function at the php docs.

Note: The output of the designfile with all replaced tags will be save in the <<CONTENT>> tag.

Example

<div><<Impress>></div>
// will be converted at runtime to
<div>© Outstand-Design</div>

// Whereas
<div><<Impress>></div>
// will output
<div><<Impress>></div>

[1]: http://de.php.net/manual/en/function.htmlspecialchars.php "htmlspecialchars function"

Special cases

There are also some tags which represent a special function. These special cases are:

• Navigation sections
• Access control sections
• Include tags
• Table sections

Navigation sections

Navigation tags have this structure: <<NAV:NAME>>. The NAME should be replaced by the name you gave your Navigation.

By using the NavigationAddLink-method you can add new links to a navigation. The parser tries to find the following files and outputs them in the order written below:

1. navigation_start_NAME
2. navigation_COUNT_NAME_off (if the active attribute isn't set) or
   navigation_COUNT_NAME_off_STYLE (if the active attribute isn't and the style attribute is set) or
   navigation_COUNT_NAME_on (if the active attribute is set) or
   navigation_COUNT_NAME_on_STYLE (if the active and style attribute is set)
3. Note: If there are no sublinks go to point 2. If all links are looped go to point 6. Increment COUNT with 1 in each sublink block
   navigation_COUNT_substart_NAME or
   navigation_COUNT_substart_NAME_STYLE (if a style attribute is set)
4. Repeating from point 2. as long as sublinks are available
5. navigation_COUNT_subend_NAME or
   navigation_COUNT_subend_NAME_STYLE (if a style attribute is set)
6. navigation_end_NAME

Example

navigation_start_example.html
 navigation_1_example_off.html
   navigation_2_substart_example.html
   navigation_2_example_off.html
     navigation_3_substart_example.html
     navigation_3_example_off.html
     navigation_3_subend_example.html
   navigation_2_example_on_act.html
   navigation_2_subend_example.html
 navigation_1_example_on_newact.html
 navigation_1_example_on.html
 navigation_end_example.html

Access control sections

ETMuS contains a very basic access control system. This system can be extended by a privilege plugin. The basic system only differs if somebody is "logged in" or not. This is achieved by checking the User Property. If it is set to something else as null the current website user is "logged in".

You can hide logged in parts from not logged in users by wrapping these parts in the design files with the <<PRIVILEGE:loggedin>> command.
You can also hide content from the logged in users by using the <<!PRIVILEGE:loggedin>> command. This way content is only shown to not logged in users.

A PRIVILEGE section should end with <</PRIVILEGE:loggedin>> if using the loggedin privilege.

In your code parts you can check if a user is logged in or not by simply checking if the $ETMuS->User variable is != null.

Example

PHP (code) file

if ( $ETMuS->User != null ) {
    // User is loggedin
} else if ( $ETMuS->User == null ) {
    // User is NOT loggedin
}

HTML (design) file

<<PRIVILEGE:loggedin>>
<!-- this part is only shown when the user is loggedin -->
<</PRIVILEGE:loggedin>>
<<!PRIVILEGE:loggedin>>
<!-- this part is only shown when the user is NOT loggedin -->
<</PRIVILEGE:loggedin>>
<!-- this part is always shown -->

Include tags

If you want to dynamicly include content in a page you can use the include tag. This tag includes the specified file and parses it for more tags. You can use the command by writing <<INCLUDE:NAME>> whereas NAME should be replaced by the html-design filename you want to include.
Note: The file will be included from the Designsheet folder.

Example

HTML (design) file:

<<INCLUDE:example>>
<!-- includes the example.html file -->

Table sections

Tables are useful when you have content that should be repeated a few time. Therefore it is not only useful for table in the known cases (HTML-Tables). You can also use them for displaying lists, shopping products, user comments and so on.
A table is set up by using the <<INCLUDE:NAME:TABLE>> command whereas NAME should be replaced by the html-design filename. It behaves like an include tag command except that it repeats itself for each table row you've inserted.

You can insert a new row by writing

$ETMuS->TableData_NAME = array("name1" => "val1", "name2" => "val2");

The values of the table can be accessed by using [<__VALNAME>] where VALNAME is the name of the value for example "name1" or "name2".

If you want to use multiple tables with the same design within one page you just have to append a counter to the filename. This counter must have this structure: __NUM (__1; __2; __3 and so on)

Example

PHP (code) file

$ETMuS->TableData_example = array("name1" => "val1", "name2" => "val2");
$ETMuS->TableData_example = array("name1" => "abc", "name2" => "def");

$ETMuS->TableData_example__1 = array("name1" => "val3", "name2" => "val4");
$ETMuS->TableData_example__1 = array("name1" => "abc1", "name2" => "def2");

HTML (design) file: page

<div id="part1">
<<INCLUDE:example:TABLE>>
</div>
<div id="part2">
<<INCLUDE:example__1:TABLE>>
</div>

HTML (design) file: example.html

<div>[<__name1>] was created by [<__name2>]</div>

A possible output could be:

<div id="part1">
    <div>val1 was created by val2</div>
    <div>abc was created by def</div>
</div>
<div id="part2">
    <div>val3 was created by val4</div>
    <div>abc1 was created by def2</div>
</div>

A detailed usage example can be found in the example directory of the ETMuS package.