Field Detail

• COMPONENT_ATTRIBUTE_METADATA

  public static final String COMPONENT_ATTRIBUTE_METADATA

  Component-level attribute used to store metadata.

  See Also:

  Constant Field Values

• COMPONENT_ATTRIBUTE_NOT_RECREATABLE

  public static final String COMPONENT_ATTRIBUTE_NOT_RECREATABLE

  Component-level attribute used to prevent recreation.

  By default, Metawidget destroys and recreates every component after processUpdates and before encodeBegin. This allows components to update to reflect changed state in underlying domain objects. For example, components may change from being UIOutput labels to UIInput text boxes after the user clicks Edit.

  Most components work well with this approach. Some, however, maintain internal state that would get lost if the component was destroyed and recreated. For example, the ICEfaces SelectInputDate component keeps its popup state internally. If it is destroyed and recreated, the popup never appears.

  Such components can be marked with COMPONENT_ATTRIBUTE_NOT_RECREATABLE to prevent their destruction and recreation. Of course, this somewhat impacts their flexibility. For example, a SelectInputDate could not change its date format in response to another component on the form.

  COMPONENT_ATTRIBUTE_NOT_RECREATABLE is also used to mark components that override default component generation, such as a UIStub used to suppress a field.

  This attribute must be used in conjunction with OverriddenWidgetBuilder.

  See Also:

  Constant Field Values

• COMPONENT_ATTRIBUTE_SECTION_DECORATOR

  public static final String COMPONENT_ATTRIBUTE_SECTION_DECORATOR

  Component-level attribute used to store metadata.

  See Also:

  Constant Field Values

Constructor Detail

• UIMetawidget

  public UIMetawidget()

Method Detail

• getFamily

  public String getFamily()

  Overrides:

  getFamily in class javax.faces.component.UIInput

• isReadOnly

  public boolean isReadOnly()

• setReadOnly

  public void setReadOnly(boolean readOnly)

• setConfig

  public void setConfig(String config)

• setInspector

  public void setInspector(Inspector inspector)

• inspect

  public String inspect(Object toInspect,
               String type,
               String... names)

  Useful for WidgetBuilders to perform nested inspections (eg. for Collections).

• addInspectionResultProcessor

  public void addInspectionResultProcessor(InspectionResultProcessor<UIMetawidget> inspectionResultProcessor)

• removeInspectionResultProcessor

  public void removeInspectionResultProcessor(InspectionResultProcessor<UIMetawidget> inspectionResultProcessor)

• setInspectionResultProcessors

  public void setInspectionResultProcessors(InspectionResultProcessor<UIMetawidget>... inspectionResultProcessors)

• setWidgetBuilder

  public void setWidgetBuilder(WidgetBuilder<javax.faces.component.UIComponent,UIMetawidget> widgetBuilder)

• getWidgetBuilder

  public WidgetBuilder<javax.faces.component.UIComponent,UIMetawidget> getWidgetBuilder()

  Exposed mainly for those using UIComponent.setBinding.

• addWidgetProcessor

  public void addWidgetProcessor(WidgetProcessor<javax.faces.component.UIComponent,UIMetawidget> widgetProcessor)

  Exposed mainly for those using UIComponent.setBinding.

• removeWidgetProcessor

  public void removeWidgetProcessor(WidgetProcessor<javax.faces.component.UIComponent,UIMetawidget> widgetProcessor)

  Exposed mainly for those using UIComponent.setBinding.

• setWidgetProcessors

  public void setWidgetProcessors(WidgetProcessor<javax.faces.component.UIComponent,UIMetawidget>... widgetProcessors)

• getWidgetProcessors

  public List<WidgetProcessor<javax.faces.component.UIComponent,UIMetawidget>> getWidgetProcessors()

• getWidgetProcessor

  public <T> T getWidgetProcessor(Class<T> widgetProcessorClass)

• setLayout

  public void setLayout(Layout<javax.faces.component.UIComponent,javax.faces.component.UIComponent,UIMetawidget> layout)

• getLayout

  public Layout<javax.faces.component.UIComponent,javax.faces.component.UIComponent,UIMetawidget> getLayout()

• setInspectFromParent

  public void setInspectFromParent(boolean inspectFromParent)

  Instructs the Metawidget to inspect the value binding from the parent.

  If the value binding is of the form #{foo.bar}, sometimes foo.getBar() has useful metadata (such as UiLookup). Metawidget inspects from parent anyway if #{foo.bar} evaluates to null, but on occasion it may be necessary to specify parent inspection explicitly.

  The disadvantage of inspecting from parent (and the reason it is not enabled by default) is that some Inspectors will not know the parent and so not be able to return anything. For example, HibernateInspector only knows the Hibernate XML mapping files of persistent classes, not the business class of a UI controller, so asking HibernateInspector to inspect #{controller.current} from its parent will always return null.

