View source for ConTeXt and Lua programming/Modules/Module Parameters

===Module parameters===

As of April 2006, ConTeXt provides a new mechanism for defining parameters
when calling a module. This is interesting for all those who consider
writing their own modules. It allows you to set variables in the call and
use them '''within''' the module's code; this was possible, but much less
convenient before. 

Here's a brief sample explaining how this mechanism works. It consists 
of a test module and an example file; they are dull (I admit) but 
instructive (I hope). In real life, this example module could be a whole 
lot shorter, but that would defeat the educational value :)

Our module will allow users to set the background color for a document. So
we call it <tt>t-bgcolor</tt>. 

The module starts, surprisingly enough, with a line saying 

<texcode>
\startmodule[bgcolor]
</texcode>

Since we need to use some internal parameters, we have to "unprotect" the
contents of the module:

<texcode>
\unprotect
</texcode>

The next step is to set up the module's variables with default parameters 
the settings asked for  by the user. This is handled by a single command 
that first processes its own argument list, and then it fetches the option
list the input file that loaded the module has asked for (such
user options overrule the default settings in the argument list):

<texcode>
\setupmodule[color=newman]
</texcode>

Our strategy will be to define a variable <tt>\BColor</tt> for the background color 
which will be set by the module; for this, we will use the
[[ConTeXt and Lua programming/Tutorials/Commands with KeyVal arguments|processaction]] mechanism. 

So we define a macro <tt>\BColor</tt>, like this:

<texcode>
\processaction[\currentmoduleparameter{color}]
   [    newman=>\def\BColor{red},
      gottlieb=>\def\BColor{yellow},
        rothko=>\def\BColor{blue},
    \v!unknown=>\def\BColor{white},
    \v!default=>\def\BColor{red}]
</texcode>

We then use this variable to define the background of our document:

<texcode>
\setupbackgrounds[page][background=color,backgroundcolor=\BColor]
</texcode>

And that's it! We now just have to finish the module with these lines:

<texcode>
\protect
\stopmodule
\endinput
</texcode>

A simple test document will look like  this:

<texcode>
\setupcolors[state=start]
\usemodule[bgcolor][color=rothko]

\starttext

Hello world!

\stoptext
</texcode>

This is just meant as a first example; of course, there are many more possibilities to use this mechanism. If you want to use the parameters directly in your code, you can use the form {{cmd|currentmoduleparameter}}<tt>{color}</tt>, or alternatively, {{cmd|moduleparameter}}<tt>{bgcolor}{color}</tt>. 

-- [[User:Thomas|Thomas]] 18:28, 26 April 2006 (CEST) --
-- [[User:Taco|Taco]] 12:46, 27 April 2006 (CEST) --

[[Category:Modules]]
[[Category:Tools]]
[[Category:Programming and Databases]]