TPageBuilder reference

TPageBuilder is a replacement for TPageProducer and produces a string of HTML commands based on one or more input templates.

Unit

PageBuilder

Description

Use a TPageBuilder instance to convert an HTML template consisting of valid HTML code and special tags into pure HTML code. The special tags are recognized by the presence of a namespace followed by colon before the tag id itself. The special tags are converted into HTML code and/or content by OnHTMLTag event or by helper components of class TTagInterpreter or its descendants.

property ParseAttributes: Boolean

Set ParseAttributes to true to recursively parse every (almost) tag attribute (event attributes on tags without namespace). If ParseAttributes is set to false, special tags embedded in a tag attribute will be ignored. For example:

The value attribute on the input tag above will be interpreted only if ParseAttributes is true. PageBuilder process attribute values by recursively calling its ContentFromString method. For efficiency reasons only tag attributes containing at last one "less than" (<) character are processed.

property OnlyRegiteredNamespaces: Boolean

Set that property to true (default is false) to process every name spaced tag. When false, just tags with registered name spaces are processed. To register a namespace, use the PageBuilder NameSpace property or the NameSpace property on the TagInterpreters linked to that PageBuilder.

property NameSpace: String

Set the namespace to process. Mandatory when OnlyRegiteredNamespaces is true. Do not include the colon (:) delimiter.

property TagInterpreters: TTagInterpreterCollection
TTagInterpreterCollection = class ( TCollection )
TTagInterpreterItem = class ( TCollectionItem )

TagInterpreters holds a list of TTagInterpreters (or its descendants) linked to that PageBuilder. Each linked TagInterpreter will care about a namespace and may be linked to others PageBuilders.

Since TagInterpreters is a descendant of TCollection, it includes a specialized design-time editor to allow linking a TagInterpreter to the current PageBuilder. Editor behavior is almost the same of Action property found on a WebDispatcher or WebModule.

property HTMLDoc: TStrings

HTML pages can be "hard-coded" in design-time. Use the TStrings editor to add lines to HTMLDoc property.

HTMLDoc is mutually exclusive with HTMLFile.

property HTMLFile: String

HTML pages can be loaded from disk on run-time. Set HTMLFile to the corresponding filename both in design-time or run-time. The file is loaded in run time when the Content method is invoked.

HTMLFile is mutually exclusive with HTMLDoc.

property OnHTMLTag: TPageBuilderTagEvent
TPageBuilderTagEvent = procedure ( sender: TBasePageBuilder; const tagString: string; tagParams: TStrings; const tagContent: string; var replaceText: string ) of object

OnHTMLTag event is fired whenever an appropriate tag is catched by the internal HTML parser. A tag is considered for processing if it has the same namespace registered on the NameSpace property or its namespace is not registered by NameSpace nor by the NameSpace of any linked TagInterpreters and OnlyRegiteredNamespaces is set to false.

Tags with namespace registered on a linked TagInterpreter does not fire the PageBuilder OnHTMLTag event. Instead it fires the corresponding TagInterpreter OnHtmlTag.

You can use sender parameter to verify the PageBuilder who originated the event. Parameter tagString contains the tag name space and id. tagParams is a string list with tag attributes in the usual "attributeName=atributeValue" format. On tagContent is passed all the text enclosed by the start and end tags.

Before returning, the event handler must set replaceText with the code that will substitute the start tag, the tag contents and the end tag.

constructor Create ( AOwner: TComponent )

After calling the inherited Create (from TComponent), Create constructor creates TagInterpreters and HTMLDoc and initialize properties ParseAttributes and OnlyRegiteredNamespaces to its default values (true and false, respectively).

destructor Destroy

Frees TagInterpreters and HTMLDoc before calling the inherited Destroy.

function Content: String

Call Content method to start the parse process over the HTML code stored on HTMLDoc or pointed by HTMLFile. Internally Content call ContentFromStream over a TStringStream or TFileStream.

function ContentFromStream ( Stream: TStream ): string

ContentFromStream is the real workhorse inside PageBuilder. It creates a instance of THtmlParser, interacts over all tokens returned by it, call the appropriate OnHTMLTag event and replaces the original tag by the replacement value.

function ContentFromString ( const s: string ): string

Internally ContentFromString call ContentFromStream over a TStringStream.