to.etc.domui.component.lookup

Class LookupForm<T>

java.lang.Object

to.etc.domui.dom.css.CssBase

to.etc.domui.dom.html.NodeBase

to.etc.domui.dom.html.NodeContainer

to.etc.domui.dom.html.Div

to.etc.domui.component.lookup.LookupForm<T>

All Implemented Interfaces:

Iterable<NodeBase>, IButtonContainer, INodeErrorDelegate, IDraggable, IDropBody, IDropTargetable

public class LookupForm<T>
extends Div
implements IButtonContainer

Creates a search box to enter search criteria. This only presents the search part of the form, constructed by metadata where needed, and the "search", "clear fields" and optional "new" buttons. The actual searching must be done by the user of this component.

The component will return a QCriteria query representing the search query constructed by the user. This QCriteria object can, after retrieval, be used to add extra search restrictions easily.

When used as-is, this form will use the class' metadata to discover any defined search properties, and then populate the form with lookup controls which allow searches on those properties. This is for "default" lookup screens. For more complex screens or lookup parts that have controls interact with each other you can manually define the contents of the lookup form. By adding lookup items manually you disable the automatic discovery of search options. This is proper because no form should ever depend on the content, structure or order of metadata-defined lookup items!!! So if you want to manipulate the lookup form's contents you have to define its layout by hand.

Defining a form by hand is easy. To just add a property to search for to the form call addProperty(String propname). This will create the default lookup input thing and label for the property, as defined by metadata and factories. If you need more control you can also call one of the addManualXXXX methods which allow full control over the controls and search criteria used by the form.

Each search item added will usually return a LookupForm.Item. This is a handle to the created lookup control and associated data and can be used to manipulate the control or its presentation at runtime.

The constructor for this control accepts an ellipsis list of property names to quickly create a lookup using user-specified properties.

Author:

Frits Jalvingh Created on Jul 14, 2008

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LookupForm.ButtonMode
static class	LookupForm.Item This is the definition for an Item to look up.

Constructor Summary

Constructors

Constructor and Description
LookupForm(Class<T> lookupClass, ClassMetaModel cmm, String... propertyList) Create a LookupForm to find instances of the specified class.
LookupForm(Class<T> lookupClass, String... propertyList)
LookupForm(QCriteria<T> rootCriteria, String... propertyList)

Method Summary

