The <xpage> tag
With Apache websites all resources, be they webpages, images or CSS stylesheets, are files in or off of the document root directory. The resources are addressed by the path part of the URL supplied in HTTP requests, which is taken as a path relative to the document root. If the file exists and can be read, the resource is served, otherwise the response is 404 (Page Not Found). By a convention all web servers must observe, a blank path or a path of '/' finds the default page (better known as the homepage), which is usually configured to be index.html (or .htm or .php). It is pretty much a what-you-see-is-what-you-get system.
Dissemino webapps also have a document root directory and could in theory, be arranged exactly as Apache websites are, with each resource being a file. However this isn't the usual practice. The document root is intended for resources that are inactive by nature, and are always served verbatim, such as images or uploaded documents. All the other resources are specified in the configs, including webpages that are completely inert. The configs are files of course, but many resources can be specified in each. The resources are given paths which the path part of the URL in a HTTP request must match, but the paths are fictitious and serve only as resource identifiers.
Dissemino webpages are defined in the configs as <xpage> tags. For example:-
<xpage url="/" title="My Home Page" access="public">
<desc>Page Description/>
<xbody bgcolor="eeeeee">
... Some Content Tags ...
</xbody>
</xpage>
It is quite obvious what this does. It defines a webpage entitled "My Home Page" whose body contains the supplied HTML content, that is available at the root URL for the domain and is accessible to everyone without any need to authenticate (please see article "User Access Rules"). Note that within the page definition (the <xpage> tag), several tags that would normally be present in an Apache .html file, are omitted. There is no <!DOCTYPE> tag, no <html> tag, no <head> tag and so no <meta> subtags. These are needed in the output HTML, but they are automatically generated by Dissemino.
Note also the <body> tag is replaced by an <xbody> tag, making it a Dissemino tag rather than a HTML tag. This is done so that Dissemino can generate a <body> tag with references to automatically generated JavaScript event handlers for onpageshow and onresize. Dissemino does a lot of automatic JavaScript generation, but this can be bypassed if the scripts are not to the webmaster's liking, by using a <body> tag instead of the <xbody> tag. There is however, no choice on the <xpage> tag.
Not shown in the above example, is the subject attrubute of the <xpage> tag. This is optional but necessary if the page is to be automatically listed under a navbar pull down menu.
The page content tags will be mostly what would appear within the <body> tag of a standard webpage in an HTML file, except that they can be mixed with Dissemino specific tags - which are the main topic of this manual. Dissemino parses the whole lot as XML. It holds the known set of HTML(5) tags as 'reserved words' that will be regurgitated in the HTML output for the page. Since the configs are XML, all HTML tags that can be left open, must be closed in the configs.
Active and Inactive Page Content
A page is considered active if it contains one or more active tags. An active tag is one whose HTML value can vary, either because it includes a percent entity reference to a value that is assumed to be dynamic, or because it depends on partiular conditions such as who is logged in. While this may not be of concern to webmasters, an active page will always be generated each time it is requested, whereas an inactive page is only generated upon application initialization and upon page config change. An inactive page can have its generated HTML cached for serving, which saves processing time. The benefits are apparent in benchmark tests but are relatively minor because page generation itself is a fast process (mostly because the necessary lookups are on memory resident entities).
Default CSS Stylesheet
The HTML <head> tag does not appear in the <xpage> tag, as it is generated automatically. If a default stylesheet is specified for the webapp, the <head> tag will contain a line of the form <link rel="stylesheet" href="appname.css"/>. Specifying a default stylesheet does not exclude the use of other stylesheets, however, as the default is the only one that will ever appear within the <head> tag, the recommendation is that the default should be the only one and that it should contain all the CSS classes used by the webapp. The default stylesheet is specified by the <xstyle> tag. This has the same format as the <style> tag except that the styles are never placed within HTML comments.
Keeping all styles in a single downloadable resource, saves bandwidth as the stylesheet is only loaded once by browsers no matter how many pages are subsequently visited. Note that robot visitors usually ignore the stylesheet, which cuts bandwidth consumption and makes it easier to identify robot visitors. Note also that use of default stylesheet, enables the web engine to flag up redundant styles and references to non-existant styles.
The <xinclude> tag: Standard look and feel.
To give pages within a website a common 'look and feel' pages can include one or more pre-defined blocks of HTML. In Dissemino the HTML blocks are defined with the <xinclude> tag which has an attribute of name. The blocks can then be included in any page by means of the <xblock> tag which names to block to include. For example:-
<xinclude name="mytop">
<table width="100%" align="center" border="0" cellspacing="0" cellpadding="0">
<tr height="66">
<td width="2"> </td>
<td align="left" class="title">My Great Website</td>
<td align="right"><img src="img/mylogo.png"/></td>
</tr>
</table>
</xinclude>
In this example, the HTML is for a bar spanning the full width of the screen, with the same background color as the page, the site name slightly offset from the left, and a logo on the right. Note the <img> is and must be closed. To include this is any page just add <xblock name="mytop"/>
Note that <xinclude> can be recursive eg:-
<xinclude name="myPgHead">
<xblock name="mytop"/>
<xblock name="some-other-include"/>
</xinclude>
Once an <xinclude> block has been defined, its HTML value can be imported into a page with an <xblock> tag. Both tags have a single attribute of name for reference. The name must be unique among <xinclude> tags.