uk.co.weft.htform
Class Form

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          uk.co.weft.maybeupload.MaybeUploadServlet
              uk.co.weft.htform.Servlet
                  uk.co.weft.htform.WithExceptionHandlerServlet
                      uk.co.weft.htform.Page
                          uk.co.weft.htform.Form

All Implemented Interfaces:

DocumentGenerator, ResourceConsumer, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

AuthenticatedForm, BasicConfigurator, ChangeStyle

public abstract class Form

extends Page

implements DocumentGenerator

An HTML page which is principally a form. The layout of the form is controlled by a Layout, q.v., but the default Layout lays widgets out as a table over four columns; specialisations could choose other layouts (for example, help-texts could be implemented as mouse-overs, narrow widgets could be laid out side by side, etc).

Note that a Form no longer automatically has a submit widget in it. You can supply one simply by adding an ActionWidget -- you don't need to specialise ActionWidget, because if your form has one and only one action you can just specialise defaultActionHandler().

This class (and consequently all servlets which are subclasses of this class) know about the following configuration parameters, in addition to those handled by Servlet:

action

URL: The URL which is to be the action of this form. Optional. Defaults to this form.

form_submit_method

String: the HTTP submit method of the form. Must be one of get or post; defaults to post

layout_engine_class

String: The fully qualified class name of a class which specialises uk.co.weft.htform.FormLayout. Optional. Defaults to FormLayout.

mandatory_prompt

String: string to append to widget prompts for mandatory widgets. Optional. Defaults to required

optional_prompt

String: string to append to widget prompts for non-mandatory widgets. Optional. no default.

Version:

$Revision: 1.82.4.7 $ This revision: $Author: simon $

Author:

Simon Brooke

See Also:

Page, Layout, Serialized Form

Field Summary

protected java.lang.String	action the URL to pass collected data to
static java.lang.String	actionExecutedToken Deprecated. use ACTIONEXECUTEDTOKEN
static java.lang.String	ACTIONEXECUTEDTOKEN the magic token in the context which holds a token representing the action performed.
protected java.util.Vector	auxiliaries My auxiliary tables
static java.lang.String	contextMenuMagicToken Deprecated. use CONTEXTMENUMAGICTOKEN
static java.lang.String	CONTEXTMENUMAGICTOKEN a magic token to retrieve menus for this service from the context
static java.lang.String	cssHelp Deprecated. use CSSHELP
static java.lang.String	CSSHELP A CSS class name for help text
static java.lang.String	cssPrompt Deprecated. use CSSPROMPT
static java.lang.String	CSSPROMPT A CSS class name for prompts
protected static java.lang.String	defaultScriptBase where to look for java scripts -- can be overridden with servlet property script_url_base
protected java.lang.String	mandatoryPrompt Text to append to widget prompts where widget is mandatory
static int	MIN_WIDGETS the minimum number of widgets a widget set can really have.
static java.lang.String	onloadFunctionToken Deprecated. use ONLOADFUNCTIONTOKEN
static java.lang.String	ONLOADFUNCTIONTOKEN the magic token in the context which holds the name of the JavaScript function to run when the page is loaded, if any
protected java.lang.String	optionalPrompt Text to append to widget prompts where widget is not mandatory
static java.lang.String	selectedWidgetSetMagicToken Deprecated. use SELECTEDWIDGETSETMAGICTOKEN
static java.lang.String	SELECTEDWIDGETSETMAGICTOKEN a magic token to retrieve the widget set for this service from the context
protected boolean	showHeadline do I show the forms headline? For most things it's a great convenience, for some a nuisance
protected java.lang.String	submitMethod what method shall I use for submitting my form?
static java.lang.String	SUBMITMETHODCONFIGTOKEN a magic token to determine the submit method for this form from the config
static java.lang.String	SUBMITMETHODGET the canonical name of the submit method 'get'
static java.lang.String	SUBMITMETHODPOST the canonical name of the submit method 'post'
static java.lang.String	validationWhingeToken Deprecated. use VALIDATIONWHINGETOKEN
static java.lang.String	VALIDATIONWHINGETOKEN the magic token in the context which holds the data validation whinges which arose while preprocessing widgets, if any.
protected java.lang.String	whingeHeader Header text for the list of validation errors if any
protected WidgetSet	widgets My default widgets
protected java.util.Vector	widgetSets All my widget sets

