Class TTemplate

Description

Implements interfaces:

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 2297 2007-10-03 21:21:40Z xue $
  • author: Qiang Xue <qiang.xue@gmail.com>

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

TComponent
   |
   --TApplicationComponent
      |
      --TTemplate
Class Constant Summary
 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 987)
  • 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 1000)

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 863)

Parses a single attribute.

  • return: attribute initialization
  • access: protected
array parseAttribute (string $value)
  • string $value: the string to be parsed.
parseAttributes (line 820)

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 852)
  • access: protected
void parseTemplateProperty (mixed $content, mixed $offset)
preprocess (line 1035)

Preprocesses the template string by including external templates

  • return: expanded template string
  • access: protected
string preprocess (string $input)
  • string $input: template string
validateAttributes (line 905)
  • 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 Mon, 21 Apr 2008 11:36:32 -0400 by phpDocumentor 1.3.0RC4