• setBuildWidgetsOnAjaxRequest

  public void setBuildWidgetsOnAjaxRequest(boolean buildWidgetsOnAjaxRequest)

  By default, UIMetawidget does not rebuild widgets upon an AJAX request unless the Metawidget's Id is explicitly included in the list of execute Ids. There are several reasons for this:

  1. Suppose a Metawidget X has children A, B and C. If B is executed by an AJAX request, this will trigger X with a PreRenderViewEvent (because it is the parent). But if X rebuilds A and C, and they weren't part of the execute request, their values will be lost. This is similar to how UIMetawidget doesn't rebuild upon a validation error
  2. Similarly, if the Metawidget's backing bean is request-scoped, rebuilding A and C will mean they fetch their values from a new (likely empty) backing bean instance. There will be no opportunity for A and C to postback their values first (because they are not executed)
  3. Some components (such as RichFaces' UIAutocomplete) do not allow fine-grained control over what is executed and rendered. They just execute and render themselves
  4. AJAX is about performance, so typically clients are not wanting to rebuild large sections of the component tree

  Although this default behaviour is safer it does, however, result in less dynamic UIs. Clients can use setBuildWidgetsOnAjaxRequest to override the default behaviour and instruct UIMetawidget to always rebuild widgets upon an AJAX request. Mechanisms such as conversation-scoped backing beans can be used to avoid losing values.

• getLabelString

  public String getLabelString(Map<String,String> attributes)

  Returns a label for the given set of attributes.

  The label is determined using the following algorithm:

  • if attributes.get( "label" ) exists...
    • attributes.get( "label" ) is camel-cased and used as a lookup into getLocalizedKey( camelCasedLabel ). This means developers can initially build their UIs without worrying about localization, then turn it on later
    • if no such lookup exists, return attributes.get( "label" )
  • if attributes.get( "label" ) does not exist...
    • attributes.get( "name" ) is used as a lookup into getLocalizedKey( name )
    • if no such lookup exists, return attributes.get( "name" )

  Returns:

  the text of the label. This may itself contain a value expression, such as UiLabel( "#{foo.name}'s name" )

• getLocalizedKey

  public String getLocalizedKey(String key)

  Returns:

  null if no bundle, ???key??? if bundle is missing a key

• setParameter

  public void setParameter(String name,
                  Object value)

  Sets the parameter with the given name to the given value.

  This method will not override existing, manually specified <f:param />. Rather it will store the given parameter in UIComponent.getAttributes. This has several advantages:

  • Creating child UIParameter components for every parameter seems very heavy
  • Copying parameters to nested Metawidgets can be done using the getAttributes Map, without needing to create nested UIParameter components
  • Nested UIParameter components complicate removeRecreatableChildren because although they are not manually specified, they will not be automatically recreated either

  A disadvantage of this approach is that clients should always use UIMetawidget.getParameter to retrieve parameters, rather than searching for UIParameter components directly.

• getParameter

  public String getParameter(String name)

  Gets the parameter with the given name.

  As discussed in the setParameter JavaDoc, clients should use this method to retrieve parameters, rather than searching for UIParameter components directly.

• copyParameters

  public void copyParameters(UIMetawidget copyFrom)

  As discussed in the setParameter JavaDoc, clients should use this method to copy parameters, rather than creating UIParameter components directly.

• putClientProperty

  public void putClientProperty(Object key,
                       Object value)

  Storage area for WidgetProcessors, Layouts, and other stateless clients.

  Unlike .setAttribute, these values are not serialized by ResponseStateManagerImpl.

• getClientProperty

  public <T> T getClientProperty(Object key)

  Storage area for WidgetProcessors, Layouts, and other stateless clients.

  Unlike .getAttribute, these values are not serialized by ResponseStateManagerImpl.

• isRendered

  public boolean isRendered()

  Overrides:

  isRendered in class javax.faces.component.UIComponentBase

• setRendererType

  public void setRendererType(String rendererType)

  Overridden to flag whether the rendererType has been set explicitly by the page.

  This stops global defaults, if defined in metawidget.xml, from overriding the page-level renderType. This is because metawidget.xml is not parsed until after setRendererType has been called.

  Overrides:

  setRendererType in class javax.faces.component.UIComponentBase

• encodeBegin

  public void encodeBegin(javax.faces.context.FacesContext context)
                   throws IOException

  Overrides:

  encodeBegin in class javax.faces.component.UIComponentBase

  Throws:

  IOException

• getComponentType

  public abstract String getComponentType()

  Get the component type used to create this Metawidget.

  Usually, clients will want to create a nested-Metawidget using the same subclass as themselves. To be 'proper' in JSF, though, we should go via application.createComponent. Unfortunately by default a UIComponent does not know its own component type, so subclasses must override this method.

  This method is public for use by NestedLayoutDecorators.

• initNestedMetawidget

  public void initNestedMetawidget(UIMetawidget nestedMetawidget,
                          Map<String,String> attributes)

  Useful for WidgetBuilders to setup nested Metawidgets (eg. for wrapping them in a h:column).

• saveState

  public Object saveState(javax.faces.context.FacesContext context)

  Specified by:

  saveState in interface javax.faces.component.StateHolder

  Overrides:

  saveState in class javax.faces.component.UIInput

• restoreState

  public void restoreState(javax.faces.context.FacesContext context,
                  Object state)

  Specified by:

  restoreState in interface javax.faces.component.StateHolder

  Overrides:

  restoreState in class javax.faces.component.UIInput

• newPipeline

  protected UIMetawidget.Pipeline newPipeline()

  Instantiate the Pipeline used by this Metawidget.

  Subclasses wishing to use their own Pipeline should override this method to instantiate their version.

• registerBuildWidgetsSupport

  protected void registerBuildWidgetsSupport()

  Register the mechanism used to build widgets.

  Subclasses wishing to use their own mechanism should override this method to instantiate their version.

• buildWidgets

  protected void buildWidgets()
                       throws Exception

  Build widgets for the given value binding.

  Subclasses can override this method as a common entry point regardless of whether PreRenderViewEventSupport (JSF2) or EncodeBeginSupport (JSF1) is being used.

  Throws:

  Exception

• getDefaultConfiguration

  protected abstract String getDefaultConfiguration()

• startBuild

  protected void startBuild()

  Build child widgets.

• layoutWidget

  protected void layoutWidget(javax.faces.component.UIComponent component,
                  String elementName,
                  Map<String,String> attributes)

  Parameters:

  elementName - XML node name of the business field. Typically 'entity', 'property' or 'action'. Never null

• endBuild

  protected void endBuild()