html.plated.macros

Once we have some chunks defined we need to provide a way of refering to them inside other chunks as a macro expansion.

#^chunkname trim=ends
I am expanded
#^mainchunk
Expand the {chunkname} to its contents.

If the above mainchunk was rendered then {chunkname} would be replace with the contents of the chunk that was defined as #^chunkname this macro expansion is recursive so you can include chunks within chunks within chunks. Combined with the cascading chunks this provides a huge amount of flexibility without any additional programming logic. Similar to {{}moustache} templates but with slightly less logic and a bit more recursion.

If {chunkname} does not exist then the text will be left untouched as {chunkname} also there must be no white space in this macro expansion. so { chunkname } will never expand to anything.

This may sound dangerous but we are able to get away with {} even inside C like languages that contain {} all over the place. If this scares you then you are free to redefine {} to {{}} when invoking plated but I assure you it is not necessary.

{jsonchunk.member}

When using a json chunk a . can be used to pull out a value from the object

{jsonarray.0.name}

If it is an array then the first item could be picked out with a number and then its member.

{jsonarray.-1.name}

Negative numbers are allowed in which case it counts backwards from the end, in this case the last name of the last object in the array would be used.

Finally a json chunk may have another chunk applied as a layout.

{jsonchunk:plate}

In this case plate is a chunk name that renders with {_it} being synonymous with {jsonchunk} This is similar to calling a macro with a number of values.

{jsonarray:plate}

If a template is applied to an array then it is applied repeatedly to each item in that array. This allows for simple formatting of json data held within an array. The loop happens auto-magically with {_it} expanding to a different value each time.

All of these templating expansions are intended for use by plugins which provide arrays or objects of data for you to display.

If a plate is applied to empty data then the empty string is returned. Eg no expansion happens, this can help with layout logic removing some chunks and showing others depending on their existence.

Finally because we also need to be able to talk about these macros here without them accidently expanding then we have a simple way to escape them.

{[}{chunkname}{]}

No matter how valid the chunkname is it will not expand because it is contained within the comment tags {[}{]} these tags will be removed after the text is rendered.

{[[}{chunkname}{]]}

If multiple [ are used instead of one then it allows one level macro replacement per extra [ so we can control expansion this way. In the above example {chunkname} will expand once but any macros within that chunk will stay untouched. A tad complex but escape syntax is always a pain.

Due to the way this expands you must be careful to balance any use of {[}{]} within this chunk so as not to accidentally close the tag prematurely. This documentation for instance is designed to be used inside such a chunk so all square brackets inside {} have been carefully balanced to stop anything from going wrong.