2,184 bytes added
, 16:30, 26 April 2006
===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). Most of what I write here I've learnt from Taco, so all praise is due to him.
Our module will allow users to set the background color for a document. So
we call it <tt>t-bgcolor</tt>.
It starts, surprisingly enough, with a line saying
<pre>
\startmodule[bgcolor]
</pre>
Since we need to use some internal parameters, we have to "unprotect" the
contents of the module:
<pre>
\unprotect
</pre>
The next step is to set up the module with default parameters:
<pre>
\setupmodule[color=red]
</pre>
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
[[Commands_with_KeyVal_arguments|processaction]] mechanism .
So we define a macro <tt>\BColor</tt> and define it:
<pre>
\processaction[\currentmoduleparameter{color}]
[blue=> \def\BColor{blue},
red=> \def\BColor{red},
yellow=> \def\BColor{yellow},
\v!unknown=> \def\BColor{white},
\v!default=> \def\BColor{red}]
</pre>
We then use this variable to define the background of our document:
<pre>
\setupbackgrounds[page][background=color,backgroundcolor=\BColor]
</pre>
And that's it! We now just have to finish the module with these lines:
<pre>
\protect
\stopmodule
\endinput
</pre>
A simple test document will look like this:
<pre>
\setupcolors[state=start]
\usemodule[bgcolor][color=blue]
\starttext
Hello world!
\stoptext
</pre>
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 <tt>\getmoduleparameter{color}</tt>.
-- [[User:Thomas|Thomas]] 18:28, 26 April 2006 (CEST) --