Modifier and Type	Method and Description
void	addButton(NodeBase thing, int order)
void	addButtonItem(NodeBase b)
void	addButtonItem(NodeBase b, int order) Add a button (or other item) to show on the button row.
void	addButtonItem(NodeBase b, int order, LookupForm.ButtonMode both) Add a button (or other item) to show on the button row.
LookupForm.Item	addChildProperty(String propPath) Add lookup control instance for search properties on child list (oneToMany relation) members.
LookupForm.Item	addChildPropertyLabel(String label, String propPath) Add lookup control instance for search properties on child list (oneToMany relation) members.
void	addFilterButton()
void	addItem(NodeBase cell) With this method you can place a NodeBase in the table where it will fill the entire row.
void	addItem(NodeBase left, NodeBase right) With this method you can place a NodeBase in the left (label) column and one in the right (control) column.
void	addItemBreak()
LookupForm.Item	addManual(ILookupControlInstance<?> lci) Add a manually-created lookup control instance to the item list.
<VT,X extends NodeBase & IControl<VT>> LookupForm.Item	addManual(String property, X control) Add a manually created control and link it to some property.
LookupForm.Item	addManualPropertyLabel(String property, ILookupControlInstance<?> lci) Adds a manually-defined control, and use the specified property as the source for its default label.
LookupForm.Item	addManualTextLabel(String labelText, ILookupControlInstance<?> lci) Add a manually-created lookup control instance with user-specified label to the item list.
LookupForm.Item	addProperty(String path) Add a property to look up to the list.
LookupForm.Item	addProperty(String path, int minlen) Add a property to look up to the list.
LookupForm.Item	addProperty(String path, int minlen, boolean ignorecase) Add a property to look up to the list.
LookupForm.Item	addProperty(String path, String label) Add a property to look up to the list with user-specified label.
void	clearInput() Tells all input items to clear their content, clearing all user choices from the form.
void	createContent() Actually show the thingy.
protected void	defineDefaultButtons()
ButtonFactory	getButtonFactory()
DefaultButton	getClearButton()
QCriteria<T>	getEnteredCriteria() This checks all of the search fields for data.
Map<String,?>	getFilterValues()
Class<T>	getLookupClass() Returns the class whose instances we're looking up (a persistent class somehow).
ClassMetaModel	getMetaModel() Return the metamodel that this class uses to get its data from.
IClicked<NodeBase>	getOnAfterCollapse() Returns listener to after collapse event.
IClicked<NodeBase>	getOnAfterRestore() Returns listener to after restore event.
IClicked<LookupForm<T>>	getOnCancel()
IClicked<? extends LookupForm<T>>	getOnClear()
IClicked<LookupForm<T>>	getOnNew() Sets the onNew handler.
String	getPageTitle() Returns the search block's part title, if present.
IQueryFactory<T>	getQueryFactory() Returns custom query factory.
IClicked<LookupForm<T>>	getSearchClicked()
boolean	hasUserDefinedCriteria() Method getEnteredCriteria() MUST BE EXECUTED BEFORE checking for this property value! This is T when the user has actually entered something in one of the search components.
boolean	isCollapsed() Returns if LookupForm is collapsed.
boolean	isSearchFilterEnabled()
void	reset() Clear out the entire definition for this lookup form.
void	setClicked(IClickBase<?> clicked) Set the handler to call when the "Search" button is clicked.
void	setCollapsed(boolean collapsed) Use to collapse/restore LookupForm search pannel.
void	setDefaultItems() This adds all properties that are defined as "search" properties in either this control or the metadata to the item list.
static void	setLookupFilterHandler(ILookupFilterHandler filterSaver)
void	setOnAfterCollapse(IClicked<NodeBase> onAfterCollapse) Attach listener to after collpase event.
void	setOnAfterRestore(IClicked<NodeBase> onAfterRestore) Attach listener to after restore event.
void	setOnCancel(IClicked<LookupForm<T>> onCancel) When set, this causes a "cancel" button to be added to the form.
void	setOnClear(IClicked<? extends LookupForm<T>> onClear) Listener to call when the "clear" button is pressed.
void	setOnNew(IClicked<LookupForm<T>> onNew) Returns the onNew handler.
void	setPageTitle(String title) Sets a part title for this search block.
void	setQueryFactory(IQueryFactory<T> queryFactory) Specifies custom query factory.
void	setSearchFilterEnabled(boolean searchFilterEnabled)
void	setSearchProperties(List<SearchPropertyMetaModel> list) Set the search properties to use from a list of metadata properties.
void	setTwoColumnsMode(int minSizeForTwoColumnsMode) Sets rendering of search fields into two columns.

Methods inherited from class to.etc.domui.dom.html.Div

afterCreateContent, componentHandleWebAction, fadeIn, fadeOut, getCustomUpdatesCallJS, getDragHandler, getDropBody, getDropHandler, getDropMode, getReturnPressed, setDragHandler, setDropBody, setDropHandler, setReturnPressed, slideDown, slideUp, tb, visit

Methods inherited from class to.etc.domui.dom.html.NodeContainer

add, add, add, addTable, addTableForLayout, addTableForLayout, appendTreeErrors, canContain, createFrame, delegateTo, disableAllChildControlsDeep, findChildIndex, forceRebuild, getChild, getChildCount, getChildren, getDeepChildren, getDelegate, getErrorFence, getTextContents, hasError, internalAdd, internalCheckNotDirty, internalClearDelta, internalClearDeltaFully, internalCreateFrame, internalGetNodeCount, internalGetOldChildren, internalOnBeforeRender, internalShelve, internalUnshelve, iterator, onRefresh, removeAllChildren, removeChild, removeChild, replaceChild, setErrorFence, setErrorFence, setText, setValue, undelegatedAdd, undelegatedGetChild

