org.kuali.rice.kns.uif.core
Interface Component

All Superinterfaces:

org.springframework.core.Ordered, ScriptEventSupport, Serializable

All Known Subinterfaces:

Container, Control, Field, Widget

All Known Implementing Classes:

Accordion, ActionField, AttributeField, BlankField, BreadCrumbs, CheckboxControl, CheckboxGroupControl, CollectionGroup, ComponentBase, ContainerBase, ControlBase, DatePicker, DirectInquiry, DocumentView, ErrorsField, FieldBase, FileControl, FormView, GeneratedField, GenericField, Group, GroupField, GrowlsWidget, HeaderField, Help, HiddenControl, IframeField, ImageField, Inquiry, InquiryView, LabelField, LightBox, LightBoxLookup, LinkField, LookupCriteriaAttributeField, LookupView, MaintenanceView, MessageField, MultiValueControlBase, NavigationGroup, PageGroup, QuickFinder, RadioGroupControl, SelectControl, Suggest, TabGroup, TableTools, Tabs, TextAreaControl, TextControl, TreeGroup, TreeWidget, View, WidgetBase

public interface Component
extends Serializable, Ordered, ScriptEventSupport

All classes of the UIF that are used as a rendering element implement the component interface. This interface defines basic properties and methods that all such classes much implement. All components within the framework have the following structure:

