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.

If the method returns a value, it is interpreted as a string as best Sandvox can
An ampersand (&) will make sure the resulting string has any HTML entities escaped. e.g. < becomes < and so forth. You should use this unless you know that the value won't be an arbitrary string, or if you know that the value is already in escaped format, like a chunk of HTML
A % will make sure the resulting string is valid as a URL parameter. e.g. a space character is converted to +, the '+' character is converted to %2B, etc. Use this if you are generating a URL.

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.