As discussed in Introduction there exist two folder trees when you work on the site -- the source tree, where you hold your content files and the target or final tree, where the final version of a site if assembled. The process of assembling the site from the source tree to the target is called a build process. It may be described as follows: we take every file in the source tree and decide whether we need this file in the target. In our config.xml file we set the rules to define the scope of files that we want to process. Files that do not match our criteria are not processed and will not appear in target tree.
So if we realized that the file will be processed we need to know whether the fresh copy of file already exists at the target. If it does we skip the file and move to the next one. If not we have to place the updated file to the target directory. How we determine freshness or how we create or replace a file in the target tree depends on the action defined for this class of files.
If the file is in copy scope, it is simply copied to the target if source is newer than target. This is used for all binary files, images, .pdf documents etc. -- for files that do not constitute your html layout. These files are copied as is and their name and extension does not change (except for an exec case when file is in exclude scope).
Otherwise, if the file is in build scope, it is considered a content file whose contents needs to be inserted into the corresponding template and then copied to the target tree. Since its modification time depends not only on content file's but also on template used, associated sections file and even the latest versions of macros and entities defined in config file, all of these must be checked to determine the most recent modification time which will be checked against the modification time of target file. If target copy is more recent the content file is skipped.
Build process is finished when all the source files in the source tree are processed. At that moment a sitemap file may be generated at the target folder if the sitemap element was defined in the configuration file and the osb.php script was launched with the corresponding sitemap id.
When processing the content file its .src extension (used by default to specify content files) is removed since it is only used to distinguish the nature of content files and a default extension is used instead in target file. For example, if you have an index.src content file in the source folder it will appear as index.html in the target (.html is a default extension to be used in target files) after merging with the template file. However you may use non-default extension if you wish. In this case just provide it with the name of the content file, like search.php.src, and OSB will not append a default extension to the target file after .src is stripped (its target name will be search.php).
When you want to use more than one template for your site you need to provide two extensions, primary and secondary, for each content file that does not use the default template -- primary .src to show the file needs to be inserted into a template and secondary .abc to show that the file will use the abc template (like index.home.src where you decided to use the home template). Both primary and secondary extensions will be replaced by a single default .html (you'll get index.html) or just stripped if you provide your own (third) extension (like in search.php.results.src where .results extension defines the use of results template and the target filename will be search.php). This design helps us easily identify which files are content files and which template is used for a particular content file by simply looking at file extensions and at the same time we are not forced to associate the same editor program with the new extension each time we introduce a new template in our development process -- we only associate it once with the primary extension (.src).
For detailed primer on using extensions see Appendix A.
Well, now we found out that the content file must be processed and put to the target folder replacing its outdated version. We know what template file we use. Now we got to insert the content of the file into the template. But before doing that, we insert all corresponding sections into the template by replacing the appearances of the &.section(name); placeholders with section content. Commands defined in content file may explicitly order to replace the content of a particular section with another. This exchange is only effective for this particular content file. After sections are in place we replace the &.text; placeholder with the text of the content file (excluding the first line where we define page titles and special commands). What's left is replacing macros, entities and variables with their respective values and the final version of the page is ready. Now we can save it to the target folder under the selected name.
Before skipping to the next file we may execute an external program on the target file (for example you may wish to encode the target file with the Zend Encoder or make additional copies of the file). See the exec element of the config.xml file for details.
When descending to the next subfolder and before processing the files in it OSB tries to create the same subfolder in the target tree if one does not exist yet.
If your system is using some kind of SQL engine you may wish to define different roles in it and grant them to the users connecting from your scripts depending on the type of subsystem where application user currently resides. For example if your intranet system is currently implementing Entry, HR and Statistical functionality you may wish to create ENTRY, HR and STATS SQL roles and grant them to corresponding users. Since application scripts for each subsystems should be placed in different folders you may use this fact to facilitate the process of updating the grants while your application changes the way it uses existing SQL objects or when you create new objects. In this case you may create a file in each folder with the list of SQL objects accessed from this particular subsystem and provide its name in config.xml file with the access-rights element. Then each time OSB is entering a new folder it looks for the provided file with the list of SQL objects and corresponding rights and automatically updates another file with exact SQL instructions used to create a role and grant it these rights. You may then pass these instructions into your SQL engine to update the corresponding role grants.