uk.co.weft.htform
Class List

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
                              uk.co.weft.htform.AuthenticatedForm
                                  uk.co.weft.htform.List

All Implemented Interfaces:

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

Direct Known Subclasses:

QueryByExampleList

public class List

extends AuthenticatedForm

An HTML page which is principally a dababase listing.

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

action_field

String: the field whose value should be appended to the action URL. Not optional, no default

action_label

String: the label for the action link. Optional, defaults to 'Edit this!'. See also link_field.

action_url

String: the action (URL) to invoke to select a record from the list. Not optional, no default

can_add

String: optional: if supplied, add a link with this text to allow the user to add a record.

can_search

Boolean: if not 'false', show a widget to allow the user to filter the list.

click_to_order

Boolean: whether or not you can reorder the results by clicking the column headers. Only relevent if show_headers is true. Optional. Defaults to true.

formatter_class

String: the name of the class to use as a result formatter. Must be a subclass of ResultFormatter, q.v.; optional, defaults to uk.co.weft.htform.ResultFormatter

link_field

String: The field whose body forms the text of the link. Optional, no default, see also action_label

lower_fn

String: if provided and can_search is true, the name of a SQL function which coerces characters to lowercase (a good thing to try is 'lower'). This will give case-insensitive search

max_rows_per_page

Integer: the maximum number of rows to return in one page. Optional. defaults to zero. Note that this option is only supported for Postgres; it will not work with MS SQL Server or Oracle, and there are no plans to fix this.

no_default_list

Boolean: if 'true' and can_search is also 'true' then don't layout the list until there is a valid search value.

order_by

String: list of names to order results by, separated by semi-colons (because commas are normally used to separate properties).

query_template

String: a SQL query, optionally with placeholder question-marks into which values will be pasted sequentially from slots. In writing the query, bear in mind that if you set can_search the search string will (at present) be added to the end in the form [where|and] link_field ~ 'search_string', so don't use a 'group by' or 'order by' clause andcan_search.

search_exact

Boolean: if 'true' do an exact match, else a substring match.

search_field

String: the name of field in the table to search on. Optional; defaults to value of link_field, q.v., for backwards compatibility

search_help

String: the help string for the search widget

search_no_widget

Boolean: if 'true', don't show a search widget (default is do if can_search is not false)

search_prompt

String: the prompt string for the search widget. Optional. Defaults to the value of search_token

search_size

Integer: size of the search widget. Optional. Defaults to default size of Widget

search_token

String: the name in the context whose value should be searched for to filter the list. Optional. Defaults to 'Search'.

set_cookie

Boolean: if true, set a cookie whose name is the value of search_token and whose value is the search string entered by the user. Optional. Defaults to false.

show_can_add_before

Boolean: whether to show the can_add link before the list, as well as after. Optional. Defaults to 'true'.

show_headers

Boolean: if present and not 'true' then don't show column headers.

show_id

Boolean: if present and not 'true' then don't show the id column.

Version:

$Revision: 1.48.4.3 $ This revision: $Author: simon $

Author:

Simon Brooke

See Also:

Page, Serialized Form

Field Summary

