uk.co.weft.htform
Class ResultFormatter

java.lang.Object
  uk.co.weft.htform.ResourceConsumerImpl
      uk.co.weft.htform.ResultFormatter

All Implemented Interfaces:

ResourceConsumer

public class ResultFormatter

extends ResourceConsumerImpl

A ResultFormatter is just a wrapper around a ResultSet that knows how to lay itself out in a Context. This functionality will probably change: (i) ResultFormatter possibly should be a subclass of ResultSet; (2) in any case the whole functionality should probably be replaced by some form of DataTable class embedded in a Form in the same way that an Auxilliary is.

Version:

$Revision: 1.38.4.7 $ This revision: $Author: simon $

Author:

Simon Brooke

Field Summary

protected java.util.Vector	actionColumns my action columns - columns of links which can be clicked on to do something with the rows
boolean	clickToOrder should those headers be clickable to reorder the result? Normally they should.
static int	DEFAULTACTIONINDEX the index within the actionColumns of the one which is default
static java.lang.String	DEFAULTACTIONLABEL the default label on my action column, if none other is supplied
RE	emailRegExp How do I recognise an email address? Less than perfect but will do for now.
RE	imageRegExp How do I recognise an image?
protected java.util.Vector	inspectPassthroughTokens a vector of tokens whose values should be passed through on inspects
protected java.lang.String	qbeButtonLabel the label of the query-by-example submit widget
protected int	qbeWidgetMaxLength the maximum length of a query-by-example widget input
protected int	qbeWidgetVisibleSize the visible length of a query-by-example widget input
boolean	queryByExample should I allow query by example? default is I should
boolean	recogniseLinks Should I use my URLs to find and make clickable things which may sensibly be links?
protected java.util.Vector	reorderPassthroughTokens a vector of tokens whose values should be passed through on reorders.
java.lang.String	searchToken the token to search for in results - so that I can pass it on in reorder headers
boolean	showHeaders should I show the field names as column headers? Normally yes
boolean	showId should I show the id field? Normally yes.
protected java.util.Hashtable	suppressFields a vector of names of fields to suppress in the display
RE	urlRegExp How do I recognise a URL? Less than perfect but will do for now.

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

resourceBundleName

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

RESOURCEBUNDLEMAGICTOKEN

Constructor Summary

ResultFormatter()
The 'no arguments' constructor, used where the result formatter is to be pluggable, as in List from version 1.14 onwards.

ResultFormatter(Contexts rs, java.util.Calendar cal)
Deprecated. not thread-safe. Use zero-arg constructor with init().

ResultFormatter(Contexts rs, java.util.Calendar cal, java.lang.String selectAction, java.lang.String selectField)
Deprecated. not thread-safe. Use zero-arg constructor with init().

ResultFormatter(Contexts rs, java.util.Calendar cal, java.lang.String selectAction, java.lang.String idCol, java.lang.String linkCol)
Deprecated. not thread-safe. Use zero-arg constructor with init().

ResultFormatter(java.sql.ResultSet rs, java.util.Calendar cal)
Deprecated. not thread-safe. Use zero-arg constructor with init().

ResultFormatter(java.sql.ResultSet rs, java.util.Calendar cal, java.lang.String selectAction, java.lang.String selectField)
Deprecated. not thread-safe. Use zero-arg constructor with init().

ResultFormatter(java.sql.ResultSet rs, java.util.Calendar cal, java.lang.String selectAction, java.lang.String idCol, java.lang.String linkCol)
Deprecated. not thread-safe. Use zero-arg constructor with init().

Method Summary

