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

java.lang.Object
  extended by to.etc.domui.dom.css.CssBase
      extended by to.etc.domui.dom.html.NodeBase
          extended by to.etc.domui.dom.html.NodeContainer
              extended by to.etc.domui.dom.html.Div
                  extended by to.etc.domui.component.lookup.LookupForm<T>
All Implemented Interfaces:
java.lang.Iterable<NodeBase>, IModelBinding, INodeErrorDelegate, IDraggable, IDropTargetable

public class LookupForm<T>
extends Div

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 eachother 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 it's 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 it's 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
static class LookupForm.ButtonMode
           
static class LookupForm.Item
          This is the definition for an Item to look up.
 
Constructor Summary
LookupForm(java.lang.Class<T> lookupClass, ClassMetaModel cmm, java.lang.String... propertyList)
          Create a LookupForm to find instances of the specified class.
LookupForm(java.lang.Class<T> lookupClass, java.lang.String... propertyList)
           
 
Method Summary
 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(java.lang.String propPath)
          Add lookup control instance for search properties on child list (oneToMany relation) members.
 LookupForm.Item addChildPropertyLabel(java.lang.String label, java.lang.String propPath)
          Add lookup control instance for search properties on child list (oneToMany relation) members.
 void addItemBreak()
           
 LookupForm.Item addManual(ILookupControlInstance lci)
          Add a manually-created lookup control instance to the item list.
<X extends NodeBase & IInputNode<?>>
LookupForm.Item
addManual(java.lang.String property, X control)
          Add a manually created control and link it to some property.
 LookupForm.Item addManualPropertyLabel(java.lang.String property, ILookupControlInstance lci)
          Adds a manually-defined control, and use the specified property as the source for it's default label.
 LookupForm.Item addManualTextLabel(java.lang.String labelText, ILookupControlInstance lci)
          Add a manually-created lookup control instance with user-specified label to the item list.
 LookupForm.Item addProperty(java.lang.String path)
          Add a property to look up to the list.
 LookupForm.Item addProperty(java.lang.String path, int minlen)
          Add a property to look up to the list.
 LookupForm.Item addProperty(java.lang.String path, int minlen, boolean ignorecase)
          Add a property to look up to the list.
 LookupForm.Item addProperty(java.lang.String path, java.lang.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()
           
 QCriteria<T> getEnteredCriteria()
          This checks all of the search fields for data.
 java.lang.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 it's 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.
 java.lang.String getPageTitle()
          Returns the search block's part title, if present.
 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.
 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 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(java.lang.String title)
          Sets a part title for this search block.
 void setSearchProperties(java.util.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, canContain, delegateTo, findChildIndex, forceRebuild, getChild, getChildCount, getChildren, getDeepChild, getDeepChildren, getErrorFence, internalCheckNotDirty, internalClearDelta, internalClearDeltaFully, internalGetOldChildren, internalShelve, internalUnshelve, iterator, moveControlToModel, moveModelToControl, onRefresh, removeAllChildren, removeChild, removeChild, replaceChild, setControlsEnabled, setErrorFence, setErrorFence, setText, setValue
 
Methods inherited from class to.etc.domui.dom.html.NodeBase
$, acceptRequestParameter, addCssClass, addGlobalMessage, appendAfterMe, appendBeforeMe, appendCreateJS, appendJavascript, build, changed, clearFocusRequested, clearGlobalMessage, clearGlobalMessage, clearGlobalMessage, clearMessage, findComponentBundle, getActualID, getAllocationTracepoint, getClicked, getComponentBundle, getCreateJS, getCssClass, getErrorDelegate, getErrorLocation, getMessage, getOnClickJS, getOnMouseDownJS, getPage, getParent, getParent, getParent, getSharedContext, getSpecialAttribute, getSpecialAttributeList, getTag, getTestID, getTitle, getUserObject, handleDrop, hasCssClass, hasError, internalGetOldParent, internalHasChangedAttributes, internalNeedClickHandler, internalOnClicked, internalOnValueChanged, internalSetHasChangedAttributes, internalSetHasChangedAttributes, internalSetLogAllocations, internalSetTag, isBuilt, isFocusRequested, isStretchHeight, onAddedToPage, onBeforeFullRender, onForceRebuild, onHeaderContributors, onRemoveFromPage, onShelve, onUnshelve, refresh, remove, removeCssClass, renderJavascriptState, replaceWith, setComponentBundle, setCssClass, setErrorDelegate, setErrorLocation, setFocus, setMessage, setOnClickJS, setOnMouseDownJS, setSpecialAttribute, setStretchHeight, setTestID, 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, 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, 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
 

Constructor Detail

LookupForm

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

LookupForm

public LookupForm(@Nonnull
                  java.lang.Class<T> lookupClass,
                  @Nullable
                  ClassMetaModel cmm,
                  java.lang.String... propertyList)
Create a LookupForm to find instances of the specified class.

Parameters:
lookupClass -
Method Detail

getMetaModel

@Nonnull
public ClassMetaModel getMetaModel()
Return the metamodel that this class uses to get it's data from.

Returns:

getLookupClass

@Nonnull
public java.lang.Class<T> getLookupClass()
Returns the class whose instances we're looking up (a persistent class somehow).

Returns:

createContent

public void createContent()
                   throws java.lang.Exception
Actually show the thingy.

Overrides:
createContent in class NodeBase
Throws:
java.lang.Exception
See Also:
NodeBase.createContent()

defineDefaultButtons

protected void defineDefaultButtons()

setSearchProperties

public void setSearchProperties(java.util.List<SearchPropertyMetaModel> list)
Set the search properties to use from a list of metadata properties.

Parameters:
list -

addProperty

public LookupForm.Item addProperty(java.lang.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(java.lang.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(java.lang.String path,
                                   java.lang.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(java.lang.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 <X extends NodeBase & IInputNode<?>> LookupForm.Item addManual(java.lang.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(java.lang.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(java.lang.String property,
                                              ILookupControlInstance lci)
Adds a manually-defined control, and use the specified property as the source for it's default label.

Parameters:
property -
lci -
Returns:

addChildProperty

public LookupForm.Item addChildProperty(java.lang.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(java.lang.String label,
                                             java.lang.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.


getEnteredCriteria

public QCriteria<T> getEnteredCriteria()
                                throws java.lang.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:
java.lang.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 java.lang.String getPageTitle()
Returns the search block's part title, if present. Returns null if the title is not set.


setPageTitle

public void setPageTitle(java.lang.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(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)

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. See Lookuporm#m_collapsed.

Returns:

setCollapsed

public void setCollapsed(boolean collapsed)
                  throws java.lang.Exception
Use to collapse/restore LookupForm search pannel. See Lookuporm#m_collapsed.

Parameters:
collapsed -
Throws:
java.lang.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