Passing arguments to functions and templates

Passing a Parameter Map

The function parameter list is actually a map, which consists of a series of key/value pairs. Each parameter is an entry in the map, with the key equal to the parameter name, and the value equal to the one you provide.  So our first way to pass parameters is to pass the function the parameter map directly.

A map consists of curly braces "{}" enclosing a comma-separated list of name:value pairs.  One nice aspect of this approach is that you need only specify the parameters you want to, in any order, and omit the optional parameters you don't care about.

{{ wiki.Tree{ path:"" } }}

{{ wiki.Tree{ reverse:true, path:""  } }}

Passing an Arg-list

Dekiscript also gives you a convenient shorthand option to pass the parameters as an arg-list, and then it'll convert it to a map for you. In this case, you enclose the list in regular parentheses "()", and just provide a list of the values you wish to specify in the order listed in the documentation. Let's recreate our above examples.

{{ wiki.Tree( "" ) }}

{{ wiki.Tree( "", nil, true ) }}

Special Considerations for Calling Templates

For the most part, templates behave a lot like built-in functions; however, there are a few additional considerations.

First, there are three at least three separate ways to call templates.  Let's take the Collapsible Page Tree template as an example.  I can call it directly as a function, either on its own or as part of the "template" namespace:

{{ CollapsibleTree() }}
{{ template.CollapsibleTree() }}

In either case, I can use a parameter map or an arg-list:

{{ CollapsibleTree( wiki.tree(), 1, true ) }}
{{ CollapsibleTree{ xml:wiki.tree(), depth:1, slide:true } }}

However, there's another option for calling templates: the wiki.template() function (we'll ignore the "target" and "conflict" args, since they're irrelevant for this discussion).  The equivalent of the above would be:

{{ wiki.template( "CollapsibleTree", { xml:wiki.tree(), depth:1, slide:true } ) }}

Here, the template name and the parameter map are passed as parameters to the wiki.template() call.  This is a bit verbose and harder to read, but there are at least three scenarios where this form is invaluable, or even necessary:

1. When you're calling a template that is not at the top level of the template namespace.  For instance, say you want to call Mindtouch/Controls/ListPages?  You're only way is {{ wiki.template( "Mindtouch/Controls/ListPages", { path:page.path, etc. etc. }) }}
2. When you want to calculate the template name.  You can assign the desired template name to a variable (determine the name however you wish), and then pass it to wiki.template().
3. When you wish to pass a parameter map intact.  Let's say you have a parameter map assigned to a variable, and wish to pass it to a template: the only efficient way to do that is with wiki.template().  This situation occurs in the real world most commonly when calling a template from another template.  The caller passes a parameter map to the top-level template, which then passes it to the lower-level template using wiki.template().

How to choose?

Personal preference, of course.  The map syntax is more robust.  You don't need to remember the argument order, and you don't need a string of nils if you only want to set the very last optional parameter.  That is both hard to read and easy to get wrong.  On the other hand, the arg-list syntax is more compact and convenient for function calls with only a few arguments.

In general, you should design your templates and extensions so that the use of either form is convenient.  That means:

1. Support both positional args ($0, $1, $2, etc.) and named args ($xml, $depth, $slide, etc.) in your code.
2. Define the sequence of positional args like this:
   1. First put the required args.
   2. Next put the most commonly used optional args.
   3. End with the least commonly used optional args.

This minimizes the need to insert nil arguments when using an arg-list.