PanuWorld Layout Manager

Installation and usage manual

To use the PanuWorld Layout Manager you will need a local copy of your web site on your hard disk. (To make the local copy to work during your testing and development, you will need to ensure that all internal links in it are relative.) The LayoutManager.exe should be copied to a folder just above the root folder of your web site local copy. Let's say that the root directory of your local copy is C:\Internet\www\. In this case, the LayoutManager.exe must be copied to directory C:\Internet\.

In addition to this, you will need to create a template file _layout.html in the same directory (and also _random.txt if you use the $EVAL RANDOM command). The template file shall contain the top and bottom parts of the HTML that are common to all web pages in the site. In the middle of the template file, there must be command  followed by command . These tags mark the location where the content section of the web page is inserted. Same tags will be present in the web page files, too. There they mark the beginning and the end of the content section, which is left unchanged when Layout Manager processes the file.

Daily use

To apply the template to a HTML file, just drag-and-drop the file on the LayoutManager.exe program icon. However, it is much more easier to process the whole folder of HTML files by dropping the folder on the Layout Manager's icon in the Windows Explorer. In such case Layout Manager processes all *.html, *.htm, *.shtml, and *.php files found in the specified folder. All other files are skipped. You can use a single Windows Explorer window for processing your web site files: Make the folder tree visible and open the folder where the LayoutManager.exe is. Then simply drag the folders from the folder tree onto the LayoutManager.exe icon one-by-one.

You can use any HTML editor (plain HTML or WYSIWYG editors) to create and edit your web page files. However, some WYSIWYG editor may mess up the Layout Manager commands by changing the line-wrapping of the HTML comments. One WYSIWYG editor that has been tested to work well with the PanuWorld Layout Manager is the free Mozilla-based Kompozer. After editing any pages, remember to reprocess them with the Layout Manager so that any changes made to Layout Manager commands will be executed. It also fixes the common sections of the web pages if they have been damaged during editing the files.

To create new web pages, just copy some existing ones and rename them accordingly. Alternatively, you can create just empty files with correct names and the process them once with the Layout Manager before starting to write the contents in them. This way the common layout and styles are added to the new page before you open them in your editor. Be careful when starting to write content on a new HTML page: all content and Layout Manager commands (see below) must be written between the  and  tags. All changes outside these tags are deleted when the file is reprocessed with the Layout Manager.

Layout Manager variables

In the simplest configuration, Layout Manager just copies the beginning of the template file (until tag ) onto the web page, then lefts the actual content section of the web page untouched and finally ends the web page with the end of the template file (starting from ).

Usually the template file contains the HTML HEAD section completely and also the <BODY> and </BODY> tags (because they should be present on all web pages). However, you might want to have different title on each page. The solution for this are Layout Manager's variables. With the variables you may insert page-specific data in the common sections of the template when the page is processed. For example, add the following HTML comment in the content section of your web page (between  and  tags):

<!--$SET TITLE layout manager manual
$SET DATE 12.1.2008
-->

Then you can simply use the $EVAL command in the template common section to insert this page-specific title in the common head section:

<head>
<title>$EVAL TITLE</title>
</head>

Command $EVAL NAME (where NAME is your choice for the variable name) in a common section of the template file _layout.html is replaced with the current value of the variable when the template is applied on a web page. Note that $EVAL commands referring to undefined variables are replaced with character 2 (two); i.e. undefined variables are not evaluated to empty strings. If you want the variable to evaluate as an empty string, you will need to set it explicitly to empty using the $SET command.

$SET and $BEGIN/$END commands are first evaluated in the template file _layout.html and then in the HTML file to be processed. This allows you to set default values for variables in the template content section (between  and ), and then override only those variables that need to differ from the defaults in the web page code.

If you want to include multi-line page-specific data (e.g. Javascript code, CSS rules, or PHP code) in the common sections (e.g. in the HEAD block), use commands $BEGIN NAME and $END NAME (where NAME is your choice for the variable name in UPPERCASE) instead if command $SET.

<!--$BEGIN SCRIPT
function foo() {
	alert("bar")
}
$END SCRIPT-->

When using $BEGIN/$END commands, all data between the command tags are stored into the variable and inserted where corresponding $EVAL command in used. Same $EVAL command can be then used to use the variable contents in the template file:

<script type="text/javascript"><!--
$EVAL SCRIPT
--></script>

To see different ways to use variables, just look at the HTML source code of different pages on panuworld.net or other sites using the PanuWorld Layout Manager. Because the HTML comments containing any page-specific $SET and $BEGIN/$END commands must be in the content section of the page, they are still visible in the processed HTML code.

The Layout Manager does not require that the commands must be enclosed in HTML comments (). However, it is the easiest way to hide the commands so that they will not be visible on the actual web page. In case of PHP-based web pages, you may also hide the $SET and $BEGIN/$END (etc.) commands in PHP code tags (<?php ... ?>). In that case the PHP processor will strip the Layout Manager commands away when serving the page to the web browser effectively hiding the Layout Manager -related stuff from the HTML source that anyone can see.

Naturally, any Layout Manager commands in a PHP code block included in the web page content section must be enclosed in PHP's comment delimiters; otherwise the PHP parser will report an error when parsing the PHP code.

