## Class TTemplate

Description

Implements interfaces:

- ITemplate

TTemplate implements PRADO template parsing logic.

A TTemplate object represents a parsed PRADO control template. It can instantiate the template as child controls of a specified control. The template format is like HTML, with the following special tags introduced,

- component tags: a component tag represents the configuration of a component.

The tag name is in the format of com:ComponentType, where ComponentType is the component class name. Component tags must be well-formed. Attributes of the component tag are treated as either property initial values, event handler attachment, or regular tag attributes.

- property tags: property tags are used to set large block of attribute values.

The property tag name is in the format of <prop:AttributeName> where AttributeName can be a property name, an event name or a regular tag attribute name.

- group subproperty tags: subproperties of a common property can be configured using

<prop:MainProperty SubProperty1="Value1" SubProperty2="Value2" .../>

- directive: directive specifies the property values for the template owner.

It is in the format of <%@ property name-value pairs %>;

- expressions: They are in the formate of <%= PHP expression %> and <%% PHP statements %>
- comments: There are two kinds of comments, regular HTML comments and special template comments.

The former is in the format of <!-- comments -->, which will be treated as text strings. The latter is in the format of <!-- comments --!>, which will be stripped out.

Tags other than the above are not required to be well-formed.

A TTemplate object represents a parsed PRADO template. To instantiate the template for a particular control, call instantiateIn($control), which will create and intialize all components specified in the template and set their parent as $control.

- since: 3.0
- version: $Id: TTemplateManager.php 2567 2008-11-12 16:53:52Z carlgmathisen $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/TTemplateManager.php (line 169)

    TComponent
       |
       --TApplicationComponent
          |
          --TTemplate

Class Constant Summary
CONFIG_ASSET = 2
CONFIG_DATABIND = 0
CONFIG_EXPRESSION = 1
CONFIG_LOCALIZATION = 4
CONFIG_PARAMETER = 3
CONFIG_TEMPLATE = 5
REGEX_RULES = '/<!--.*?--!>|<!---.*?--->|<\/?com:([\w\.]+)((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?"|\s*[\w\.]+\s*=\s*<%.*?%>)*)\s*\/?>|<\/?prop:([\w\.]+)\s*>|<%@\s*((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?")*)\s*%>|<%[%#~\/\\$=\\[](.*?)%>|<prop:([\w\.]+)((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?"|\s*[\w\.]+\s*=\s*<%.*?%>)*)\s*\/>/msS'
Method Summary
void configureComponent (TComponent $component, string $name, mixed $value)
void configureControl (TControl $control, string $name, mixed $value)
void configureEvent (TControl $control, string $name, string $value, TControl $contextControl)
void configureProperty (TComponent $component, string $name, mixed $value)
void configureSubProperty (TComponent $component, string $name, mixed $value)
TTemplate __construct (string $template, string $contextPath, [string $tplFile = null], integer $startingLine, [boolean $sourceTemplate = true])
string getContextPath ()
array getDirective ()
string getHashCode ()
array getIncludedFiles ()
boolean getIsSourceTemplate ()
array &getItems ()
string getTemplateFile ()
void handleException (Exception $e, int $line, [string $input = null])
void instantiateIn (TControl $tplControl, [TControl $parentControl = null])
void parse (string $input)
array parseAttribute (string $value)
array parseAttributes (string $str, mixed $offset)
void parseTemplateProperty (mixed $content, mixed $offset)
string preprocess (string $input)
void validateAttributes (mixed $type, mixed $attributes)
Methods
configureComponent (line 438)

Configures a property of a non-control component.

- access: protected

void configureComponent (TComponent $component, string $name, mixed $value)

- TComponent $component: component to be configured
- string $name: property name
- mixed $value: property initial value

configureControl (line 422)

Configures a property/event of a control.

- access: protected

void configureControl (TControl $control, string $name, mixed $value)

- TControl $control: control to be configured
- string $name: property name
- mixed $value: property initial value

configureEvent (line 453)

Configures an event for a control.

- access: protected

void configureEvent (TControl $control, string $name, string $value, TControl $contextControl)

- TControl $control: control to be configured
- string $name: event name
- string $value: event handler
- TControl $contextControl: context control

configureProperty (line 467)

Configures a simple property for a component.

- access: protected

void configureProperty (TComponent $component, string $name, mixed $value)

- TComponent $component: component to be configured
- string $name: property name
- mixed $value: property initial value

configureSubProperty (line 520)

Configures a subproperty for a component.

- access: protected

void configureSubProperty (TComponent $component, string $name, mixed $value)

- TComponent $component: component to be configured
- string $name: subproperty name
- mixed $value: subproperty initial value

Constructor __construct (line 240)

Constructor.

The template will be parsed after construction.

- access: public

TTemplate __construct (string $template, string $contextPath, [string $tplFile = null], integer $startingLine, [boolean $sourceTemplate = true])

