Want to build a site? A small one for your homepage or a large corporate portal? Already have a page that looks great and want to populate it without copying its layout in all your content files? Or maybe you are sick of fixing the same line on all the pages of your site? Well, let's do it together. We are going to use templates...

Templating practice is very straightforward: instead of supporting many files with the same layout and different content, you just define a single template file and many content files. Template file contains common page layout while content files -- the varying contents. The final site is built from the content (source) files by inserting them one by one into the template and thus generating destination documents in appropriate folders. Of course some kind of documents like JPEG images don't need to be parsed but will be copied to the destination as is.

Open Site Builder templates (there actually may be more than one template for a site, for example a home page may use a different layout from other site) are HTML files containing special placeholder which defines where the text from content files will be positioned in the template.

Different page areas (like menus or navigation bars) may contain slight design deviations from page to page while staying consistent with common site design. Those parts of a main template which change we will call sections and store them in separate files. Template may contain placeholders for sections just like for content. Sections may vary on per-directory or even per-file basis. Section files in most cases define a submenu information for a given zone of a site. For example, a submenu in your About zone may contain "Mission", "Contacts" and "Partners" links, while a submenu of Jobs zone will contain "Open vacancies", "Add resume" and "Check my resume" links.

Sample site structure may look like this:

index.html          (Welcome page)
|
+-about/            (About zone)
| index.html        (Mission)
| contacts.html     (Company contacts)
| partners.html     (Business partners)
|
+-jobs/             (Jobs zone)
| index.html        (Current vacancies)
| add.php           (Add resume)
| check.php         (Check my resume)
|
+-products/         (Products zone)
  index.html        (Price list)
  product.php       (Product description)

If this submenu needs to have more than one implementation for the zone (for ex. you decided to paint current page name in bold when user loads it, so on Mission page "Mission" will be in bold face while on Contacts page we emphasize "Contacts") you may create different sections for the same zone and include a command in your content file notifying that on this page it needs to use another section instead of a standard one.

A Mission page in About zone may look like this:

After template, content and section files are presented, we need to define the main configuration file which contains the control information about where to take the template and content files, how your sections are stored, the target location for assembled files and so on.

Except the above mentioned parameters your config file may define special "entities", which are then usable in your templates, section and content files. These entities are simple strings and behave just like HTML predefined special characters encoded in & and ; symbols. For example © entity represents a © symbol in HTML. When you insert your defined entity in a content file it will be automatically translated into the appropriate string when the content file is assembled. You may use these entities for the blocks of code that appear more than once on your content pages like color constants or different footer notifications. For example, you may define a vat entity with VAT included value so that every time a &vat; appears in text it is replaced by VAT included string.

When you become more familiar with entities you may notice that it would be of a great convenience to have a construct like functions or macros in C, a dynamic entity, where you may pass parameters to it. This is possible: you can define a, say, href macro with two arguments (first is a url resource, second -- a link title) to be <a href="$1">$2</a> which you then use in your text like this: &href {mission.html} {Our Mission};. This macro will be converted to <a href="mission.html">Our Mission</a> string in target file by taking parameters from curly braces and inserting them in place of $1 and $2 variables in macro definition.

Actually you may have files on your site which you want to be copied as is, without using templates. Those may include different binary data like images or PDF documents. Specifying the extensions for those files that you want to just 'copy' and others for files that you want to 'build' you explicitly set the scope of files that will be present at the target location. Files outside of this scope will not be processed.

The process of building a site is accomplished by calling the file osb.php from your browser, with the path to your config file and the level of information you want displayed (only a total of all processed files or a list of all files in all processed directories with their corresponding status: updated or up-to-date). This script scans all the subdirs of your source (mentioned in your config file), selects the files within the specified scope and checks the corresponding files in destination subfolders. If destination is up to date the content file is skipped, otherwise if content (or even template or section) files changed since last execution (are newer) it rebuilds (or copies, depending on extension) the target file. The destination filename is computed from the name of source file (see Content files section in Tutorial).

That's almost all. Actually there are some supplemental actions like automatic creation of sitemap file, running programs on destination files after update (if you use some kind of encoder for your commercial scripts, all updated php files need to be re-encoded after the build) and setting SQL permissions for specified roles (each directory may define its own SQL role and grant it different permissions).

For a primer on assembling a sample site see the Tutorial document.

For a full list of parameters available in Open Site Builder see the Commands Reference document.