protected java.lang.String	action the action (URL) to invoke to select a record from the results.
protected java.lang.String	actionField the field by which to select a record from the results.
static java.lang.String	ACTIONFIELDCONFIGTOKEN configuration token: the token for the name of the field to append to the action URL
static java.lang.String	ACTIONLABELCONFIGTOKEN configuration token: the token for the label on the action url
static java.lang.String	ACTIONURLCONFIGTOKEN configuration token: the token for the action URL
protected java.lang.String	canAdd the text of a 'add another' link; if set, use action URL; if not set, don't show
static java.lang.String	CANADDBEFORECONFIGTOKEN configuration token: the token for whether to show the 'add a new' link before the list as well as after
static java.lang.String	CANADDCONFIGTOKEN configuration token: the token for whether to show a 'can add' link
static java.lang.String	CANSEARCHCONFIGTOKEN configuration token: the token for whether to show a 'Search' widget
protected boolean	clickToOrder should those headers be clickable to reorder the result? Normally they should.
static java.lang.String	CLICKTOORDERCONFIGTOKEN configuration token: the token for whether to implement 'click to order'
protected ResultFormatter	formatter my result formatter object
static java.lang.String	FORMATTERCLASSCONFIGTOKEN configuration token: the token for the name of the formatter class
protected java.lang.String	formatterName the classname of my result formatter object
protected java.lang.String	linkField the field to highlight to allow the user to select a record in the results
static java.lang.String	LINKFIELDCONFIGTOKEN configuration token: the token for the name of the field to use as a link in the action URL
protected java.lang.String	listQueryTemplate a query template to select the records to list.
protected java.lang.String	lowerFn the name of the SQL function which coerces characters to lower case
static java.lang.String	LOWERFNCONFIGTOKEN configuration token: the token for the 'tolower' function in the SQL used by the connected database
protected java.lang.String	matchDelimEnd suffix for substring match
protected java.lang.String	matchDelimStart prefix for substring match
protected java.lang.String	matchOp the SQL operator to use to do matching
protected boolean	noDefaultList should I layout a default list first?
static java.lang.String	NODEFAULTLISTCONFIGTOKEN configuration token: the token for whether to suppress the default list
protected java.lang.String	orderBy the names I should order the results by
static java.lang.String	ORDERBYMAGICTOKEN configuration/context magic token: the token for the name(s) of the field(s) to order by
static java.lang.String	QUERYTEMPLATECONFIGTOKEN configuration token: the token for the query template
protected boolean	recogniseLinks should I recognise links and format them appropriately? Normally yes
static java.lang.String	RECOGNISELINKSCONFIGTOKEN configuration token: the token for whether to recognise URLs in the data
static java.lang.String	RESULTSMAXROWSMAGICTOKEN configuration/context magic token: the maximum number of results to show on one page
static java.lang.String	RESULTSOFFSETMAGICTOKEN magic token: the offset into the result set
static java.lang.String	SEARCHEXACTCONFIGTOKEN configuration token: the token for whether to do exact matching in search
protected java.lang.String	searchField the database field in which to search
static java.lang.String	SEARCHFIELDCONFIGTOKEN configuration token: the token for the name of the field to search
protected java.lang.String	searchHelp the help string for the search widget
static java.lang.String	SEARCHHELPCONFIGTOKEN configuration token: the token for the helptext of the search widget
protected java.lang.String	searchPrompt the prompt string for the search widget
static java.lang.String	SEARCHPROMPTCONFIGTOKEN configuration token: the token for the prompt for the search widget
static java.lang.String	SEARCHSETCOOKIECONFIGTOKEN configuration token: the token for whether set a cookie whose name is the value of search_token and whose value is the search string entered by the user.
protected int	searchSize the size of the widget
static java.lang.String	SEARCHSIZECONFIGTOKEN configuration token: the token for the size of the seach widget
protected java.lang.String	searchToken the magic token for searching.
static java.lang.String	SEARCHTOKENCONFIGTOKEN configuration token: the token for the name of the token in the context whose value should be searched for to filter the list.
protected Widget	searchw the widget in which search text should be entered, if any
protected boolean	showCanAddBefore whether to show the cannAdd link before the list, as well as after it; default is we do.
protected boolean	showHeaders should I show the field names as column headers? Normally yes
static java.lang.String	SHOWHEADERSCONFIGTOKEN configuration token: the token for whether to show column headers
protected boolean	showId should I show the id column? Normally yes
static java.lang.String	SHOWIDCONFIGTOKEN configuration token: the token for whether to show the id column
protected java.lang.String[]	slots an array of the names of values in the context to be pasted into the query.
static java.lang.String	SORTDIRECTIONMAGICTOKEN context magic token: the token for the direction to order by; value (if supplied) must be the value of SORTORDERDESCENDINGMAGICVALUE
static java.lang.String	SORTORDERDESCENDINGMAGICVALUE magic value to indicate that the sort direction is descending

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

allowLogout, ALLOWLOGOUTCONFIGTOKEN, AUTHENTICATEDUSERMAGICTOKEN, authenticator, AUTHENTICATORCLASSMAGICTOKEN, authentificationWidgets, logoutPrompt, LOGOUTPROMPTCONFIGTOKEN, logoutWidget, onLogoutRedirect

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

actionExecutedToken, ACTIONEXECUTEDTOKEN, auxiliaries, contextMenuMagicToken, CONTEXTMENUMAGICTOKEN, cssHelp, CSSHELP, cssPrompt, CSSPROMPT, defaultScriptBase, mandatoryPrompt, MIN_WIDGETS, onloadFunctionToken, ONLOADFUNCTIONTOKEN, optionalPrompt, selectedWidgetSetMagicToken, SELECTEDWIDGETSETMAGICTOKEN, showHeadline, submitMethod, SUBMITMETHODCONFIGTOKEN, SUBMITMETHODGET, SUBMITMETHODPOST, validationWhingeToken, VALIDATIONWHINGETOKEN, whingeHeader, widgets, widgetSets

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

List()

Method Summary

protected Contexts	fetch(Context context) fetch my results.
protected java.lang.String	getTitle(Context context) Specialisation: show what we're searching for
void	init(Context config) Read my configuration and, if required, set up my search form
protected void	postForm(Context context) Layout my listing.

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

