Many of these concepts will be further detailed later on in this guide.
</para>
<glossentry id="producers">
- <glossterm>producer</glossterm>
+ <glossterm>producers</glossterm>
<glossdef>
<para>As mentioned in the architecture overview, mir
generates a set of static html pages called the static site.
used by various indymedia sites to customize things
such open posting mechanisms, open
posting validation, data model enhancements, etc.
+In other words, the localizer framework provides "hooks"
+where admins can plug in
+their custom code.
</para>
<para>
The <classname>MirLocalizer</classname> interface describes
and it's associated classes. These classes can be extended to
override default behavior.
</para>
+<para>
+To override default behavior you must implement a new
+<classname>MirLocalizer</classname>
+and give the path to your class in the
+<code>Mir.Localizer</code> property of the
+<filename>config.properties</filename>
+file.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="abuse">
+ <glossterm>abuse filter framework</glossterm>
+ <glossdef>
+ <para>
+Mir can be configured to refuse postings or spam. This is done
+by using a set of filters that will attempt to match posted content.
+If any filter matches, appropriate action (FIXME? what action? ) will be taken.
+Three types of filters are currently implemented: IP filters
+(reject certain ip adresses), regular expression filters
+(try to match parts (FIXME? ip? title? content?) of the posting) and
+throttle filters (avoid repeated postings (FIXME? is this ok?)).
+ </para>
+<para>
+Filters may be organized into groups for easier management.
+</para>
</glossdef>
</glossentry>
</glossdef>
</glossentry>
+
<glossentry id="mircoders">
<glossterm>mircoders packages</glossterm>
<glossdef>
<para>
Originally, the mircoders packages were meant for local developments,
-as opposed to the core Mir code. This distinction is now obsolete
+as opposed to core Mir code. This distinction is now obsolete
and these packages will probably be reorganized in future releases.
</para>
</glossdef>
<glossterm>bundles</glossterm>
<glossdef>
<para>
-bundles are key/value pairs in a text file, used for configuration
-and internationalization
+Bundles are key/value pairs in a text file, used for configuration
+and internationalization.
+Bundles may be used to create a template for multiple languages. The
+language dependent aspects are stored in a properties file.
</para>
</glossdef>
</glossentry>
+<glossentry id="search">
+ <glossterm>search framework</glossterm>
+ <glossdef>
+ <para>
+Mir's search framework relies on
+<ulink url="http://lucene.apache.org/java/docs/index.html">apache lucene
+</ulink>.
+Content is inserted into a special index file while it is produced
+(see <glossterm linkend="producers">producers</glossterm> framework).
+This allows for quick retreival during search.
+Indexing is requested in the <filename>producers.xml</filename> file
+by the <code><IndexContent></code> node.
+In other words, when Mir generates a static html page for an article,
+it also creates <classname>SearchTerm</classname>'s and inserts
+them into the index.
+By default, the index file is stored in <filename>FIXME</filename>.
+</para>
+<para>
+Search queries are managed by <function>ServletModuleContent.search()</function>
+</para>
+
+ </glossdef>
+</glossentry>
+
+<glossentry id="servlet">
+ <glossterm>servlet framework</glossterm>
+ <glossdef>
+ <para>
+Mir uses the tomcat servlet framework for the admin interface,
+for open posting and for search queries (FIXME something else?).
+Mir exposes two servlets: the <classname>Mir</classname>
+servlet and the <classname>OpenMir</classname> servlet, whose
+methods are directly called in response to an http request.
+For example, a request for <uri>http://somehost.org/mir/servlet/Mir</uri>
+will call the <function>doGet()</function> method of the
+<classname>Mir</classname> class.
+ </para>
+ <para>
+Once requests are received by the
+<classname>Mir</classname> or <classname>OpenMir</classname>
+classes, they are dispatched to other servlet classes.
+The <code>module</code> argument of the http request
+determines the classes name.
+The <code>do</code> argument determines the method's name.
+So
+<uri>http://somehost.org/mir/servlet/Mir?module=Comment&do=list</uri>
+will call <function>ServletModuleComment.list()</function>.
+
+
+ </para>
+ </glossdef>
+</glossentry>
+
+
+<glossentry id="media">
+ <glossterm>media framework</glossterm>
+ <glossdef>
+ <para>
+The media framework is quite old and will be thoroughly changed
+in a future release.
+</para>
+ </glossdef>
+</glossentry>
+
+
</section>
<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>
projects / mir.git / commitdiff