What are Visible Entities?
Visible entities (VEs) are the means by which resources produce HTML. Each will evaluate to one or more HTML tags. Under the Dissemino regime, the HTML sent to a client in response to a HTTP request, is assembled by evaluating all the VEs assigned to the applicable resource. All VEs are instances of a class derived from the hdsVE base class.
VEs are either active or passive, depending of whether they do or do not include percent entities. If passive, evaluation of the VE simply returns a pre-prepared HTML fragment from cache. The fragment is only generated during application initialization and on live edit of the host resource. If ALL VEs in a resource are passive, the resource is passive and the total resource HTML can be cached. If a VE is active, its HTML fragment will depend on the current value of one or more percent entities and so it must be generated each time it is evaluated. As this will alter the resource HTML as a whole, if any VEs in a resource are active, the whole resource is deemed active. This will mean the HTML is assembed every time the resource is requested.
The current list of visible entity classes are as follows:-
| hdsTable | This generates a HTML table with data drawn from a repository. The columns are selected from members of the repository native data class. There can be lower and upper limits on the objects found and search critieria. hdsTable Instances are configured by the <xtable> tag in the configs. This is a complex tag with subtags of <xcol> to tie columns to data class the members. There are also optional subtags of <header> and <footer> to specify supportive HTML for before and after the listing, and compulsory subtags of <none> to specify the HTML for an empty list and <foreach> to specify subtags rendered for each row. |
| hdsDirlist | Directory listing (special case of a hdsTable). Instances of hdsDirlist are configured by means of the <xdirlist> tag. The HTML output generated is a table with columns that are related to members of the hzDirent class. The <xcol> tags specified within <xdirlist> must specifically name these members. <xdirlist> also has the <none>, <header>, <footer> and <foreach> subtags of hdsTable and for the same purposes. |
Note that the directories listed in the output will form HTML links to the same page in which the <xdirlist> appears but with an appended resource argument. Files listed in the output will have links of the same form. The <xdirlist> tag has parameters of 'directory' which can be specified using percent entitits, and criteria (the file selection criteria) which must be specified using the usual globing notation.
| hdsHtag | Dissemino representation of a standard HTML5 tag. |
| hdsXtag | hdsXtag instances are created by the <x> tag in the configs, to mark text for or not for language translation. <x> is inserted when text is to be translated into other languages when it otherwise would not be. For example, by default, the text content of <pre> and <td> are exempted from translation because <pre> commonly contains code fragments which are not meaningful when translated. The <x> tags switches translation on/off for the whole or a part of these tags. It has the opposite effect within the <p> tag where it switches off translation. |
| hdsBlock | A block of tag for later inclusion by an <xinclude> tag. representation of a standard HTML5 tag. |
| hdsCond | Conditional visible entity. This produces no HTML tags itself but will include/exclude the subtags depending on the condition specified in the configs. |
| hdsXdiv | Special case of a hdsCond in which the condition is the logged in status of the user/visitor. |
| hdsNavbar | A hierarchical pull-down menu of links that is generated depending on the status of the user. There are headings which are omnipresent (always visible) and for each of these, there is either a direct link to a page or there is a sub-menu. The sub-menu if applicable, becomes visible by virtue of an onmouseover event on the heading, and contains a set of one or more links. In theory a navbar could support sub-menus but this is not currently implimented. By default, the menu is populated by the subject attribute in each page. |
| hdsField | A hdsField instance is created by the <xfield> tag and serves as a form field. The <xfield> tag must name either a free standing variable or a member of the applicable data class (the form native) as without this, Dissemino would not know how to name the field in the form's HTML or what to do with any submitted value. Note that fields may contain pre-populated values by means of percent entities. The value is obtained DURING the HTML generation process. Where the field relates to a class member, the lookup for the value must have the repository class, the class member and the object id. By default, the class will be that of the host form unless otherwise stated in the 'var' attribute of the <xfield> tag. The object id is not part of the hdsField class or the <xfield> tag and is supplied as the argument to the host page. |
| hdsArtref | An in-page reference to an article (hdsArticle). An article reference is a visible entity because it can manifest as the article title, the article content, or both. An article itself is not a visible entity but is a visible entitiy container. An article reference name the article group, the article itself, and have flags to control the manifestation. 1 shows the article title, 2 for content, 3 for both. |
| hdsFormref | This will manifest the entire set of HTML tags for the form, as set out in the form definition. Please see article on Dissemino forms. |
| hdsButton | Two types of button exists, link and form action. hdsButon serves both. |
| hdsRecap | This should appear once within an <xform> tag and will generate a human test icon (google recaptcha) |
How text is handled
Not all HTML tags are text bearing but where they are, note how the text is assigned within the corresponding visible entity, and how it is used in the formation of HTML. If a text bearing visible entity is acting as a sub-tag of another text bearing entity, it can have pre-text as well as main text. The main text of an entity is always that specified between the opening and closing of the progenitor tag in the XML configs, MINUS the content and pre-text of any text-bearing sub-tags. For example:-
<p>Please read the <a href="/tnc">Terms and Conditions</a> before proceeding</p>
Here the anchor subtag has main text of "Terms and Conditions" and pre-text of "Please read the ". The main text of the paragraph tag is " before proceeding". Thus, where a tag has subtags, HTML generation is a matter of visiting each subtag in turn and writing the pre-text, the tag open, the main text and the tag close. The content of the tag in question, is written last.
Fortunately, this is not something website developers need to dwell upon when writing application configs!
Language Support
Multi-lingual websites initially provide content in either a language chosen on the basis of client IP address, or a default language. Users can select another language by means of a pull-down menu or similar, and the usual response to this selection is to redisplay the current page in the new language. Navigation of such sites depends on keeping track of the user's language choice, which is either done by user session and cookie, or on the basis of embedding the language in the URLs.
Both navigation methods suggest that the website layout should be language independent, i.e. there would be the exact same set of pages for each language and so a different version of each page for each language. This is not as straightforward as it may seem. For best quality pages will be translated by humans, which can easily result in dalays and/or version lag between languages. Machine translation is of inferior quality but is much cheaper, quicker and can be automated. From the Dissemino design perspective, both methods are here to stay and so must be accommodated, and organizations can be expected to tolerate a degree of version lag, use a mix of human and machine translation and to routinely change the mix!
In the configs, human translations appear either as repeated definitions of pages or articles OR as language conditional HTML blocks. Only the last known translation will appear in the configs and the resource will be marked with date and version information, as a result of the configs being re-exported on acceptance of any changes. Where machine translations are used there will be no repeated definitions or language dependent HTML blocks, but there will be notes in respect of the translations, stating target language and time and date.
Machine Translation Method
It is assumed that machine translation is performed by an external service that the site vendor subscribes to. It is further assumed that paragraph demarcation will be preserved in machine translations. This allows strings in the original language to be directly mapped to translated strings in another.
Translation programs usually leave alphanumeric sequences unchanged, so something like "p1.1.4 Hello World" translated to German becomes "p1.1.4 Hallo Welt". Dissemino assigns each string occuring anywhere in the website, a USL (Universal String Lable), which is an id of alphanumeric (and hierarchical) form. During HTML response generation, the USL is used to look up the actual string value in a map in an instance of the hdsLang class - for which there is one for every language the website supports.
This arrangement allows whole sets of strings to be mass exported, sent for translation (by program or human) and then re-imported. It is not automated but automation would not be a big step. Lookup in hdsLang USL to string maps only needs a 32-bit unique number but by building in notational hierarchy, USLs make it easier to translate page by page and are a more effective aid to diagnostics. The entities covered by USLs are visual entities and containers of visual entities, such as include blocks, pages and articles but also trees.
The text form of a USL will be a letter to indicate visible entity container type (e.g page), and a number. USLs are run time ids based on order of incidence in the configs. So the first page declared in the configs will have a USL of p1. Include blocks are given a 'b' prefix so the first include block declared in the configs has a USL of b1. Visual entities within containers have USLs of the form "container-USL.N' where N is the order in which the visual entity appears in the container definition. The first visual entity in the first page will thus be p1.1. The most complex USL are those of visual entities within articles that are members of an article group. An article has a prefix of 'a' so a visual entity in a lone article would have a USL of the form aX.Y. A visual entity in a article in a group would have a USL of the form gX.Y.Z. Note only one prefix is needed as it is obvious the second number indicated the article.
Note that USL are implimented as the hdsUSL class, to encapsulate the complex and varied id allocation regime. hdsUSL is 4 bytes in size and the encoding places tight limits on the available range, as is clear from the markers and masks defined in hzDissemino.h and listed below:-
| #define USL_G_MARK | 0x80000000 | // | USL is that of an article group |
| #define USL_P_MARK | 0x04000000 | // | USL is that of a page |
| #define USL_S_MARK | 0x02000000 | // | USL is that of a page subject |
| #define USL_B_MARK | 0x01000000 | // | USL is that of an include block |
| #define USL_G_MASK | 0x78000000 | // | Bits 01 thru 04 inclusive, identify article group (if applicable) |
| #define USL_C_MASK | 0x07ffc000 | // | Bits 05 thru 17 inclusive, identify visual entity container |
| #define USL_V_MASK | 0x00003ffe | // | Bits 18 thru 30 inclusive, identify the visual entity within a container |
| #define USL_X_MASK | 0x00000001 | // | Bit 31 indicates the visual entity as pretext, rather then content |
USLs for articles are the most challenged. The regime was designed for resources that are fixed in terms of content. Websites were considered to comprise a set of pages that during runtime were fixed. Articles were included because of their use in complex documents such as online manuals, again a fixed resource. Articles drawn from a dynamic source, such as a database of uploaded articles, would have to be exempt from language support as things currently stand.