Methods inherited from class to.etc.domui.dom.html.NodeBase

$, acceptRequestParameter, addBinding, addCssClass, addGlobalMessage, addNotificationListener, alignToLeft, alignToLeft, alignToMiddle, alignToMiddle, alignTopToBottom, alignTopToBottom, alignToRight, alignToRight, alignToTop, alignToTop, appendAfterMe, appendBeforeMe, appendCreateJS, appendJavascript, appendJQuerySelector, appendJsCustomUpdatesContributor, appendShowOverflowTextAsTitleJs, appendStatement, beforeCreateContent, bind, bind, bindErrors, build, calcTestID, changed, changedJavascriptState, clearFocusRequested, clearGlobalMessage, clearGlobalMessage, clearGlobalMessage, clearMessage, clearValidationFailure, componentHandleWebDataRequest, createStatement, findComponentBundle, findParent, getActualID, getAllocationTracepoint, getBindingErrors, getBindingList, getBrowserWindowSize, getCalculatedTestID, getClicked, getClientBounds, getComponentBundle, getComponentDataURL, getComponentDataURL, getComponentInfo, getComponentJSONURL, getCreateJS, getCssClass, getErrorList, getErrorLocation, getFocusID, getMessage, getOnClickJS, getOnMouseDownJS, getOnSizeAndPositionChange, getPage, getParent, getParent, getParent, getParentOfTypes, getSharedContext, getSharedContextFactory, getSpecialAttribute, getSpecialAttributeList, getTag, getTestID, getTestRepeatId, getThemedResourceRURL, getTitle, getUserObject, handleDrop, hasCssClass, hasParent, internalGetOldParent, internalGetParent, internalHasChangedAttributes, internalNeedClickHandler, internalOnClicked, internalOnValueChanged, internalRenderJavascriptDelta, internalRenderJavascriptState, internalSetHasChangedAttributes, internalSetHasChangedAttributes, internalSetLogAllocations, internalSetTag, isAttached, isBuilt, isFocusable, isFocusRequested, isRendersOwnClose, isStretchHeight, lc, notify, notifyParentOrOpenerPage, onAddedToPage, onBeforeFullRender, onBeforeRender, onForceRebuild, onHeaderContributors, onRemoveFromPage, onShelve, onUnshelve, refresh, remove, removeBinding, removeCssClass, renderJavascriptDelta, renderJavascriptState, renderJavascriptState, replaceWith, setBrowserWindowSize, setCalculcatedId, setCalculcatedId, setClientBounds, setComponentBundle, setCssClass, setErrorLocation, setFocus, setMessage, setOnClickJS, setOnMouseDownJS, setOnSizeAndPositionChange, setOverrideTitle, setSpecialAttribute, setStretchHeight, setTestID, setTestRepeatID, setTitle, setUserObject, toString

Methods inherited from class to.etc.domui.dom.css.CssBase