login, logout

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

addAuxiliary, addWidget, defaultActionHandler, doBody, doHead, doHeadBodySep, fixupMagicValues, generate, getLayout, getNextActionURL, getSelectedWidgetSet, getTransformURL, getWidgetSetByName, handleAction, hasWidgets, makeReady, postProcess, preForm, preProcess, selectNextWidgetSet, setContextMenuQuery

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

ACTIONFIELDCONFIGTOKEN

public static final java.lang.String ACTIONFIELDCONFIGTOKEN

configuration token: the token for the name of the field to append to the action URL

See Also:

Constant Field Values

ACTIONLABELCONFIGTOKEN

public static final java.lang.String ACTIONLABELCONFIGTOKEN

configuration token: the token for the label on the action url

See Also:

Constant Field Values

ACTIONURLCONFIGTOKEN

public static final java.lang.String ACTIONURLCONFIGTOKEN

configuration token: the token for the action URL

See Also:

Constant Field Values

CANADDBEFORECONFIGTOKEN

public static final java.lang.String CANADDBEFORECONFIGTOKEN

configuration token: the token for whether to show the 'add a new' link before the list as well as after

See Also:

Constant Field Values

CANADDCONFIGTOKEN

public static final java.lang.String CANADDCONFIGTOKEN

configuration token: the token for whether to show a 'can add' link

See Also:

Constant Field Values

CANSEARCHCONFIGTOKEN

public static final java.lang.String CANSEARCHCONFIGTOKEN

configuration token: the token for whether to show a 'Search' widget

See Also:

Constant Field Values

CLICKTOORDERCONFIGTOKEN

public static final java.lang.String CLICKTOORDERCONFIGTOKEN

configuration token: the token for whether to implement 'click to order'

See Also:

Constant Field Values

FORMATTERCLASSCONFIGTOKEN

public static final java.lang.String FORMATTERCLASSCONFIGTOKEN

configuration token: the token for the name of the formatter class

See Also:

Constant Field Values

LINKFIELDCONFIGTOKEN

public static final java.lang.String LINKFIELDCONFIGTOKEN

configuration token: the token for the name of the field to use as a link in the action URL

See Also:

Constant Field Values

LOWERFNCONFIGTOKEN

public static final java.lang.String LOWERFNCONFIGTOKEN

configuration token: the token for the 'tolower' function in the SQL used by the connected database

See Also:

Constant Field Values

NODEFAULTLISTCONFIGTOKEN

public static final java.lang.String NODEFAULTLISTCONFIGTOKEN

configuration token: the token for whether to suppress the default list

See Also:

Constant Field Values

ORDERBYMAGICTOKEN

public static final java.lang.String ORDERBYMAGICTOKEN

configuration/context magic token: the token for the name(s) of the field(s) to order by

See Also:

Constant Field Values

SORTDIRECTIONMAGICTOKEN

public static final java.lang.String SORTDIRECTIONMAGICTOKEN

context magic token: the token for the direction to order by; value (if supplied) must be the value of SORTORDERDESCENDINGMAGICVALUE

See Also:

SORTORDERDESCENDINGMAGICVALUE, Constant Field Values

SORTORDERDESCENDINGMAGICVALUE

public static final java.lang.String SORTORDERDESCENDINGMAGICVALUE

magic value to indicate that the sort direction is descending

See Also:

Constant Field Values

QUERYTEMPLATECONFIGTOKEN

public static final java.lang.String QUERYTEMPLATECONFIGTOKEN

configuration token: the token for the query template

See Also:

Constant Field Values

RECOGNISELINKSCONFIGTOKEN

public static final java.lang.String RECOGNISELINKSCONFIGTOKEN

configuration token: the token for whether to recognise URLs in the data

See Also:

Constant Field Values

RESULTSOFFSETMAGICTOKEN

public static final java.lang.String RESULTSOFFSETMAGICTOKEN

magic token: the offset into the result set

See Also:

Constant Field Values

RESULTSMAXROWSMAGICTOKEN

public static final java.lang.String RESULTSMAXROWSMAGICTOKEN

configuration/context magic token: the maximum number of results to show on one page

See Also:

Constant Field Values

SEARCHFIELDCONFIGTOKEN

public static final java.lang.String SEARCHFIELDCONFIGTOKEN

configuration token: the token for the name of the field to search

See Also:

Constant Field Values

SEARCHSIZECONFIGTOKEN

public static final java.lang.String SEARCHSIZECONFIGTOKEN

configuration token: the token for the size of the seach widget

See Also:

Constant Field Values

SHOWHEADERSCONFIGTOKEN

