Config file elements

Config file is a place where you set the parameters of assembling your site. Here you define source and target folders, template files, your entities and macros etc. When calling the osb.php script which does all the work of assembling the site you pass a link to this file from which it loads all the defined parameters.

When setting source and target folders you may specify path as absolute or relative to your config.xml file. See source, target tags.

See template tag for a way to define different templates, suffix tag to change the default .src extension and Appendix A for a primer on resolution of file names.

Here is a sample config.xml file which closely resembles the default parameters for most tags. You may use it as a reference for elements description.

<site title="Test Site">
  <source>test</source>
  <target>/Users/stas/Sites/test</target>

  <template>base/main.html</template>
  <template suffix=".help">base/help.html</template>
  <template suffix=".home">base/home.html</template>
  <template suffix=".0">base/empty.txt</template>

  <entity name="w1">640</entity>
  <entity name="w2">800</entity>
  <entity name="promo-link" filename="base/promo.html" />

  <macro name="tr" params="2"><![CDATA[<tr><td>$1</td><td>$2</td></tr>]]></macro>

  <access-rights grant-section="grants" role-mask="osb_%s" schema="osb">roles</access-rights>
  <exec suffix=".php" exclude=".nocode">d:\zend\zendenc --delete-source %s</exec>

  <ver-file>ver.txt</ver-file>
  <log-file>build.log</log-file>

  <!-- default values follow -->

  <sections>_sections.xml</sections>

  <suffix action="copy">.html;.htm;.shtml;.css;.js;
    .jpeg;.jpg;.gif;.png;.ico;.swf;
    .php;.phtml;.php3;.pl;.java;.asp;.asx;
    .zip;.gz;.tar;.bz2;
    .doc;.xls;.pdf;.xml;.txt
  </suffix>
  <suffix action="build" default="html">.src</suffix>
</site>
access-rights

This element contains the name of section responsible for granting different kind of SQL permissions to the role. File which name is constructed by applying this value into the section-mask is located in each folder and scanned through for the presence of lines defining the grants. The new section file is then created with correct SQL lines used to create the corresponding SQL role and grant it the rights to the listed objects in the specified schema. Schema is specified by the schema attribute, role name is created by applying current folder name to role-mask attribute and the new section file name is created by applying grant-section attribute to section-mask element.

Consider the following section file _roles.cfg with role description:

UPDATE
    Employees

SELECT
    ViewTrackEmployees
    ViewRolesList
    Qualification
    Qualification2
    ViewSubcategories
    Makers

# track_sticker
    ViewTrackReceipts
    ViewTrackWares
    Employees
    PriceList2
    WaresPayment
    ViewPartsUsed
    ViewPartsNeeded
    WaresList
    MakersOrders
    PartsGiven
    ViewServicesUsed
    ClientCalls

EXECUTE
    AddNeededSupplement
    GetSupplement

SYSTEM
    OSBDBA

END

Then the resulting file _grants.cfg will contain the following SQL (based on values from the sample config.xml file above and supposing current folder name is stats):

create role osb_stats not identified;
grant CREATE SESSION to osb_stats;
grant UPDATE on osb_schema.Employees to osb_stats;
grant SELECT on osb_schema.ViewTrackEmployees to osb_stats;
grant SELECT on osb_schema.ViewRolesList to osb_stats;
grant SELECT on osb_schema.Qualification to osb_stats;
grant SELECT on osb_schema.Qualification2 to osb_stats;
grant SELECT on osb_schema.ViewSubcategories to osb_stats;
grant SELECT on osb_schema.Makers to osb_stats;
grant SELECT on osb_schema.ViewTrackReceipts to osb_stats;
grant SELECT on osb_schema.ViewTrackWares to osb_stats;
grant SELECT on osb_schema.Employees to osb_stats;
grant SELECT on osb_schema.PriceList2 to osb_stats;
grant SELECT on osb_schema.WaresPayment to osb_stats;
grant SELECT on osb_schema.ViewPartsUsed to osb_stats;
grant SELECT on osb_schema.ViewPartsNeeded to osb_stats;
grant SELECT on osb_schema.WaresList to osb_stats;
grant SELECT on osb_schema.MakersOrders to osb_stats;
grant SELECT on osb_schema.PartsGiven to osb_stats;
grant SELECT on osb_schema.ViewServicesUsed to osb_stats;
grant SELECT on osb_schema.ClientCalls to osb_stats;
grant EXECUTE on osb_schema.AddNeededSupplement to osb_stats;
grant EXECUTE on osb_schema.GetSupplement to osb_stats;
grant OSBDBA to osb_stats;

grant-section
section name to create and populate with SQL instructions granting rights to the current role. This name will be incorporated into section-mask by means of sprintf function to get the resulting section file name. In the above example: grant-section is grants, section-mask is _%s.cfg, so resulting file with SQL code is _grants.cfg.

