Summary

Tag Name:<af:declarativeComponent>
Java Class:oracle.adf.view.rich.component.rich.fragment.RichDynamicDeclarativeComponent
Component Type:oracle.adf.RichDynamicDeclarativeComponent
Naming Container:Yes. When referring to children of this component ("partialTriggers", findComponent(), etc.), you must prefix the child's ID with this component's ID and a colon (':').

Defines a dynamic declarative component without a need for a specific tag. Dynamic declarative components allow the UI definition of a component to be defined in terms of a composition of other components and then treated as a single component.

You can pass attributes using JSP tag attributes, or by using <f:attribute>. Facets can also be set as normal using <f:facet> tags. The definition can refer to the attributes of the component by using the "var" EL variable and the component itself using the "componentVar" EL variable that are setup on the <af:componentDef> tag. The definition can reference a facet using the <af:facetRef> tag. Each facet can only be referenced once.

If you put a component as a child of a declarative component but fail to put it inside of a facet and fail to reference that facet in the component definition file (via facetRef), that component will not be rendered.

Dynamic declarative components support flattened chlidren. This means that children of the declarative component can be seen by the declarative component parent. So for example, input components at the root level of the declarative component will be correctly rendered if the declarative component resides in a panelFormLayout component.

Dynamic declarative components support being a partial trigger as well as a partial target. The component will trigger partial updates when any of its children broadcast an event. So for example, a value change event in an input text component that is a child of the declarative component will trigger components listening on the declarative components. By using #{attrs.partialTriggers} (assuming var is 'attrs'), child components may partially update when an action triggers the declarative component. One difference from other components is that the declarative component itself is not re-rendered. Therefore, to be able to change the viewId of the declarative component during a partial update, the parent of the declarative component must be updated.

Note about stretching layouts and flowing/scrolling layouts:

With today's web browsers, it is not reliable to have vertically-stretched content inside of areas that also have scroll bars. If you want the outer areas of your page structure to stretch, you need to be careful of how you assemble your component tree.

  • First, build up a structure of stretchable components (using panelSplitters and panelStretchLayouts).
  • Second, inside of this structure, create islands of non-stretched content. These islands should be rooted with panelGroupLayouts with layout="scroll". This is an ideal component because it can be stretched and does not stretch its children--which likely don't support being stretched anyway.
Rules of thumb:
  1. Never place a scrolling panelGroupLayout inside of another scrolling panelGroupLayout since users do not like nested scroll bars.
  2. Never specify percentage heights in any component's inlineStyle attribute.
  3. Never use the "position" style in any component's inlineStyle attribute.
  4. Unless you are using fixed pixel heights on them, you would never place a panelSplitter or panelStretchLayout inside of any panelGroupLayout regardless of what you have set its layout attribute to.
If you believe that you need to break one of these rules, this is an indication that your page structure is not following the page structure guidelines and you will likely have troubles getting your application to render consistently across various web browsers and computing platforms.
  • For specific details of about component stretching, please see the "geometry management" section in the tag documentation of each component.
  • See the demo application for real world layout examples that you can use as a starting point in your application. A good starting point is the "Layout Basics" page listed under the "Framework Features" tab of the demo application.

Example:

<af:declarativeComponent
  id="weather"
  viewId="pagefragments/weatherBox.jsff"
  zip="94065"
  description="Redwood Shores, CA">
  <f:facet name="forecastSummary">
    <af:outputText value="Partly Cloudy"/>
  </f:facet>
  <f:facet name="forecastDetail">
    <af:panelGroupLayout layout="vertical">
      <af:outputText value="72'F"/>
      <af:outputText value="Partly Cloudy"/>
      <af:outputText value="Wind: W at 16 mph"/>
      <af:outputText value="Humidity: 46%"/>
    </af:panelGroupLayout>
  </f:facet>
</af:declarativeComponent>
And this is the corresponding pagefragments/weatherBox.jsff:
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
          version="2.1">
  <af:componentDef var="attrs">
    <af:xmlContent>
<component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
  <description>
  This component will show weather forecasts in a box.
  </description>
  <facet>
    <facet-name>forecastSummary</facet-name>
    <description>This child draws out the summary forecast</description>
  </facet>
  <facet>
    <facet-name>forecastDetail</facet-name>
    <description>This child draws out the detailed forecast</description>
  </facet>
  <attribute>
    <attribute-name>zip</attribute-name>
    <description>The Zip code of the area</description>
    <required>true</required>
  </attribute>
  <attribute>
    <attribute-name>description</attribute-name>
    <default-value>Unknown</default-value>
    <description>The city/state of the zip code </description>
  </attribute>
