org.ceryle.wiki.plugin.form
Class FormPlugin

java.lang.Object
  com.ecyrd.jspwiki.forms.FormElement
      org.ceryle.wiki.plugin.form.FormPlugin

All Implemented Interfaces:

WikiPlugin, PluginConstants

Direct Known Subclasses:

AssertionFormPlugin, BibRefPlugin, Form, WikiChatPlugin

public abstract class FormPlugin
extends FormElement
implements WikiPlugin, PluginConstants

FormPlugin extends FormElement (in the same manner as FormOpen, except that is its own FormHandler) to respond to edits to an ongoing wiki-based form, using a single plugin. It provides only fill-in single-line fields and textareas. It is designed to be subclassed to provide a form templating facility.

Parameters

• debug = 'true' | 'false'. When "true" the plugin displays the form plus is incoming and processed parameters. The default is false. (For extreme debugging (shazam!) try verbose='true'.)
• prefix = 'prefix' If absent, all parameters not defined by the plugin itself will be used as the names of form fields. If the prefix parameter is available, its value acts as a filter. E.g., if the prefix is set to "DC.", only those parameters beginning with "DC." (such as "DC.title", "DC.creator" and "DC.subject") will be used to create form fields. If the prefix does not end in a period ('.') one will be automatically appended to it as a delimiter. Multiple prefixes can be used, separated by spaces and/or commas (e.g., prefix='DC,DCTERMS').
• cap = 'true' | 'false'. If true, displayed form field labels will be capitalized.
• about = 'pagename' This is the value used for the subject of the form (e.g., metadata). The basic form doesn't have any meaning associated with this parameter; it is likely to be used in subclasses of the FormPlugin. As an optional parameter, it will default to the current page name if absent.
• form = 'formname' This is the value used for the form identifier of the generated XHTML. This is an optional parameter, but should be specified if you care about the form identifier. Though not currently supported, multiple forms per page will automatically receive unique IDs that won't carry over properly between edit sessions, so they must each have explicit form names.
• style = 'value'. This parameter is used internally by the plugin to store style information for display of the form.
• edit = 'buttonname'. This optional parameter will rename the Edit button.
• save = 'buttonname'. This optional parameter will rename the Save button.
• cancel = 'buttonname'. This optional parameter will rename the Cancel button.

Field Removal

If a user enters #REMOVE (REMOVE_TAG) into any field and saves the form, that field will be permanently removed from the form. It can of course be manually re-entered in the wiki text parameters for the form. There is no #ADD facility.

Page Locks

Currently, the plugin will actually fail to create edit session if unable to obtain a page lock. This may be extreme, given that normally the wiki permits over-edits, but given this is a form interface it is more likely to lose content in the event of a failure. Maybe not? This is something to check out in practice...

Sorting

If a prefix is defined, it's possible to order the resulting form by adding a sortable value (generally a digit) following the prefix and another period. For example:

   [{Form form='testForm' prefix='DC.' debug='true'
     DC.title.1='The Alexandria Quartet'
     DC.creator.2='Durrell, Alexander'
     DC.identifier.3='0 571 05204 5'
     DC.type.4='Text'
  }]
  

Potential Security Issues

If there comes a point in its development where the form is used to assert page variables, we should consider making sure that no variables can be used to alter page permissions, otherwise it might be possible to alter the permissions of a target page via the AssertionFormPlugin.

Extending

The plugin operates according under one of a number of modes. Upon each display it actually is called twice, once to set itself up and a second time to actually display the form content (both in MODE_INIT). When the Edit button is activated it goes into MODE_EDIT; if cancelled, MODE_CANCEL; if saved, MODE_SAVE.

Extending the FormPlugin requires paying attention to these modes. There are two primary methods likely to be subclassed:

• writeFormOutput(WikiContext,List,StringBuffer) writes the HTML form content to the output buffer.
• writePageText(WikiContext,Map,String,String) writes the modified wiki text back to the WikiPageProvider's repository.

But rather than muck directly with them, there are also four stub (empty) methods that occur at important processing points:

• preSave(WikiContext,List) is called prior to writePageText() only in MODE_SAVE (just prior to saving a form, i.e., submitting via the Save button).
• postSave(WikiContext,List) is called after writePageText() only in MODE_SAVE (just after saving a form, i.e., submitting via the Save button).
• preWrite(WikiContext,List,StringBuffer) is called prior to writeFormOutput() only in mode MODE_VIEW (i.e., normal, non-edit display of the form).
• postWrite(WikiContext,List,StringBuffer) is called after writeFormOutput() only in mode MODE_VIEW (i.e., normal, non-edit display of the form).

Author:

Murray Altheim

Field Summary

protected static String	CANCEL_BUTTON_NAME
protected static String	cancelButtonLabel
protected static String	editButtonLabel
protected static org.apache.log4j.Logger	log
protected boolean	m_capitalize
protected boolean	m_checkAboutPage
protected boolean	m_checkPermissions
protected boolean	m_debug
protected WikiEngine	m_engine
protected String	m_formname
protected String	m_id
protected static HashSet	m_ignore
protected int	m_mode
protected String	m_pluginName This is the common plugin invocation name, and should match a wiki page name for documentation.
protected String	m_prefix
protected String[]	m_prefixes
protected boolean	m_prototype
protected String	m_style
protected String	m_submitServlet
protected boolean	m_useSelect
protected boolean	m_verbose
static int	MAX_FIELD_LENGTH The maximum field content length before the form will use a textarea rather than an input field.
static int	MODE_CANCEL Constant indicating Cancel button activated mode.
static int	MODE_EDIT Constant indicating Edit mode.
static int	MODE_INIT Constant indicating initial mode.
static int	MODE_SAVE Constant indicating Save button activated mode.
static int	MODE_SELECT Constant indicating Select button activated mode.
static int	MODE_VIEW Constant indicating form view mode.
static String	PARAM_ABOUT The about parameter name.
static String	PARAM_CAPITALIZE The cap parameter name.
static String	PARAM_LABEL_CANCEL The cancel parameter name.
static String	PARAM_LABEL_EDIT The edit parameter name.
static String	PARAM_LABEL_SAVE The save parameter name.
static String	PARAM_PREFIX The prefix parameter name.
static String	PARAM_STYLE The style parameter name.
static String	PARAM_TEST The test parameter name.
static String	PARAM_VERBOSE The verbose parameter name.
static String	REMOVE_TAG If a user saves a form with the tag "#REMOVE" in a field causes that field to be removed from the form.
protected static String	saveButtonLabel
protected static String	SELECT_BUTTON_NAME
protected static String	selectButtonLabel
protected static String	SIZEMAP_PREFIX
protected static String	SUBMIT_BUTTON_NAME
protected static String	unknownUser

Fields inherited from class com.ecyrd.jspwiki.forms.FormElement

FORM_VALUES_CARRIER, HANDLERPARAM_PREFIX, HIDE_SUCCESS, PARAM_ELEMENT, PARAM_FORM, PARAM_FORMNAMEHIDDEN, PARAM_HANDLER, PARAM_HIDEFORM, PARAM_INPUTNAME, PARAM_POPULATE, PARAM_SUBMITHANDLER, PARAM_VALUE

Fields inherited from interface com.ecyrd.jspwiki.plugin.WikiPlugin

CORE_PLUGINS_RESOURCEBUNDLE

Fields inherited from interface org.ceryle.wiki.plugin.util.PluginConstants

ACL, AOP, APOS_ENT, ASTERISK, BCL, BOP, BR, CAPCL, CAPOP, CLATT, COLON, COMMA, DIV_class, DIV_style, DIVCL, DOT, EQ, EQQUO, EQSQUO, FALSE, FORMCL, FORMOP, GET, ICL, INPUTOP, IOP, LABELCL, LABELFOR, LABELOP, LCURL, LICL, LIOP, LPAR, LSBR, MT, NBSP, NL, OLCL, OLOP, P_class, PCL, PLUGCL, PLUGO, POP, POST, QUO, QUOCL, QUOETCL, RCURL, RPAR, RSBR, SEMI, SP, SPAN_class, SPANCL, SPANOP, SQUO, TABLECL, TABLEOP, TDCL, TDOP, THCL, THOP, TRCL, TROP, TRUE, TTCL, TTOP, ULCL, ULOP, UNDER

