HTML Template

An HTML Template 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 plugin, or limited program-like functionality like branches and loops.

You can also override the template files in existing Sandvox plugins.

Accessors

If the first character after [[ is "=" then the rest of the contents of the directive up to the ]] is interpreted as a Cocoa Key Path; the entire tag is substituted with the value of the keypath.

After the "=" you can also use a "&" to indicate that the value fetched must have its entities escaped, e.g. & becomes &amp;; < becomes &lt;, 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.

You can also use % to indicate that the value fetched should be escaped for generation of a URL, e.g. a space character is converted to +, the '+' character is converted to %2B, etc. Use this if you are generating a URL.

If % comes before &, then the string is first encoded for a URL, then the HTML entities are escaped. If & comes before %, the string is first HTML escaped, and then URL encoded. There are probably some examples of when we would want these cases.

Parser 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)

|editing

special "or editing" method used for placing items into the output if the left-hand operand is true, or if the editing markers are visible.

"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.

[[target otherPage.keyPath]]

Used in <a<> tags; If otherPage has the property of openInNewWindow then generate target="_BLANK" .

[[path page.keypath]]

Returns the relative path to the specified page. This allows for relative paths to another page from whatever page is being generated.

[[rsspath page.keypath]]

Returns the relative path to the RSS feed of the specified page. If the page is not a collection or is not set to generate an RSS feed, returns an empty string.

[[mediainfo info:path/width/height/MIMEType/dataLength media:aMediaContainer (sizeToFit:aSize.keypath)]]

Returns the requested info about the specified KTMediaContainer object. You can user sizeToFit: to have the media be appropriately scaled first..

[[resourcepath resource.keypath (page.keypath)]]

Returns the path to the specified resource, relative to the specified page. This allows for relative paths to resources from whatever page is being generated.

[[parsecomponent component.keypath templateHTML.keypath]]

Starts up a new HTML parser to parse the specified HTML template and component. The full parsed HTML is returned.

[[textblock ______]]

Generates a block of text using the same syntax as [[idClass]].

[[idclass (various)]]

Used internally to generate and ID and class. Documented in the source code.

Used Internally: Plugins probably won't need

[[continuereadinglink ______]]

____________.

[[index ______]]

____________.

[[summary ______]]

____________.

[[endbody]]

Collects markup that the page's elements want to put at the end of the <body> tag.

[[extraheaders]]

Collects markup that the page's elements want to put at the end of the <head> tag.

[[stylesheet]]

Loads the style sheet into the <head> area.

How can we improve this page? Let us know.