</component>
    </af:xmlContent>
    <af:panelHeader text="Weather Forecast for Zip:#{attrs.zip}, #{attrs.description}"
      partialTriggers="#{attrs.partialTriggers}">
      <af:facetRef facetName="forecastSummary"/>
      <af:showDetail>
        <af:facetRef facetName="forecastDetail"/>
      </af:showDetail>
    </af:panelHeader>
  </af:componentDef>        
</jsp:root>

Geometry Management

  • This component can be stretched by a parent layout component that stretches its children, e.g. panelStretchLayout, panelSplitter.
  • You can only safely stretch a declarativeComponent if you can guarantee that inside of it, there is only a single root component and that single component supports being stretched by an ancestor. Otherwise, you may get different results in different web browsers.

Events

Type Phases Description
org.apache.myfaces.trinidad.event.AttributeChangeEventInvoke Application,
Apply Request Values
Event delivered to describe an attribute change. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change event might include the width of a column that supported client-side resizing.

Attributes

Name Type Supports EL? Description
attributeChangeListenerjavax.el.MethodExpressionOnly EL a method reference to an attribute change listener. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change events might include the width of a column that supported client-side resizing.
bindingoracle.adf.view.rich.component.rich.fragment.RichDynamicDeclarativeComponentOnly EL an EL reference that will store the component instance on a bean. This can be used to give programmatic access to a component from a backing bean, or to move creation of the component to a backing bean.
clientComponentbooleanYes Default Value: false

whether a client-side component will be generated. A component may be generated whether or not this flag is set, but if client Javascript requires the component object, this must be set to true to guarantee the component's presence. Client component objects that are generated today by default may not be present in the future; setting this flag is the only way to guarantee a component's presence, and clients cannot rely on implicit behavior. However, there is a performance cost to setting this flag, so clients should avoid turning on client components unless absolutely necessary.
customizationIdStringYes This attribute is deprecated. This attribute will be removed in the next release. Use the 'id' attribute instead.

This attribute is deprecated. The 'id' attribute should be used when applying persistent customizations. This attribute will be removed in the next release.
idStringYes The identifier for the component. The identifier must follow a subset of the syntax allowed in HTML
partialTriggersString[]Yes the IDs of the components that should trigger a partial update. This component will listen on the trigger components. If one of the trigger components receives an event that will cause it to update in some way, this component will request to be updated too. Identifiers are relative to the source component (this component), and must account for NamingContainers. If your component is already inside of a naming container, you can use a single colon to start the search from the root of the page, or multiple colons to move up through the NamingContainers - "::" will pop out of the component's naming container (or itself if the component is a naming container) and begin the search from there, ":::" will pop out of two naming containers (including itself if the component is a naming container) and begin the search from there, etc.
renderedbooleanYes Default Value: true

whether the component is rendered. When set to false, no output will be delivered for this component (the component will not in any way be rendered, and cannot be made visible on the client). If you want to change a component's rendered attribute from false to true using PPR, set the partialTrigger attribute of its parent component so the parent refreshes and in turn will render this component.
viewIdStringYes

The view ID to include. This attribute should not be set on the component, but should be set using the tag, not the component.

The view ID is evaluated during tag execution, not during stamping. Therefore, if EL is used to specify the value, it must have a valid value during tag execution, and cannot be based on component values, like the iterator var attribute. This value should be consistent during all the JSF lifecycle phases. It is recommended to only change the view ID in the invoke application JSF phase, if necessary, as this will allow child components to be correctly processed.

The view ID is the ID of the view to build the component tree from and only the components constructed during the include will be present. So if it is desirable to stamp different include components in an iterating component, like the iterator or table, then each different view ID must be represented. For example:

<af:iterator var="item" value="#{bean.values}">
  <af:switcher facetName="#{item.type}">
    <f:facet name="type1">
      <af:declarativeComponent viewId="type1.jsff" />
    </f:facet>
    <f:facet name="type2">
      <af:declarativeComponent viewId="type2.jsff" />
    </f:facet>
    <f:facet name="type3">
      <af:declarativeComponent viewId="type3.jsff" />
    </f:facet>
  </af:switcher>
</af:iterator>
        

As shown above, three dynamic declarative components are used in the iterator, and only the correct one is displayed based on the stamped item's type attribute.

Note that tag execution is performed at the beginning of the render response phase, during the building of the view, before the view root is being rendered. This means that any EL variables must be set up prior to the render response in order to be using in this attribute.