getBackgroundAttachment, getBackgroundColor, getBackgroundImage, getBackgroundPosition, getBackgroundRepeat, getBorderBottomColor, getBorderBottomStyle, getBorderBottomWidth, getBorderLeftColor, getBorderLeftStyle, getBorderLeftWidth, getBorderRightColor, getBorderRightStyle, getBorderRightWidth, getBorderTopColor, getBorderTopStyle, getBorderTopWidth, getBottom, getCachedStyle, getClear, getColor, getDisplay, getFloat, getFontFamily, getFontSize, getFontSizeAdjust, getFontStyle, getFontVariant, getFontWeight, getHeight, getLeft, getLineHeight, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOverflow, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPosition, getRight, getTextAlign, getTop, getTransform, getVerticalAlign, getVisibility, getWidth, getZIndex, internalSetDisplay, setBackgroundAttachment, setBackgroundColor, setBackgroundImage, setBackgroundPosition, setBackgroundRepeat, setBorder, setBorder, setBorderBottomColor, setBorderBottomStyle, setBorderBottomWidth, setBorderColor, setBorderLeftColor, setBorderLeftStyle, setBorderLeftWidth, setBorderRightColor, setBorderRightStyle, setBorderRightWidth, setBorderStyle, setBorderTopColor, setBorderTopStyle, setBorderTopWidth, setBorderWidth, setBottom, setBottom, setCachedStyle, setClear, setColor, setDisplay, setFloat, setFontFamily, setFontSize, setFontSizeAdjust, setFontStyle, setFontVariant, setFontWeight, setHeight, setLeft, setLeft, setLineHeight, setMargin, setMarginBottom, setMarginLeft, setMarginRight, setMarginTop, setMaxHeight, setMaxWidth, setMinHeight, setMinWidth, setOverflow, setPadding, setPaddingBottom, setPaddingLeft, setPaddingRight, setPaddingTop, setPosition, setRight, setRight, setTextAlign, setTop, setTop, setTransform, setVerticalAlign, setVisibility, setWidth, setZIndex

Methods inherited from class java.lang.Object

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

Methods inherited from interface to.etc.domui.component.layout.IButtonContainer

getPage

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

LookupForm

public LookupForm(@Nonnull
                  Class<T> lookupClass,
                  String... propertyList)

LookupForm

public LookupForm(@Nonnull
                  Class<T> lookupClass,
                  @Nullable
                  ClassMetaModel cmm,
                  String... propertyList)

Create a LookupForm to find instances of the specified class.

Parameters:

lookupClass -

LookupForm

public LookupForm(@Nonnull
                  QCriteria<T> rootCriteria,
                  String... propertyList)

Method Detail

getClearButton

@Nullable
public DefaultButton getClearButton()

getFilterValues

public Map<String,?> getFilterValues()

isSearchFilterEnabled

public boolean isSearchFilterEnabled()

setSearchFilterEnabled

public void setSearchFilterEnabled(boolean searchFilterEnabled)

getMetaModel

@Nonnull
public ClassMetaModel getMetaModel()

Return the metamodel that this class uses to get its data from.

Returns:

getLookupClass

@Nonnull
public Class<T> getLookupClass()

Returns the class whose instances we're looking up (a persistent class somehow).

Returns:

createContent

public void createContent()
                   throws Exception

Actually show the thingy.

Overrides:

createContent in class NodeBase

Throws:

Exception

See Also:

NodeBase.createContent()

setLookupFilterHandler

public static void setLookupFilterHandler(@Nullable
                                          ILookupFilterHandler filterSaver)

defineDefaultButtons

protected void defineDefaultButtons()

addFilterButton

public void addFilterButton()

setDefaultItems

public void setDefaultItems()

This adds all properties that are defined as "search" properties in either this control or the metadata to the item list. The list is cleared before that!

setSearchProperties

public void setSearchProperties(List<SearchPropertyMetaModel> list)

Set the search properties to use from a list of metadata properties.

Parameters:

list -

addProperty

public LookupForm.Item addProperty(String path,
                                   int minlen,
                                   boolean ignorecase)

Add a property to look up to the list. The controls et al will be added using the factories.

Parameters:

path - The property name (or path to some PARENT property) to search on, relative to the lookup class.

minlen -

ignorecase -

addProperty

public LookupForm.Item addProperty(String path,
                                   int minlen)

Add a property to look up to the list. The controls et al will be added using the factories.

Parameters:

path - The property name (or path to some PARENT property) to search on, relative to the lookup class.

minlen -

addProperty

