Event Handling

Pages have UI components that trigger events that are handled by event handlers in the managed bean [Layout-Name]Bean.java. The generator JSF Web-Fragment can create event handlers for all such components. Per convention almost all names of generated event handler methods start with action..(). In only one case, namely <p:fileUpload>, the related event handler follows a different convention: handleFileUpload(FileUploadEvent event).

Event handlers are always generated for UI components where a user would naturally expect that something is happening when the component is clicked. Most event handlers are being triggered by means of AJAX calls (HTTP POST).

Re-initialization of DTOs

Sometimes data is going to be modified as part of the execution of an event handler. The web page should then display the modified data. That’s what the generated method initDtos() is meant for. Implement the initialization of DTO objects therein and call that method whenever you need to re-initialize those objects.

Selection Components¶

For UI components that have the purpose to select something, an event handler is only generated when the modeling option ‘HandleSelectionEvent’ is set to true, e.g.:

display MyDisplay {
    component MySelection : Choice {
        set HandleSelectionEvent = true;
    }
}

With this option set to true, an event handler is generated that can be used to do things like:

change the visibility of UI components
validate input data
call webservices

The corresponding generated event handler in [Layout‑Name]Bean.java is String actionMySelectionMyDisplay(...). In case of a generated autocomplete component, the method signature is a bit different (see further down).

By default the generated XHTML code with the <p:ajax> tag makes use of <o:skipValidators>. With this the validation is automatically skiped when the AJAX call is being made. Most of the time this is desirable. When there is for instance a required field that is not yet filled and you select something in a combo box, to execute the code in the event handler, is more important than to force the user to input something in the required field. Command buttons or links that serve the purpose of saving all changes will not have the <o:skipValidators> generated, since there the validation of required fields has a higher priority than the excution of the save-logic.

Autocomplete¶

When you model a Choice like this

display MyDisplay {
    component MyAutoComplete : Choice {
        set ChoiceType = AutoComplete;
        set HandleSelectionEvent = true;
    }
}

an action handler method String actionMyAutoCompleteMyDisplay(SelectEvent event) is generated in [Layout‑Name]Bean.java. That action handler gets called when a user selects one of the entries that are displayed for the autocomplete component. The information about the selected entry is stored in a DTO object and is already available when the action handler gets called.

Check Box¶

When you model a Choice like this

display MyDisplay {
    component MyBooleanChoice : BooleanChoice {
        set HandleSelectionEvent = true;
    }
}

an action handler method String actionMyBooleanChoiceMyDisplay() is generated in [Layout‑Name]Bean.java. That action handler gets called when a user clicks on the check box. The information about the selection state of the check box is stored in a DTO object and is already available when the action handler gets called.

Date/Time Selection¶

When you model a Choice like this

display MyDisplay {
    component MyDateSelector : DateSelector {
        set HandleSelectionEvent = true;
    }
}

an action handler method String actionMyDateSelectorMyDisplay(SelectEvent event) is generated in [Layout‑Name]Bean.java. That action handler gets called when a user selects a date or a time. The information about the selected entry is stored in a DTO object and is already available when the action handler gets called.

Wizard¶

For a modeled wizard (layout MyWizard with set Type = Wizard;) the PrimeFaces component <p:wizard> is generated, together with a special flow event handler:

public String actionWizardFlowMyWizard(FlowEvent event) {
    return event.getNewStep();
}

Additionally, an enumeration [Layout-Name]Tab is generated as an inner class of [Layout‑Name]Bean.java. This enumeration has one entry for each wizard step. That enumeration is well suited to be used for the manual implementation of actionWizardFlowMyWizard(FlowEvent event).

File Upload¶

When you model a file upload like this

display MyDisplay {
    component MyUpload : FileUpload;
}

an inner class MyUploadFileUploadBean is generated in [Layout‑Name]Bean.java. That inner class has the method void handleFileUpload(FileUploadEvent event), which gets called whan a user pressed the ‘upload’-button. The inner class represents a @RequestScope managed bean and has access to the @ViewScope managed bean of the web page.

Button or Link¶

When you model a Button or Link like this

display MyDisplay {
    component MyButton : Button;
    component MyLink : Link;
}

the action handler methods String actionMyButtonMyDisplay() and
String actionMyLinkMyDisplay() are generated in [Layout‑Name]Bean.java. Those action handlers get called when a user clicks on the button or the link on the page.

Note

There will always be action handlers generated for buttons and links, not matter what options you set in your model.