Module Parameters

From ConTeXt wiki

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 t-bgcolor.

The module starts, surprisingly enough, with a line saying

\startmodule[bgcolor]

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

\unprotect

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):

\setupmodule[color=newman]

Our strategy will be to define a variable \BColor for the background color which will be set by the module; for this, we will use the processaction mechanism.

So we define a macro \BColor, like this:

\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}]

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

\setupbackgrounds[page][background=color,backgroundcolor=\BColor]

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

\protect
\stopmodule
\endinput

A simple test document will look like this:

\setupcolors[state=start]
\usemodule[bgcolor][color=rothko]

\starttext

Hello world!

\stoptext

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 \currentmoduleparameter{color}, or alternatively, \moduleparameter{bgcolor}{color}.

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