public LookupForm.Item addProperty(String path,
                                   String label)

Add a property to look up to the list with user-specified label. The controls et al will be added using the factories.

Parameters:

path - The property name (or path to some PARENT property) to search on, relative to the lookup class.

label - The label text to use. Use the empty string to prevent a label from being generated. This still adds an empty cell for the label though.

addProperty

public LookupForm.Item addProperty(String path)

Add a property to look up to the list. The controls et al will be added using the factories.

Parameters:

path - The property name (or path to some PARENT property) to search on, relative to the lookup class.

addItemBreak

public void addItemBreak()

addManual

public LookupForm.Item addManual(ILookupControlInstance<?> lci)

Add a manually-created lookup control instance to the item list.

Returns:

addManual

public <VT,X extends NodeBase & IControl<VT>> LookupForm.Item addManual(String property,
                                                                        X control)

Add a manually created control and link it to some property. The controls's configuration must be fully done by the caller; this will ask control factories to provide an ILookupControlInstance for the property and control passed in. The label for the lookup will come from property metadata.

Type Parameters:

X -

Parameters:

property -

control -

Returns:

addManualTextLabel

public LookupForm.Item addManualTextLabel(String labelText,
                                          ILookupControlInstance<?> lci)

Add a manually-created lookup control instance with user-specified label to the item list.

Returns:

addManualPropertyLabel

public LookupForm.Item addManualPropertyLabel(String property,
                                              ILookupControlInstance<?> lci)

Adds a manually-defined control, and use the specified property as the source for its default label.

Parameters:

property -

lci -

Returns:

addChildProperty

public LookupForm.Item addChildProperty(String propPath)

Add lookup control instance for search properties on child list (oneToMany relation) members. This adds a query by using the "exists" subquery for the child record. See QCriteria rules for details.

Parameters:

propPath - Must be parentprop.childprop dotted form. Label is used from parent property meta.

addChildPropertyLabel

public LookupForm.Item addChildPropertyLabel(String label,
                                             String propPath)

Add lookup control instance for search properties on child list (oneToMany relation) members. This adds a query by using the "exists" subquery for the child record. See QCriteria rules for details.

Parameters:

label - Label that is displayed. If null, default label from parent property meta is used.

propPath - Must be parentprop.childprop dotted form.

reset

public void reset()

Clear out the entire definition for this lookup form. After this it needs to be recreated completely.

addItem

public void addItem(@Nullable
                    NodeBase left,
                    @Nullable
                    NodeBase right)

With this method you can place a NodeBase in the left (label) column and one in the right (control) column. If you use the left column only, you can tell whether this column should be spread across both columns. (A colspan=2 will be added in that case)

addItem

public void addItem(@Nullable
                    NodeBase cell)

With this method you can place a NodeBase in the table where it will fill the entire row. A colspan=2 will be added

getEnteredCriteria

@Nullable
public QCriteria<T> getEnteredCriteria()
                                          throws Exception

This checks all of the search fields for data. For every field that contains search data we check if the data is suitable for searching (not too short for instance); if it is we report errors. If the data is suitable and at least one field is filled we create a Criteria containing the search criteria. If anything goes wrong (one of the above mentioned errors occurs) ths returns null. If none of the input fields have data this will return a Criteria object, but the restrictions count in it will be zero. This can be used to query but will return all records.

Internal working

Internally this just walks the list of thingies added when the components were added to the form. Each thingy refers to the input components used to register the search on a property, and knows how to convert that thingy to a criteria fragment.

Returns:

Throws:

Exception

clearInput

public void clearInput()

Tells all input items to clear their content, clearing all user choices from the form. After this call, the form should return an empty QCriteria without any restrictions.

getOnNew

public IClicked<LookupForm<T>> getOnNew()

Sets the onNew handler. When set this will render a "new" button in the form's button bar.

Returns:

setOnNew

public void setOnNew(IClicked<LookupForm<T>> onNew)

