Reference: Enable/Disable an ADF Component Functional UI Pattern

This topic contains the following sections:

Problem Description

A rich client User Interface (UI) may have by default, a component or part of a page that is set to a disabled state until a user action. An example of a user action might be changing the state of a different component which triggers the disabled component or part of a page to become enabled. Presently, ADF does not provide a general "out of the box" approach for achieving this behavior.

Technical Pattern Description

This pattern demonstrates how to create typical rich client UI behavior, which by default sets components or part of a page to a disabled state unless or until a user action, such as changing the state of a component, triggers a component or part of a page to enabled. For example, many rich client UIs keep the Save button disabled until the user makes changes that requires persistence. At that point the Save button enables. The reverse scenario from enabled to disabled is also applicable. That is, elements on the page can disable based on user actions.

ADF technologies used in this pattern include an inputNumberSpinbox and a selectBooleanCheckbox along with various layout components. The implementation is achieved with a combination of an autoSubmit, partialTriggers, and an EL binding to a disabled attribute.

The User Experience

In this Functional UI Pattern autosubmit and partialTriggers respond to user entered values. In the illustrated UI, the collate checkbox is enabled or disabled based on the number of copies the user selects to make. If the number of copies is 1, the collate checkbox is disabled. If the number of copies requested by the user is greater than 1, the collate checkbox is enabled.

Illustrations of example enabled user interface

Illustrations of example disabled user interface

Artifacts

User Interface Elements

ADF Input Number Spinbox: The af:inputNumberSpinbox is an input component that presents the user with an input field for numerical values and a set of up and down arrow keys to increment or decrement the current value in the input field.

ADF Select Boolean Checkbox: The af:selectBooleanCheckbox component allows more flexibility in how the checkbox components are laid out on the page. For example, selectBooleanCheckbox components can be laid out in a grid by using h:panelGrid. The value attribute should be set to a boolean. The required attribute whether a non-null, non-empty value must be entered. If false, validators will not be executed when the value is null or empty. Having the required attribute set to true, does not mean that the user must check the checkbox before submitting. False is a valid value, even if the required attribute is true.

Code Snippet

Number of copies: To the af:inputNumberSpinbox add the EL binding, #{test.copies}, to the Value property of the Common section of the Property Inspector. Ensure that the AutoSubmit property within the Behavior section of the Property Inspector is set to true.

Collate: To the af:selectBooleanCheckbox add the EL binding, #{test.collateDisabled} to the Disabled property in the Behavior section of the Property Inspector. Ensure that the PartialTriggers property is set to copies within the Behavior section of the Property Inspector.

Pattern Implementation

This sample implementation of the UI pattern is divided into 5 major steps.

  1. Create the application workspace, project, and a simple jspx page.
  2. Add ADF components to construct the UI.
  3. Create a managed bean.
  4. Add the required EL bindings within the ADF UI components.
  5. Run the application.

Create the application workspace, project, and a simple jspx page

  1. Click the New Application icon button in the Application Navigator to create a new application workspace.

    The Model project is not used in this sample app.

  2. In the Create Application wizard, type enableDisable or other appropriate name for the Application Name.
  3. Click Fusion Web Application (ADF) from the Application Template.
  4. Click Next
  5. For project names, type enableDisableModel and enableDisable for the Model and ViewController respectively, or other appropriate names.
  6. For Application Package Prefix, type enabledisable.
  7. Click Finish.
  8. Open the adfc-config.xml from the WEB-INF folder within the Web Content folder of the enabledisable project.
  9. Create a JSF Page by dragging and dropping a View from the Component Palette onto the adfc-config.xml diagram. Give the page a appropriate name (e.g., EnableDisable.jspx).
  10. Double click on the enabledisable.jspx icon within the adfc-config.xml diagram and accept the defaults to create the enabledisable.jspx page.

