====== 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 [[class:taginfo|TagInfo Class]].  For example:

<code php>

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

</code>

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

''setEndTag'' tells the compiler how to process tags with contents.  Allowable values are:
^ ENDTAG_REQUIRED  | Closing tag is required. |
^ ENDTAG_OPTIONAL  | not implented yet.  Treated the same as ENDTAG_REQUIRED for now. |
^ 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:

<code php>

TagDictionary::registerTag($taginfo, __FILE__);

</code>

====== Creating a Tag Class ======

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

^ [[class:slientcompilerdirective|SilentCompilerDirective Tag]] | Silent compiler directive tags are instructions for the compiler and do not have corresponding [[class:component|Components]], nor do they normally generate output into the compiled template. |
^ [[class:compilerdirective|CompilerDirective Tag]] | Compiler directive tags do not have corresponding server [[class:component|Components]], but they do render their contents into the compiled template. |
^ [[class:servercomponent|ServerComponent Tag]] | Server component tags have a corresponding server component which represents an API which can be used to manipulate the marked up portion of the template. |
^ [[class:servertagcomponent|ServerTagComponent Tag]] | Server tag component tags are [[class:servercomponent|ServerComponent Tag]]s which also correspond to an HTML tag. |

Here is an example tag class definition:


<code php>

class CoreIncludeTag extends CompilerDirective {
}

</code>



====== Override Template Methods ======

After defining your class, you can now override the appropriate [[pattern:template_method|TemplateMethod]]s to provide the functionality of your tag.  See [[class:codewriter|CodeWriter]] for information on how to generate code for a template.


===== Code Generation Methods =====


==== preGenerate ====

<code php>

function preGenerate(&$code)

</code>


Generate Template code //before// the contents of your tag.


==== generateContents ====

<code php>

function generateContents(&$code)

</code>


Generate Template for the contents of your tag.


==== postGenerate ====

<code php>

function postGenerate(&$code)

</code>


Generate Template code //after// the contents of your tag.


===== Parser Interface Methods =====


==== CheckNestingLevel ====

<code php>

function CheckNestingLevel

</code>


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


==== preParse ====

<code php>

function preParse

</code>


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 ====

<code php>

function prepare

</code>


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 [[class:servercomponent|ServerComponent Tags]] and [[class:servertagcomponent|ServerTagComponent Tags]]:


==== generateConstructor ====

<code php>

function generateConstructor(&$code)

</code>


Generate code in this method which is used to construct the [[class:component|Component]] which corresponds to your class


==== generateExtraAttributes ====

<code php>

function generateExtraAttributes(&$code)

</code>



==== getRenderedTag ====


<code php>

function getRenderedTag

</code>



===== DataSource Methods =====

Override the following two methods to make your tag a [[class:datasource|DataSource]]:


==== getDataSource ====


<code php>

function &getDataSource()

</code>



==== getDataSourceRefCode ====


<code php>

function getDataSourceRefCode

</code>



===== Debugging =====

Some basic functionality for debugging templates as you develop them is provided by the [[tag:dev:source|Dev Source Tag]] and the [[tag:dev:tree|Dev Tree Tag]].

===== More Info =====
For further information see [[Developing_A_Calendar_Component_Tag]] and [[Developing_A_Data_Table_Component_Tag]].