Content files

When assembling a site we take content files from the source directory, check their freshness by comparing the source date with the date of the same file in destination and if needed proceed with the update process. We check not only the date of content file, but also the dates of a template file and a sections file. So if we changed the main template, the whole site will be rebuilt. If we only change a sections file in a particular directory, only files in this directory will be rebuilt. If we change a content file, only this file will be rebuilt.

So what is a structure of a content file, why does it have a structure at all, what are the commands that we can use in it and how we enter those commands?

Like templates and sections content files are text files. The first line of a content file is reserved for titles and commands, which we'll discuss later, and the rest of the file is yours. The content which will replace the .text placeholder is started on the second line and flows till the end of file without any more restrictions.

This structure is needed to hold the control information like main page title, definition of other titles, insertion of special commands and so on. By reserving one line for the special purposes we achieve simplicity of concept, visibility for our content and ease of support for our whole site.

Now let's see the real content file, say links.html (line numbers are not present in the real file and are provided for a better orientation):

001  Links ^.replace(links,links-a)
002
003  <h2>Built with Open Site Builder</h2>
004
005  <p>Open Site Builder lets you create sites of any complexity level
006  using a ready-made template like on this site (thanx Google) or developing
007  your own.</p>
008  . . .

What we see here is a page title Links in the first line separated from the .replace command by a ^ symbol. That symbol is configurable and by default it is a tabulator character, \t, but for this project it's better to use something more visible. The content text starts at line 002 and continues till the end of file. Actually on the first line we can define as many titles as needed and access them in our template or sections via the .title(n) placeholder, where n is a 0-based index. For example, if we change our first line to

Links ^ OSB Related Sites ^ © 2007

then we will have a .title and .title(0) defined as Links, .title(1) defined as OSB Related Sites and .title(2) defined as © 2007.

Restrictions for the first line... well, it's as long as you need, as many titles as needed, may be blank (no titles defined). If you put in your template a .title(x) placeholder for a non-existent title, it will be defined as an empty string. If a title is defined which is not referenced in template or section files, it will be ignored.

All clear by now? Let's proceed to commands. Commands are used to control appearance of sections. They may be used in place of one or more titles (in which case a corresponding title is set to an empty string if it is referenced in template). The command may ask to use another section in place of one defined in a template (.replace command), or print something in place of a section (.print command). In our case to replace a contents of links section by the contents of links-a section we used the .replace(links,links-a) command in the source file.

Alternatively if the replacing section is small and you don't want to produce more sections:

Links ^.print(links,Links)

Both commands result in the same: instead of a links section (which is defined as <a href="links.html">Links</a>) the string Links is placed in the target file whether from a links-a section or directly by the .print command.

This is all for now about the titles and commands in content files. See the Content file structure and commands in Commands Reference for a list and syntax of commands.

The next section contains information about the config file which you use to describe system-wide parameters.