void	addActionColumn(ActionColumn col) append this action column to my list of action columns
void	addActionColumn(java.lang.String label, java.lang.String urlStub, java.util.Vector passThroughs) append an action column with this label and this URL stub, which will be extended by passing through the values of these passthrough tokens
void	addSuppressField(java.lang.String fieldToSuppress) add the fields whose name is passed to the set of fieldnames which I will suppress (i.e.
void	addSuppressFields(java.util.Vector fieldsToSuppress) add the fields whose names are listed in this vector to the set of fieldnames which I will suppress (i.e.
protected java.lang.String	composeActionURL(Context row) Deprecated. use composeActionURL( Context, Context)
protected java.lang.String	composeActionURL(Context context, Context row) construct the default action URL with the correct embedded arguments for this row
protected java.lang.String	composeAllRowsURL(Context context, Context showfields) compose a (possibly relative) URL to pull all rows
protected java.lang.String	composePrevNextURL(Context context, Context showfields, int index) compose a (possibly relative) URL to pull the next or previous page
protected java.lang.String	composeReorderURL(java.lang.String fieldName, Context showfields, Context context) compose a (possibly relative) URL to reorder the list on this field
void	init(java.util.Calendar cal, java.lang.String selectAction, java.lang.String idCol, java.lang.String linkCol) Initialiser, to be called only if the no-arguments constructor is used (for example, where ResultFormatters are pluggable at run time).
void	layout(Context context) Deprecated. not thread safe. Use layout( data, context).
void	layout(Contexts data, Context context) Lay me out in this context.
void	layout(java.sql.ResultSet data, Context context) Lay me out in this context.
protected void	layoutDataCell(int colNum, int actionCol, int urlCol, Context context, java.lang.String name, Context row) lay out a single data cell in the result.
void	layoutFirst(Context context) Deprecated. no non-deprecated replacement at present.
protected void	layoutQueryWidget(Context context, java.lang.String fieldname) Layout a query-by-example widget for a column
protected void	layoutSubmitWidget(Context context) layout the query-by-example 'match' button
protected void	maybeLayoutNavLinks(Contexts data, Context context, Context showfields, javax.servlet.ServletOutputStream out) if we have a maximum number of rows, print 'previous' and 'next' links as required
void	setActionLabel(java.lang.String label) set my action label to this.
void	setInspectPassthroughTokens(java.util.Vector tokens)
boolean	setRecogniseLinks(boolean val) set whether or not I recognise (and make clickable) links.
void	setReorderPassthroughTokens(java.util.Vector tokens) pass through the values of these tokens when reordering the list.
void	setShowId(boolean val) set whether or not I show the id field

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

getContextOrResource, getResource, getResourceOrContext, getResourceString, grs, grs, init

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULTACTIONLABEL

public static final java.lang.String DEFAULTACTIONLABEL

the default label on my action column, if none other is supplied

See Also:

Constant Field Values

DEFAULTACTIONINDEX

public static final int DEFAULTACTIONINDEX

the index within the actionColumns of the one which is default

See Also:

Constant Field Values

emailRegExp

public RE emailRegExp

How do I recognise an email address? Less than perfect but will do for now.

imageRegExp

public RE imageRegExp

How do I recognise an image?

urlRegExp

public RE urlRegExp

How do I recognise a URL? Less than perfect but will do for now.

searchToken

public java.lang.String searchToken

the token to search for in results - so that I can pass it on in reorder headers

clickToOrder

public boolean clickToOrder

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

Since:

Jacquard 1.9.1

queryByExample

public boolean queryByExample

should I allow query by example? default is I should

recogniseLinks

public boolean recogniseLinks

Should I use my URLs to find and make clickable things which may sensibly be links?

showHeaders

public boolean showHeaders

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

showId

public boolean showId

should I show the id field? Normally yes.

suppressFields

protected java.util.Hashtable suppressFields

a vector of names of fields to suppress in the display

Since:

Jacquard 1.12

qbeButtonLabel

protected java.lang.String qbeButtonLabel

the label of the query-by-example submit widget

Since:

Jacquard 1.12

actionColumns

protected java.util.Vector actionColumns

my action columns - columns of links which can be clicked on to do something with the rows

Since:

Jacquard 1.10

inspectPassthroughTokens

protected java.util.Vector inspectPassthroughTokens

a vector of tokens whose values should be passed through on inspects

reorderPassthroughTokens

protected java.util.Vector reorderPassthroughTokens

a vector of tokens whose values should be passed through on reorders.

qbeWidgetMaxLength

protected int qbeWidgetMaxLength

the maximum length of a query-by-example widget input

Since:

Jacquard 1.12

qbeWidgetVisibleSize

protected int qbeWidgetVisibleSize

the visible length of a query-by-example widget input

Since:

Jacquard 1.12

Constructor Detail

ResultFormatter

public ResultFormatter()

The 'no arguments' constructor, used where the result formatter is to be pluggable, as in List from version 1.14 onwards. If you use this constructor you should subsequently call init(). This is the only constructor which is thread safe; once this one is satisfactorily tested all others will become deprecated. This method does nothing (and nor should specialisations).

See Also:

init(java.util.Calendar, java.lang.String, java.lang.String, java.lang.String), List

ResultFormatter

public ResultFormatter(Contexts rs,
                       java.util.Calendar cal)

Deprecated. not thread-safe. Use zero-arg constructor with init().

Constructor; Contexts to format, and a calendar to use in formatting dates. The calendar can be got from the Page I'm in.

See Also:

Page

ResultFormatter

public ResultFormatter(Contexts rs,
                       java.util.Calendar cal,
                       java.lang.String selectAction,
                       java.lang.String selectField)

Deprecated. not thread-safe. Use zero-arg constructor with init().

Constructor: additinally, a field to make the record selectable on, and what to do when the record is selected

ResultFormatter

public ResultFormatter(Contexts rs,
                       java.util.Calendar cal,
                       java.lang.String selectAction,
                       java.lang.String idCol,
                       java.lang.String linkCol)

Deprecated. not thread-safe. Use zero-arg constructor with init().

Constructor: additinally, a field to make the record selectable on, and what to do when the record is selected

ResultFormatter

public ResultFormatter(java.sql.ResultSet rs,
                       java.util.Calendar cal)
                throws DataStoreException

Deprecated. not thread-safe. Use zero-arg constructor with init().

Constructor; ResultSet to format, and a calendar to use in formatting dates. The calendar can be got from the Page I'm in.

See Also:

Page

ResultFormatter

public ResultFormatter(java.sql.ResultSet rs,
                       java.util.Calendar cal,
                       java.lang.String selectAction,
                       java.lang.String selectField)
                throws DataStoreException

Deprecated. not thread-safe. Use zero-arg constructor with init().

Constructor: additinally, a field to make the record selectable on, and what to do when the record is selected

ResultFormatter

public ResultFormatter(java.sql.ResultSet rs,
                       java.util.Calendar cal,
                       java.lang.String selectAction,
                       java.lang.String idCol,
                       java.lang.String linkCol)
                throws DataStoreException

Deprecated. not thread-safe. Use zero-arg constructor with init().

Constructor: additinally, a field to make the record selectable on, and what to do when the record is selected

Method Detail

setActionLabel

public void setActionLabel(java.lang.String label)

set my action label to this. The acion label is the label on the link to a form for inspecting or editing the object implied by the row.

Parameters:

label - the new value for my action label.

setInspectPassthroughTokens

public void setInspectPassthroughTokens(java.util.Vector tokens)

Parameters:

tokens - a vector of tokens which should be passed through on inspect

setRecogniseLinks

public boolean setRecogniseLinks(boolean val)

set whether or not I recognise (and make clickable) links.

Parameters:

val - the value to set

Returns:

false if unable to recognise links, otherwise returns the value set.

setReorderPassthroughTokens

public void setReorderPassthroughTokens(java.util.Vector tokens)

pass through the values of these tokens when reordering the list. This implies that the list is reorderable!

Parameters:

tokens - the tokens (a Vector of Strings) which should be passed through.

setShowId

public void setShowId(boolean val)

set whether or not I show the id field

addActionColumn

public void addActionColumn(ActionColumn col)

append this action column to my list of action columns

addActionColumn

public void addActionColumn(java.lang.String label,
                            java.lang.String urlStub,
                            java.util.Vector passThroughs)

append an action column with this label and this URL stub, which will be extended by passing through the values of these passthrough tokens

Parameters:

label - the label for the column

urlStub - the stub URL

passThroughs - a vector of tokens whose values from the context and row should be appended as token=value pairs to the urlStub. Values from the row will over-ride those from the context if both are present.

addSuppressField

public void addSuppressField(java.lang.String fieldToSuppress)

add the fields whose name is passed to the set of fieldnames which I will suppress (i.e. not show)

addSuppressFields

public void addSuppressFields(java.util.Vector fieldsToSuppress)

add the fields whose names are listed in this vector to the set of fieldnames which I will suppress (i.e. not show)

init

public void init(java.util.Calendar cal,
                 java.lang.String selectAction,
                 java.lang.String idCol,
                 java.lang.String linkCol)

Initialiser, to be called only if the no-arguments constructor is used (for example, where ResultFormatters are pluggable at run time).

Parameters:

cal - a calendar to use to format dates

selectAction - the URL to follow if a link is selected

idCol - the name of the column in the results which holds the value to append to the selectAction URL for each record

linkCol - the name of the column in the results which holds the item which should form the link for each record (if any, else null)

layout

public void layout(Context context)
            throws java.lang.Exception

Deprecated. not thread safe. Use layout( data, context).

Lay me out in this context. This method pretty much assumes that all elements in the dataset have the same keys.

Parameters:

context - the context in which to lay me out

Throws:

java.lang.Exception

layout

public void layout(java.sql.ResultSet data,
                   Context context)
            throws java.lang.Exception

Lay me out in this context. This method pretty much assumes that all elements in the dataset have the same keys

Parameters:

data - the ResultSet representing the data to lay out

context - the context in which to lay it out

Throws:

java.lang.Exception

layout

public void layout(Contexts data,
                   Context context)
            throws java.lang.Exception

Lay me out in this context. This method pretty much assumes that all elements in the dataset have the same keys

Parameters:

data - the contexts representing the data to lay out

context - the context in which to lay it out

Throws:

java.lang.Exception

layoutFirst

public void layoutFirst(Context context)
                 throws java.sql.SQLException,
                        java.io.IOException,
                        javax.servlet.ServletException

Deprecated. no non-deprecated replacement at present.

Lay out only my first row, vertically in a table with column names to the left

Throws:

java.sql.SQLException

java.io.IOException

javax.servlet.ServletException

composeActionURL

protected java.lang.String composeActionURL(Context row)

Deprecated. use composeActionURL( Context, Context)

construct the default action URL with the correct embedded arguments for this row

Parameters:

row - a Context containing the fields of this row.

composeActionURL

protected java.lang.String composeActionURL(Context context,
                                            Context row)

construct the default action URL with the correct embedded arguments for this row

Parameters:

context - the context for this service.

row - a Context containing the fields of this row.

composeAllRowsURL

protected java.lang.String composeAllRowsURL(Context context,
                                             Context showfields)

compose a (possibly relative) URL to pull all rows

Parameters:

context - the context of the service

composePrevNextURL

protected java.lang.String composePrevNextURL(Context context,
                                              Context showfields,
                                              int index)
                                       throws java.lang.Exception

compose a (possibly relative) URL to pull the next or previous page

Parameters:

context - the context of the service

index - the offset from which to start the new page

Throws:

java.lang.Exception

composeReorderURL

protected java.lang.String composeReorderURL(java.lang.String fieldName,
                                             Context showfields,
                                             Context context)
                                      throws java.lang.Exception

compose a (possibly relative) URL to reorder the list on this field

Parameters:

fieldName - name of the field to reorder on

showfields - a context containing the fields to show

context - the context of the service

Throws:

java.lang.Exception

layoutDataCell

protected void layoutDataCell(int colNum,
                              int actionCol,
                              int urlCol,
                              Context context,
                              java.lang.String name,
                              Context row)
                       throws java.lang.Exception

lay out a single data cell in the result.

Parameters:

colNum - the index of this cell in its row

actionCol - the index of the action field in the row

urlCol - the index of a field expected to contain URLs (dodgy, don't use in conjunction with recogniseLinks)

context - the context in which this datacell is being printed

name - the name of the field this column represents

row - the context in which values may be found

Throws:

throws - any exception encountered up the chain for handling

java.lang.Exception

layoutQueryWidget

protected void layoutQueryWidget(Context context,
                                 java.lang.String fieldname)
                          throws java.io.IOException

Layout a query-by-example widget for a column

Parameters:

context - the service context

fieldname - the name of the column

Throws:

java.io.IOException - probably doesn't

layoutSubmitWidget

protected void layoutSubmitWidget(Context context)
                           throws java.io.IOException

layout the query-by-example 'match' button

Parameters:

context - the service context

Throws:

java.io.IOException - actually doesn't

maybeLayoutNavLinks

protected void maybeLayoutNavLinks(Contexts data,
                                   Context context,
                                   Context showfields,
                                   javax.servlet.ServletOutputStream out)
                            throws java.lang.Exception

if we have a maximum number of rows, print 'previous' and 'next' links as required

Parameters:

data - the dataset being layed out

context - the context in which it's being layed out

out - the stream on which it's being layed out

Throws:

java.lang.Exception