role-mask
attribute defining mask into which the name of current folder is inserted to get a role name for this folder (example above: if dir name is stats and mask is osb_%s then the name of the SQL role becomes osb_stats). Since element value will be processed by sprintf function with one parameter specifying section name, the value must contain one %s placeholder for it. All other % symbols must be prefixed with another %.

schema
default SQL schema to whose objects the rights are granted (example above: schema is osb_schema so each mentioned SQL object is prefixed with this name, like osb_schema.ClientCalls).

delimiter

defines the delimiter character that separates titles in content files or values of different lists in configuration file (default is tab character \t for titles and ; for lists).

group
identifies the list containing values to separate. The value suffix defines the delimiter for a list of suffixes to build / copy (see suffix). If omitted then the delimiter is defined for titles in content files.

entity

definition of site-wide entities. OSB entities are used in template, section and content files just like other HTML-style entities (wrapped in & and ; symbols, like &copy; or &amp;). Entity value may be defined directly in config.xml or in external file in which case file name must be provided with the filename attribute. May not contain macros. If contains other entities the following apply: entities are processed in order in which they were defined in config.xml file. If entity A contains entity B in it then A must be declared before B. As a rule of thumb define complex entities first and atomic entities then.

name
defines the name of the entity. The entity will be accessed by its name so that if it is named promo its value is retrieved in content, section and template files with &promo;.

filename
sets the name of the file containing entity value. Path may be absolute or relative to config.xml. May be used in situations with large values.

For example, we may consider to define a promotional link at the end of each page of our site (see below). We know that the text for the link will be the same on each page. At the same time we want flexibility in the sense that when we decide to change that text it must automatically change on all corresponding pages. We create file promo.html in our base folder with the text of the entity. Then in config.xml we include the following line which creates the entity promo and reads its content from file base/promo.html:

  <entity name="promo-link" filename="base/promo.html" />

See also:     macro.

exec

specifies a program to execute each time a conforming file is updated/copied to the target folder. Since element value will be processed by sprintf function with one parameter specifying target file name, the value must contain one %s placeholder for it. All other % symbols must be prefixed with another %. Conforming files are restricted by element arguments. exec call is executed on the conforming target file. The return status of the program is analyzed to define whether it ended successfully.

suffix
defines target file extension for conforming files. If extension equals to suffix and file is not denied by exclude argument it is considered conforming.

exclude
if one of source file extensions is equal to exclude value this extension is stripped from target file name and the target file is considered non conforming even if its extension equals to suffix.

host

defines remote host parameters. Used by OSB FTP Uploader and OSB Sitemap Generator.

id
sets host identifier to use when launching FTP Uploader.

user
defines username for connection.

pass
defines password.

path
defines base directory on host used to upload files.

Example:

  <host id="ftp1" user="uploader" pass="00000" path="/www">ftp.myhost.com</host>
log-file

defines a filename for the log file which tracks the names of updated/copied files. Log is not written if no files were updated/copied. If ver-file element is specified version info is also logged. Path may be absolute or relative to config.xml.

macro

defines site-wide macro command. Macros are more powerful entities which may use parameters to provide changing content. Parameters for the macro are stored in curly braces and $1, $2, ..., $n placeholders in macro content are replaced by corresponding parameters at runtime. OSB macros are used in template, section and content files and are of the form &macro{param1}{param2}{param3}; where the name of the macro and the number of parameters is defined by element arguments. Macro value may be defined directly in config.xml or in external file in which case file name must be provided with the filename attribute. May contain entities. If contains other macro the following apply: macros are processed in order in which they were defined in config.xml file. If macro A contains macro B in it then A must be declared before B. As a rule of thumb define complex macros first and atomic macros then.

name
defines the name of the macro. The macro will be accessed by its name so that if it is named tr and has params value set to 2 its value is retrieved in content, section and template files with &tr{cell 1}{cell 2};.

params
defines the number of parameters available to the macro. When using macro in source files exactly the same number of parameters must be provided in curly braces. Otherwise the macro will not be recognized. The number of parameters is unlimited. $1, $2, ..., $n placeholders are used in macro content to determine the placement of corresponding parameters.

filename
sets the name of the file containing macro value. Path may be absolute or relative to config.xml. May be used in situations when defining large macro values.

An example that demonstrates the tr macro from above is:

  <macro name="tr" params="2"><![CDATA[<tr><td>$1</td><td>$2</td></tr>]]></macro>

Since our config file is an XML document we have to use the CDATA form to put HTML tags in macro content. Otherwise you'll have to use &lt; - &gt; pairs around all the tags. If macro content is significantly larger than the one line example or you just want to separate macros bodies from configuration instructions you may prefer to provide the filename argument instead of incorporating macros into config.xml file.

See also:     entity.

section-mask

specifies the look of section files. Since element value will be processed by sprintf function with one parameter specifying section name, the value must contain one %s placeholder for it. All other % symbols must be prefixed with another %. Section names are thus restricted to filesystem allowed characters. For example, if section-mask is defined as _%s.cfg then section named submenu-level-2 will reside in file _submenu-level-2.cfg.

