<chapter id="introduction">
<title>The producer framework</title>
+Please read the presentation of the <glossterm linkend="producers">producers</glossterm> concept
+for an introduction.
<section><title>How to use the <filename>producers.xml</filename> file</title>
- [FIXME: this should be in the user's guide, not here]
+ [FIXME: this should be in the admin's guide, not here]
+
+<para>
+Please check the standard <filename>producers.xml</filename> file
+for two fully commented, real-world examples :
+the <code><nodedefinition name="Language"></code> node
+and the <code><producer name="articles"></code> node.
+</para>
<section><title>Introduction</title>
<para>
- With Mir, it is now possible to set up arbitrary producers using an xml file.
+ Mir allows admins to fully configure the producer tasks and set up
+ arbitrary producers through the <filename>producers.xml</filename> file.
</para>
<para>
<para>
A producer is defined using a Producer tag:
-
<programlisting>
<producer name="content"/>
- </programlisting>
-
- would define a producer named <code>content</code>.
-
- </para><para>
+ </programlisting>
+ This would define a producer named <code>content</code>.
+ </para><para>
In a producer, <emphasis>verbs</emphasis> must be defined.
Verbs are sub-tasks of a producer.
<producer name="content"/>
</programlisting>
- would define a producer with verbs named <code>all</code> and <code>new</code>.
+ This would define a producer with verbs named <code>all</code> and <code>new</code>.
</para><para>
And also the specific nodes and their relationship should be specified:
Sub tags</td></tr>
<tr><td>parameters</td> <td>a list describing the arguments the "function" must be given </td></tr>
- <tr><td>definition</td> <td>the actual body of the function, containing the code that should be executed. Note that this may contain a <code><sub/></code> tag that is replaced by the child nodes of the calling node (FIXME is this true???) </td></tr>
+ <tr><td>definition</td> <td>the actual body of the function, containing the code that should be executed. Note that this may contain a <code><sub/></code> tag that is replaced by the child nodes of the calling node. </td></tr>
+ <tr><td>Name</td> <td bgcolor="#eea8a8"><code>GenerateMedia</code></td></tr>
+ <tr><td>Purpose</td> <td>
+The generateMedia node instructs the media handler associated with the media to
+"reproduce" the media. In practice this can mean generate an icon from an image,
+writing an image from the database to the web root, or create an m3u file or so.
+Media handling is limited at this moment, but a serious
+redesign is planned right after 1.1
+</td></tr>
+ <tr><td colspan="2">
+
+ Arguments</td></tr>
+
+ <tr><td>key</td> <td>FIXME???</td></tr>
+
+
<tr><td>Name</td> <td bgcolor="#eea8a8"><code>DeleteFile</code></td></tr>
<tr><td>Purpose</td> <td>Delete a file</td></tr>
<tr><td>Name</td> <td bgcolor="#eea8a8"><code>Resource</code></td></tr>
- <tr><td>Purpose</td> <td>Make a message resource bundle available</td></tr>
+ <tr><td>Purpose</td> <td>Make a message resource bundle available. In other words, this defines a function that can be used in expressions to reference a bundle. </td></tr>
<tr><td colspan="2">
Arguments</td></tr>
- <tr><td>key</td> <td>The variable in which the bundle will be stored</td></tr>
+ <tr><td>key</td> <td>The name of the function.</td></tr>
<tr><td>bundle</td> <td>The bundle to use</td></tr>
<tr><td>language (optional)</td> <td>The specific language to use</td></tr>
+ <tr>
+ <td>Example</td>
+ <td>
+ <code>
+ <Resource bundle="bundles.producer" key="lang" language="en"/>
+ </code>
+ This makes the english language producer bundle available
+ through the "lang()" function. One
+ can then use expressions like ${lang("page.title")} to
+ refer to a that value.
+ </td>
+ </tr>
<tr><td>key</td> <td>The variable containing the article</td></tr>
+ <tr><td>Name</td> <td bgcolor="#eea8a8"><code>IndexContent</code></td></tr>
+ <tr><td>Purpose</td> <td>adds/updates content to the search index (search engine)</td></tr>
+ <tr><td colspan="2">
+ Arguments</td></tr>
+
+ <tr><td>key</td> <td>The variable containing the article (FIXME????)</td></tr>
+ <tr><td>pathToIndex</td> <td>(FIXME????)</td></tr>
+
+ <tr><td>Name</td> <td bgcolor="#eea8a8"><code>UnIndexContent</code></td></tr>
+ <tr><td>Purpose</td> <td>removes content from the search index (search engine)</td></tr>
+ <tr><td colspan="2">
+ Arguments</td></tr>
+ <tr><td>key</td> <td>The variable containing the article (FIXME????)</td></tr>
+ <tr><td>pathToIndex</td> <td>(FIXME????)</td></tr>
</table>
</section>
<section><title>How the producer framework is implemented</title>
-<para>A Producer is a set of tasks, scripted in xml. Producers allow
-mir installations to have their own actions that can be called for
-instance when a new article is posted. Originally producers were
-mostly used to generate pages, but they are used for a lot of
-other tasks such as pulling rss feeds for the global wire on
-indymedia.org. Producers are added and configured through the
-<filename>producers.xml</filename> file.</para>
+<!-- <para>A Producer is a set of tasks, scripted in xml. Producers allow -->
+<!-- mir installations to have their own actions that can be called for -->
+<!-- instance when a new article is posted. Originally producers were -->
+<!-- mostly used to generate pages, but they are used for a lot of -->
+<!-- other tasks such as pulling rss feeds for the global wire on -->
+<!-- indymedia.org. Producers are added and configured through the -->
+<!-- <filename>producers.xml</filename> file.</para> -->
<para>The xml nodes contained within a <code><producer></code>
a small program.
This program (or script) may contain constructs
such as <code>if</code> clauses, loops and variables... The program is parsed into a
-tree of ProducerNodes (figure). The root of this tree is defined in a
-NodedProducer (which is the only class that currently implements
-the Producer interface). When the Producer is executed, the
-<function>produce</function> methods of each node are recursively called, effectively
+tree of <classname>ProducerNode</classname>s (figure). The root of this tree is defined in a
+<classname>NodedProducer</classname> (which is the only class that currently implements
+the <classname>Producer</classname> interface). When the producer is executed, the
+<function>produce()</function> methods of each node are recursively called, effectively
executing the program as it was scripted. </para>
<figure><title>A producer in the <filename>producer.xml</filename> file is parsed into a tree of <classname>ProducerNodes</classname></title>