Creating a tag file

Tagfiles are a more powerful version of a standard template. Most users will find that tag files contain all the functionality they need.

Basic tagfiles just work as templates. You can drop a file into the taglib's template directory and it will be found automatically. If your taglib classname is SimpleTaglib then your template directory will be:

HTML_Template_Nest_View::$VIEW_DIR . "/templates/simpletaglib/"

If we want to explicitly add a tag file (for example to override tag methods or add declared attributtes), we need to extend the tag file class and specify the path to the tag file's template.

SimpleTaglib.php

<php
require_once 'HTML/Template/Nest/Taglib.php';
require_once 'HTML/Template/Nest/TagFile.php';

class SimpleTaglib extends HTML_Template_Nest_Taglib
{
    protected $tags = array(
        "simpleTagFile" => "SimpleTaglib_SimpleTagFile", 
        "simpleTag" => "SimpleTaglib_SimpleTag",
    );
}

class SimpleTaglib_SimpleTagFile extends HTML_Template_Nest_TagFile
{
    public function getTagFilename() 
    {
        return HTML_Template_Nest_View::$VIEW_DIR . "/templates/simpletaglib/simple_tagfile.tmpl";
    }
}

Now we'll create the template in the same directory as our SimpleView.php file.

simple_tagfile.tmpl

<div class="welcome">
    <h1>Hello <b>${username}</b>!</h1>
</div>

Now we'll edit our original template to use our new tag library:

simpleview.nst

<html xmlns:simple="urn:nsttl:SimpleTaglib">
    <head>
        <title>A Simple View</title>
    </head>
    <body>
        <simple:simpleTagFile />
    </body>
</html>

Which gives us basically the same output as before, but this time it's wrapped in a div. Rather than hard code that information, however we can put the tag <nst:processBody /> into our template and then move the actual text back out of the tag file. This is where the nesting actually comes into play.

simple_tagfile.tmpl

<div class="welcome">
    <nst:processBody xmlns:nst="http://nest.sourceforge.net" />
</div>

simpleview.nst

<html xmlns:simple="urn:nsttl:SimpleTaglib">
    <head>
        <title>A Simple View</title>
    </head>
    <body>
        <simple:simpleTagFile>
            <h1>Hello <b>${username}</b>!</h1>
        </simple:simpleTagFile>
    </body>
</html>

We get basicaly the same output, but now we can easily change the actual text if requirements change without changing the actual document structure. Tags can be nested and you can include tag libraries in tag files. If we wanted to add the standard tag library in our simple_tagfile.tmpl we'd do so like this:

simple_tagfile.tmpl

<div class="welcome" xmlns:c="urn:nsttl:HTML_Template_Nest_Taglib_Standard" xmlns:nst="http://nest.sourceforge.net/">
    <nst:processBody />
</div>

Exposing Attributes

Attributes can be exposed with the $declaredAttributes array. Any keys in that array will be declared as local variables for the current tag and can be accessed like any other variable.

class SimpleTaglib_SimpleTagFile extends HTML_Template_Nest_TagFile
{
    protected $declaredAttributes = array("param1", "param2");
    ...
}

You can then access ${param1} and ${param2} inside the tag.

That's it for tag files. They'll work in pretty much every simple situation.