From: grok Date: Fri, 12 Aug 2005 09:19:35 +0000 (+0000) Subject: working on doc X-Git-Tag: LATEST_MERGED_1_1~120 X-Git-Url: http://erislabs.net/gitweb/?p=mir.git;a=commitdiff_plain;h=da9904ba5215aa6f6142b04a799bd4aaa43631b7 working on doc --- diff --git a/doc/developers-guide/developers-guide.xml b/doc/developers-guide/developers-guide.xml index cabc2c76..d3a2f1c1 100755 --- a/doc/developers-guide/developers-guide.xml +++ b/doc/developers-guide/developers-guide.xml @@ -8,7 +8,7 @@ ] > - Mir CMS 1.1, developpers guide + Mir CMS 1.1: developer's guide @@ -37,10 +37,11 @@ - This document is meant for helping mir developpers. It is assumed that - you have allready installed mir and have some basic knowledge + This document is meant for helping mir developers (people that + write java code within Mir). It is assumed that + you have already installed mir and have some basic knowledge on how to use it. However, reading the introduction chapter might - also be worthwhile for sysadmins and template designers. + also be worthwhile for sysadmins, webmasters and template designers. diff --git a/doc/developers-guide/introduction.xml b/doc/developers-guide/introduction.xml index 8b0b2532..e83daa80 100755 --- a/doc/developers-guide/introduction.xml +++ b/doc/developers-guide/introduction.xml @@ -16,9 +16,9 @@ the dynamic site (see figure).
mir architecture (single host) - + - + @@ -35,9 +35,9 @@ site. Mirrors are simple to set up, since only static pages are involved
mir architecture (mirrored) - + - + @@ -47,7 +47,7 @@ site. Mirrors are simple to set up, since only static pages are involved
Concepts used by Mir Here's a list of important terms and concepts used by Mir. -Many of these concepts will be further detailed latter on in this guide. +Many of these concepts will be further detailed later on in this guide. producer @@ -61,11 +61,11 @@ In many CMS systems, the available variables (data) are hard-coded into the software. In practice, this is often not flexible enough for web designers. Mir allows designers to request the data they need by using -the producer framework, configured in the "producers.xml" file. +the producer framework, configured in the producers.xml file. Originally producers were mostly used to generate pages, but they are now used for a lot of -other tasks. In fact, the producers.xml file provides a +other tasks. In fact, the producers.xml file provides a simple, xml-based, programing (scripting) language, so that site administrators can script their own custom tasks without changing the java code. @@ -75,13 +75,15 @@ feeds for the global wire.
An example of article generation with the producers framework - + - +
+In the admin web interface, producers appear, for example, on +the admin->"Generate manually"->"advanced page": (they are called Tasks) Further information on producers may be found at XXX and in the javadoc (classes Producer, NodedProducer, roducerNode...). @@ -90,14 +92,14 @@ Further information on producers may be found at XXX and in the javadoc - database + database access Mir uses a postgres database to store it's data. -Currently, the mir.storage, mircoders.storage, mir.entity, and -mir.entity.adapter +Currently, the mir.storage, mircoders.storage, +mir.entity, and mir.entity.adapter packages -are used to acces the database in Mir. However, these packages +are used to access the database in Mir. However, these packages are obsolete and will be replaced by the hibernate object/relational persistence system. @@ -110,10 +112,26 @@ object/relational persistence system. localizer -FIXME localizers are to allow mir installations to add code seperate from the -main code. A lot of things can be changed in an installation (and are -by various mir sites). Think of custom open posting mechanism, open -posting validation, data model enhancements. +Localizers provide a customization framework that allows +different mir sites to behave differently. Each site can +write it's own bits of java code that override default behavior. +This is effectively +used by various indymedia sites to customize things +such open posting mechanisms, open +posting validation, data model enhancements, etc. + + +The MirLocalizer interface describes +the centralized localizer, that may be accessed via the global +MirGlobal.localizer() +function. The central localizer provides accessors to +domain specific localizers +(like MirBasicOpenPostingLocalizer). + + +Default behavior is provided by the MirBasicLocalizer +and it's associated classes. These classes can be extended to +override default behavior. @@ -137,10 +155,10 @@ sites) and velocity (not used at all but supported anyway). logger -Logging is understood here as "sytem logs" : information written +Logging is understood here as "system logs" : information written out to files that may be used to track what is going on in Mir, -especially errors and warnings. Mir uses the log4j logging system. -This alows us to split logs into different files, making them +especially errors and warnings. Mir uses the log4j logging system. +This allows us to split logs into different files, making them easier to understand. @@ -150,7 +168,7 @@ easier to understand. mircoders packages -Originally, the mircoders packages were meant for local developpements, +Originally, the mircoders packages were meant for local developments, as opposed to the core Mir code. This distinction is now obsolete and these packages will probably be reorganized in future releases. diff --git a/doc/developers-guide/producers.xml b/doc/developers-guide/producers.xml index 3a49c864..fef45910 100755 --- a/doc/developers-guide/producers.xml +++ b/doc/developers-guide/producers.xml @@ -1,9 +1,458 @@ -Producers framework +The producer framework + +
How to use the <filename>producers.xml</filename> file + [FIXME: this should be in the user's guide, not here] + +
Introduction + + + With Mir, it is now possible to set up arbitrary producers using an xml file. + + + + Producers consist of "nodes". Every node has a specific function. + For example, it is possible to use a node to generate a file out of a template. + Or it is possible to use a node to enumerate over a collection of articles. + + + + + + A producer is defined using a Producer tag: + + + <producer name="content"/> + + + would define a producer named content. + + + + In a producer, verbs must be defined. + Verbs are sub-tasks of a producer. + + + + <producer name="content"> + <verbs> + <verb name="new"> + </verb> + <verb name="all"> + <verb> + </verbs> + <producer name="content"/> + + + would define a producer with verbs named all and new. + + + And also the specific nodes and their relationship should be specified: + + + + <producer name="content"> + <verbs> + <verb name="new"> + </verb> + <verb name="all"> + <verb> + </verbs> + <body> + <Generate + generator="/producer/startpage.template" + destination="${config.storageRoot}/index.shtml"/> + </body> + </producer> + + + we will later learn that this producer generates a single file. + + + Producers can be made to do different things for different verbs: + + + + <producer name="content"> + <verbs> + <verb name="new"> + <Set key="count" value="3"/> + </verb> + <verb name="all"> + <Set key="count" value="5"/> + <verb> + </verbs> + <body> + <Generate + generator="/producer/startpage.template" + destination="${config.storageRoot}/index.shtml"/> + </body> + </producer> + + + if a producer is called with a specific verb, first the nodes of that verb + are processed, and only thereafter the body: in our case, if the producer + content is called with verb new, first the variable count + + is set to 3, and after that, a file is generated. + + +
+
Node arguments + + Nodes can have arguments. + Arguments that amount to integer values can be direct expressions. + Arguments that amount to text values can be enriched with expressions between ${}. + + + + Some examples: + + <Log message="This article has the following title: ${content.title}"/> + + + Log has 1 mandatory argument, message. This argument should be text, + but can be enriched with expressions enclosed by ${ and }. In this example, + the title of an article is logged. + + + <Set key="age" value="34+22*(3+2)"/> + + Set has 2 mandatory argument: key and value. + The key arugment is a fixed text, + the value argument is a direct expression, in this case of arithmetic nature. + + + +
+
Expressions + + + + Expressions, either direct expressions, or expressions between ${}, can contain the following + constructions: + + + + + + + + + + + + +
a string literal 'hello'
a numeric literal 2138
a variable reference content.title
arithmetic operators 3 + 4 *(2+5-2)
string operators 'hello' ++ ' ' ++ 'Mir'
boolean operators (content.id==3) or (content.id in (5,7,2,8) and (content.title!='hello')
+ + +
+
Node types and statements + + Here's a list of different node types that can be used inside + producer definitions. +Currently, there exists only one statement (<nodedefinition>), that +is declared outside producer definitions. + + + Here an overview: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name Set
Purpose Alter a variable's using a free expression
+ Arguments
key The variable
value The expression to set the variable to
Example + + <Set key="data.result" value="3 + 5 * (5-2)"/> + + +
Name Define
Purpose Alter a variable's using a string
+ + Arguments
key The variable
value The string to set the variable to
Example + + <Define key="filename" value="/var/www/${content.id}.shtml"/> + +
Name If
Purpose Create a conditional part of a producer
+ Arguments
condition The expression to test
+ Sub tags
then The part to process if the expression evaluates to true
else The part to process if the expression evaluates to false
Name nodedefinition  (statement)
Purpose Acts as a "function" (or "macro") that can be "called" elsewhere in a producer. +More precisely, it is a way to define a new producer node type +inside the producers.xml file. +(check the Language node in that file for an example). +
+ Arguments
name The name of the newly created node ("function")
+ Sub tags
parameters a list describing the arguments the "function" must be given
definition the actual body of the function, containing the code that should be executed. Note that this may contain a <sub/> tag that is replaced by the child nodes of the calling node (FIXME is this true???)
Name Log
Purpose Log a message in the producer log
+ Arguments
message The message to log
Name Enumerate
Purpose Enumerate over the results of a query
+ Arguments
key The variable name that receives the enumerated record
table The table that is used to enumerate over
selection (optional) The condition (where clause) of the query.
order (optional) The order in which the results of the query are enumerated.
skip (optional) The number of records to skip
limit (optional) The maximum number of records to enumerate
+ Sub tags
+ This node can have subnodes that will be processed for every enumerated record
Name List
Purpose Store the results of a query into a variable
+ Arguments
key The variable name that receives the result list
table The table that is used to select from
selection (optional) The condition (where clause) of the query.
order (optional) The order in which the results of the query are put into the list.
skip (optional) The number of records to skip
limit (optional) The maximum size of the list
Name Batch
Purpose Divide the results of a query into batches
+ Arguments
key The variable name that receives the batch
infokey The variable name that receives meta information on the batches
table The table that is used to select from
batchsize The size of a batch (the first batch however varies in size)
selection (optional) The condition (where clause) of the query.
order (optional) The order in which the results of the query are put into the list.
skip (optional) The number of records to skip
process (optional) The maximum number of batches to process
minbatchsize (optional) The minimal size of the first batch
+ Sub tags
batches The part to process for every batch
batchlist The part to process once with the meta info
Name Generate
Purpose Generate a page using a generator (i.e. an abstraction of a template)
+ + Arguments
generator the generator to use
destination the specification of the destination.
parameters Additional configuration info for the generator (for + freemarker this now only contains the wanted encoding, + empty for the default).
Remarks + This node is used to have an actual page generated. + The generator parameter usually is the name of a template. + The destination is the file to be generated. + Variable references are possible in all arguments, and, especially for the + destination attribute, widely used. +
Example + + <Generate generator="/producer/content.template" destination="/var/www/${content.date.formatted.yyyy}/${content.date.formatted.MM}/${content.id}.shtml"/> + +
Name DeleteFile
Purpose Delete a file
+ Arguments
filename The filename of the file to delete
Name SetFileDate
Purpose Set a file's date
+ Arguments
filename The filename
date The date to use
Name Resource
Purpose Make a message resource bundle available
+ + Arguments
key The variable in which the bundle will be stored
bundle The bundle to use
language (optional) The specific language to use
Name Execute
Purpose Execute a script
+ Arguments
command The command to execute
Name ModifyContent
Purpose Modify a field of an article
+ + Arguments
key The variable containing the article
field The field to modify
value The value to set the field to
Name MarkContent
Purpose Mark an article as produced
+ Arguments
key The variable containing the article
+
+
+ +
How the producer framework is implemented + +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 +producers.xml file. + + +The xml nodes contained within a <producer> +tag in the producers.xml file define +a small program. +This program (or script) may contain constructs +such as if 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 +produce methods of each node are recursively called, effectively +executing the program as it was scripted. + +
A producer in the <filename>producer.xml</filename> file is parsed into a tree of <classname>ProducerNodes</classname> + + + + + + + + +
-
qsdqs -sdfqsdf