mandatoryResourceConfiguration

Overview

When using the ACE Components and specific ICE Components on your page it may be necessary to pre-load component resources into the HEAD during the initial page load in order to ensure proper component execution. Specifically, in cases where the component is not present on the initial page load, but is later added to the page dynamically via a partial-page-update. When using the ACE Components on your page it may be necessary to pre-load certain component resources during the initial page load in order to ensure proper component execution. Specifically, in cases where the component is not present on the initial page load, but is added to the page later dynamically. This is required as it is not possible to add resources to the head dynamically in JSF 2.

For example, you may have an ACE component that is included on an ace:tabPane that is not initially rendered when the page is loaded, but is later rendered to the page via a dynamic Ajax update. In these cases the necessary JavaScript resources for the component may not be added to the page resulting in a none-functional component.

To ensure the all required resources are present on the page during the initial page load for components that are later added to the page dynamically one of the following mandatoryResource configuration techniques should be used.

Components that are rendered onto the page during the initial page load will have their resources loaded automatically and do not require a mandatoryResource configuration entry.

Since ICEfaces 4.0 the use of mandatoryResource for dynamically added components is no longer necessary, so long as "org.icefaces.generateHeadUpdate='true'" (default). Note that it may still be desirable to specify mandatoryResource for certain components in order to force their resources to be loaded at page-load time instead of dynamically when they are first rendered.

Application Scope

The org.icefaces.mandatoryResourceConfiguration context-parameter may be set to one of three values: none, all, or a space delimited list of components.

• When none is specified, only components that are rendered during the initial full-page load will have their resources loaded.

• When all is specified, all components on the classpath with mandatoryResource support will have their resources preloaded in the head of every page. This ensures that the components will function correctly in all cases. However, there is a significant avoidable performance penalty to this approach due to the unnecessary loading of component resources for components that are not used on the page.

• When a space-delimited list of components is specified, only the resources for the listed components will be preloaded.
  • ICEfaces 2: The component's full class name must be specified. For example, to specify sliderEntry, org.icefaces.component.sliderentry.SliderEntry would be given.
  • ICEfaces 3+: The component's tag name may be specified, or for backwards compatibility, the component class name may still be specified. For example, to specify sliderEntry, either of sliderEntry or the longer org.icefaces.component.sliderentry.SliderEntry may be given.

For example, to pre-load resources for sliderEntry and dateTimeEntry:

    <context-param>
        <param-name>org.icefaces.mandatoryResourceConfiguration</param-name>
        <param-value>sliderEntry dateTimeEntry</param-value>
    </context-param>

Page Scope

This feature can also be controlled on a per-page basis using the <ice:config> tag and setting the desired attribute.

    <icecore:config mandatoryResource="sliderEntry dateTimeEntry" />

See the documentation on the <ice:config> tag for additional information.

It is generally preferable to specify the mandatoryResource configuration on a per-page basis as it permits the developer to tune the mandatoryResource behaviour for each page, thus avoiding the unnecessary overhead related to loading component resources on pages that do not use those components.

If you are experiencing improper or failed component rendering or execution on your page, it may be due to missing component resources. A useful for debugging technique is to set <icecore:config mandatoryResource='all' /> on the page to see if it resolves the issue. If it does, you may further refine the mandatoryResource configuration to specify just those components that require preloading.