public static final java.lang.String SHOWHEADERSCONFIGTOKEN

configuration token: the token for whether to show column headers

See Also:

Constant Field Values

SHOWIDCONFIGTOKEN

public static final java.lang.String SHOWIDCONFIGTOKEN

configuration token: the token for whether to show the id column

See Also:

Constant Field Values

SEARCHEXACTCONFIGTOKEN

public static final java.lang.String SEARCHEXACTCONFIGTOKEN

configuration token: the token for whether to do exact matching in search

See Also:

Constant Field Values

SEARCHHELPCONFIGTOKEN

public static final java.lang.String SEARCHHELPCONFIGTOKEN

configuration token: the token for the helptext of the search widget

See Also:

Constant Field Values

SEARCHPROMPTCONFIGTOKEN

public static final java.lang.String SEARCHPROMPTCONFIGTOKEN

configuration token: the token for the prompt for the search widget

See Also:

Constant Field Values

SEARCHSETCOOKIECONFIGTOKEN

public static final java.lang.String SEARCHSETCOOKIECONFIGTOKEN

configuration token: the token for whether set a cookie whose name is the value of search_token and whose value is the search string entered by the user.

See Also:

Constant Field Values

SEARCHTOKENCONFIGTOKEN

public static final java.lang.String SEARCHTOKENCONFIGTOKEN

configuration token: the token for the name of the token in the context whose value should be searched for to filter the list.

See Also:

Constant Field Values

formatter

protected ResultFormatter formatter

my result formatter object

action

protected java.lang.String action

the action (URL) to invoke to select a record from the results. Should be set up in the init method.

actionField

protected java.lang.String actionField

the field by which to select a record from the results. Should be set up in the init method.

canAdd

protected java.lang.String canAdd

the text of a 'add another' link; if set, use action URL; if not set, don't show

formatterName

protected java.lang.String formatterName

the classname of my result formatter object

linkField

protected java.lang.String linkField

the field to highlight to allow the user to select a record in the results

listQueryTemplate

protected java.lang.String listQueryTemplate

a query template to select the records to list. Should be set up in the init method.

See Also:

PreparedStatement

lowerFn

protected java.lang.String lowerFn

the name of the SQL function which coerces characters to lower case

matchDelimEnd

protected java.lang.String matchDelimEnd

suffix for substring match

matchDelimStart

protected java.lang.String matchDelimStart

prefix for substring match

matchOp

protected java.lang.String matchOp

the SQL operator to use to do matching

orderBy

protected java.lang.String orderBy

the names I should order the results by

searchField

protected java.lang.String searchField

the database field in which to search

searchHelp

protected java.lang.String searchHelp

the help string for the search widget

searchToken

protected java.lang.String searchToken

the magic token for searching. Should be configurable or come from a properties file for flexibility and i18n reasons

searchPrompt

protected java.lang.String searchPrompt

the prompt string for the search widget

searchw

protected Widget searchw

the widget in which search text should be entered, if any

slots

protected java.lang.String[] slots

an array of the names of values in the context to be pasted into the query. Should be set up in the init method. If there are no slots in the query, should be left null.

clickToOrder

protected boolean clickToOrder

should those headers be clickable to reorder the result? Normally they should.

Since:

Jacquard 1.9.1

noDefaultList

protected boolean noDefaultList

should I layout a default list first?

recogniseLinks

protected boolean recogniseLinks

should I recognise links and format them appropriately? Normally yes

showCanAddBefore

protected boolean showCanAddBefore

whether to show the cannAdd link before the list, as well as after it; default is we do.

showHeaders

protected boolean showHeaders

should I show the field names as column headers? Normally yes

showId

protected boolean showId

should I show the id column? Normally yes

searchSize

protected int searchSize

the size of the widget

Constructor Detail

List

public List()

Method Detail

init

public void init(Context config)
          throws InitialisationException

Read my configuration and, if required, set up my search form

Specified by:

init in interface DocumentGenerator

Overrides:

init in class AuthenticatedForm

Parameters:

config - my configuration

Throws:

InitialisationException - if my configuration is unsuitable

getTitle

protected java.lang.String getTitle(Context context)

Specialisation: show what we're searching for

Overrides:

getTitle in class Form

Returns:

the title

fetch

protected Contexts fetch(Context context)
                  throws DataStoreException,
                         java.sql.SQLException

fetch my results. The reason for compiling the query template into a prepared statement is because it makes pasting in slot values easier; however, we don't re-use it, for security reasons.

Throws:

DataStoreException

java.sql.SQLException

postForm

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

Layout my listing.

Overrides:

postForm in class Form

Throws:

java.lang.Exception