Cocoon Documentation
The FP logicsheet is an XSP logicsheet, a TagLib, that performs tasks useful to people wanting to build and handle HTML Forms within Cocoon. Some of the tags are general enough to be used for other purposes as well.
The Tags form a simple XML language that can be mixed with other TagLibs, for writing the typical logic required for modifying XML Files with HTML Forms.
They allow you to work with data (Strings and Nodes) from external XML Files, both reading and writing to them using the XPath Specification to identify your target. There are also tags to choose between HTTP Methods GET and POST, so you could have a page that can both build a Form and handle saving it's data.
Check your cocoon.properties for this line and add it if it's not already there:
processor.xsp.logicsheet.fp.java = resource://org/apache/cocoon/processor/xsp/library/java/fp.xsl
Note the line break is for formatting purposes, it should not appear in your cocoon.properties file.
Map the
http://apache.org/cocoon/XSP/FP/1.0
namespace to the fp prefix. Elements in the fp taglib namespace will be interpreted as input to the fp taglib and will be stripped from the output.
This is typically done like this:
<xsp:page language="java" xmlns:sql="http://apache.org/cocoon/XSP/FP/1.0" xmlns:xsp="http://www.apache.org/1999/XSP/Core" > . . . </xsp:page>
The fp:resource
element with it's mandatory id
attribute, is for defining a file you would like to read and/or write to. It takes a series of configuration elements as children.
The list of valid child elements is:
None of the above tags have any relevance outside of the fp:resource-file
.
You can use as many fp:resource-file
elements as you have unique files to work with, each one should have a unique id
attribute, this is what you use to refer to them. ie. the FP TagLib can work with multiple files at the same time.
Errors are flagged by placing an fp-error
attribute into the parent of the fp:resource-file
tag, with a value that is an IDREF pointing to an fp-error
element in your document root.
The fp:read
element reads TextNodes or Nodes from the specified fp:resource
into it's parent Element using a relative XPath. It has several mandatory attributes.
The list of valid attributes is:
It is safe to use an XPath in your fp:read
element select
attribute that selects multiple Nodes.
If the parent of an fp:read
element is an fp:write
element, the output of the fp:read
element goes to the fp:write
element and is written to file. Otherwise the output goes to the user, like any other TagLib.
The fp:write
element writes TextNodes or Nodes to the specified fp:resource
at the location specified by it's relative XPath. It has several mandatory attributes.
The list of valid attributes is:
It is not safe to use an XPath in your fp:write
element select
attribute that selects multiple Nodes.
Only FP or other TagLib Tags can be used as child elements of the fp:write
element. To do otherwise, causes compilation errors that can be difficult to track down. There may be a solution to this
The fp:write
element may only use a simplified form of XPath in it's select
attribute, one that is just a simple "path/to/node", because the TagLib has to be able to construct any Nodes you ask for and it can only interpret the simplest case. ie. you can use an XPath like this/is/an/xpath/to/nowhere
and the data will be written with all the intervening elements whether they currently exist or not, but an XPath like title/*
will not work. (This is different from fp:read
's behaviour).
The fp:if-post
element allows simple logic, based on the HTTP Method of the incoming request.
Any child elements of the fp:if-post
element are ignored during GET, HEAD, PUT and DELETE requests.
The fp:if-get
element allows simple logic, based on the HTTP Method of the incoming request.
Any child elements of the fp:if-get
element are ignored during POST, HEAD, PUT and DELETE requests.
The fp:redirect
element can be used to redirect the user to another URL when two conditions have been met, that this was a POST Request, and there were no errors generated by any of the other FP Tags.
The value of the fp:redirect
element, is the URL you want users to go to, it should accept relative, root and absolute addressed URLs.
Try the sample. The URL is http://[your server]/[your cocoon path]/samples/fp/index.xml
The sample files
These are bits of annotated code from fp/form/item-add.xml
This is how to set up a file resource that you want to modify.
<fp:resource id="external-item"> <fp:resource-file>../index.xml</fp:resource-file> <fp:resource-node>item[position()=<request:get-parameter name="item"/>]</fp:resource-node> <fp:default-mode>insert-before</fp:default-mode> </fp:resource>
We are nesting an element from the Request TagLib inside an FP element to build an XPath on the fly from the "item" request parameter. Now you can use fp:read
and fp:write
elements to read and/or write to this file, inserting a new "item" Node before the current one, from text in a Form field.
You can have as many fp:resource
elements in your XSP as you need.
The id
attribute of the fp:resource
must be unique, you use it's value in the fp:read
or fp:write
elements to define which file you want.
Here, I want to get the Title of all onf the Items, to build a Menu.
<menu action="item-add.xml?item="> <fp:read select="../item/title" from="external-item" as="node"/> </menu>
The fp:read
element is replaced by the contents of the read.
The from
attribute is the name of the resource you want to read.
The select
attribute is an XPath relative to the Node specified in this resource's "resource-node".
The as
attribute, in this case node
specified that the data should be read and passed on as XML.
Status and Error id's are added as attributes to the parent of the fp:read
tag, in this case the <menu/>
tag.
If there is an error, you get the ID of the error report, placed at the end of the page.
The output looks like this:
<menu fp-action="read" [fp-error="fp-1"] fp-from="external-item" fp-select="../item/title" fp-type="text/xml"> <title>Title 1</title> <title>Title 2</title> <title>Title ...</title> </menu>
Here we make a Form input
Field, so the name is important, but it does not need to relate to the name of the location where the data is to be stored. The parent deos not have to be input
, use whatever you want.
<input name="title"> <xsp:attribute name="label"><fp:read select="title/label" from="default-item"/></xsp:attribute> <fp:if-post> <fp:write to="external-item" select="title"> <request:get-parameter name="title"/> </fp:write> <fp:read select="title" from="external-item"/> </fp:if-post> <fp:if-get> <fp:read select="title/value" from="default-item"/> </fp:if-get> </input>
I create a label
attribute in the input
element, using XSP, but the content comes from reading Text from the defaults file (I would have had to set this file up previously as a fp:resource
). The default value for the as
attribute is "string", so I am leaving it out. I understand Xerces prefers you to write attributes before elements.
Next I write, only if someone is POSTing a Form.
Write the contents of the fp:write
element, in this case the value of the POSTed Form field called "title" (this one), to the title
Node of our selected item
in the external file, as Text.
The fp:write
element does not emit anything into the <input/>
tag, except status Attributes.
After finishing the write, we read the info back out, this is what ends up being the contents of the input
element. I am reading it back out incase I want to display that the user has written etc.
Lastly, only get the default value for the field if someone is GETting a Form.
Copyright © 1999-2000 The Apache Software Foundation.
All rights reserved.