Difference between revisions of "Module Parameters"
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). | + | 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>. | ||
− | + | 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= | + | \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> | + | So we define a macro <tt>\BColor</tt>, like this: |
<texcode> | <texcode> | ||
\processaction[\currentmoduleparameter{color}] | \processaction[\currentmoduleparameter{color}] | ||
− | [ | + | [newman =>\def\BColor{red}, |
− | + | gottlieb =>\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= | + | \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) --