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:fp="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:

fp:resource-file (mandatory) -

The path to a file you want to work with

fp:resource-node (mandatory) -

An XPath to select the Node in your file that you want to work with

fp:default-mode (defaults to replace if not present) -

The default mode you want to use when writing your Nodes, replace replaces the selected Node, insert-before and inser-after create a new Node, with the same name as the selected, and inserts before or after.

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:

from (mandatory) -

The id of the fp:resource you want to read

select (mandatory) -

An XPath (relative to fp:resource-node) to select the Node(s) in the fp:resource you want to read

as (defaults to string) -

The way you want to read the Node(s) selected by your XPath. The default, string reads all of the TextNodes that are children of the selected Node(s); node reads all of the selected Nodes as deep cloned XML.

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:

to (mandatory) -

The id of the fp:resource you want to write

select (mandatory) -

An XPath (relative to fp:resource-node) to select the Node in the fp:resource you want to write

as (defaults to string) -

The way you want to write the Node selected by your XPath. The default, string overwrites all of the TextNodes that are children of the selected Node with the text content of the fp:write element; node replaces the selected Node with the content of the fp:write element as XML.

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

form/default.xml -

Default values used by the Forms

form/form-html.xsl -

Renders the Form to HTML

form/form-xml.xsl -

Renders the Form to XML (for debugging purposes)

form/item-add.xml -

Builds and saves a Form to add new Items in index.xml

form/item-edit.xml -

Builds and saves a Form to edit existing Items in index.xml

images -

Folder of images

index.xml -

The content XML file

page-html.xsl -

Renders the normal view of the project

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.