TPBTagInterpreter reference

TPBTagInterpreter is descendant of TTagInterpreter (to be precise a descendant of TCustomTagInterpreter) and includes a very useful set of tags. These tags are generic enough to be used in every web system. Probably every PageBuilder you use will link to a PBTagInterpreter.

Unit

PBTools

Description

PBTagIntrepreter does not publish NameSpace and internally initializes its value to "pb". It means, by default, a PBTagInterpreter will process every tag started with "pb:", but, programaticaly, in run-time you can change the name space to whatever you want.

Most applications will need just one instance of PBTagInterpreter. Remember, you can link a TagInterpreter to how many PageBuilders you want.

constructor Create ( pOwner: TComponent )

After calling the inherited method, Create initialize NameSpace to 'pb' and GetVarMode to gvmNotStored, and creates internal storage to variables and 'if' tags evaluation.

destructor Destroy

After releasing internal storage, Destroy calls the inherited method.

procedure Clear

Clears internal storage. Useful when this PBTagInterpreter is linked to two or more PageBuilders that really gets activated in the same program execution.

property IncludeDir: String

Points to a directory where templates will be searched. Default value is the directory of the "main template" pointed by the HTMLFile property or the current directory if no HTMLFile is supplied.

property VarPool: TStringList

Allow access to internal variables storage. You can add, remove or change variable values programaticaly in run-time through that property.

Variables are stored in the usual = format.

property GetVarMode: TGetVarMode
TGetVarMode = ( gvmAllways, gvmNotStored )

Toggles the way OnGetVar event is called. If TGetVarMode is gvmAllways, OnGetVar is always called. When setting OnGetVar to gvmNotStored (default) the OnGetVar event will be called just when a variable is referenced but not stored in VarPool.

property OnHTMLTag

In that version OnHTMLTag is not called. The behavior of OnHTMLTag is yet to be defined.

property OnGetVar: TGetVarEvent
TGetVarEvent = procedure ( const sender: TPBTagInterpreter; const varName: String; var value: String ) of object;

Write an OnGetVar event handler to supply variable values in run-time.

OnGetVar is called according to GetVarMode property value and availability of that variable in the VarPool.

sender is the calling PBTagInterpreter. varName is the variable to have its value supplied. Var value must be returned on value parameter.

Pre-defined Tags

A PBTagInterpreter is prepared to process many pre-defined tags. The complete set of tags includes: pb:include, pb:includeindirect, pb:encapsule, pb:var, pb:clearVar, pb:pageTitle, pb:capsuleContent, pb:if, pb:then, pb:else.

Tag pb:include

Syntax: <pb:include fileName="filePathAndName" [(additional arbitrary attributes)]/>

pb:include tag causes the inclusion of a entire file content. The included text takes place of all pb:include tag. Tag contents, if present, is discarded, so the pb:include tag is usually a simple tag, finished by />.

Optionally pb:include can be supplied with an arbitrary number of aditional attributes. Every additional attributes are transformed in temporary variables valid during the inclusion process.

For simplicity and efficiency PBTagInterpreter expect fileName attribute be located before any additional one. In other words it must be the very first tag attribute.

Tag pb:includeindirect

Syntax: <pb:includeindirect varName="nameOfVar" [(additional arbitrary atributes)]/>

As expected pb:includeindirect behaves in all aspects like pb:include, except by the fileName attribute, substituted by varName. PBTagInterpreter will looks for the name of the file to be included on the variable value.

Tag pb:encapsule

pb:encapsule includes a file and accepts additional attributes that got transformed in temporary variables just like pb:include. pb:encapsule usually is not a simple tag, it normally have a start tag, an end tag and tag content.

The pb:encapsule content is collected and stored in a special var called "capsuleContent". As the additional attributes, that variable exists during file inclusion only. In the included file, a pb:capsuleContent tag will be substituted by the original tag content.

In this way, the included file works like a "capsule" for the tag content. If the pb:encapsule tag does not have a content, it will work just like a pb:include tag.

Tag pb:encapsuleindirect

Once again, pb:encapsuleindirect behaves like pb:encapsule, except by the fileName attribute, substituted by varName.

Tag pb:var

Long syntax: <pb:var name="varName" [value="varValue"]/>
Short syntax: <pb:var varName [="varValue"]/>

pb:var stores or replaces variable values. In the long syntax, the variable name and variable value goes on separate tag attributes. In the short syntax the variable name is the tag attribute by itself and the attribute value will be the var value. The long syntax is more generic and allow for variables with spaces in its names.

In both syntax, when the value is omitted, a var replacement takes place. When the value is present, a storage is performed. pb:var is usually a simple tag. If you supply a tag content it will be simply discarded.

Tag pb:clearVar

Syntax: <pb:clearVar name="varName"/>

pb:clearVar simply removes the specified variable from VarPool. It is a simple tag and any tag content eventually present will be discarded.

Tag pb:pageTitle

Syntax: <pb:pageTitle/>

pb:pageTile is just a short form of <pb:var name="pageTitle"/>. pb:pageTitle is a simple tag and any tag content eventually present will be discarded.

Tag pb:capsuleContent

Syntax: <pb:capsuleContent/>

pb:capsuleContent is just a short form of <pb:var name="capsuleContent"/>. pb:capsuleContent is a simple tag and any tag content eventually present will be discarded.

Tag pb:if

pb:if evaluates a simple expression and store its results in a internal stack. The expression result may be an empty string, meaning false, or a non empty one, meaning true. The stacked value will eventually be used by one or more pb:then and/or pb:else tags placed in the tag content area.

The pb:if expression may be a var reference, or a var reference preceded by a not operator or a var or value followed by a binary operator and then another var or value. Note that operator are specified as tag attributes. pb:if also supports short syntax when specifying variable names.

A simple pb:if makes no sense. To be meaningful a pb:if must contain at last one pb:then or a pb:else. The stacked expression is dropped at the pb:if end tag.

Tag pb:then

pb:then causes the tag content to substitute the entire tag, but just when the top stacked if expression evaluates to true (non empty string). When the stacked if expression is false, all the tag disappears. In other words, the pb:then keeps its tag contents on the resulting page if the innermost if was true.

Tag pb:else

pb:else causes the tag content to substitute the entire tag, but just when the top stacked if expression evaluates to false. As expected pb:else is the inverse of pb:then.