• Dictionary Configuration/Composition
• Java Class (the Component implementation
• >JSP Template Renderer

There are three basic types of components:

• Container Components: View, Group
• Field Components: Field
• Widget Components: Widget

Author:

Kuali Rice Team (rice.collab@kuali.org)

See Also:

Container, Field, Widget

Field Summary

Fields inherited from interface org.kuali.rice.kns.uif.core.Ordered

INITIAL_ORDER_VALUE

Fields inherited from interface org.springframework.core.Ordered

HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE

Method Summary

void	addStyleClass(String styleClass) Adds a single style to the list of styles on this component
void	appendToStyle(String itemStyle) TODO: javadoc
int	getColSpan() Number of places the component should take up horizontally in the container
List<ComponentModifier>	getComponentModifiers() ComponentModifier instances that should be invoked to initialize the component
Map<String,String>	getComponentOptions() Options that are passed through to the Component renderer.
String	getComponentTypeName() The name for the component type
String	getConditionalReadOnly() Expression language string for conditionally setting the readOnly property
String	getConditionalRefresh()
String	getConditionalRefreshConditionJs()
List<String>	getConditionalRefreshControlNames()
String	getConditionalRender() Expression language string for conditionally setting the render property
Map<String,Object>	getContext() Context map for the component
MethodInvokerConfig	getFinalizeMethodInvoker() MethodInvokerConfig instance for the method that should be invoked for finalizing the component configuration
String	getFinalizeMethodToCall() Name of the method that should be invoked for finalizing the component configuration (full method name, without parameters or return type)
String	getId() The unique id (within a given tree) for the component
List<Component>	getNestedComponents() List of components that are contained within the component
int	getOrder() Can be used to order a component within a List of other components, lower numbers are placed higher up in the list, while higher numbers are placed lower in the list
String	getProgressiveDisclosureConditionJs()
List<String>	getProgressiveDisclosureControlNames()
String	getProgressiveRender()
Set<String>	getPropertiesForReferenceCopy() Used by the copy process to determine for which properties only the value reference should be copied (not a new copy instance).
List<PropertyReplacer>	getPropertyReplacers() List of PropertyReplacer instances that will be evaluated during the view lifecycle to conditional set properties on the Component based on expression evaluations
String	getRefreshWhenChanged() Specifies a property by name that when it value changes will automatically perform a refresh on this component.
List<String>	getRefreshWhenChangedControlNames() Control names which will refresh this component when they are changed, added internally
String	getRenderOutput() Rendering output for the component that will be sent as part of the response (can contain static text and HTML)
Boolean	getRequired() Indicates whether the component is required
int	getRowSpan() Number of places the component should take up vertically in the container
String	getStyle() CSS style string to be applied to the component
List<String>	getStyleClasses() CSS style class(s) to be applied to the component
String	getTemplate() The path to the JSP file that should be called to render the component
String	getTitle() A title for the component.
boolean	isHidden() Indicates whether the component should be hidden in the UI
boolean	isProgressiveRenderAndRefresh() If true, when the progressiveRender condition is satisfied, the component will always be retrieved from the server and shown(as opposed to being stored on the client, but hidden, after the first retrieval as is the case with the progressiveRenderViaAJAX option).
boolean	isProgressiveRenderViaAJAX()
boolean	isReadOnly() Indicates whether the component can be edited
boolean	isRefresh() Result of the conditionalRefresh expression, true if satisfied, otherwise false.
boolean	isRender() Indicates whether the component should be rendered in the UI
boolean	isSelfRendered() Indicates whether the component contains its own render output (through the renderOutput property)
void	performApplyModel(View view, Object model) Called after the initialize phase to perform conditional logic based on the model data
void	performFinalize(View view, Object model, Component parent) The last phase before the view is rendered.
void	performInitialization(View view) Should be called to initialize the component
void	pushObjectToContext(String objectName, Object object) Places the given object into the context Map for the component with the given name
void	setColSpan(int colSpan) Setter for the components column span
void	setComponentModifiers(List<ComponentModifier> componentModifiers) Setter for the components List of ComponentModifier instances
void	setComponentOptions(Map<String,String> componentOptions) Setter for the widget's options
void	setConditionalReadOnly(String conditionalReadOnly) Setter for the conditional readOnly string
void	setConditionalRefresh(String conditionalRefresh)
void	setConditionalRender(String conditionalRender) Setter for the conditional render string
void	setContext(Map<String,Object> context) Setter for the context Map
void	setHidden(boolean hidden) Setter for the hidden indicator
void	setId(String id) Sets the unique id (within a given tree) for the component
void	setOrder(int order) Setter for the component's order
void	setProgressiveRender(String progressiveRender)
void	setProgressiveRenderAndRefresh(boolean progressiveRenderAndRefresh)
void	setProgressiveRenderViaAJAX(boolean progressiveRenderViaAJAX)
void	setPropertyReplacers(List<PropertyReplacer> propertyReplacers) Setter for the components property substitutions
void	setReadOnly(boolean readOnly) Setter for the read only indicator
void	setRefresh(boolean refresh)
void	setRefreshWhenChanged(String refreshWhenChanged)
void	setRender(boolean render) Setter for the components render indicator
void	setRenderOutput(String renderOutput) Setter for the component's render output
void	setRequired(Boolean required) Setter for the required indicator
void	setRowSpan(int rowSpan) Setter for the component row span
void	setSelfRendered(boolean selfRendered) Setter for the self render indicator
void	setStyle(String style) Setter for the components style
void	setStyleClasses(List<String> styleClasses) Setter for the components style classes
void	setTemplate(String template) Setter for the components template
void	setTitle(String title) Setter for the components title

Methods inherited from interface org.kuali.rice.kns.uif.core.ScriptEventSupport

getOnBlurScript, getOnChangeScript, getOnClickScript, getOnCloseScript, getOnDblClickScript, getOnDocumentReadyScript, getOnFocusScript, getOnKeyDownScript, getOnKeyPressScript, getOnKeyUpScript, getOnLoadScript, getOnMouseDownScript, getOnMouseMoveScript, getOnMouseOutScript, getOnMouseOverScript, getOnMouseUpScript, getOnSubmitScript, getOnUnloadScript, getSupportsOnBlur, getSupportsOnChange, getSupportsOnClick, getSupportsOnClose, getSupportsOnDblClick, getSupportsOnDocumentReady, getSupportsOnFocus, getSupportsOnKeyDown, getSupportsOnKeyPress, getSupportsOnKeyUp, getSupportsOnLoad, getSupportsOnMouseDown, getSupportsOnMouseMove, getSupportsOnMouseOut, getSupportsOnMouseOver, getSupportsOnMouseUp, getSupportsOnSubmit, getSupportsOnUnload, setOnBlurScript

Method Detail

getId

String getId()

The unique id (within a given tree) for the component

The id will be used by renderers to set the HTML element id. This gives a way to find various elements for scripting. If the id is not given, a default will be generated by the framework

Returns:

String id

setId

void setId(String id)

Sets the unique id (within a given tree) for the component

Parameters:

id - - string to set as the component id

getComponentTypeName

String getComponentTypeName()

The name for the component type

This is used within the rendering layer to pass the component instance into the template. The component instance is exported under the name given by this method.

Returns:

String type name

getTemplate

String getTemplate()

The path to the JSP file that should be called to render the component

The path should be relative to the web root. An attribute will be available to the component to use under the name given by the method getComponentTypeName. Based on the component type, additional attributes could be available for use. See the component documentation for more information on such attributes.

e.g. '/krad/WEB-INF/jsp/tiles/component.jsp'

Returns:

String representing the template path

setTemplate

void setTemplate(String template)

Setter for the components template

Parameters:

template -

getTitle

String getTitle()

A title for the component. Depending on the component can be used in various ways. For example with a Container component the title is used to set the header text. For components like controls other other components that render an HTML element it is used to set the HTML title attribute

Returns:

String title for component

setTitle

void setTitle(String title)

Setter for the components title

Parameters:

title -

performInitialization

void performInitialization(View view)

Should be called to initialize the component

Where components can set defaults and setup other necessary state. The initialize method should only be called once per component lifecycle and is invoked within the initialize phase of the view lifecylce.

Parameters:

view - - view instance in which the component belongs

See Also:

ViewHelperService#initializeComponent

performApplyModel

void performApplyModel(View view,
                       Object model)

Called after the initialize phase to perform conditional logic based on the model data

Where components can perform conditional logic such as dynamically generating new fields or setting field state based on the given data

Parameters:

view - - view instance to which the component belongs

model - - Top level object containing the data (could be the form or a top level business object, dto)

performFinalize

void performFinalize(View view,
                     Object model,
                     Component parent)

The last phase before the view is rendered. Here final preparations can be made based on the updated view state

Parameters:

view - - view instance that should be finalized for rendering

model - - top level object containing the data

parent - - parent component

getNestedComponents

List<Component> getNestedComponents()

List of components that are contained within the component

Used by ViewHelperService for the various lifecycle callbacks

Returns:

List child components

getComponentModifiers

List<ComponentModifier> getComponentModifiers()

ComponentModifier instances that should be invoked to initialize the component

These provide dynamic initialization behavior for the component and are configured through the components definition. Each initializer will get invoked by the initialize method.

Returns:

List of component modifiers

See Also:

ViewHelperService#initializeComponent

setComponentModifiers

void setComponentModifiers(List<ComponentModifier> componentModifiers)

Setter for the components List of ComponentModifier instances

Parameters:

componentModifiers -

getPropertiesForReferenceCopy

Set<String> getPropertiesForReferenceCopy()

Used by the copy process to determine for which properties only the value reference should be copied (not a new copy instance). Subclasses can define the properties for which only the reference should be copied

Returns:

Set property names for which only the value reference should be copied

See Also:

org.kuali.rice.kns.uif.util.ComponentUtils.copy(T)

isRender

boolean isRender()

Indicates whether the component should be rendered in the UI

If set to false, the corresponding component template will not be invoked (therefore nothing will be rendered to the UI).

Returns:

boolean true if the component should be rendered, false if it should not be

setRender

void setRender(boolean render)

Setter for the components render indicator

Parameters:

render -

getConditionalRender

String getConditionalRender()

Expression language string for conditionally setting the render property

Returns:

String el that should evaluate to boolean

setConditionalRender

void setConditionalRender(String conditionalRender)

Setter for the conditional render string

Parameters:

conditionalRender -

isHidden

boolean isHidden()

Indicates whether the component should be hidden in the UI

How the hidden data is maintained depends on the views persistence mode. If the mode is request, the corresponding data will be rendered to the UI but not visible. If the mode is session, the data will not be rendered to the UI but maintained server side.

For a Container component, the hidden setting will apply to all contained components (making a section hidden makes all fields within the section hidden)

Returns:

boolean true if the component should be hidden, false if it should be visible

setHidden

void setHidden(boolean hidden)

Setter for the hidden indicator

Parameters:

hidden -

isReadOnly

boolean isReadOnly()

Indicates whether the component can be edited

When readOnly the controls and widgets of Field components will not be rendered. If the Field has an underlying value it will be displayed readOnly to the user.

For a Container component, the readOnly setting will apply to all contained components (making a section readOnly makes all fields within the section readOnly)

Returns:

boolean true if the component should be readOnly, false if is allows editing

setReadOnly

void setReadOnly(boolean readOnly)

Setter for the read only indicator

Parameters:

readOnly -

getConditionalReadOnly

String getConditionalReadOnly()

Expression language string for conditionally setting the readOnly property

Returns:

String el that should evaluate to boolean

setConditionalReadOnly

void setConditionalReadOnly(String conditionalReadOnly)

Setter for the conditional readOnly string

Parameters:

conditionalReadOnly -

getRequired

Boolean getRequired()

Indicates whether the component is required

At the general component level required means there is some action the user needs to take within the component. For example, within a section it might mean the fields within the section should be completed. At a field level, it means the field should be completed. This provides the ability for the renderers to indicate the required action.

Returns:

boolean true if the component is required, false if it is not required

setRequired

void setRequired(Boolean required)

Setter for the required indicator

Parameters:

required -

getStyle

String getStyle()

CSS style string to be applied to the component

Any style override or additions can be specified with this attribute. This is used by the renderer to set the style attribute on the corresponding element.

e.g. 'color: #000000;text-decoration: underline;'

Returns:

String css style string

setStyle

void setStyle(String style)

Setter for the components style

Parameters:

style -

getStyleClasses

List<String> getStyleClasses()

CSS style class(s) to be applied to the component

Declares style classes for the component. Multiple classes are specified with a space delimiter. This is used by the renderer to set the class attribute on the corresponding element. The class(s) declared must be available in the common style sheets or the style sheets specified for the view

e.g. 'header left'

Returns:

List css style classes to apply

setStyleClasses

void setStyleClasses(List<String> styleClasses)

Setter for the components style classes

Parameters:

styleClass -

addStyleClass

void addStyleClass(String styleClass)

Adds a single style to the list of styles on this component

Parameters:

style -

appendToStyle

void appendToStyle(String itemStyle)

TODO: javadoc

Parameters:

itemStyle -

getColSpan

int getColSpan()

Number of places the component should take up horizontally in the container

All components belong to a Container and are placed using a LayoutManager. This property specifies how many places horizontally the component should take up within the container. This is only applicable for table based layout managers. Default is 1

TODO: this should not be on component interface since it only applies if the layout manager supports it, need some sort of layoutOptions map for field level options that depend on the manager

Returns:

int number of columns to span

setColSpan

void setColSpan(int colSpan)

Setter for the components column span

Parameters:

colSpan -

getRowSpan

int getRowSpan()

Number of places the component should take up vertically in the container

All components belong to a Container and are placed using a LayoutManager. This property specifies how many places vertically the component should take up within the container. This is only applicable for table based layout managers. Default is 1

TODO: this should not be on component interface since it only applies if the layout manager supports it, need some sort of layoutOptions map for field level options that depend on the manager

Returns:

int number of rows to span

setRowSpan

void setRowSpan(int rowSpan)

Setter for the component row span

Parameters:

rowSpan -

getContext

Map<String,Object> getContext()

Context map for the component

Any el statements configured for the components properties (e.g. title="@{foo.property}") are evaluated using the el context map. This map will get populated with default objects like the model, view, and request from the ViewHelperService. Other components can push further objects into the context so that they are available for use with that component. For example, Field instances that are part of a collection line as receive the current line instance

Context map also provides objects to methods that are invoked for GeneratedField instances

The Map key gives the name of the variable that can be used within expressions, and the Map value gives the object instance for which expressions containing the variable should evaluate against

Returns:

Map context

setContext

void setContext(Map<String,Object> context)

Setter for the context Map

Parameters:

context -

pushObjectToContext

void pushObjectToContext(String objectName,
                         Object object)

Places the given object into the context Map for the component with the given name

Parameters:

objectName - - name the object should be exposed under in the context map

object - - object instance to place into context

getPropertyReplacers

List<PropertyReplacer> getPropertyReplacers()

List of PropertyReplacer instances that will be evaluated during the view lifecycle to conditional set properties on the Component based on expression evaluations

Returns:

List replacers to evaluate

setPropertyReplacers

void setPropertyReplacers(List<PropertyReplacer> propertyReplacers)

Setter for the components property substitutions

Parameters:

propertyReplacers -

getComponentOptions

Map<String,String> getComponentOptions()

Options that are passed through to the Component renderer. The Map key is the option name, with the Map value as the option value. See documentation on the particular widget render for available options.

Returns:

Map options

setComponentOptions

void setComponentOptions(Map<String,String> componentOptions)

Setter for the widget's options

Parameters:

widgetOptions -

getOrder

int getOrder()

Can be used to order a component within a List of other components, lower numbers are placed higher up in the list, while higher numbers are placed lower in the list

Specified by:

getOrder in interface org.springframework.core.Ordered

Returns:

int ordering number

See Also:

Ordered.getOrder()

setOrder

void setOrder(int order)

Setter for the component's order

Parameters:

order -

See Also:

org.springframework.core.Ordered.getOrder()

getFinalizeMethodToCall

String getFinalizeMethodToCall()

Name of the method that should be invoked for finalizing the component configuration (full method name, without parameters or return type)

Note the method can also be set with the finalizeMethodInvoker targetMethod property. If the method is on the configured ViewHelperService, only this property needs to be configured

If the component is selfRendered, the finalize method can return a string which will be set as the component's renderOutput. The selfRendered indicator will also be set to true on the component.

Returns:

String method name

getFinalizeMethodInvoker

MethodInvokerConfig getFinalizeMethodInvoker()

MethodInvokerConfig instance for the method that should be invoked for finalizing the component configuration

MethodInvoker can be configured to specify the class or object the method should be called on. For static method invocations, the targetClass property can be configured. For object invocations, that targetObject property can be configured

If the component is selfRendered, the finalize method can return a string which will be set as the component's renderOutput. The selfRendered indicator will also be set to true on the component.

Returns:

MethodInvokerConfig instance

isSelfRendered

boolean isSelfRendered()

Indicates whether the component contains its own render output (through the renderOutput property)

If self rendered is true, the corresponding template for the component will not be invoked and the renderOutput String will be written to the response as is.

Returns:

boolean true if component is self rendered, false if not (renders through template)

setSelfRendered

void setSelfRendered(boolean selfRendered)

Setter for the self render indicator

Parameters:

selfRendered -

getRenderOutput

String getRenderOutput()

Rendering output for the component that will be sent as part of the response (can contain static text and HTML)

Returns:

String render output

setRenderOutput

void setRenderOutput(String renderOutput)

Setter for the component's render output

Parameters:

renderOutput -

getProgressiveRender

String getProgressiveRender()

Returns:

the progressiveRender

setProgressiveRender

void setProgressiveRender(String progressiveRender)

Parameters:

progressiveRender - the progressiveRender to set

getConditionalRefresh

String getConditionalRefresh()

Returns:

the conditionalRefresh

setConditionalRefresh

void setConditionalRefresh(String conditionalRefresh)

Parameters:

conditionalRefresh - the conditionalRefresh to set

getProgressiveDisclosureControlNames

List<String> getProgressiveDisclosureControlNames()

Returns:

the progressiveDisclosureControlNames

getProgressiveDisclosureConditionJs

String getProgressiveDisclosureConditionJs()

Returns:

the progressiveDisclosureConditionJs

getConditionalRefreshConditionJs

String getConditionalRefreshConditionJs()

Returns:

the conditionalRefreshConditionJs

getConditionalRefreshControlNames

List<String> getConditionalRefreshControlNames()

Returns:

the conditionalRefreshControlNames

isProgressiveRenderViaAJAX

boolean isProgressiveRenderViaAJAX()

Returns:

the progressiveRenderViaAJAX

setProgressiveRenderViaAJAX

void setProgressiveRenderViaAJAX(boolean progressiveRenderViaAJAX)

Parameters:

progressiveRenderViaAJAX - the progressiveRenderViaAJAX to set

isProgressiveRenderAndRefresh

boolean isProgressiveRenderAndRefresh()

If true, when the progressiveRender condition is satisfied, the component will always be retrieved from the server and shown(as opposed to being stored on the client, but hidden, after the first retrieval as is the case with the progressiveRenderViaAJAX option). By default, this is false, so components with progressive render capabilities will always be already within the client html and toggled to be hidden or visible.

Returns:

the progressiveRenderAndRefresh

setProgressiveRenderAndRefresh

void setProgressiveRenderAndRefresh(boolean progressiveRenderAndRefresh)

Parameters:

progressiveRenderAndRefresh - the progressiveRenderAndRefresh to set

getRefreshWhenChanged

String getRefreshWhenChanged()

Specifies a property by name that when it value changes will automatically perform a refresh on this component. This can be a comma separated list of multiple properties that require this component to be refreshed when any of them change.
DO NOT use with progressiveRender unless it is know that progressiveRender condition will always be satisfied before one of these fields can be changed.

Returns:

the refreshWhenChanged

setRefreshWhenChanged

void setRefreshWhenChanged(String refreshWhenChanged)

Parameters:

refreshWhenChanged - the refreshWhenChanged to set

isRefresh

boolean isRefresh()

Result of the conditionalRefresh expression, true if satisfied, otherwise false. Note: not currently used for any processing, required by the expression evaluator.

Returns:

the refresh

setRefresh

void setRefresh(boolean refresh)

Parameters:

refresh - the refresh to set

getRefreshWhenChangedControlNames

List<String> getRefreshWhenChangedControlNames()

Control names which will refresh this component when they are changed, added internally

Returns:

the refreshWhenChangedControlNames