Noel Tags

Noel can define and extend custom HTML-like tags in order to abstract out duplicate or complex content. Tags are initially defined using the built-in <TAG> tag. Unmatched tags (including regular HTML tags) are ignored by the Noel parser.

<foo> <tag Foo><b>squee!</b></tag> <foo> <foo> <Tag foo>42</Tag> <foo>

=>

<foo> <b>squee!</b> <foo> 42

Tag names, like variable names, must begin with a letter and can contain letters, digits, dashes (-), and underscores (_). Unlike variable names, tag names are not case sensitive. Tag definitions can be nested inside tag definitions.

Tag Resolution

Resolving a tag is similar to resolving a variable. When the Noel parser encounters a custom tag in the output, the tag is replaced with the custom tag contents. Sometimes you will have tags that may or may not be defined (especially within higher-level template files). You can use silent tag notation to hide tags when no matching custom tag is defined. You can also use required tag notation to assert that a tag is resolved by a custom Noel tag.

There is also an <IFTAG> conditional for more complex behavior based on tag existence.

Extending Tags

Content can be inserted into an existing tag (creating the tag if it is undefined) using the built-in <INSERTTAG> tag.

<Tag Site>-- Site Header --<p></Tag> <InsertTag Site>Content</InsertTag> <Site> -- Site Header --<p>Content

By default content is appended to the end of a tag, but insertion points can be used to insert content into different locations within a tag. The default insertion point is '<<>>'. Insertion points can be inserted/relocated by the insert content.

<Tag Site>Header <<>> Footer</Tag> <InsertTag Site>Content</InsertTag> <InsertTag Site>...<<>> More</InsertTag> <InsertTag Site>!!!</InsertTag> <Site> Header Content...!!! More Footer

The special insertion points 'TOP' and 'BOTTOM' can be used for prepending or appending content to a tag.

<Tag Site>FOO <<>> BAR</Tag> <InsertTag Site>middle</InsertTag> <InsertTag Site@TOP>top </InsertTag> <InsertTag Site@BOTTOM> bottom</InsertTag> <Site> top FOO middle BAR bottom

Insertion points can be escaped by using a Copy Content delimiter around the first two less-than signs, i.e..: <!!::<<::>>>. Insertion points are not escaped when they are completely enclosed within a Copy Content section; this allows Javascript and CSS to be easily inserted into copy content-delimited sections of a page.

As of version 0.9.6, tags can also be modified via the built-in <WRAPTAG> tag, which is the inverse of <INSERTTAG>:

<Tag Content>This is my content.</Tag> <WrapTag Content><div class="content"><<>></div></Tag> <Content> <div class="content">This is my content.</div>

The content of <WRAPTAG> must contain an <<>> insertion point, which is where the previous content of the tag is pushed into.

Copying Tags

You can copy a tag, including its local variables and local tags state, via the <COPYTAG> tag:

<Tag Foo name="World">Hello $name!</tag> <CopyTag Bar=Foo name="Bob"> <Foo> <Bar> Hello World! Hello Bob!

There are some short-term benefits to copying tags, but also on the higher-end <COPYTAG> can be used for creating tag prototypes and for abstracting out complex logic into different branches of tags.

Closure Tags

Custom tags are by default standalone tags: When you define <Foo>, you just use <Foo> in your source—there is no </Foo>. Closure tags are tags that have both an opening and closing tag when used, e.g. <Foo>inserted content<<Foo>. When you define a custom tag with "..." appended to the tag name, it is defined as a closure tag:

<Tag Box...><div class="box"><<>></div></Tag> <Box>This is my content.</Box> <div class="box">This is my content.</div>

Before closure tags, you would have to separately define both an opening and closing tag to get the same effect. And even then you couldn't share local variables and tags between the two tags. Closure tags are an elegant feature to use when you want a custom tag to act as a container for other content.

Local Tags

Local tags are tags within tags which can be referenced using the 'insertion point' format given above. Local tags can be defined using the notation "<Tag parentTagName@localTagName>" and extended using the notation "<InsertTag parentTagName@localTagName>".

<Tag Header><HTML><Head><Title><TITLE></Title></Head></Tag> <InsertTag Header@TITLE>Site Name</InsertTag> <InsertTag Header@TITLE> - Section Name</InsertTag> <InsertTag Header@TITLE> - Page Name</InsertTag> <Header> <HTML><Head><Title>Site Name - Section Name - Page Name</Title></Head>

Like local variables, local tags only exist within the context of their parent tag; changes to local tags do not effect parent or children tags.

If you insert into a local tag but the tag is never used in its parent tag, the content is discarded (without any error or warning.)

Undefining Tags

Tags can also be undefined via the built-in <UNDEFTAG> tag. Example:

<undeftag Foo>