uk.ac.ed.epcc.webapp.forms

Interface Form

All Superinterfaces:

Contexed, java.lang.Iterable<Field>

All Known Implementing Classes:

BaseForm, BaseHTMLForm, CommandLineForm, HTMLForm, MapForm, PageHTMLForm

public interface Form
extends java.lang.Iterable<Field>, Contexed

Interface for building and querying Forms. A Form is functionally an ordered set of Fields. Once built a Form can be used as a Map between field names and values. The methods used to actually edit a form are specific to the implementing class.

A Form may either be used as just a collection of fields with associated validation ie as a component of a larger composite form or may contain a set of FormAction classes to define an action to take on form submission.

Method Summary

Modifier and Type	Method and Description
void	addAction(java.lang.String name, FormAction action) add an FormAction to this Form
<I> Field	addInput(java.lang.String key, java.lang.String label, Input<I> s) Add and input to the next slot in the form
<I> Field	addInput(java.lang.String key, java.lang.String label, java.lang.String help, Input<I> s) Add and input to the next slot in the form
void	addValidator(FormValidator v) Add a FormValidator to perform overall sanity check on the form.
boolean	containsInput(java.lang.Class<? extends Input> c) Check a form to see if it contains an input of a particular type.
java.lang.String	diff(java.util.Map<java.lang.String,java.lang.Object> m) Compare the values of this forms inputs with the contents of a Map and generate a text summary;
FormResult	doAction(java.lang.String name) perform a named action on this form.
java.lang.Object	get(java.lang.String key) get the value associated with a Form field.
FormAction	getAction(java.lang.String name) get a FormAction by name.
java.util.Set<java.lang.String>	getActionNames() Get an Set of the names of the installed Actions.
java.lang.String	getAutoFocus() get field for auto-focus
java.util.Map<java.lang.String,java.lang.Object>	getContents() get the contents of a form as a Map
Field	getField(java.lang.String key) get a Field object
java.util.Iterator<java.lang.String>	getFieldIterator() get an iterator over the field names
java.lang.String	getFormID() get the form-ids In HTML this is used as a prefix for the input html-ids
Input	getInput(java.lang.String key) get the Input associated with a Field
java.lang.Object	getItem(java.lang.String key) get the Item associated with a Form field.
Table<java.lang.String,java.lang.String>	getTable() get the form contents as a Table
default int	getTargetStage() get which stage of a multi-stage form is being shown/read.
java.util.Set<FormValidator>	getValidators() Get the set of FormValidators installed in the form.
boolean	hasField(java.lang.String key) Does form contain specified field
default boolean	isComplete() returns the last value returned by #poll(FormResult)
default boolean	isFixed(java.lang.String key) Is the current value of this field fixed and connot be changed Also returns false if the field is not defined.
default boolean	poll() Attempt to show/validate the current state of the form as part of a multi-phase form.
java.lang.Object	put(java.lang.String key, java.lang.Object value) set the value associated with a form field
void	removeAction(java.lang.String name) remove a FormAction.
void	removeField(java.lang.String key) remove a field from the form
void	removeValidator(FormValidator v) Remove a FormValidator
void	setAutoFocus(java.lang.String field) set field for auto-focus
void	setConfirm(java.lang.String name, java.lang.String conf)
void	setContents(java.util.Map<java.lang.String,java.lang.Object> m) set the contents of a Form from a Map
void	setFormID(java.lang.String id) Set a form-id for this form.
default void	setTargetStage(int stage) set which stage of a multi-stage form is being shown/read
default boolean	supportsMultiStage() Query if multi stage forms are supported by this implementation
void	update(java.util.Map<java.lang.String,java.lang.Object> m) modify an existing Map updating the fields represented by the Form.
boolean	validate() validate a form.

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Methods inherited from interface uk.ac.ed.epcc.webapp.Contexed

getContext

Method Detail

addAction

void addAction(java.lang.String name,
               FormAction action)

add an FormAction to this Form

Parameters:

name - String action-name/button-text

action - FormAction

removeAction

void removeAction(java.lang.String name)

remove a FormAction.

Parameters:

name -

getAction

FormAction getAction(java.lang.String name)

get a FormAction by name.

Parameters:

name -

Returns:

FormAction

addInput

<I> Field addInput(java.lang.String key,
                   java.lang.String label,
                   Input<I> s)

Add and input to the next slot in the form

Parameters:

key - key to use to refer to field

label - String to display to user

s - Input to add

Returns:

Field object created

addInput

<I> Field addInput(java.lang.String key,
                   java.lang.String label,
                   java.lang.String help,
                   Input<I> s)

Add and input to the next slot in the form

Parameters:

key - key to use to refer to field

label - String to display to user

help - tooltip String

s - Input to add

Returns:

