Document object models in general

Object models of certain documents are popular way to deal with them. Today many popular technologies use object models as part of their standard or related tools. Some of the most popular examples are the DHTML DOM and XML DOM. Using a structured representation of a document is much more convenient for any application than generic parsing mechanisms. This technique has one very important advantage - it specifies what a particular parser component/tool should serve to the application. Object models are used in many applications and while the models related to the world wide standards are standardized many other applications use similar techniques to represent their specific documents. Many samples are available - most of the MS Office applications, some of the Corel products, almost all the GIS applications and so on.

The role of the object model of a document is the document active state. What means the word "active" depends on the application specifics. Most often the active state is related to edit/modification operations over the document. Thus using object model is convenient way to supply flexible way to manage/modify the document and then at a certain moment to save it in a persistent form with all the changes applied.

ASP Compiler uses its component TextEmbedParser to construct object models of the processed files or their parts. If a general comparison should be made - ASPC functionality should be positioned somewhere in the middle between the editing tools and the unattended pre-processors. And the object model of the processed files is designed to match its needs. You may thinks for ASPC as for a document editing tool in which all the operations are performed sequentially without user interaction, but the user has a "proxy" interacting with the document during the file processing - the compile time scripts (CTS). Thus object model oriented structure brings flexibility and universality.

Although ASPC is oriented to HTML and ASP files it has no real need to deal with them using some of the standard object models - such as DHTML DOM. ASPC is not a browser or WYSWYG HTML editor thus it does not need to know the entire page structure. The processing made by ASPC likes a kind of a server side processing (for example ASP to VB processing), but it could benefit of some elements similar to the client side processing - some techniques similar to the DHTML client side scripting. However CTS in ASP Compiler could be used over the most textual formats and the processed file could be a HTML page but it could be even a plain text document with some custom markups. We made the logical step - a tree like representation of the file implemented with universal collections used to represent the nodes of the document. Therefore the document model (will be called Page Object Model - POM below) is a collection that contains other collections and they may contain other collections in turn. VarDictionary collection object is used for the purpose.

Some words about the VarDictionary object.

Looking at its documentation you will find out that it has  the typical collection methods and properties but also serves many advanced features some convenient when dealing with tree like structures, others related to the general behavior of the object. It supports also cloning (see Clone method) - that allows a copy of the collection to be obtained with all of its sub-collections (if any). This allows a branch of a tree constructed with VarDictionaries to be cloned with one method call! Also note the FindByValue and FindByName methods which allow searching for sub-collections (tree nodes/branches) and other items through the entire structure.

Page Object Model in ASPC

ASP Compiler serves some predefined elements to the compile time scripts. Depending on the processing type they cold include ASP scripts in the page (<% %>, <%= %> and <SCRIPT RUNAT=SERVER> elements), embedded CTS (<SCRIPT RUNAT=COMPILER> elements), CUSTOM and CUSTOMFIELD elements (the predefined tags for developer defined operations), HTML comments.Also  ASPC may serve specific HTML elements if they are explicitly requested by the compile time script (see OnModifyParser event).

Therefore the elements of the POM are two types - ASPC standard and CTS requested. Defining some standard ASPC elements allows cooperation between different compile time scripts (even from different vendors) and ability to request specific elements allows the model to be extended when needed.

General rules:

The HTML attributes are represented as string items in the VarDictionary object that represents the element in the POM. The name of the item is the name of the attribute and its value is the value set to the attribute in the file source. Thus this element:
<CUSTOMFIELD Attr1="Val1" Attr2=Val2>
will be represented with a collection which contains item named Attr1 with string value "Val1" and item named Attr2 with value "Val2".
When the CTS requested specific HTML tag to be included in the POM the same rule will be followed.

The ID attribute specifies the item name of the element in its parent collection. Therefore:
<HTML><BODY>
<CUSTOMFIELD ID="Field1">
</BODY></HTML>
Will appear in the POM as an item in the root collection of the document named "Field1" and the item will contain a VarDictionary object (sub-collection) representing the CUSTOMFIELD element (tag) and its attributes (if any). This rule is true for the specific elements requested by CTS too.
Therefore to distinguish attribute from an element node IsObject VBScript function can be used. The objects in the POM are always elements/nodes and non-object values are element's attributes. Note that the root of the document has no attributes - it represents the entire document thus it contains its root level elements/nodes only.

The standard ASPC defined information about the element is served as string items in the collection. In other words they appear in the same manner as the HTML attributes appear but their names are "well-known" (defined by ASPC).

Standard ASPC attributes for the ASPC defined elements (not the CTS requested elements):

Class - the type name of the element (node). The possible values are:

Text - non-parsed part of the document. Represents the parts of the page between the ASPC elements. These parts could be HTML or plain text. When the page is regenerated they appear "as is".

Script - Represent <% %> and <SCRIPT RUNAT=Server>...</SCRIPT> elements - ASP code. CTS may change them or use the ASP notation for non-ASP purposes if desired.

Assignment - Represents the <%= %> elements - ASP direct output.

ASPDirective - Represents the <% @... %> ASP elements. Supported for internal needs. Not recommended to use in CTS!

Object - Represents <OBJECT RUNAT=Server> ASP elements. Supported mostly for internal needs but CTS may use them if needed.

Custom - Represents the CUSTOM or CUSTOMFIELD element.

CompileTimeScript - Represents the <SCRIPT RUNAT=Compiler>...</SCRIPT> elements. These elements are expected to contain (or refer) script code the ASPC will execute when the POM is generated. The CTS attached to the file may access them and call functions defined in the contained script or interact with them in other ways.

IncludeBegin - A flag node. Marks the place in the POM where an <!-- #include ... --> directive is used. Contains information for the included file only - the contents of the file follows as it is a part of the document. In other words include files are first resolved and if the CTS is not interested exactly how the page is constructed from the include files it may ignore the IncludeBegin and IncludeEnd nodes.

IncldeEnd - A flag node. Marks the place in the POM where the include file ended.  

Comment - Represent HTML comments

Content - Contains the element's content. This is the content between the open and close tag (for the CUSTOM elements for example) or the ASP code between the <% %> or the text in the unparsed parts (Text nodes).

For the elements that follow HTML syntax the node also contains all their HTML attributes as it was mentioned above. For the ASP defined element Class and Content are reserved and should not be used as HTML attributes! Note that they are not visible elements thus they have not meaning for the WEB browsers. Therefore there is no relation between the DHTML class attribute and ASPC class attribute. Also the ASPC defined element will never appear in the output file.

CTS requested elements - see OnModifyParser event and TextEmbedParser reference. CTS requests some HTML elements to be included in the POM. The reason to request them could be information collecting task or other usage. Thus the elements requested are almost always regular HTML elements.

__class - the element (tag) name.

__container - numeric 0 - if the element has not closing tag, 1 - if it has a closing tag. Defined by the script through the AddTag method call when handling the OnModifyParser event. Note that CTS may want to treat a HTML element as an element that has no closing tag without risk - no matter if by HTML definition it has closing tag or not. However following the HTML definitions will make the CTS easier to read and understand.

To see the POM in action see the ASPC examples.