Fields inherited from class uk.co.weft.htform.Page

DOCTYPECONFIGTOKEN, dynamicFootInclude, dynamicHeadInclude, footInclude, footIncludeURL, headInclude, headIncludeURL, imageUrlBase, layout, printStylesheet, PRINTSTYLESHEETCONFIGTOKEN, stylesheet, STYLESHEETCONFIGTOKEN, title, titleMagicToken, TITLEMAGICTOKEN

Fields inherited from class uk.co.weft.htform.WithExceptionHandlerServlet

EXCEPTIONHANDLERCLASSCONFIGTOKEN

Fields inherited from class uk.co.weft.htform.Servlet

calendar, conf, contentType, CONTENTTYPECONFIGTOKEN, cookieDomain, cookiePath, COOKIESCONFIGTOKEN, cookieTTL, dbPassword, dbUrl, dbUsername, debug, DEBUGCONFIGTOKEN, driverName, embedded, here, identity, localeMagicToken, LOCALEMAGICTOKEN, outputStreamMagicToken, OUTPUTSTREAMMAGICTOKEN, parsePathInfo, PATHINFOMAGICTOKEN, ready, redirectMagicToken, REDIRECTMAGICTOKEN, requestMagicToken, REQUESTMAGICTOKEN, resourceBundleName, responseMagicToken, RESPONSEMAGICTOKEN, servletMagicToken, SERVLETMAGICTOKEN, sessionMagicToken, SESSIONMAGICTOKEN, USEHTTPSCONFIGTOKEN, zone

Fields inherited from class uk.co.weft.maybeupload.MaybeUploadServlet

allowOverwrite, maxUpload, saveUploadedFilesToDisk, silentlyRename, uploadDir, uploadDirPath, uploadDirURL

Fields inherited from interface uk.co.weft.htform.ResourceConsumer

RESOURCEBUNDLEMAGICTOKEN

Constructor Summary

Form()

Method Summary

