Macro Libraries

1 Definition
2 Use in Templates
3 Scripting
4 Sample Usage

Draft

A macro library is a collection of macros which can be used by templates.

Definition

A macro library can be defined as in the example below:

File /templates/macros/Library.tml

{Library{
    $classpath : "ariadoc.snippets.templates.macros.Library"

}}

{macro printMult(one, two)}

   {for var i=0; i < two ; i++ }

      + ${one} <br/>

   {/for}

   ------ <br/>

   Result: ${ one * two }

{/macro}

{/Library}

Notes:

All libraries have the extension .tml (template macro library), therefore the file above is called Library.tml.
Access to the data and the module controller is not allowed as the data and moduleCtrl object are not put in the Library's scope. The only way in which a Library can access this and other data supplied by the template is by taking them as macro parameters.
Libraries cannot use CSS templates. The option to do so will be offered in a future release.

Use in Templates

A macro library can be declared in the macrolibs section of the Template statement. The declaration includes a configuration, which is a number of handles and a classpaths. The handles can then be used throughout the template to access the library's macros as shown in the example below.

File /templates/macros/Template.tpl

{Template{
  $classpath : "my.simple.Template",

  $macrolibs : {

    myLib : "my.simple.lib",

    otherLib : "my.other.lib" }

} }

  {macro main ( )}

    Let' s multiply 2 by 5 . <br />

    { call myLib.printMult ( 5 , 2 ) /}

  {/macro}

{/Template}

The declaration takes as parameter a Javascript Object, in which every property is an identifier (the handle which will be used in the template) and each corresponding value is a string (the classpath of the library which will be bound to the handle). Furthermore the declaration:

Can include several handle-classpath couples in the argument.
Can also be used in Libraries exactly like it's used in Templates, making it possible to arbitrarily organize library inclusion hierarchies.
Cannot be used in CSS templates.

Scripting

Libraries can use scripts just like templates by providing them in the Library declaration. From a design standpoint, access to the script functions should be restricted to libraries, even though script methods are still accessible as properties of the handle in the template. An example of this is shown below.

Script

File /templates/macros/LibScript.js

Aria.tplScriptDefinition({
  $classpath : 'my.simple.LibScript',

  $prototype : {

    scriptHello : function () {

      return "script says hello!";

    }

  }

});

Library

File /templates/macros/Lib.tml

{Library{
  $classpath : "my.simple.Lib",

  $hasScript : true } }

{macro libHello ( )}

  ${ scriptHello() }

{/macro}

{/Library}

Template

File /templates/macros/TemplateForLib.tpl

{Template{
  $classpath : "my.simple.TemplateForLib",

  $macrolibs : {

    myLib : "my.simple.lib" }

} }

  {macro main ( )}

    The following lines both print "script says hello!" .

    { call myLib.libHello ( ) /}

    ${ myLib.scriptHello() /}

  {/macro}

{/Template}

Libraries inherit from aria.templates.Template, therefore any library script should do the same, following the concepts explained in the article about Template Scripts.

Sample Usage

Simple macro definition inside a library
Simple macro definition inside a library with an associated script

Retrieved from "http://ariatemplates.com/wiki/index.php?title=Macro_Libraries&oldid=2293"