Difference between revisions of "Module Parameters"

From ConTeXt wiki
Jump to navigationJump to search
m (<texcode>)
(patched up a bit)
Line 5: Line 5:
 
writing their own modules. It allows you to set variables in the call and
 
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
 
use them '''within''' the module's code; this was possible, but much less
convenient before. Here's a brief sample explaining how this mechanism
+
convenient before.  
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.
+
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
 
Our module will allow users to set the background color for a document. So
 
we call it <tt>t-bgcolor</tt>.  
 
we call it <tt>t-bgcolor</tt>.  
  
It starts, surprisingly enough, with a line saying  
+
The module starts, surprisingly enough, with a line saying  
  
 
<texcode>
 
<texcode>
Line 25: Line 28:
 
</texcode>
 
</texcode>
  
The next step is to set up the module with default parameters:
+
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>
 
<texcode>
\setupmodule[color=red]
+
\setupmodule[color=newman]
 
</texcode>
 
</texcode>
  
Our strategy will be to define a variable <tt>\BColor</tt> for the background color which
+
Our strategy will be to define a variable <tt>\BColor</tt> for the background color  
will be set by the module; for this, we will use the
+
which will be set by the module; for this, we will use the
[[Commands_with_KeyVal_arguments|processaction]] mechanism .  
+
[[Commands_with_KeyVal_arguments|processaction]] mechanism.  
  
So we define a macro <tt>\BColor</tt> and define it:
+
So we define a macro <tt>\BColor</tt>, like this:
  
 
<texcode>
 
<texcode>
 
\processaction[\currentmoduleparameter{color}]
 
\processaction[\currentmoduleparameter{color}]
   [blue=> \def\BColor{blue},
+
   [newman    =>\def\BColor{red},
     red=> \def\BColor{red},
+
     gottlieb  =>\def\BColor{yellow},
     yellow=> \def\BColor{yellow},
+
     rothko    =>\def\BColor{blue},
     \v!unknown=> \def\BColor{white},
+
     \v!unknown=>\def\BColor{white},
     \v!default=> \def\BColor{red}]
+
     \v!default=>\def\BColor{red}]
 
</texcode>
 
</texcode>
  
Line 64: Line 71:
 
<texcode>
 
<texcode>
 
\setupcolors[state=start]
 
\setupcolors[state=start]
\usemodule[bgcolor][color=blue]
+
\usemodule[bgcolor][color=rothko]
  
 
\starttext
 
\starttext
Line 73: Line 80:
 
</texcode>
 
</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 <tt>\getmoduleparameter{color}</tt>.  
+
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>\currentmoduleparameter{color}</tt>, or alternatively, <tt>\getmoduleparameter{bgcolor}{color}</tt>.  
  
 
-- [[User:Thomas|Thomas]] 18:28, 26 April 2006 (CEST) --
 
-- [[User:Thomas|Thomas]] 18:28, 26 April 2006 (CEST) --
 +
-- [[User:Taco|Taco]] 12:46, 27 April 2006 (CEST) --
  
 
[[Category:Modules]]
 
[[Category:Modules]]
 
[[Category:Inside ConTeXt]]
 
[[Category:Inside ConTeXt]]

Revision as of 10:48, 27 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). 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, \getmoduleparameter{bgcolor}{color}.

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