HTML Template

Each Template.html file is a fragment of HTML, with special characters [[ and ]] for preprocessing by Sandvox. Within these brackets can go codes for substitution of properties of your plug-in, or limited program-like functionality like branches and loops.

During -[SVPlugIn writeHTML:], Sandvox reads the template, preprocesses everything between the special characters, writing the results to the context.

Values

[[=foo]]
[[=&foo]]
[[=&%foo]]

The = function calls through to the corresponding value on your plug-in. In practice, this is typically used one of two ways: to bring in the value of a plug-in property or key path, or as a hook in to plug-in code that writes its own HTML to the current context.

Advanced Usage

The = function also allows you to mix together a template and custom Cocoa code. For example this method on a plug-in:

- (void)writeHomePageLink
{
    id <SVPlugInContext> context = [self currentContext];
    [context startAnchorElementWithPage:[[context page] rootPage]];
    [context writeText:@"Go Home"];
    [context endElement];
}

could be called from the template with a simple:

[[=writeHomePageLink]]

You can gain access to the full breadth of SVHTMLContext's functionality at any point of HTML generation.

Localized Strings

The " and ' characters are used to indicate that the string is localized.

Other Functions

The text in bold demonstrates how to use each function. Parameters in brackets are optional.

If Statements

[[if expression]]
Start a conditional branch, testing for the value of expression. If it evaluates to true, then the HTML up to the balancing [[else]] (optional) or [[endif]] is parsed and included in the output; if false, then the part between any balancing [[else]] and [[endif]] is included. If nested within other if tags, then it should be balanced by [[else2]] / [[endif2]], [[else3]] / [[endif3]], etc.


The expression between the [[if and the ]] is quite flexible.

(no operation, just a single key path)
test to see if the value of the key path is non-empty
==, !=, <>, ><
compares numeric or "isEqual:" equality/inequality of the left and right sides
>=, =>, <=, =<, <, >, =
compares two items numerically
||, &&
tests left and right side for being non-empty, and ORs or ANDs them together (short-circuits)


"Non Empty" works for many objects that respond to "count", "length", or "intValue", or tests for nil.

Loops

[[foreach array.keypath newkey]]
Begins a loop. The second item is the key path to some array or list of items; the newkey is the string that is put into context for accessors to use. Should be balanced by [[endForEach]], or if nested within other foreachs, then by [[endForEach2]], [[endForEach3]], etc.
[[i]]
inserts a number representing the current index (1-based) of the loop. Used for CSS numeric keys. An empty string if not in a loop.
[[eo]]
inserts 'e' or 'o' depending on whether the index (1-based) of the loop is even or odd. Used for CSS even/odd generation. An empty string if not in a loop.
[[last]]
Inserts " last-item" (including the space) if this is the last item in a loop; empty otherwise.

Other Utilities

[[comment foo bar]]
The parser complete ignores anything inside a comment function. Use it for comments which are for readability of the template but shouldn't appear in the published HTML.
How can we improve this page? Let us know.