Skip to main content

D2FS Dialog

What is it?​

D2FS dialog is a core component of D2 API. It is a declarative tool to design UI interaction and business logic code to create, update, delete data in the system with the help of other D2 and/or DFC APIs. D2 runtime itself heavily relies on many out-of-the-box(OOTB) D2FS dialogs to implement many of its functionalities, e.g., Property page, Lifecycle, Workflow etc.

D2FS dialog mostly starts in the context of an existing object in the system, drives capturing various (un)assisted input from end-user based on the context, then finally alters the contextual object itself or its related objects by creating or modifying data. This contextual, data-driven nature of a single functional unit that already has much of its behavior pre-defined, makes it a great tool for customizations.

D2FS dialog can prove to be a handy tool in custom business flow implementations that are heavily end-user input oriented.

Components of D2FS dialog​

Each D2FS dialog consists of server-side & client-side components that work together to create its UI, appearance and behavior.

Server side​

Component nameDescriptionIs customizable?
Dialog structure XMLAn XML file defining the overall structure, layout of the dialog's UI and its constituent elementsYes
Dialog labelsA Java properties file containing the display labels associated with the dialogYes
Dialog Java classJava class responsible for building, validating and/or running business specific logic for the dialogYes

Client side​

Component nameDescriptionIs customizable?
Dialog stateHolder for dialog's state data and overall context. It also acts as the interface between state methods and actions for the dialog. It is created as soon as a dialog execution stars on the UI and lives on until the dialog closes, keeping a history of all the state changes that happens in between.No
Dialog state methodDefines the means for a dialog to navigate to its next possible presentation and data state from current presentation and data stateYes
Schema builderData transformer that converts the dialog definition from server-side format into its client-side format(a.k.a schema) which is interpreted by the content viewYes
Content viewUI component responsible for creating the interactive visual rendition of a dialog schemaYes
ActionDefines the behavior of buttons attached to a dialogYes
UI containerThe client-side component that brings all other dialog related client-side components together and finally renders the dialog's UI enclosed inside a modal popup/side-panel.No

What and when to customize?​

The server-side components play the key role in defining a dialog i.e., for every new dialog, a new set of server-side component has to be created. Whereas, a default set of client-side components can automatically bind to any such server-side definitions in order to display it in UI and provide its behavior. It means, the client-side components needs customization only when their default capabilities fall short for a certain dialog's display and/or expected behavior. Also see Detailed customization topics.

Basics of implementing a business flow​

To implement a business flow using dialogs, first thing we have to know is the total number of distinct (in terms of UI appearance) steps in the flow. For each step identified, we have to define a new dialog. Once the server-side components for each of the dialogs have been defined, the dialogs have to be linked with each other as per required business logic.

To link, DialogB to the positive sense of navigation from DialogA and to link DialogC to the negative sense of navigation from DialogA, the DialogA.java has to be modified w.r.t validDialog and cancelDialog methods to make them look like -

class DialogA extends AbstractDialog implements ID2Dialog {
    @Override
    public XmlNode validDialog(D2fsContext context) throws Exception {
        XmlNode result = super.validDialog(context);
        result.setAttribute("nextDialogName", "DialogB");
        result.setAttribute("attr1", "value1"); // Attributes set on the return value like this line, will be avaialble to DialogB as input data when that is being built
        return result;
    }
    
    @Override
    public XmlNode cancelDialog(D2fsContext context) throws Exception {
        XmlNode result = super.cancelDialog(context);
        result.setAttribute("nextDialogName", "DialogC");
        result.setAttribute("attr2", "value2"); // Attributes set on the return value like this line, will be avaialble to DialogC as input data when that is being built
        return result;
    }
}
tip

As an alternative to setting nextDialogName attribute from validDialog() or cancelDialog() of a specific dialog definition to achieve linking, a single D2DialogService override can be used to achieve the same. But, as the override will be called for all OOTB as well as plugin-defined dialogs, so maintaining the condition logic can easily become overwhelming, making it a downside of that approach.

Passing data from one dialog to another​

When two dialogs are linked in a flow, the default state method implementation automatically passes the data collected in a dialog to its next immediate dialog; next in the sense of both positive and negative side of the navigation. Most of the time this behavior suffices the data passing requirement between two dialogs. However, if a synthesized piece of data i.e., data not captured as part of dialog, has to passed to the next dialog, then we have two options to do that -

  1. If the synthesized data exists on the server-side, then the data can be set as additional attribute to the return value of validDialog() or cancelDialog(), as shown in the above code snippet.
  2. If the synthesized data exists on the client-side, then the data can be injected upon the collected form data through a customized client-side action. See DialogAction.

Entry point of a D2FS dialog​

Once a D2FS dialog has been defined, it can be invoked from the Smartview UI through a menu configuration. In D2-Config, we can add a new menu item under any of the toolbars of "Menu Smart View" type of configurations. The Action field for the menu configuration should be set to Show dialog and the Dialog field should be set to the name of the dialog we want to invoke.

tip

A similar menu configuration can be automatically created by appropriately answering the relevant question asked by Workspace assistant while creating a dialog boilerplate using it.

This all sounds interesting, how do I create one?​

A bare-minimum yet functional server-side boilerplate can be easily created through the use of Workspace assistant. At first, create a plugin project in your SDK workspace, if there is none, and then use the Add D2FS dialog to a plugin option to create a dialog boilerplate.

Detailed customization topics​