Skip to main content

Design Dialog with Fields

Overview​

This sample dialog demonstrates the primary layout containers and field controls available within the D2FS SDK dialog framework.

Containers help organize controls, structure the user interface, and improve usability. Controls provide mechanisms for capturing and displaying user input.

The sample showcases:

Containers​

  • Tabs
  • Fieldsets
  • Grids
  • Columns

Controls​

  • Text
  • List
  • Password
  • Combo
  • Date
  • Memo
  • HTML Editor

These containers and controls can be combined and nested to create flexible and user-friendly dialog layouts.

Sample Dialog Structure​

Dialog
│
├── Tabs
│   └── Tab
│       ├── Text
│       └── List
│
├── Fieldset
│   └── Password
│
├── Grid
│   ├── Combo
│   └── Date
│
└── Columns
    ├── Memo
    └── HTML Editor

Container Types​

Tabs Container​

The tabs container organizes content into multiple tab pages. Each tab can contain one or more controls or nested containers.

Example​

<tabs>
    <tab label_en="tab 1">
        <text id="object_name"/>
        <list id="r_composite_label"/>
    </tab>
</tabs>

When to Use​

  • Large forms containing multiple categories of information
  • Separating logically related content
  • Improving navigation within complex dialogs

Supported Content​

A tab can contain:

  • Text controls
  • Lists
  • Combos
  • Date fields
  • Fieldsets
  • Grids
  • Column layouts
  • Other supported controls

Fieldset Container​

The fieldset container groups related controls under a labeled section.

Example​

<fieldset label_en="Credentials">
    <password id="passwordfield"/>
</fieldset>

When to Use​

  • Security settings
  • User information
  • Configuration sections
  • Logical grouping of related fields

Benefits​

  • Provides visual separation
  • Improves readability
  • Allows logical grouping of controls

Grid Container​

The grid container arranges controls in a structured tabular layout.

Example​

<grid label_en="Author Information">
    <combo id="authors"/>
    <date id="a_effective_date"/>
</grid>

When to Use​

  • Data-entry forms
  • Related fields requiring alignment
  • Compact layouts

Benefits​

  • Consistent alignment
  • Better space utilization
  • Improved form readability

Columns Container​

The columns container divides available space into multiple columns.

Example​

<columns count="2">
    <memo id="a_status"/>
    <html-editor id="title"/>
</columns>

Attributes​

count​

Specifies the number of columns to create.

<columns count="2">

When to Use​

  • Side-by-side editing
  • Displaying related information together
  • Maximizing horizontal screen space

Benefits​

  • Efficient use of available width
  • Cleaner layouts
  • Reduced scrolling

Controls Used in the Sample​

Text Control​

The text control provides a single-line text input field.

Example​

<text id="object_name"/>

Typical Use Cases​

  • Object names
  • Titles
  • Reference numbers
  • Short text values

List Control​

Overview​

The list control displays a collection of selectable values. Values can be populated dynamically from repository queries (DQL) or centrally managed dictionaries.

Data Sources​

DQL-Based List​
<list
    assistance_dql="select user_name from dm_users"
    assistance_type="dql"
    asynchronous="false"
    autoselect_single="true"
    enableImportExport="true"
    horizontal_display="true"
    id="r_composite_label"
    sorted="true"
    update_upon_edit="true"/>

Used when values need to be retrieved dynamically from the repository.

Dictionary-Based List​
<list
    assistance_dictionary="D2-Base Types"
    assistance_dictionary_alias="en"
    assistance_type="dictionary"
    asynchronous="false"
    autoselect_multi="true"
    autoselect_single="false"
    enableImportExport="true"
    horizontal_display="true"
    id="r_composite_label"
    sorted="true"
    update_upon_edit="true"/>

Used when values are predefined and centrally managed.

Key Attributes​

assistance_type​

Determines the data source.

Supported values:

  • dql
  • dictionary
  • java (see Java assistance documentation)
assistance_dql​

DQL query used to retrieve values dynamically.

assistance_dictionary​

Dictionary used as the source of values.

assistance_dictionary_alias​

Language/alias used when retrieving dictionary values.

asynchronous​

Controls asynchronous loading of values.

autoselect_single​

Automatically selects the value when only one result is returned.

autoselect_multi​

Automatically selects values in a multi-selection list.

enableImportExport​

Enables import and export operations.