<?php /*
$SET TITLE layout manager manual
$SET DATE 12.1.2008
*/ ?>

Conditional inclusion

In addition to some specific variables, you may want to have one block of HTML code on one set of pages and another block of HTML on another set of pages. As shown above, you could use $SET or $BEGIN/$END commands on each page to select the code the particular page and $EVAL in the template file at location where you ant to insert the code. However, what happens if you want to change either one of these widely used HTML code snippets? You would have to edit the $SET (or $BEGIN/$END) commands separately on each web page file!

There is also a more clever way to accomplish the same result, let's call it conditional inclusion of template rows. By using commands $IF and $IFNOT in the template common sections you may control which parts of the template are included in on the web page. For example:

$IF NAMEthis line of this template is included <b>only if variable NAME has been set
$IFNOT NAMEthis line of this template is included <b>only if variable NAME has not been set
</b>

If these kind of rows are present in the template, then you can select which line you want to include on the web page by setting the variable NAME in the web page content section or leaving it unset. The same approach can be used for selecting HTML code from more than two choices, just use more variables (one variable for each choice). Note that the $IF/$IFNOT commands affect only the rest of the corresponding template row: if you want to conditionally include many rows if data, you have to add $IF/$IFNOT commands in the beginning of each line separately.

Predefined variables

There are some variables that are automatically set when the processing starts (for each file). These variables are ROOT and GENERATOR:

Variable name	Description	Example value
`ROOT`	Relative path from the web page to the root level of the site	`../../../`
`GENERATOR`	The current version of the Layout Manager	`PanuWorld Layout Manager 2; https://panuworld.net/`

By using $EVAL ROOT when referencing to images in the common section of template file allows using relative URLs also there. This way the images are displayed correctly even when browsing the local copy of the web site. Note that the variable ROOT contains the trailing slash (/, when applicable), so you need to start the subdirectory/file name immediately after the $EVAL ROOT command:

<img src="$EVAL ROOTimages/title.jpg alt="My Site Title">

Some web pages cannot use relative URLs in links and for images. This kind of pages are for example the HTTP error handler pages that can be displayed with any URL. However, they can still use the same Layout Manager template if you override the variable ROOT in the page content with command $SET ROOT /. Effectively after this, all images and links included in the common sections of that page will use absolute URLs. For an example of this, enter an incorrect URL to this panuworld.net site and look at the HTML source code of the error message page.

PanuWorld Layout Manager is originally designed for sites with all-lowercase file and directory names. If the subdirectory/file name begins with an UPPERCASE letter, you have to escape it so that the letter is not considered as a part of the $EVAL command. In URLs you can do this with URL-encoding. For example, if images directory name above would have been Images, then the URL should have been written like this:

<img src="$EVAL ROOT%49mages/title.jpg alt="My Site Title">

The same thing must be taken into account always when an UPPERCASE letter follows any Layout Manager command. Outside URLs, you can use HTML character entities (&...;) or extra HTML tags, e.g. comments to make it clear where the Layout Manager command ends. Similar escaping techniques must be used if the actual contents of the web page contains text that looks like Layout Manager commands (as have been done on this web page).

Folder variables

If you want to include images in the common section that reflect the location in your site, e.g. for navigational purposes, you can use command $SET on each page telling which image file should be included for that page. However, the $FOLDER command allows you to set the variables automatically based on the directory names in the URL of the web page. For example, if you have subdirectories utils, misc, and games on your web site, add the following commands in the content section of the template file:

<!--$FOLDER UTILS
$FOLDER MISC
$FOLDER GAMES
-->

Note that the directory names must be written in UPPERCASE, like all Layout Manager commands. When the commands above are processed, e.g. variable UTILS is set to character 1 (one) if there is a directory name utils (case-insensitive) as a part of the URL path of the web page under processing. If you remember that $EVAL command is replaced with character 2 (two) for unset variables, $EVAL UTILS will return character 1 if the current web page is under directory utils and character 2 if not. This can be used for example in image URLs selecting different images based on the URL path of the web page.

You may also evaluate variables in e.g. in Javascript code included in the common section of the template:

<script type="text/javascript"><!--
var under_utils = $EVAL UTILS
function check_folder() {
	if( under_utils == 1 ) alert("This file is below the 'utils' directory.")
}
--></script>

Because the $FOLDER command lefts the variable unset if there is no match in the URL path, you can also use $IF/$IFNOT commands to conditionally include template data based on the web page URL. This is useful especially in building other types of navigational elements than simple changing images.

Inserting randomly selected data

Special $EVAL command $EVAL RANDOM allows inserting randomly varying element on the web page. These randomly selected elements could be for example image URLs or HTML code for banners. They will change every time when the file is processed by the Layout Manager.

When the command $EVAL RANDOM is found in the template common sections, it is replaced with a randomly selected row picked from the file _random.txt. The file _random.txt must be located in the same directory where the LayoutManager.exe is (_random.txt is not needed if command $EVAL RANDOM is not used in the web site). All empty lines and lines beginning with hash (#) character are ignored in file _random.txt, all other rows are subject to the random picking.

More information

For complete list of PanuWorld Layout Manager commands, see the PanuWorld Layout Manager command reference. Example template file and the download link can be found on the PanuWorld Layout Manager home page.