X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fdevelopers-guide%2Fproducers.xml;fp=doc%2Fdevelopers-guide%2Fproducers.xml;h=61d5ecdef96b06885a8825c870c6aaf6d87787c8;hb=c9ac8fa71b679f8d967aac901bbef945c13b94c9;hp=0000000000000000000000000000000000000000;hpb=d63595f89aaa4b6a524dc0b4af9e0eef888f4c6b;p=mir.git diff --git a/doc/developers-guide/producers.xml b/doc/developers-guide/producers.xml new file mode 100755 index 00000000..61d5ecde --- /dev/null +++ b/doc/developers-guide/producers.xml @@ -0,0 +1,509 @@ + +The producer framework +Please read the presentation of the producers concept +for an introduction. + +
How to use the <filename>producers.xml</filename> file + [FIXME: this should be in the admin's guide, not here] + + +Please check the standard producers.xml file +for two fully commented, real-world examples : +the <nodedefinition name="Language"> node +and the <producer name="articles"> node. + + +
Introduction + + + Mir allows admins to fully configure the producer tasks and set up + arbitrary producers through the producers.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"/> + + This 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"/> + + + This 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: + + + + + Expressions + + + + + + + + + +
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: + + + + Reference for producer node types and statements + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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.
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 GenerateMedia
Purpose +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 +
+ + Arguments
key FIXME???
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. In other words, this defines a function that can be used in expressions to reference a bundle.
+ + Arguments
key The name of the function.
bundle The bundle to use
language (optional) The specific language to use
Example + + <Resource bundle="bundles.producer" key="lang" language="en"/> + + 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. +
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
Name IndexContent
Purpose adds/updates content to the search index (search engine)
+ Arguments
key The variable containing the article (FIXME????)
pathToIndex (FIXME????)
Name UnIndexContent
Purpose removes content from the search index (search engine)
+ Arguments
key The variable containing the article (FIXME????)
pathToIndex (FIXME????)
+
+
+ +
How the producer framework is implemented + + + + + + + + + + +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> + + + + + + + + +
+ + + +
+