Message Boxes

Configuring a Message Box

The class RequestOperation provides all methods required to completely customize and display a message box:

The code snippets used in this section are highly simplified. Numerous classes included in the source code of the ContentCreator Examples module source code illustrate drawing dialogs, first and foremost the class SectionLifespanWebeditInlineEditItemsPlugin included in the package de.espirit.firstspirit.opt.example.webedit.inlineedit.

/**
 * This is a simplified version of the method execute() in DefineLifespanExecutableAction.
 * Try/catch and other error handling blocks have been removed to improve legibility.
 * Likewise, functionality has been modified to illustrate diverse use cases.
 * 
 * @param context The context operating in.
 */
public void execute(@NotNull final InlineEditContext context) {

As a best practice, a store element that may be modified during a programmatic action should be place in edit mode (in API terms, "locked") if this element supports locking. This example code expects to operate on a Section object - in this case, it is recommended to place the surrounding page and all its child objects (content areas and sections) in edit mode.

    final Section<?> section = (Section<?>) context.getElement();
    final Page page = (Page) section.getParent().getParent();
    page.setLock(true, true);

After the appropriate store elements have been placed in edit mode, a RequestOperation object is obtained by using the OperationAgent.

    final OperationAgent operationAgent = context.requireSpecialist(OperationAgent.TYPE);
    final RequestOperation request = operationAgent.getOperation(RequestOperation.TYPE);

The title text may be customized by using RequestOperation.setTitle(String titleText);.

    requestOperation.setTitle("Delete Section");

The message box kind maybe set using the values stored in enum RequestOperation.Kind. This influences the icon graphic displayed next to the message box text as well as the title displayed in the title bar. If the kind is not explicitly set, the message box will default to an information display.

    requestOperation.setKind(RequestOperation.Kind.QUESTION);

• RequestOperation.Kind.INFO will cause the message box to be drawn with an information icon ('i') and the title "Information". The default button action is "OK".
• RequestOperation.Kind.QUESTION will cause the message box to be drawn with a question mark icon ('?') and the title "Question". The default buttons available in this message box kind are "Yes" and "No".
• RequestOperation.Kind.WARN will cause the message box to be drawn with an exclamation mark icon ('!') and the title "Warning".The default button action is "OK".
• RequestOperation.Kind.ERROR will cause the message box to be drawn with an error icon ('x') and the title "Error".The default button action is "OK".

The ContentCreator does not differentiate between message box kind WARN and message box kind INFO. Both message box kinds are displayed identically with an exclamation mark symbol.

All button actions cause the message box to close when clicked. The specific answer selected by the user can be programmatically determined; see the section Handling Returned Answers.

For all message box kinds, custom answer sets can be defined that will be shown as individual buttons below the question text:

• Four pre-defined answer buttons are available. These will be localized according to the user interface language ContentCreator currently operates with.
• RequestOperation.Answer RequestOperation.addOk() adds an "OK" button.
• RequestOperation.Answer RequestOperation.addCancel() adds a "Cancel" button.
• RequestOperation.Answer RequestOperation.addYes() adds a "Yes" button.
• RequestOperation.Answer RequestOperation.addNo() adds a "No" button.
• Additionally, buttons with custom labels may be added. The label text should be localized during configuration of a RequestOperation.
• RequestOperation.Answer RequestOperation.addAnswer(String label) adds a button that uses label as its text.

Unless RequestOperation.setInitialAnswer(RequestOperation.Answer defaultAnswer); is called, the last answer added will be used as a default.

    RequestOperation.Answer answerYes = requestOperation.addYes();
    RequestOperation.Answer answerNo = requestOperation.addAnswer("No, I want to keep this section!");

Finally, the message box will be drawn upon "performing" the request operation. The message text displayed to the user is provided as a String parameter to perform().

    RequestOperation.Answer answerReturned = requestOperation.perform("Are you sure you wish to delete this section?");

    // Continued in the next section...

Handling Returned Answers

RequestOperation.perform() always returns a RequestOperation.Answer object that represents the answer selected by the user. This allows program code to branch depending on the selected answer to a question message box.

    // ...continued from the previous section.

    RequestOperation.Answer answerReturned = requestOperation.perform("Are you sure you want to delete this section?");
    if (answerReturned.equals(answerYes)) {
        // delete the section element using an API call
    }

}