horizontal_display​

Controls horizontal or vertical rendering.

sorted​

Sorts values before display.

update_upon_edit​

Refreshes values during edit operations.

Example Use Cases​

User List​
<list
    id="reviewers"
    assistance_type="dql"
    assistance_dql="select user_name from dm_users"
    sorted="true"/>
Group List​
<list
    id="groups"
    assistance_type="dql"
    assistance_dql="select group_name from dm_group"
    sorted="true"/>
Document Type List​
<list
    id="document_types"
    assistance_type="dictionary"
    assistance_dictionary="D2-Base Types"
    sorted="true"/>

Best Practices​

  • Use DQL for dynamic repository data.
  • Use dictionaries for static reference values.
  • Enable sorting whenever possible.
  • Keep DQL queries lightweight.
  • Use dictionary aliases in multilingual environments.

Password Control​

The password control provides a masked text-entry field for sensitive information.

Example​

<password id="passwordfield"/>

Typical Use Cases​

  • Password entry
  • Secret keys
  • Temporary access codes

Combo Control​

Overview​

The combo control presents users with a dropdown list for selecting a single value. Values can be sourced from DQL, dictionaries, or taxonomies.

The framework also supports combo-editable, which allows users to enter custom values.

Combo Types​

DQL-Based Combo​
<combo
    assistance_dql="select user_name from dm_users"
    assistance_type="dql"
    asynchronous="true"
    autoselect_single="true"
    control="true"
    id="combofielddql"/>

Used for dynamic repository-driven selections.

Dictionary-Based Combo​
<combo
    assistance_dictionary="D2-Base Types"
    assistance_dictionary_alias="auto"
    assistance_type="dictionary"
    autoselect_single="true"
    control="true"
    id="combofielddictionary"/>

Used for predefined and localized values.

Taxonomy-Based Combo​

Taxonomies support hierarchical classifications.

Level 1​
<combo
    assistance_dictionary="Level1"
    assistance_taxo_attrib_after="combofieldtaxonomy2"
    assistance_taxonomy="New taxonomy"
    assistance_type="taxonomy"
    id="combofieldtaxonomy1"/>
Level 2​
<combo
    assistance_dictionary="Level2"
    assistance_taxo_attrib_after="combofieldtaxonomy3"
    assistance_taxo_attrib_before="combofieldtaxonomy1"
    assistance_taxonomy="New taxonomy"
    assistance_type="taxonomy"
    id="combofieldtaxonomy2"/>
Level 3​
<combo
    assistance_dictionary="Level3"
    assistance_taxo_attrib_before="combofieldtaxonomy2"
    assistance_taxonomy="New taxonomy"
    assistance_type="taxonomy"
    id="combofieldtaxonomy3"/>
Editable Combo​

DQL-Based:

<combo-editable
    assistance_dql="select user_name from dm_users"
    assistance_type="dql"
    control="true"
    id="editablecombo1"/>

Dictionary-Based:

<combo-editable
    assistance_dictionary="D2-Base Types"
    assistance_type="dictionary"
    control="true"
    id="editablecombo2"/>

Common Attributes​

control​

Indicates that the control is managed by the framework.

assistance_type​

Supported values:

  • dql
  • dictionary
  • taxonomy
assistance_dql​

DQL query used to load values.

assistance_dictionary​

Dictionary name used to populate values.

assistance_dictionary_alias​

Dictionary language alias.

assistance_taxonomy​

Taxonomy name.

assistance_taxo_attrib_before​

Parent taxonomy field.

assistance_taxo_attrib_after​

Child taxonomy field.

asynchronous​

Controls asynchronous data loading.

autoselect_single​

Automatically selects a value when only one value is available.

Best Practices​

  • Use repository-backed combos for dynamic data.
  • Use dictionaries for reusable business values.
  • Use taxonomies for hierarchical classifications.
  • Use editable combos when custom entries are permitted.

Date Control​

The date control provides a date picker.

Example​

<date id="a_effective_date"/>

Typical Use Cases​

  • Effective dates
  • Expiration dates
  • Review dates
  • Contract dates

Memo Control​

Overview​

The memo control provides a multi-line text input area for entering and displaying longer text values. Unlike the text control, a memo can span multiple lines and is ideal for comments, descriptions, notes, and status information.

Syntax​

<memo
    id="memo"
    control="true"
    rows="5"/>