Returns the onNew handler. When set this will render a "new" button in the form's button bar.

Parameters:

onNew -

getPageTitle

public String getPageTitle()

Returns the search block's part title, if present. Returns null if the title is not set.

setPageTitle

public void setPageTitle(String title)

Sets a part title for this search block. When unset the search block does not have a title, when set the search block will be shown inside a CaptionedPanel.

Parameters:

title -

setClicked

public void setClicked(@Nullable
                       IClickBase<?> clicked)

Set the handler to call when the "Search" button is clicked.

Overrides:

setClicked in class NodeBase

See Also:

to.etc.domui.dom.html.NodeBase#setClicked(to.etc.domui.dom.html.IClicked)

getSearchClicked

public IClicked<LookupForm<T>> getSearchClicked()

getOnClear

public IClicked<? extends LookupForm<T>> getOnClear()

setOnClear

public void setOnClear(IClicked<? extends LookupForm<T>> onClear)

Listener to call when the "clear" button is pressed.

Parameters:

onClear -

setOnCancel

public void setOnCancel(IClicked<LookupForm<T>> onCancel)

When set, this causes a "cancel" button to be added to the form. When that button is pressed this handler gets called.

Parameters:

onCancel -

getOnCancel

public IClicked<LookupForm<T>> getOnCancel()

addButtonItem

public void addButtonItem(NodeBase b)

addButtonItem

public void addButtonItem(NodeBase b,
                          int order)

Add a button (or other item) to show on the button row. The item will be visible always.

Parameters:

b -

order -

addButtonItem

public void addButtonItem(NodeBase b,
                          int order,
                          LookupForm.ButtonMode both)

Add a button (or other item) to show on the button row.

Parameters:

b -

order -

both -

setTwoColumnsMode

public void setTwoColumnsMode(int minSizeForTwoColumnsMode)

Sets rendering of search fields into two columns. It is in use only in case when search fields are loaded from metadata and search fields count reach minSizeForTwoColumnsMode value.

Parameters:

minSizeForTwoColumnsMode -

hasUserDefinedCriteria

public boolean hasUserDefinedCriteria()

Method getEnteredCriteria() MUST BE EXECUTED BEFORE checking for this property value! This is T when the user has actually entered something in one of the search components. Any restriction that has been added by code that is not depending on user input is ignored.

Returns:

isCollapsed

public boolean isCollapsed()

Returns if LookupForm is collapsed.

Returns:

setCollapsed

public void setCollapsed(boolean collapsed)
                  throws Exception

Use to collapse/restore LookupForm search pannel.

Parameters:

collapsed -

Throws:

Exception

getOnAfterRestore

public IClicked<NodeBase> getOnAfterRestore()

Returns listener to after restore event.

Returns:

the onAfterRestore

setOnAfterRestore

public void setOnAfterRestore(IClicked<NodeBase> onAfterRestore)

Attach listener to after restore event.

Parameters:

onAfterRestore - the onAfterRestore to set

getOnAfterCollapse

public IClicked<NodeBase> getOnAfterCollapse()

Returns listener to after collapse event.

Returns:

the onAfterCollpase

setOnAfterCollapse

public void setOnAfterCollapse(IClicked<NodeBase> onAfterCollapse)

Attach listener to after collpase event.

Parameters:

onAfterCollapse - the onAfterCollapse to set

getQueryFactory

public IQueryFactory<T> getQueryFactory()

Returns custom query factory.

Returns:

setQueryFactory

public void setQueryFactory(IQueryFactory<T> queryFactory)

Specifies custom query factory.

Parameters:

queryFactory -

addButton

public void addButton(@Nonnull
                      NodeBase thing,
                      int order)

Specified by:

addButton in interface IButtonContainer

See Also:

IButtonContainer.addButton(to.etc.domui.dom.html.NodeBase, int)

getButtonFactory

@Nonnull
public ButtonFactory getButtonFactory()