Custom Dialogs, Forms and Rulesets

A custom dialog created in ContentCreator with ShowFormDialogOperation.

Forms are the primary method to display and edit store element data that is more complex than its final representation as rendered in the preview pane and the final, generated product of a web page. The FirstSpirit APIs enable plug-ins to create, configure and handle dialog windows, to generate and handle forms, form data and rulesets and to process modified data submitted by users.

The main methods to create and interact with dialogs, forms and rulesets are provided by three API operation classes:

ShowFormDialogOperation

• Allows the configuration and creation of a dialog that displays a form. Preset form contents, defaults and validation and language settings can be supplied to fit a plug-in's needs.
• If the dialog's form data is modified and saved by the user, this form data is returned for further processing and storing.

OpenElementDataFormOperation

• This specialized operation displays a form for a specific store element. The store element used must be based on a form-providing template, and loading/saving form data for this element is handled by the operation itself.
• The form drawn by this operation provides all client-specific user interface features, including project language switching and validation. Additionally, the operation can be configured to display the store element's form in a specific project language, and contents of individual form fields may be overridden by providing a special form data object.
• In SiteArchitect, the form is displayed as a tab in the editorial pane, while in ContentCreator, an Edit dialog containing the form will be opened.

OpenElementMetaFormOperation

• This is a specialized operation that displays an element's metadata form. The operation is carried out in the context of a specific store element and handles loading and storing metadata internally.
• In order to use this operation on a store element in ContentCreator, a metadata entry must be named for this store element type in the project's ContentCreator settings in ServerManager.

The operations OpenElementDataFormOperation and OpenElementMetaFormOperation are described in the section Working With Store Elements. The remainder of this page will treat creating and handling a custom form using ShowFormDialogOperation.

Configuring a Form Dialog

The class ShowFormDialogOperation provides all methods required to completely customize a form dialog.

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

/**
 * 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 ShowFormDialogOperation object is obtained by using the OperationAgent.

    final OperationAgent operationAgent = context.requireSpecialist(OperationAgent.TYPE);
    final ShowFormDialogOperation operation = operationAgent.getOperation(ShowFormDialogOperation.TYPE);

In turn, a Form object can be obtained by using FormsAgent.getForm(String formXml). The form XML must adhere to the template syntax described in Template Development: Forms.

    final String formDefinition = section.getTemplate().getGomSource();
    final FormsAgent formAgent = context.requireSpecialist(FormsAgent.TYPE);
    final Form form = formAgent.getForm(formDefinition);

Especially for existing objects (be they store elements or custom data objects), form data needs to be supplied. Most store elements do possess form data, which can be obtained using, e.g., FormData sectionFormData = section.getFormData();. For other purposes, form data may have to be set manually. The lines below illustrate a simple case of manual form data assignment.

Once form data is obtained from a store element or manually set, it is passed to the ShowFormDialogOperation object.

    final Language language = context.getLanguage();
    final FormData formData = form.createFormData();
    final FormField<?> formField = formData.get(language, "CMS_INPUT_TEXT_component_name");
    formField.set("Sample Text");
    operation.setFormData(formData);

Default values (used as fallback values if an input component specified in the form has no set content) can be set accordingly:

    final FormData formDefaults = section.getTemplate().getFormDefaults();
    operation.setDefaults(formDefaults);

The ruleset used to validate the form will be passed to the operation as a simple String object. As with a form definition, dynamic forms definitions must follow the rules syntax described in Chapter Rules / Dynamic Forms.

In this example block, the section's template is queried for the ruleset definition, and validation is explicitly turned on for this operation:

    String rulesetDefinition = section.getTemplate().getRulesetDefinition();
    operation.setRuleset(rulesetDefinition);
    operation.setValidation(true);

Lastly, two settings - which will help users identify the purpose and context of the dialog about to be displayed - are configured:

    operation.setTitle("Sample Dialog");
    operation.setContextElement(section);

The operation is now ready to be "performed", meaning the dialog that has been configured will be displayed to the user, and ContentCreator will poll the dialog for content modifications as well as " Save" or "Cancel" operations.

    final FormData formData = operation.perform(form, Arrays.asList(language));

    // Continued in the next section...

Handling Returned Form Data

ShowFormDialogOperation.perform() always returns a FormData object. If form contents displayed in the dialog have not been modified (e.g. the dialog was closed by clicking "Cancel"), the object will be null. If modifications have been saved, the FormData object will carry the complete set of form fields, which should be processed according to the dialog's purpose and context.

    // ...continued from the previous section.

    final FormData formData = operation.perform(form, Arrays.asList(language));
    section.setFormData(formData);

}