Difference between revisions of "Module Parameters"

From ConTeXt wiki
Jump to navigationJump to search
 
m (<texcode>)
Line 14: Line 14:
 
It starts, surprisingly enough, with a line saying  
 
It starts, surprisingly enough, with a line saying  
  
<pre>
+
<texcode>
 
\startmodule[bgcolor]
 
\startmodule[bgcolor]
</pre>
+
</texcode>
  
 
Since we need to use some internal parameters, we have to "unprotect" the
 
Since we need to use some internal parameters, we have to "unprotect" the
 
contents of the module:
 
contents of the module:
  
<pre>
+
<texcode>
 
\unprotect
 
\unprotect
</pre>
+
</texcode>
  
 
The next step is to set up the module with default parameters:
 
The next step is to set up the module with default parameters:
  
<pre>
+
<texcode>
 
\setupmodule[color=red]
 
\setupmodule[color=red]
</pre>
+
</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 which
Line 37: Line 37:
 
So we define a macro <tt>\BColor</tt> and define it:
 
So we define a macro <tt>\BColor</tt> and define it:
  
<pre>
+
<texcode>
 
\processaction[\currentmoduleparameter{color}]
 
\processaction[\currentmoduleparameter{color}]
 
   [blue=> \def\BColor{blue},
 
   [blue=> \def\BColor{blue},
Line 44: Line 44:
 
     \v!unknown=> \def\BColor{white},
 
     \v!unknown=> \def\BColor{white},
 
     \v!default=> \def\BColor{red}]
 
     \v!default=> \def\BColor{red}]
</pre>
+
</texcode>
  
 
We then use this variable to define the background of our document:
 
We then use this variable to define the background of our document:
  
<pre>
+
<texcode>
 
\setupbackgrounds[page][background=color,backgroundcolor=\BColor]
 
\setupbackgrounds[page][background=color,backgroundcolor=\BColor]
</pre>
+
</texcode>
  
 
And that's it! We now just have to finish the module with these lines:
 
And that's it! We now just have to finish the module with these lines:
  
<pre>
+
<texcode>
 
\protect
 
\protect
 
\stopmodule
 
\stopmodule
 
\endinput
 
\endinput
</pre>
+
</texcode>
  
 
A simple test document will look like  this:
 
A simple test document will look like  this:
  
<pre>
+
<texcode>
 
\setupcolors[state=start]
 
\setupcolors[state=start]
 
\usemodule[bgcolor][color=blue]
 
\usemodule[bgcolor][color=blue]
Line 71: Line 71:
  
 
\stoptext
 
\stoptext
</pre>
+
</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>\getmoduleparameter{color}</tt>.  
  
 
-- [[User:Thomas|Thomas]] 18:28, 26 April 2006 (CEST) --
 
-- [[User:Thomas|Thomas]] 18:28, 26 April 2006 (CEST) --
 +
 +
[[Category:Modules]]
 +
[[Category:Inside ConTeXt]]

Revision as of 04:06, 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). 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 t-bgcolor.

It 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 with default parameters:

\setupmodule[color=red]

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 and define it:

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

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=blue]

\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 \getmoduleparameter{color}.

-- Thomas 18:28, 26 April 2006 (CEST) --