Constructor Summary

FormPlugin()
Default constructor.

Method Summary

protected String	checkAuthorization(WikiContext context) Check user authorization.
protected List	createFormControls(Map params) Provided the Map of parameters, convert suitable ones into FormControls.
protected void	error(WikiContext context, StringBuffer out, Exception e) Process an error by clearing the existing buffer and populating it with an error message.
String	execute(WikiContext context, Map params) Execute the plugin, obtaining the '_cmdline' parameter, processing accordingly, returning XHTML-compatible markup.
String	getAbout() Return the value of the about parameter, null if undefined.
protected static Set	getIgnoreParams()
int	getMode() Return the current plugin mode.
String	getModeName() Return the name of the current mode.
protected Object	getSizeFor(String name) Return the field size for input field name, either as a String or a two-element int[] array.
protected Map	getSizeMap() Return the field size map.
protected String	getStyleParameter(List list) Processes the FormControl list to provide a style string.
protected PageLock	lockPage(WikiPage page, String username, StringBuffer out) Lock the WikiPage for the provided username.
abstract void	postSave(WikiContext context, List controls) A stub method called just after saving the plugin text back to the page provider in mode MODE_SAVE.
abstract void	postWrite(WikiContext context, List controls, StringBuffer out) A stub method called just after the form output has been generated to the output buffer in mode MODE_VIEW.
abstract void	preSave(WikiContext context, List controls) A stub method called just prior to saving the plugin text back to the page provider in mode MODE_SAVE.
abstract void	preWrite(WikiContext context, List controls, StringBuffer out) A stub method called just prior to the form output being generated to the output buffer in mode MODE_VIEW.
protected void	printTest(Map map, StringBuffer out, String title, String color) Print out the name-value pairs of the Map map to the StringBuffer, using the title and color spec.
protected void	setSizeFor(String name, Object value) Permits subclasses to set the field size for form control name to the provided value, which must be either an int as a String or a two-element int[] array, { rows, cols }.
protected void	transferSubmission(FormInfo info) Move parameters from submission map to sizemap.
protected boolean	unlockPage(WikiPage page, String username, StringBuffer out) Unlock the WikiPage page if there is a match on the username.
protected void	writeFormOutput(WikiContext context, List controls, StringBuffer out) Writes the form output provided by the List of FormControls to the StringBuffer out.
protected String	writePageText(WikiContext context, Map params, String pagename, String username) Write the changed page text to the Wiki's page provider.

Methods inherited from class com.ecyrd.jspwiki.forms.FormElement

getFormInfo, storeFormInfo

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static org.apache.log4j.Logger log

REMOVE_TAG

public static String REMOVE_TAG

If a user saves a form with the tag "#REMOVE" in a field causes that field to be removed from the form.

m_pluginName

protected String m_pluginName

This is the common plugin invocation name, and should match a wiki page name for documentation. This must be set by the in the constructor for all subclasses.

MODE_INIT

public static final int MODE_INIT

Constant indicating initial mode.

See Also:

Constant Field Values

MODE_VIEW

public static final int MODE_VIEW

Constant indicating form view mode.

See Also:

Constant Field Values

MODE_CANCEL

public static final int MODE_CANCEL

Constant indicating Cancel button activated mode.

See Also:

Constant Field Values

MODE_EDIT

public static final int MODE_EDIT

Constant indicating Edit mode.

See Also:

Constant Field Values

MODE_SELECT

public static final int MODE_SELECT

Constant indicating Select button activated mode. Currently unused.

See Also:

Constant Field Values

MODE_SAVE

public static final int MODE_SAVE

Constant indicating Save button activated mode.

See Also:

Constant Field Values

PARAM_ABOUT