DEPRECATED See also:     sections.

sections

specifies the name of an xml file containing sections definitions for the current directory. Default value is _sections.xml. File structure is as follows:

<sections>
  <section name="menu"><a href="&.root;/">Home</a> || <a href="links.html">Links</a></section>

  <section name="home"><![CDATA[<a href="index.html">Home</a>]]></section>
  <section name="home-a">Home</section>

  <section name="links"><![CDATA[<a href="links.html">Links</a>]]></section>
  <section name="links-a">Links</section>
</sections>

Each section is identified by name attribute. In the above example Home :: Download :: Introduction :: Tutorial :: Reference :: Support :: Links is placed in the template file to indicate the position of the menu for all files that will use this template. Then when OSB visits the directory containing this sections file the menu section is translated into the following: <a href="&.root;/">Home</a> || <a href="links.html">Links</a>. Since home and links are also defined in the file this construction is resolved to the form <a href="index.html">Home</a> || <a href="links.html">Links</a>. This representation replaces Home :: Download :: Introduction :: Tutorial :: Reference :: Support :: Links placeholder in the template.

Source file links.src may contain command .replace(links,links-a). In this case the whole Home :: Download :: Introduction :: Tutorial :: Reference :: Support :: Links placeholder will be replaced by <a href="index.html">Home</a> || Links. Guess why.

site

a container element for config.xml file.

title
attribute contains current site title and will show in a list of config parameters while building site. Site title may be accessed through a .site-title placeholder in template, section and content files.

sitemap

defines the name for a sitemap file. This file will be generated in target folder. If omitted the sitemap file will not be generated.

id
the unique id that identifies sitemap definition. This Sitemap id is provided when launching OSB.

url
defines the site url as visible from the user's perspective. The address must identify the directory containing document root (whether the site root or a site subfolder).

Example:

  <sitemap id="sm1" url="http://www.myhost.com/">sitemap.xml</sitemap>
source

defines the root of source structure which will be processed. May be absolute or relative to config.xml. The files in the source tree are content and section files which are copied/built into the target. The folder structure from the source will be copied into the target. Section files in each subfolder correspond to this subfolder only.

See also:     target.

suffix

element that defines which action will be taken on file depending on file extension. Element content is a list of extensions each starting with a dot. The list of action includes copy, build and sitemap. If omitted, default values for corresponding actions are used (see the sample config.xml file above). If provided, the list of specified extensions overwrites the default list for specified action. Files whose extensions do not appear in suffix elements are not processed (do not appear in target or are not included in sitemap).

action
this attribute defines the action taken on source or target file if its extension is in the list. The value of copy states that the file will be copied from the source to the target directory as is without modification if source is newer than the target. If the value is build the element defines primary extensions for content files which will be built from source to target folders if content file is newer than the target or if corresponding section or template files are newer. The value sitemap defines the list of target file extensions to be included into the sitemap file.

Default list for build:

.src

Default list for copy:

.html;.htm;.shtml;.css;.js;
.jpeg;.jpg;.gif;.png;.ico;.swf;
.php;.phtml;.php3;.pl;.java;.asp;.asx;
.zip;.gz;.tar;.bz2;
.doc;.xls;.pdf;.xml;.txt

Default list for sitemap:

.html;.htm;.shtml;
.php;.phtml;.php3;.pl;.java;.asp;.asx;.cgi;
.doc;.xls;.pdf;
.xml;.txt

default
used only in combination with build action. Defines target file extension for content file in case it only provides a primary extension. For example, if set to htm then all content files of form name.src will be translated to name.htm in target. Default is html.

Example:

  <suffix action="build" default="php">.src;.psrc</suffix>

Here we specify that source content files may have .src or .psrc primary extensions and if the content file name is in the script.psrc form the resulting target file name will be script.php.

target

defines the root of target structure to be built. May be absolute or relative to config.xml. The files in the target tree appear during the build process and directory structure is identical to the source tree. The target file is only updated if it is older than the corresponding source content file, one of the section files for the current folder or the template file used for the content file.

See also:     source.

template

element defining file name for the template holding the common page layout. In case of non-default template also provides content file secondary extension. Path may be absolute or relative to config.xml. The default template is required. Non-default templates are optional.

suffix
attribute defines content file secondary extension for non-default template. Omit when declaring the default template.

See also:     suffix element for the way to change the content file extension used for default template.

ver-file

provides file name of a one-line text file that handles site versioning. The number at the end of the first line (before the last dot) is incremented on each build if at least one target file were updated or created. The full content of version file is available trough .ver and .version placeholders in template, section and content files. Path may be absolute or relative to config.xml.

Example version file:

Version 3.1.0.371

In this case the last number in the string is considered 371 and this number will be incremented to 372 on the next build if at least one file in the target tree is updated. The new version file will be:

Version 3.1.0.372