Attributes​

id​

Specifies the unique identifier of the control.

id="memo"

Required: Yes

control​

Determines whether the control is managed by the dialog framework and is editable by users.

control="true"

Supported Values

true
false
rows​

Specifies the number of visible rows displayed within the memo field.

rows="5"

A larger value increases the visible height of the control, allowing users to view and edit more content without scrolling.

Typical Use Cases​

  • Comments
  • Notes
  • Status descriptions
  • Review feedback
  • Business justifications
  • Change summaries
  • Additional information fields

Examples​

Basic Memo​
<memo
    id="comments"
    control="true"/>
Memo with Fixed Height​
<memo
    id="description"
    control="true"
    rows="5"/>
Larger Memo Area​
<memo
    id="review_notes"
    control="true"
    rows="10"/>

Best Practices​

  • Use a memo control when users need to enter multi-line content.
  • Configure the rows attribute according to the expected amount of text.
  • Use meaningful control IDs that reflect the business purpose of the field.
  • Avoid unnecessarily large memo areas unless significant text input is expected.
  • Group memo controls within fieldsets or tabs when collecting related information.

Example in a Dialog​

<fieldset label_en="Comments">
    <memo
        id="comments"
        control="true"
        rows="5"/>
</fieldset>

Summary​

The memo control is used for multi-line text entry and display. It is commonly used for comments, notes, descriptions, and other long-form content. The optional rows attribute allows developers to control the visible height of the field and optimize the user experience.

HTML Editor Control​

The html-editor control provides rich-text editing capabilities.

Example​

<html-editor id="title"/>

Typical Use Cases​

  • Formatted descriptions
  • Business content
  • Rich text notes
  • HTML content authoring

Dynamic Control​

Overview​

The dynamic-control element provides a runtime extension mechanism for D2FS dialogs. Unlike standard dialog definitions, which statically declare controls in XML, a dynamic control allows developers to generate dialog content programmatically during dialog rendering.

Dynamic controls are implemented using the IDynamicControls interface and can be used to create:

  • Standard controls
  • Assistance-enabled controls
  • Conditional fields
  • Repository-driven UI elements
  • Complex business-specific dialog sections

In the current sample, the dynamic control generates two combo controls at runtime:

  • A DQL-assisted combo (field1)
  • A Java-assisted combo (field2)

Dialog Configuration​

A dynamic control is referenced within a dialog using its fully qualified Java class name.

<dynamic-control
    class="com.opentext.d2.smartview.sample.assistance.SampleDynamicControls"/>

Java Implementation​

The dynamic control class implements the IDynamicControls interface.

public class SampleDynamicControls
        implements IDynamicControls

The framework invokes the getXmlControls() method whenever the dialog is rendered.

public XmlNode getXmlControls(
        D2fsContext context,
        MultiResourceBundle labelsBundle,
        Map attributes) throws Exception

The method returns XML nodes that are injected into the dialog at runtime.

Method Parameters​

D2fsContext​

Provides access to:

  • Current repository session
  • Current repository object
  • Request parameters
  • User context

Example:

ParameterParser parameterParser =
        context.getParameterParser();
MultiResourceBundle​

Provides access to localized labels and resource bundle entries.

MultiResourceBundle labelsBundle
Attributes​

Contains attributes configured on the dynamic-control tag.

Example:

<dynamic-control
    class="com.opentext.d2.smartview.sample.assistance.SampleDynamicControls"
    customAttribute="sample"/>

Accessing attributes:

if (attributes != null) {

    Set keySet = attributes.keySet();

    for (Object key : keySet) {
        log.debug(
            "Key {} Value {}",
            key,
            attributes.get(key));
    }
}

Runtime Controls Generated by the Sample​

The sample dynamically creates two combo controls.

Field 1: DQL-Assisted Combo​

The first control uses a DQL query to retrieve values.

XmlNode moreCombo =
        result.appendChildNode("combo");

moreCombo.setAttribute("id", "field1");
moreCombo.setAttribute("control", true);

moreCombo.setAttribute(
        "label",
        "Dynamic control User name list DQL 2");

moreCombo.setAttribute(
        "assistance_type",
        "dql");

moreCombo.setAttribute(
        "assistance_dql",
        "select object_name from dm_document enable (return_top 101)");

Generated XML:

<combo
    id="field1"
    control="true"
    label="Dynamic control User name list DQL 2"
    assistance_type="dql"
    assistance_dql="select object_name from dm_document enable (return_top 101)"/>
Additional Configuration​
moreCombo.setAttribute("asynchronous", true);
moreCombo.setAttribute("condition_required_create", true);
moreCombo.setAttribute("condition_required_edit", true);
moreCombo.setAttribute("condition_required_import", true);
moreCombo.setAttribute("readonly", false);
moreCombo.setAttribute("condition_visible", true);
moreCombo.setAttribute("order", "1");
Default Value Population​

The control retrieves its value from the repository attribute:

field1

Example:

if(sysObject.hasAttr("field1")) {
    value = sysObject.getString("field1");
}

The value is then assigned to the generated control:

moreCombo.setAttribute("value", value);

Field 2: Java-Assisted Combo​

The second control uses a custom Java assistance provider.

XmlNode documentTypeCombo =
        result.appendChildNode("combo");

documentTypeCombo.setAttribute(
        "id",
        "field2");

documentTypeCombo.setAttribute(
        "label",
        "Dynamic control Java assistance 2");

documentTypeCombo.setAttribute(
        "assistance_type",
        "java");

documentTypeCombo.setAttribute(
        "assistance_java",
        "com.opentext.d2.smartview.sample.assistance.RadioFieldAssistance");

Generated XML:

<combo
    id="field2"
    label="Dynamic control Java assistance 2"
    assistance_type="java"
    assistance_java="com.opentext.d2.smartview.sample.assistance.RadioFieldAssistance"/>
Visibility Configuration​
documentTypeCombo.setAttribute(
        "condition_visible_create",
        true);

documentTypeCombo.setAttribute(
        "condition_visible_edit",
        true);

documentTypeCombo.setAttribute(
        "condition_visible_import",
        true);

documentTypeCombo.setAttribute(
        "condition_visible",
        true);
Default Value Population​

The control retrieves its value from the repository attribute:

field2

Example:

if(sysObject.hasAttr("field2")) {
    value = sysObject.getString("field2");
}

The value is assigned to the generated control:

documentTypeCombo.setAttribute(
        "value",
        value);

Accessing the Current Object​

The sample obtains the current object using the D2FS context.

private IDfSysObject getSysObject(
        D2fsContext context)
        throws Exception {

    IDfPersistentObject persistentObject =
            context.getFirstObject();

    return (IDfSysObject)
            persistentObject;
}

The retrieved object can be used to:

  • Read attributes
  • Apply business rules
  • Determine object type
  • Populate fields
  • Configure visibility
  • Control layout generation

Example Dialog Usage​

<fieldset label_en="Dynamic Controls">

    <dynamic-control
        class="com.opentext.d2.smartview.sample.assistance.SampleDynamicControls"/>

</fieldset>

Generated Runtime Structure​

Dynamic Controls
│
├── Combo (field1)
│     └── DQL Assistance
│
└── Combo (field2)
      └── Java Assistance

Common Dynamic Attributes​

id​

Unique control identifier.

setAttribute("id", "field1");

label​

Display label for the control.

setAttribute("label", "Document Type");

assistance_type​

Specifies the assistance mechanism.

setAttribute("assistance_type", "dql");

Supported values:

dql
dictionary
java
taxonomy

assistance_dql​

Repository query used to populate values.

setAttribute(
    "assistance_dql",
    "select object_name from dm_document");

assistance_java​

References a custom assistance class.

setAttribute(
    "assistance_java",
    "com.opentext.d2.smartview.sample.assistance.RadioFieldAssistance");

readonly​

Controls whether the field can be edited.

setAttribute("readonly", false);

condition_visible​

Controls field visibility.

setAttribute("condition_visible", true);

condition_required_create​

Marks the field as mandatory during create operations.

setAttribute(
    "condition_required_create",
    true);

condition_required_edit​

Marks the field as mandatory during edit operations.

setAttribute(
    "condition_required_edit",
    true);

condition_required_import​

Marks the field as mandatory during import operations.

setAttribute(
    "condition_required_import",
    true);

order​

Controls the display order.

setAttribute("order", "1");

Beyond Controls: Dynamic Container Generation​

Although the current sample generates only combo controls, the IDynamicControls framework is not limited to field controls.

A dynamic control implementation can generate any supported dialog element, including containers.

Supported Containers​