public static final String PARAM_ABOUT

The about parameter name.

See Also:

Constant Field Values

PARAM_CAPITALIZE

public static final String PARAM_CAPITALIZE

The cap parameter name.

See Also:

Constant Field Values

PARAM_PREFIX

public static final String PARAM_PREFIX

The prefix parameter name.

See Also:

Constant Field Values

PARAM_VERBOSE

public static final String PARAM_VERBOSE

The verbose parameter name.

See Also:

Constant Field Values

PARAM_STYLE

public static final String PARAM_STYLE

The style parameter name.

See Also:

Constant Field Values

PARAM_LABEL_EDIT

public static final String PARAM_LABEL_EDIT

The edit parameter name.

See Also:

Constant Field Values

PARAM_LABEL_SAVE

public static final String PARAM_LABEL_SAVE

The save parameter name.

See Also:

Constant Field Values

PARAM_LABEL_CANCEL

public static final String PARAM_LABEL_CANCEL

The cancel parameter name.

See Also:

Constant Field Values

PARAM_TEST

public static final String PARAM_TEST

The test parameter name. TEMP

See Also:

Constant Field Values

MAX_FIELD_LENGTH

public static int MAX_FIELD_LENGTH

The maximum field content length before the form will use a textarea rather than an input field. The default value is 60 characters.

SUBMIT_BUTTON_NAME

protected static final String SUBMIT_BUTTON_NAME

See Also:

Constant Field Values

CANCEL_BUTTON_NAME

protected static final String CANCEL_BUTTON_NAME

See Also:

Constant Field Values

SELECT_BUTTON_NAME

protected static final String SELECT_BUTTON_NAME

See Also:

Constant Field Values

SIZEMAP_PREFIX

protected static final String SIZEMAP_PREFIX

See Also:

Constant Field Values

saveButtonLabel

protected static String saveButtonLabel

editButtonLabel

protected static String editButtonLabel

selectButtonLabel

protected static String selectButtonLabel

cancelButtonLabel

protected static String cancelButtonLabel

unknownUser

protected static String unknownUser

m_formname

protected String m_formname

m_prefix

protected String m_prefix

m_style

protected String m_style

m_capitalize

protected boolean m_capitalize

m_debug

protected boolean m_debug

m_verbose

protected boolean m_verbose

m_prototype

protected boolean m_prototype

m_mode

protected int m_mode

m_useSelect

protected boolean m_useSelect

m_submitServlet

protected String m_submitServlet

m_prefixes

protected String[] m_prefixes

m_id

protected final String m_id

m_checkPermissions

protected boolean m_checkPermissions

m_checkAboutPage

protected boolean m_checkAboutPage

m_ignore

protected static HashSet m_ignore

m_engine

protected WikiEngine m_engine

Constructor Detail

FormPlugin

public FormPlugin()

Default constructor.

Method Detail

execute

public String execute(WikiContext context,
                      Map params)

Execute the plugin, obtaining the '_cmdline' parameter, processing accordingly, returning XHTML-compatible markup.

Specified by:

execute in interface WikiPlugin

Parameters:

context -

params -

Returns:

the generated output to be displayed on the wiki page.

See Also:

WikiPlugin.execute(com.ecyrd.jspwiki.WikiContext,java.util.Map)

transferSubmission

protected void transferSubmission(FormInfo info)

Move parameters from submission map to sizemap.

checkAuthorization

protected String checkAuthorization(WikiContext context)

Check user authorization. If this returns anything but null it is an error message to be returned to the users signalling a lack of authorization. If m_checkPermissions is false this always returns null.

createFormControls

protected List createFormControls(Map params)

Provided the Map of parameters, convert suitable ones into FormControls.

getAbout

public String getAbout()

Return the value of the about parameter, null if undefined.

Returns:

the value of the about parameter.

preSave

public abstract void preSave(WikiContext context,
                             List controls)

A stub method called just prior to saving the plugin text back to the page provider in mode MODE_SAVE.

Parameters:

context - the WikiContext of the form session

controls - the List of FormControls