- string $template: the template string
- string $contextPath: the template context directory
- string $tplFile: the template file, null if no file
- integer $startingLine: the line number that parsing starts from (internal use)
- boolean $sourceTemplate: whether this template is a source template, i.e., this template is loaded from some external storage rather than from within another template.

getContextPath (line 272)

- return: context directory path
- access: public

string getContextPath ()
getDirective (line 280)

- return: name-value pairs declared in the directive
- access: public

array getDirective ()
getHashCode (line 288)

- return: hash code that can be used to identify the template
- access: public

string getHashCode ()
getIncludedFiles (line 989)

- return: list of included external template files
- access: public

array getIncludedFiles ()
getIsSourceTemplate (line 264)

- return: whether this template is a source template, i.e., this template is loaded from some external storage rather than from within another template.
- access: public

boolean getIsSourceTemplate ()
getItems (line 296)

- return: the parsed template
- access: public

array &getItems ()
getTemplateFile (line 255)

- return: template file path if available, null otherwise.
- access: public

string getTemplateFile ()
handleException (line 1002)

Handles template parsing exception.

This method rethrows the exception caught during template parsing. It adjusts the error location by giving out correct error line number and source file.

- access: protected

void handleException (Exception $e, int $line, [string $input = null])

- Exception $e: template exception
- int $line: line number
- string $input: template string if no source file is used

instantiateIn (line 308)

Instantiates the template.

Content in the template will be instantiated as components and text strings and passed to the specified parent control.

- access: public

void instantiateIn (TControl $tplControl, [TControl $parentControl = null])

- TControl $tplControl: the control who owns the template
- TControl $parentControl: the control who will become the root parent of the controls on the template. If null, it uses the template control.

parse (line 578)

Parses a template string.

This template parser recognizes five types of data: regular string, well-formed component tags, well-formed property tags, directives, and expressions.

The parsing result is returned as an array. Each array element can be of three types:

- a string, 0: container index; 1: string content;
- a component tag, 0: container index; 1: component type; 2: attributes (name=>value pairs)

If a directive is found in the template, it will be parsed and can be retrieved via getDirective, which returns an array consisting of name-value pairs in the directive.

Note, attribute names are treated as case-insensitive and will be turned into lower cases. Component and directive types are case-sensitive. Container index is the index to the array element that stores the container object. If an object has no container, its container index is -1.

- access: protected
- throws: TConfigurationException if a parsing error is encountered

void parse (string $input)

- string $input: the template string

parseAttribute (line 865)

Parses a single attribute.

- return: attribute initialization
- access: protected

array parseAttribute (string $value)

- string $value: the string to be parsed.

parseAttributes (line 822)

Parses the attributes of a tag from a string.

- return: attribute values indexed by names.
- access: protected

array parseAttributes (string $str, mixed $offset)

- string $str: the string to be parsed.

parseTemplateProperty (line 854)

- access: protected

void parseTemplateProperty (mixed $content, mixed $offset)
preprocess (line 1037)

Preprocesses the template string by including external templates

- return: expanded template string
- access: protected

string preprocess (string $input)

- string $input: template string

validateAttributes (line 907)

- access: protected

void validateAttributes (mixed $type, mixed $attributes)

#### Inherited Methods

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
CONFIG_ASSET = 2 (line 187)
CONFIG_DATABIND = 0 (line 185)

Different configurations of component property/event/attribute

CONFIG_EXPRESSION = 1 (line 186)
CONFIG_LOCALIZATION = 4 (line 189)
CONFIG_PARAMETER = 3 (line 188)
CONFIG_TEMPLATE = 5 (line 190)
REGEX_RULES = '/<!--.*?--!>|<!---.*?--->|<\/?com:([\w\.]+)((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?"|\s*[\w\.]+\s*=\s*<%.*?%>)*)\s*\/?>|<\/?prop:([\w\.]+)\s*>|<%@\s*((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?")*)\s*%>|<%[%#~\/\\$=\\[](.*?)%>|<prop:([\w\.]+)((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?"|\s*[\w\.]+\s*=\s*<%.*?%>)*)\s*\/>/msS' (line 180)

'<!--.*?--!>' - template comments

'<!--.*?-->' - HTML comments '<\/?com:([\w\.]+)((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?"|\s*[\w\.]+\s*=\s*<%.*?%>)*)\s*\/?>' - component tags '<\/?prop:([\w\.]+)\s*>' - property tags '<%@\s*((?:\s*[\w\.]+\s*=\s*\'.*?\'|\s*[\w\.]+\s*=\s*".*?")*)\s*%>' - directives '<%[%#~\/\\$=\\[](.*?)%>' - expressions '<prop:([\w\.]+)((?:\s*[\w\.]+=\'.*?\'|\s*[\w\.]+=".*?"|\s*[\w\.]+=<%.*?%>)*)\s*\/>' - group subproperty tags

Documentation generated on Sun, 11 Jan 2009 20:24:09 -0500 by phpDocumentor 1.3.0RC4