<tabs/>
<tab/>
<fieldset/>
<grid/>
<columns/>

Supported Controls​

<text/>
<memo/>
<password/>
<list/>
<combo/>
<combo-editable/>
<date/>
<html-editor/>
<dynamic-control/>

Example: Dynamic Fieldset​

XmlNode fieldset =
        result.appendChildNode("fieldset");

fieldset.setAttribute(
        "label_en",
        "Dynamic Metadata");

Generated XML:

<fieldset label_en="Dynamic Metadata">
</fieldset>

Example: Dynamic Tab​

XmlNode tabs =
        result.appendChildNode("tabs");

XmlNode tab =
        tabs.appendChildNode("tab");

tab.setAttribute(
        "label_en",
        "Advanced Settings");

Generated XML:

<tabs>
    <tab label_en="Advanced Settings"/>
</tabs>

Example: Dynamic Layout​

XmlNode fieldset =
        result.appendChildNode("fieldset");

XmlNode grid =
        fieldset.appendChildNode("grid");

XmlNode text =
        grid.appendChildNode("text");

text.setAttribute(
        "id",
        "object_name");

Generated XML:

<fieldset label_en="Properties">

    <grid>

        <text id="object_name"/>

    </grid>

</fieldset>

Typical Use Cases​

Dynamic Object Forms​

Generate fields based on:

  • Object type
  • Metadata model
  • Lifecycle state

Role-Based Interfaces​

Display different controls depending on user permissions.

Metadata-Driven Layouts​

Generate complete forms from repository configuration.

Conditional Sections​

Show or hide tabs, fieldsets, and grids depending on object properties.

Custom Assistance Integration​

Integrate specialized assistance providers through Java implementations.

Best Practices​

  • Keep dynamic generation logic modular and reusable.
  • Populate existing values when editing objects.
  • Avoid expensive repository operations during rendering.
  • Use meaningful control IDs and labels.
  • Reuse assistance implementations whenever possible.
  • Log runtime exceptions and validation errors.
  • Generate containers only when business requirements demand dynamic layouts.

Summary​

The SampleDynamicControls implementation demonstrates how D2FS dialogs can be extended through runtime UI generation.

The sample dynamically generates:

  • A DQL-assisted combo (field1)
  • A Java-assisted combo (field2)

using repository data and business logic.

While this implementation focuses on combo controls, the IDynamicControls API supports generation of any dialog element, including containers such as:

  • Tabs
  • Fieldsets
  • Grids
  • Columns

This allows developers to build fully dynamic, metadata-driven dialogs where both the content and the layout structure can be determined at runtime.

Complete Dialog Example​

<dialog id="PropertiesDialog">

    <content>

        <tabs>
            <tab label_en="tab 1">
                <text id="object_name"/>
                <list id="r_composite_label"/>
            </tab>
        </tabs>

        <fieldset label_en="fs1">
            <password control="true" id="passwordfield"/>
        </fieldset>

        <grid label_en="table1">
            <combo id="authors"/>
            <date id="a_effective_date"/>
        </grid>

        <columns count="2">
            <memo id="a_status"/>
            <html-editor id="title"/>
        </columns>

    </content>

</dialog>

Best Practices​

Use Tabs For​

  • Large forms
  • Multiple categories
  • Improved navigation

Use Fieldsets For​

  • Logical grouping
  • Related settings
  • Readability

Use Grids For​

  • Aligned fields
  • Structured forms
  • Compact layouts

Use Columns For​

  • Better width utilization
  • Side-by-side editing
  • Balanced layouts

General Recommendations​

  • Keep layouts simple and intuitive.
  • Avoid excessive nesting.
  • Group related controls together.
  • Use meaningful labels and control IDs.
  • Reuse dictionaries and taxonomies where possible.

Summary​

The D2FS SDK dialog framework provides a rich set of containers and field controls for building structured, maintainable, and user-friendly interfaces.

Key capabilities include:

  • Flexible page organization with Tabs
  • Logical grouping through Fieldsets
  • Structured layouts using Grids and Columns
  • Dynamic data retrieval via DQL
  • Reusable value sets through Dictionaries
  • Hierarchical classification using Taxonomies
  • Rich input controls including Text, List, Combo, Date, Memo, Password, and HTML Editor

By combining these components effectively, developers can create scalable dialogs that support a wide range of business and repository-driven use cases.