postSave

public abstract void postSave(WikiContext context,
                              List controls)

A stub method called just after saving the plugin text back to the page provider in mode MODE_SAVE.

Parameters:

context - the WikiContext of the form session

controls - the List of FormControls

preWrite

public abstract void preWrite(WikiContext context,
                              List controls,
                              StringBuffer out)

A stub method called just prior to the form output being generated to the output buffer in mode MODE_VIEW.

Parameters:

context - the WikiContext of the form session

controls - the List of FormControls

out - the output buffer

postWrite

public abstract void postWrite(WikiContext context,
                               List controls,
                               StringBuffer out)

A stub method called just after the form output has been generated to the output buffer in mode MODE_VIEW.

Parameters:

context - the WikiContext of the form session

controls - the List of FormControls

out - the output buffer

writeFormOutput

protected void writeFormOutput(WikiContext context,
                               List controls,
                               StringBuffer out)

Writes the form output provided by the List of FormControls to the StringBuffer out. This is dependent upon the plugin mode. This should write something intelligent even if the List is empty.

Parameters:

context - the WikiContext of the form session

controls - the List of FormControls

out - the output buffer

writePageText

protected String writePageText(WikiContext context,
                               Map params,
                               String pagename,
                               String username)
                        throws WikiException

Write the changed page text to the Wiki's page provider. The parameter Map will be copied into a new Map and is not itself modified. Note that the pagename parameter is the page that the form is about, not the page that the plugin lives on and is written to, which is always derived from the WikiContext.

Parameters:

context - the WikiContext of the form session

params - the parameters supplied to the plugin

pagename - the name of the wiki page

username - the name of the user

Throws:

WikiException - if an error occurs writing to the repository

lockPage

protected PageLock lockPage(WikiPage page,
                            String username,
                            StringBuffer out)
                     throws PluginException

Lock the WikiPage for the provided username.

Parameters:

page - the WikiPage to lock.

username - the username to use in creating the lock.

out - the StringBuffer for messages (used only in verbose mode)

Throws:

PluginException - if unable to create a lock (too harsh?)

unlockPage

protected boolean unlockPage(WikiPage page,
                             String username,
                             StringBuffer out)

Unlock the WikiPage page if there is a match on the username.

Parameters:

page - the WikiPage to unlock.

username - the username to match in unlocking the page.

out - the StringBuffer for messages (used only in verbose mode)

getStyleParameter

protected String getStyleParameter(List list)

Processes the FormControl list to provide a style string. If there is no styling information available, returns null.

The format is reminiscent of CSS:

 fieldname:size ; fieldname:size ; fieldname:size ; 

where 'size' can either be a single integer or an integer pair, the latter used for a textarea's row and column specification.

Parameters:

list - the list of FormControls

setSizeFor

protected void setSizeFor(String name,
                          Object value)

Permits subclasses to set the field size for form control name to the provided value, which must be either an int as a String or a two-element int[] array, { rows, cols }.

Parameters:

name - the name of the field/form control

value - the value associated with the form control

getSizeMap

protected Map getSizeMap()

Return the field size map.

getSizeFor

protected Object getSizeFor(String name)

Return the field size for input field name, either as a String or a two-element int[] array. If undefined, the default is returned.

error

protected void error(WikiContext context,
                     StringBuffer out,
                     Exception e)

Process an error by clearing the existing buffer and populating it with an error message. The WikiContext is optional; if provided, it may suggest help with a link to a wiki page.

getIgnoreParams

protected static Set getIgnoreParams()

printTest

protected void printTest(Map map,
                         StringBuffer out,
                         String title,
                         String color)

Print out the name-value pairs of the Map map to the StringBuffer, using the title and color spec.

getMode

public int getMode()

Return the current plugin mode. Values include:

• MODE_INIT initial mode
• MODE_VIEW form view display
• MODE_CANCEL cancel button selected
• MODE_EDIT set up for edit mode
• MODE_SELECT select button selected
• MODE_SAVE save content mode

getModeName

public final String getModeName()

Return the name of the current mode.