Field object created

containsInput

boolean containsInput(java.lang.Class<? extends Input> c)

Check a form to see if it contains an input of a particular type.

Parameters:

c - Class for the Input type to be testes

Returns:

bioolean true if input exists

doAction

FormResult doAction(java.lang.String name)
             throws FieldException,
                    ActionException

perform a named action on this form. This also checks the form is validated

Parameters:

name - String name of action

Returns:

FormResult returned by action

Throws:

FieldException

ActionException

get

java.lang.Object get(java.lang.String key)

get the value associated with a Form field. non existent fields alwayrs return null.

Parameters:

key -

Returns:

value

getItem

java.lang.Object getItem(java.lang.String key)

get the Item associated with a Form field.

Parameters:

key -

Returns:

item

getActionNames

java.util.Set<java.lang.String> getActionNames()

Get an Set of the names of the installed Actions.

Returns:

Iterator

setConfirm

void setConfirm(java.lang.String name,
                java.lang.String conf)

getContents

java.util.Map<java.lang.String,java.lang.Object> getContents()

get the contents of a form as a Map

Returns:

Map

getField

Field getField(java.lang.String key)

get a Field object

Parameters:

key -

Returns:

Field

hasField

boolean hasField(java.lang.String key)

Does form contain specified field

Parameters:

key -

Returns:

isFixed

default boolean isFixed(java.lang.String key)

Is the current value of this field fixed and connot be changed Also returns false if the field is not defined.

Parameters:

key -

Returns:

boolean

getFieldIterator

java.util.Iterator<java.lang.String> getFieldIterator()

get an iterator over the field names

Returns:

Iterator

getInput

Input getInput(java.lang.String key)

get the Input associated with a Field

Parameters:

key -

Returns:

the Input or null if Input does not exist

getTable

Table<java.lang.String,java.lang.String> getTable()

get the form contents as a Table

Returns:

Table

put

java.lang.Object put(java.lang.String key,
                     java.lang.Object value)

set the value associated with a form field

Parameters:

key -

value -

Returns:

previous value

removeField

void removeField(java.lang.String key)

remove a field from the form

Parameters:

key -

setContents

void setContents(java.util.Map<java.lang.String,java.lang.Object> m)

set the contents of a Form from a Map

Parameters:

m - Map of values

addValidator

void addValidator(FormValidator v)

Add a FormValidator to perform overall sanity check on the form.

Parameters:

v - The FormValidator to set.

removeValidator

void removeValidator(FormValidator v)

Remove a FormValidator

Parameters:

v -

getValidators

java.util.Set<FormValidator> getValidators()

Get the set of FormValidators installed in the form. This is a copy of the internal set and is not modifiable, though its members can be removed from the active set by passing them to removeValidator(FormValidator)

Returns:

Set

update

void update(java.util.Map<java.lang.String,java.lang.Object> m)

modify an existing Map updating the fields represented by the Form. Fields that are null are removed from the Map

Parameters:

m - Map to update

diff

java.lang.String diff(java.util.Map<java.lang.String,java.lang.Object> m)

Compare the values of this forms inputs with the contents of a Map and generate a text summary;

Parameters:

m - Map to compare to

Returns:

String summary or null

validate

boolean validate()

validate a form. This method checks the fields and the installed FormValidator if any. No details of the exact error are returned by this call.

Returns:

boolean true if valid

poll

default boolean poll()
              throws TransitionException

Attempt to show/validate the current state of the form as part of a multi-phase form. This is called during form construction when values from inputs are needed to construct the rest of the form. If the method returns true then form construction can continue. For GUI forms this may mean that a partial form has been shown and completed by the end user. If false then the method will have modified the form to add actions to progress the multi-stage completion and the form should be displayed as-is.

If multi-stage submission is not supported the method will just return true.

Returns:

boolean true if form build should continue

Throws:

TransitionException

supportsMultiStage

default boolean supportsMultiStage()

Query if multi stage forms are supported by this implementation

Returns:

isComplete

default boolean isComplete()

returns the last value returned by #poll(FormResult)

Returns:

getTargetStage

default int getTargetStage()

get which stage of a multi-stage form is being shown/read.

Returns:

setTargetStage

default void setTargetStage(int stage)

set which stage of a multi-stage form is being shown/read

Parameters:

stage -

setFormID

void setFormID(java.lang.String id)

Set a form-id for this form. In HTML this is used as a prefix for the input html-ids

Parameters:

id -

getFormID

java.lang.String getFormID()

get the form-ids In HTML this is used as a prefix for the input html-ids

Returns:

setAutoFocus

void setAutoFocus(java.lang.String field)

set field for auto-focus

Parameters:

field -

getAutoFocus

java.lang.String getAutoFocus()

get field for auto-focus

Returns: