The Golden Rules

The Dissemino method enshrines two golden rules. The first is DDA: "Define, Declare, Access". For any entity to be accessed, it must first be created, and any creation process must follow a definition. The second is SESA: "Single entity, single action". This applies only where tags affect data entities. Such tags must either define, declare, or access exactly one entity. Both rules benefit clarity, but DDA confers other advantages. It allows the config read to be single pass process. It also encourages the practice of config sectioning, so that all database entities and defined and declared before any of the pages and forms that would use them.

Webapp configs ultimately amount to a single XML document but are usually spread across several files. There must be a single starting 'root' file but within (and only within) this file, there can be numerous <includeCfg> tags, each equating to the XML content of the section file it names. It is entirely up to webmasters how configs should be sectioned, providing that data operations adhere to SESA, the configs as a whole adhere to DDA, and that data entity definitions or web resources, are not split across sections. Typically the data entity definitions are in the root file or the first section file, with webpages placed in other section files, usually reflecting some logical grouping. It can make sense to group related webpages together in a single file, as it can make it easier to spot contradictions and unnecessary repitition of salient points.

Config Manifestation and HTTP Resource Acceptance Process

Webmasters can edit application config files directly or they may use the in-built config tool, which exports application config files. There are merits to both approaches with the config tool prefered for minor changes and direct editing prefered for major development. It is easy to see why. The config tool is a part of the online webmaster control panel. It offers rapid testing and deployment of changes but of necessity, edits are done within the confines of forms in a webpage. Working directly on config files confers the advantage of working with your favorite editor in full screen mode. For those that edit files directly on the server using editors such as vim however, do please avoid using the in-built config tool at the same time!

Webapp config files are authorative, but only after they are accepted. Unlike Apache where a flawed edit of a .html file will simply result in the page not rendering as expected in the browser, config changes have no impact on served content until the changes are tested and accepted. The XML must first parse and any resources or entities referred, must exist. The change acceptance process for data object entities is described in article 2.5 "Data Classes and Repositories". The change acceptance for declared HTTP resources is outlined as follows:-

 - For each changed HTTP resource in the configs
  - Parse the XML into visual entities
  - If parse successful
   - If all of the visual entities in the resource are inactive
    - The pro-forma HTML will be the final HTML so store it.
    - Zip and store zipped final HTML
   - Else (resource is deemed active)
    - Process the visual entities into pro-forma HTML (HTML containing entities that are expanded on serving).
    - Store the pro-forma HTML.
  - Else (parse fails)
   - Reject the change, terminate process.

Note that the following are stored in respect of each resorce:-

 - The resource definition XML, as last accepted
 - Either the pro-forma HTML (active resources) or the final HTML, both raw and zipped (inactive resources)

Storing this data helps speed up the startup process although this will depend on how much has changed in the configs. If none of the config files for a given application have been changed since the last startup, the config read process is avoided altogether and the entire set of HTTP resources is loaded from the database. Only changed configs are loaded into XML documents and only new and changed HTTP resources are parsed into visual entities. In a virgin run of course, all resources in the configs are new.

The Webapp Root

In the root file of a webapp config, the root tag is <webappCfg>. This has numerous attributes to set the application parameters as follows:-

Note 1: There must be a document root directory specified, even if there are no passive HTML files or other resources placed in it. By default, images referred to in pages, will be expected in ~/docroot/img unless otherwise stated. Likewise JavaScripts defined outside the XML configs will be expected to be in ~/docroot/jsc. If there are passive pages or other files you will need to direct Dissemino as to which ones to load with a <passive> tag, e.g. <passive files="/passive/*.html"/>. This tag assumes file paths are relative to the document root.

Note 2: The URL for the webmaster account is configurable and there is no default value. It is recommended that it be set to something unexpected such as "/themadhatter" to make it harder for hackers to find. Attempts to access non-existant URLs is a trigger for an IP address ban.

These application parameters can be edited in the webmaster config tool. They are available under "Application Parameters" which is the first item under "Application Resources" in the navtree.