Add ADF components to construct the UI

  1. Add a Panel Group Layout component from the Layout section of the Component Palette to the Visual Editor for the enabledisable.jspx page.
  2. In the Common section of the Property Inspector, set the Layout property to scroll and the halign to center.
  3. From the Layout section of the Component Palette, add a Spacer component to the Panel Group Layout component in the Structure Window.
  4. In the Common section fo the Property Inspector, set the height to 100.
  5. Add another Panel Group Layout component from the Layout section of the Component Palette to the first Panel Group Layout.
  6. In the Common section of the Property Inspector, set the Layout property to horizontal.
  7. From the Component accordion of the Component Palette, click the Input Number Spinbox component to add it to the Panel Group Layout component.
  8. In the Common section of the Property Inspector, set Id to copies.
  9. In the Common section of the Property Inspector, type Number of copies in the Label property.
  10. In the Data section of the Property Inspector, set the Minimum property to 1.
  11. In the Behavior section of the Property Inspector, set the AutoSubmit property to true.
  12. From the Component section of the Component Palette, drag and drop a Select Boolean Checkbox onto the Panel Group Layout component in the Structure Window.
  13. In the Common section of the Property Inspector, select the Property Menu of the Label property.
  14. In the Property Menu, select Reset to Default.
  15. In the Appearance section of the Property Inspector, type collate in the Text property.

Create a managed bean

  1. In the Visual Editor, select the Input Number Spinbox.
  2. In the Common section of the Property Inspector, select the Property Menu of the Value property.
  3. In the Property Menu, select Expression Builder.
  4. Select the JSF Managed Beans folder, followed by clicking on the Create Managed Bean button in the Expression Builder dialog.
  5. In the Create Managed Bean dialog, type the following.
    1. Bean Name: enableDisable.
    2. Class Name: EnableDisable.
    3. Package: enabledisable.
    4. Extends: java.lang.Object.
    5. Scope: session.
    6. Check that the Generate Class If It Does Not Exist check box is set.
  7. Once the Managed Bean has been created, properties can be added to it within the Expression Builder. Ensure that the managed bean that was created is selected and click the Create Property button.
  8. In the Create Property dialog, type the following.
    1. Name: copies.
    2. Type: int.
  10. Click OK.
  11. Ensure that the managed bean that was created is selected and click the Create Property button again.
  12. In the Create Property dialog, type the following.
    1. Name: collateDisabled.
    2. Type: boolean.
  14. Click OK.

Add the required EL bindings within the ADF UI components

  1. Now that the properties for the managed bean has been created, under the JSF Managed Beans folder select the copies property of the newly created managed bean enableDisable.

    This inserts the following EL Binding, #{enableDisable.copies}, into the Expression field of the Expression Builder dialog.

  2. Click OK.
  3. In the Structure Window, select the af:selectBooleanCheckbox.
  4. In the Behavior section of the Property Inspector, type #{enableDisable.collateDisabled} into the Disabled property.
  5. In the Behavior section of the Property Inspector, select the Property Menu of the PartialTriggers property.
  6. In the Property Menu, select Edit.
  7. In the Edit Properties: PartialTriggers dialog, shuttle inputNumberSpinbox - copies to Selected.
  8. Click OK.
  9. Open the managed bean, EnableDisable.java, under Application Sources > enabledisable package into the Source Editor.
  10. Ensure that the source is as follows.

package enabledisable;

public class EnableDisable{
    private int copies = 1;

    public EnableDisable() {
    }

    public void setCopies(int copies) {
        this.copies = copies;
    }

    public int getCopies() {
        return copies;
    }

    public boolean getCollateDisabled() {
        return copies < 2;
    }
}

Run the application

  1. Save the application workspace.
  2. Open a context menu on the enabledisable.jspx page within the Visual Editor or or on its node in the Structure Window.
  3. Select Run.

Instead of completing these step, an ADF sample application on OTN called enabledisable is available at https://www.oracle.com/docs/tech/developer-tools/enabledisable.zip can be unzipped into the designated JDeveloper work area. Open enableDisablePattern.jws with JDeveloper.