protected Auxiliary	addAuxiliary(Auxiliary aux) Add this auxiliary to my auxiliaries.
protected Widget	addWidget(Widget w) Add this widget to the front of my default widget set
protected void	defaultActionHandler(Context context, Context whinges) Final fall-back action handler for this form.
protected void	doBody(Context context) Produce the body for a form, establishing the values in the context of this request and printing out the form header, the widgets, and the form footer
protected void	doHead(Context context) Output my HTML HEAD section, up to but not including the closing /HEAD tag.
protected void	doHeadBodySep(Context context) Output the close of the head tag and the opening of the body tag.
protected Context	fixupMagicValues(Context context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Fix up the magic values stored on the context by this class
Document	generate(Context context) Deprecated. this is the future, but it isn't finished yet; expect some changes to the interface definition and XML
Layout	getLayout(Context context) Return my layout engine for this context.
java.lang.String	getNextActionURL(Context context) Return my action: a method, to allow for specialisation.
WidgetSet	getSelectedWidgetSet(Context context) return the widget set in use.
protected java.lang.String	getTitle(Context context) return a suitable title for this service of this form
java.lang.String	getTransformURL(Context context) get the URL of my preferred XSL transform as a String.
protected WidgetSet	getWidgetSetByName(java.lang.String name) Return, strictly, my first widget set with this name
protected void	handleAction(Context context) The action despatcher.
boolean	hasWidgets() Do I already have widgets?
void	init(Context config) Basic initialisation, taking my configuration from this Context.
protected void	makeReady(Context context) Second-stage initialisation hook.
protected void	postForm(Context context) Layout material which appears in the page below the main form area.
protected void	postProcess(Context context) perform any processing of the contents of the context which has been passed back by the application, prior to passing it on to the user.
protected void	preForm(Context context) Do any arbitrary processing after the body of the page has been set up but before emitting the form; default lists the validation whinges
protected void	preProcess(Context context) perform any processing of the contents of the context which has been passed in by the user, prior to passing it on to application layer processing.
WidgetSet	selectNextWidgetSet(Context context, Context whinges) Return the widget set which puts in the highest bid.
protected void	setContextMenuQuery(Context context, java.lang.String name, java.lang.String query) set the query used by this menu in this context to this

Methods inherited from class uk.co.weft.htform.Page

doFoot, doFoot, generateContent, getFootInclude, getFootIncludeURL, getFootIncludeURL, getHeadInclude, getHeadIncludeURL, getHeadIncludeURL, getStylesheet, getStylesheets, getTables, getTitle, outputRedirectBlock, readStringFromURL

Methods inherited from class uk.co.weft.htform.WithExceptionHandlerServlet

whinge, whinge, whinge

Methods inherited from class uk.co.weft.htform.Servlet

addCookie, addCookie, coerceCookiesToContext, coerceToContext, coerceToContext, coerceToContext, coerceToContext, coerceToUrl, createContext, doGet, doPost, getCalendar, getContentType, getDebug, getLocale, getOutputStream, getResource, getResourceString, getServletInfo, grs, grs, handleCookies, handleRedirect, init, setCookieValues, storeOnSession

Methods inherited from class uk.co.weft.maybeupload.MaybeUploadServlet

doDelete, doHead, doOptions, doPut, doTrace, getUploadDir, getUploadURL, service

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletName, init, log, log

Methods inherited from class java.lang.Object

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

Methods inherited from interface uk.co.weft.domutil.DocumentGenerator

destroy

Field Detail

SUBMITMETHODCONFIGTOKEN

public static final java.lang.String SUBMITMETHODCONFIGTOKEN

a magic token to determine the submit method for this form from the config

Since:

Jacquard 1.10.8

See Also:

Constant Field Values

SUBMITMETHODGET

public static final java.lang.String SUBMITMETHODGET

the canonical name of the submit method 'get'

Since:

Jacquard 1.10.8

See Also:

Constant Field Values

SUBMITMETHODPOST

public static final java.lang.String SUBMITMETHODPOST

the canonical name of the submit method 'post'

Since:

Jacquard 1.10.8

See Also:

Constant Field Values

CONTEXTMENUMAGICTOKEN

public static final java.lang.String CONTEXTMENUMAGICTOKEN

a magic token to retrieve menus for this service from the context

See Also:

Constant Field Values

SELECTEDWIDGETSETMAGICTOKEN

public static final java.lang.String SELECTEDWIDGETSETMAGICTOKEN

a magic token to retrieve the widget set for this service from the context

See Also:

Constant Field Values

ONLOADFUNCTIONTOKEN

public static final java.lang.String ONLOADFUNCTIONTOKEN

the magic token in the context which holds the name of the JavaScript function to run when the page is loaded, if any

See Also:

Constant Field Values

VALIDATIONWHINGETOKEN

public static final java.lang.String VALIDATIONWHINGETOKEN

the magic token in the context which holds the data validation whinges which arose while preprocessing widgets, if any. If this name is set in a context, it holds a context which binds widget names to the exceptions thrown when they were preprocessed

See Also:

Constant Field Values

ACTIONEXECUTEDTOKEN

public static java.lang.String ACTIONEXECUTEDTOKEN

the magic token in the context which holds a token representing the action performed.

CSSPROMPT

public static final java.lang.String CSSPROMPT

A CSS class name for prompts

See Also:

Constant Field Values

CSSHELP

public static final java.lang.String CSSHELP

A CSS class name for help text

See Also:

Constant Field Values

contextMenuMagicToken

public static final java.lang.String contextMenuMagicToken

Deprecated. use CONTEXTMENUMAGICTOKEN

a magic token to retrieve menus for this service from the context

See Also:

Constant Field Values

selectedWidgetSetMagicToken

public static final java.lang.String selectedWidgetSetMagicToken

Deprecated. use SELECTEDWIDGETSETMAGICTOKEN

a magic token to retrieve the widget set for this service from the context

See Also:

Constant Field Values

onloadFunctionToken

public static final java.lang.String onloadFunctionToken

Deprecated. use ONLOADFUNCTIONTOKEN

the magic token in the context which holds the name of the JavaScript function to run when the page is loaded, if any

See Also:

Constant Field Values

validationWhingeToken

public static final java.lang.String validationWhingeToken

Deprecated. use VALIDATIONWHINGETOKEN

the magic token in the context which holds the data validation whinges which arose while preprocessing widgets, if any. If this name is set in a context, it holds a context which binds widget names to the exceptions thrown when they were preprocessed

See Also:

Constant Field Values

cssPrompt

public static final java.lang.String cssPrompt

Deprecated. use CSSPROMPT

A CSS class name for prompts

See Also:

Constant Field Values

cssHelp

public static final java.lang.String cssHelp

Deprecated. use CSSHELP

A CSS class name for help text

See Also:

Constant Field Values

actionExecutedToken

public static java.lang.String actionExecutedToken

Deprecated. use ACTIONEXECUTEDTOKEN

the magic token in the context which holds a token representing the action performed.

defaultScriptBase

protected static java.lang.String defaultScriptBase

where to look for java scripts -- can be overridden with servlet property script_url_base

MIN_WIDGETS

public static int MIN_WIDGETS

the minimum number of widgets a widget set can really have. Any connected WidgetSet has at least a hidden selected_widget_set widget.

action

protected java.lang.String action

the URL to pass collected data to

mandatoryPrompt

protected java.lang.String mandatoryPrompt

Text to append to widget prompts where widget is mandatory

optionalPrompt

protected java.lang.String optionalPrompt

Text to append to widget prompts where widget is not mandatory

submitMethod

protected java.lang.String submitMethod

what method shall I use for submitting my form?

Since:

Jacquard 1.10.8

whingeHeader

protected java.lang.String whingeHeader

Header text for the list of validation errors if any

auxiliaries

protected java.util.Vector auxiliaries

My auxiliary tables

widgetSets

protected java.util.Vector widgetSets

All my widget sets

widgets

protected WidgetSet widgets

My default widgets

showHeadline

protected boolean showHeadline

do I show the forms headline? For most things it's a great convenience, for some a nuisance

Constructor Detail

Form

public Form()

Method Detail

getLayout

public Layout getLayout(Context context)
                 throws javax.servlet.ServletException

Return my layout engine for this context.

Overrides:

getLayout in class Page

Parameters:

context - is passed because later we may want to use different layout engines for different browsers (or, conceivably, different levels of security clearance or whatever)

Throws:

javax.servlet.ServletException

See Also:

Layout

getNextActionURL

public java.lang.String getNextActionURL(Context context)
                                  throws java.lang.Exception

Return my action: a method, to allow for specialisation. Note: this method was formerly 'getAction()'; it has been renamed to disambiguate it from 'action' in the sense of ActionWidgets, etc.

Throws:

java.lang.Exception

getSelectedWidgetSet

public WidgetSet getSelectedWidgetSet(Context context)

return the widget set in use. Note that prior to handleAction this means the last widget set, and after it it means the next widget set

Parameters:

context - the context in which we're looking for the widget set

Returns:

the widget set selected in this context

Since:

protected until Jacquard 1.8

getTransformURL

public java.lang.String getTransformURL(Context context)
                                 throws GenerationException

get the URL of my preferred XSL transform as a String. Default behaviour is to return null; specialise if you want something different

Specified by:

getTransformURL in interface DocumentGenerator

Parameters:

context - the context for the present service

Throws:

GenerationException

generate

public Document generate(Context context)
                  throws java.lang.Exception

Deprecated. this is the future, but it isn't finished yet; expect some changes to the interface definition and XML

Generate this form as a jacquard-format XML document, to be formatted with a stylesheet. In the process do all the non-layout-related things that a form should normally do.#

Specified by:

generate in interface DocumentGenerator

Throws:

java.lang.Exception

hasWidgets

public boolean hasWidgets()

Do I already have widgets?

init

public void init(Context config)
          throws InitialisationException

Basic initialisation, taking my configuration from this Context. Important: specialisations are very strongly urged to call super.init( config).

Specified by:

init in interface DocumentGenerator

Overrides:

init in class Page

Throws:

InitialisationException

selectNextWidgetSet

public WidgetSet selectNextWidgetSet(Context context,
                                     Context whinges)
                              throws java.lang.Exception

Return the widget set which puts in the highest bid. Doesn't really throw an exception but things it calls may

Parameters:

context - the context for this service

whinges - a context for collecting exceptions thrown by widgets; the keys should be the names of widgets throwing exceptions, the values the exceptions thrown

Returns:

the widget set to use next

Throws:

java.lang.Exception

setContextMenuQuery

protected void setContextMenuQuery(Context context,
                                   java.lang.String name,
                                   java.lang.String query)

set the query used by this menu in this context to this

Parameters:

context - the context

name - the name of the menu widget whose menu is being set

query - the query to use in this context

getTitle

protected java.lang.String getTitle(Context context)

return a suitable title for this service of this form

Overrides:

getTitle in class Page

Parameters:

context - the context for this service

Returns:

the title

getWidgetSetByName

protected WidgetSet getWidgetSetByName(java.lang.String name)

Return, strictly, my first widget set with this name

addAuxiliary

protected Auxiliary addAuxiliary(Auxiliary aux)

Add this auxiliary to my auxiliaries. An auxilliary is an uneditable sub-form showing information from a related table.

addWidget

protected Widget addWidget(Widget w)
                    throws InitialisationException

Add this widget to the front of my default widget set

Throws:

InitialisationException

defaultActionHandler

protected void defaultActionHandler(Context context,
                                    Context whinges)
                             throws java.lang.Exception

Final fall-back action handler for this form. Default does nothing. Specialise with care!

Parameters:

context - the context for this service

whinges - a context for collecting exceptions thrown by widgets; the keys should be the names of widgets throwing exceptions, the values the exceptions thrown

Throws:

java.lang.Exception

doBody

protected void doBody(Context context)
               throws java.lang.Exception

Produce the body for a form, establishing the values in the context of this request and printing out the form header, the widgets, and the form footer

Specified by:

doBody in class Page

Throws:

java.lang.Exception

doHead

protected void doHead(Context context)
               throws java.lang.Exception

Output my HTML HEAD section, up to but not including the closing /HEAD tag. Specialisation: output the script requests made by my widgets.

Overrides:

doHead in class Page

Throws:

java.lang.Exception

doHeadBodySep

protected void doHeadBodySep(Context context)
                      throws java.lang.Exception

Output the close of the head tag and the opening of the body tag.

Overrides:

doHeadBodySep in class Page

Throws:

java.lang.Exception

fixupMagicValues

protected Context fixupMagicValues(Context context,
                                   javax.servlet.http.HttpServletRequest request,
                                   javax.servlet.http.HttpServletResponse response)

Fix up the magic values stored on the context by this class

Overrides:

fixupMagicValues in class Servlet

Parameters:

context - the context in which the values are to be fixed

request - the request for this service

response - the response to this request

Returns:

the same context.

handleAction

protected void handleAction(Context context)
                     throws java.lang.Exception

The action despatcher. If I have come from a previous invocation of myself, offer the context to each of my widgets in turn until one claims it; if none of them want it, do my defaultActionHandler().

Overrides:

handleAction in class Servlet

Parameters:

context - the context for this service

Throws:

java.lang.Exception

See Also:

handleAction(uk.co.weft.dbutil.Context)

makeReady

protected void makeReady(Context context)
                  throws DataStoreException,
                         javax.servlet.ServletException

Second-stage initialisation hook. Specialisation; make my widgets and auxiliaries ready

Overrides:

makeReady in class Servlet

Parameters:

context - my first context.

Throws:

DataStoreException

javax.servlet.ServletException

postForm

protected void postForm(Context context)
                 throws java.lang.Exception

Layout material which appears in the page below the main form area. Principally, show my auxiliary information if any. May be specialised to do any other processing to appear below a form.

Throws:

java.lang.Exception

postProcess

protected void postProcess(Context context)
                    throws DataStoreException,
                           javax.servlet.ServletException

perform any processing of the contents of the context which has been passed back by the application, prior to passing it on to the user. Specialise this method to handle any postprocessing which is common to all widget sets; specialise WidgetSet.postProcess for any per-WidgetSet postprocessing and, of course, specialise Widget.postProcess for any per-widget postprocessing. Default does nothing.

Parameters:

context - the context in which this response is being generated

Throws:

doesn - 't really throw any exceptions but things which specialise it may want to.

DataStoreException

javax.servlet.ServletException

preForm

protected void preForm(Context context)
                throws java.lang.Exception

Do any arbitrary processing after the body of the page has been set up but before emitting the form; default lists the validation whinges

Throws:

java.lang.Exception

preProcess

protected void preProcess(Context context)
                   throws DataStoreException,
                          javax.servlet.ServletException

perform any processing of the contents of the context which has been passed in by the user, prior to passing it on to application layer processing. Specialise this method to handle any preprocessing which is common to all widget sets; specialise WidgetSet.preProcess for any per-WidgetSet preprocessing and, of course, specialise Widget.preProcess for any per-widget preprocessing. Default does nothing.

Parameters:

context - the context in which this response is being generated

Throws:

doesn't - really throw any exceptions but things which specialise it may want to.

DataStoreException

javax.servlet.ServletException