Define Tag Information

The first step in creating a custom tag is to create a file in the tag search path with the extension .tag.php. Any files with this extension in the compiler search path will automatically be loaded by the compiler.

This file must register its tag class using by creating an instance of the TagInfo Class. For example:

/**
* Register the tag
*/
$taginfo =& new TagInfo('core:INCLUDE', 'CoreIncludeTag');
$taginfo->setEndTag(ENDTAG_FORBIDDEN);
$taginfo->setCompilerAttributes(array('file', 'literal'));

The first argument, Tag represents the name of the tag.

setEndTag tells the compiler how to process tags with contents. Allowable values are:

Constant	Description
`ENDTAG_REQUIRED`	Closing tag is required.
`ENDTAG_OPTIONAL`	Not implemented yet. Currently treated the same as `ENDTAG_REQUIRED`.
`ENDTAG_FORBIDDEN`	No closing tag is allowed.

TagClass tells the compiler which tag class to instantiate when this tag is used in a template.

The .tag.php file should register the tags that it contains with the compiler using the TagDictionary::registerTag function. for example:

TagDictionary::registerTag($taginfo, __FILE__);

Creating a Tag Class

When creating a tag class, you can inherit from one of four base classes:

Tag Type	Description
SilentCompilerDirective Tag	Silent compiler directive tags are instructions for the compiler and do not have corresponding Components. They also do not normally generate output in the compiled template.
CompilerDirective Tag	Compiler directive tags do not have corresponding server Components, but they render their contents into the compiled template.
ServerComponent Tag	Server component tags have a corresponding server component that represents an API (Application Programming Interface) used to manipulate the marked-up portion of the template.
ServerTagComponent Tag	Server tag component tags are ServerComponent Tags that also correspond to an HTML (HyperText Markup Language) tag.

Here is an example tag class definition:

class CoreIncludeTag extends CompilerDirective {
}

Override Template Methods

After defining your class, you can now override the appropriate TemplateMethods to provide the functionality of your tag. See CodeWriter for information on how to generate code for a template.

Code Generation Methods

preGenerate

function preGenerate(&$code)

Generate Template code before the contents of your tag.

generateContents

function generateContents(&$code)

Generate Template for the contents of your tag.

postGenerate

function postGenerate(&$code)

Generate Template code after the contents of your tag.

Parser Interface Methods

CheckNestingLevel

function CheckNestingLevel

Called by the parser to check for proper usage and nesting.

preParse

function preParse

The result of this method tells the parser whether to parse the contents of this tag. Allowable return values are:

PARSER_FORBID_PARSING
PARSER_REQUIRE_PARSING
PARSER_ALLOW_PARSING

prepare

function prepare

This method is called on your tag when the entire document tree has been parsed. This is an opportunity to manipulate the tree or initialize variables before code generation begins.

Component Methods

The following methods are only used for ServerComponent Tags and ServerTagComponent Tags:

generateConstructor

function generateConstructor(&$code)

Generate code in this method which is used to construct the Component which corresponds to your class

generateExtraAttributes

function generateExtraAttributes(&$code)

getRenderedTag

function getRenderedTag

DataSource Methods

Override the following two methods to make your tag a DataSource:

getDataSource

function &getDataSource()

getDataSourceRefCode

function getDataSourceRefCode

Debugging

Some basic functionality for debugging templates as you develop them is provided by the Dev Source Tag and the Dev Tree Tag.

More Info

For further information see Developing_A_Calendar_Component_Tag and Developing_A_Data_Table_Component_Tag.