devextreme/ui/form.d.ts

HTML5 JavaScript Component Suite for Responsive Web Development

/**
* DevExtreme (ui/form.d.ts)
* Version: 21.1.4
* Build date: Mon Jun 21 2021
*
* Copyright (c) 2012 - 2021 Developer Express Inc. ALL RIGHTS RESERVED
* Read about DevExtreme licensing here: https://js.devexpress.com/Licensing/
*/
import {
    UserDefinedElement,
    DxElement
} from '../core/element';

import {
    DxPromise
} from '../core/utils/deferred';

import {
    template
} from '../core/templates/template';

import {
    EventInfo,
    InitializedEventInfo,
    ChangedOptionInfo
} from '../events/index';

import dxButton, {
    dxButtonOptions
} from './button';

import Editor from './editor/editor';

import {
    dxTabPanelOptions
} from './tab_panel';

import {
    AsyncRule,
    CompareRule,
    CustomRule,
    EmailRule,
    NumericRule,
    PatternRule,
    RangeRule,
    RequiredRule,
    StringLengthRule
} from './validation_rules';

import {
    dxValidationGroupResult
} from './validation_group';

import Widget, {
    WidgetOptions
} from './widget/ui.widget';

export type ContentReadyEvent = EventInfo<dxForm>;

export type DisposingEvent = EventInfo<dxForm>;

export type EditorEnterKeyEvent = EventInfo<dxForm> & {
    readonly dataField?: string;
}

export type FieldDataChangedEvent = EventInfo<dxForm> & {
    readonly dataField?: string;
    readonly value?: any;
}

export type InitializedEvent = InitializedEventInfo<dxForm>;

export type OptionChangedEvent = EventInfo<dxForm> & ChangedOptionInfo;

export type GroupItemTemplateData = {
    readonly component: dxForm;
    readonly formData?: any;
}

export type SimpleItemTemplateData = {
    readonly component: dxForm;
    readonly dataField?: string;
    readonly editorOptions?: any;
    readonly editorType?: string;
    readonly name?: string;
}

/**
 * @deprecated use Properties instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export interface dxFormOptions extends WidgetOptions<dxForm> {
    /**
     * Specifies whether or not all root item labels are aligned.
     */
    alignItemLabels?: boolean;
    /**
     * Specifies whether or not item labels in all groups are aligned.
     */
    alignItemLabelsInAllGroups?: boolean;
    /**
     * The count of columns in the form layout.
     */
    colCount?: number | 'auto';
    /**
     * Specifies dependency between the screen factor and the count of columns in the form layout.
     */
    colCountByScreen?: any;
    /**
     * Specifies a function that customizes a form item after it has been created.
     */
    customizeItem?: ((item: dxFormSimpleItem | dxFormGroupItem | dxFormTabbedItem | dxFormEmptyItem | dxFormButtonItem) => void);
    /**
     * Provides the Form&apos;s data. Gets updated every time form fields change.
     */
    formData?: any;
    /**
     * Holds an array of form items.
     */
    items?: Array<dxFormSimpleItem | dxFormGroupItem | dxFormTabbedItem | dxFormEmptyItem | dxFormButtonItem>;
    /**
     * Specifies the location of a label against the editor.
     */
    labelLocation?: 'left' | 'right' | 'top';
    /**
     * The minimum column width used for calculating column count in the form layout.
     */
    minColWidth?: number;
    /**
     * A function that is executed when the Enter key has been pressed while an editor is focused.
     */
    onEditorEnterKey?: ((e: EditorEnterKeyEvent) => void);
    /**
     * A function that is executed when the value of a formData object field is changed.
     */
    onFieldDataChanged?: ((e: FieldDataChangedEvent) => void);
    /**
     * The text displayed for optional fields.
     */
    optionalMark?: string;
    /**
     * Specifies whether all editors on the form are read-only. Applies only to non-templated items.
     */
    readOnly?: boolean;
    /**
     * The text displayed for required fields.
     */
    requiredMark?: string;
    /**
     * Specifies the message that is shown for end-users if a required field value is not specified.
     */
    requiredMessage?: string;
    /**
     * Specifies a function that categorizes screens by their width.
     */
    screenByWidth?: Function;
    /**
     * A Boolean value specifying whether to enable or disable form scrolling.
     */
    scrollingEnabled?: boolean;
    /**
     * Specifies whether or not a colon is displayed at the end of form labels.
     */
    showColonAfterLabel?: boolean;
    /**
     * Specifies whether or not the optional mark is displayed for optional fields.
     */
    showOptionalMark?: boolean;
    /**
     * Specifies whether or not the required mark is displayed for required fields.
     */
    showRequiredMark?: boolean;
    /**
     * Specifies whether or not the total validation summary is displayed on the form.
     */
    showValidationSummary?: boolean;
    /**
     * Gives a name to the internal validation group.
     */
    validationGroup?: string;
}
/**
 * The Form UI component represents fields of a data object as a collection of label-editor pairs. These pairs can be arranged in several groups, tabs and columns.
 */
export default class dxForm extends Widget {
    constructor(element: UserDefinedElement, options?: dxFormOptions)
    /**
     * Gets a button&apos;s instance.
     */
    getButton(name: string): dxButton | undefined;
    /**
     * Gets an editor instance. Takes effect only if the form item is visible.
     */
    getEditor(dataField: string): Editor | undefined;
    /**
     * Gets a form item&apos;s configuration.
     */
    itemOption(id: string): any;
    /**
     * Updates the value of a single item option.
     */
    itemOption(id: string, option: string, value: any): void;
    /**
     * Updates the values of several item properties.
     */
    itemOption(id: string, options: any): void;
    /**
     * Resets the editor&apos;s value to undefined.
     */
    resetValues(): void;
    /**
     * Merges the passed `data` object with formData. Matching properties in formData are overwritten and new properties added.
     */
    updateData(data: any): void;
    /**
     * Updates a formData field and the corresponding editor.
     */
    updateData(dataField: string, value: any): void;
    /**
     * Updates the dimensions of the UI component contents.
     */
    updateDimensions(): DxPromise<void>;
    /**
     * Validates the values of all editors on the form against the list of the validation rules specified for each form item.
     */
    validate(): dxValidationGroupResult;
}

/**
 * Configures a button form item.
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export interface dxFormButtonItem {
    /**
     * Configures the button.
     */
    buttonOptions?: dxButtonOptions;
    /**
     * Specifies how many columns the item spans.
     */
    colSpan?: number;
    /**
     * Specifies a CSS class to be applied to the item.
     */
    cssClass?: string;
    /**
     * Specifies the button&apos;s horizontal alignment.
     */
    horizontalAlignment?: 'center' | 'left' | 'right';
    /**
     * Specifies the item&apos;s type. Set it to &apos;button&apos; to create a button item.
     */
    itemType?: 'empty' | 'group' | 'simple' | 'tabbed' | 'button';
    /**
     * Specifies the item&apos;s identifier.
     */
    name?: string;
    /**
     * Specifies the button&apos;s vertical alignment.
     */
    verticalAlignment?: 'bottom' | 'center' | 'top';
    /**
     * Specifies whether the item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the item&apos;s position regarding other items in a group, tab, or the whole UI component.
     */
    visibleIndex?: number;
}

/**
 * This article describes configuration properties of an empty form item.
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export interface dxFormEmptyItem {
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string;
    /**
     * Specifies the item&apos;s type. Set it to &apos;empty&apos; to create an empty item.
     */
    itemType?: 'empty' | 'group' | 'simple' | 'tabbed' | 'button';
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string;
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number;
}

/**
 * This article describes configuration properties of a group form item.
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export interface dxFormGroupItem {
    /**
     * Specifies whether or not all group item labels are aligned.
     */
    alignItemLabels?: boolean;
    /**
     * Specifies the group caption.
     */
    caption?: string;
    /**
     * The count of columns in the group layout.
     */
    colCount?: number;
    /**
     * Specifies the relation between the screen size qualifier and the number of columns in the grouped layout.
     */
    colCountByScreen?: any;
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string;
    /**
     * Specifies the item&apos;s type. Set it to &apos;group&apos; to create a group item.
     */
    itemType?: 'empty' | 'group' | 'simple' | 'tabbed' | 'button';
    /**
     * Holds an array of form items displayed within the group.
     */
    items?: Array<dxFormSimpleItem | dxFormGroupItem | dxFormTabbedItem | dxFormEmptyItem | dxFormButtonItem>;
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string;
    /**
     * A template to be used for rendering a group item.
     */
    template?: template | ((data: GroupItemTemplateData, itemElement: DxElement) => string | UserDefinedElement);
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number;
}

/**
 * This article describes configuration properties of a simple form item.
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export interface dxFormSimpleItem {
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string;
    /**
     * Specifies the path to the formData object field bound to the current form item.
     */
    dataField?: string;
    /**
     * Configures the form item&apos;s editor.
     */
    editorOptions?: any;
    /**
     * Specifies which editor UI component is used to display and edit the form item value.
     */
    editorType?: 'dxAutocomplete' | 'dxCalendar' | 'dxCheckBox' | 'dxColorBox' | 'dxDateBox' | 'dxDropDownBox' | 'dxHtmlEditor' | 'dxLookup' | 'dxNumberBox' | 'dxRadioGroup' | 'dxRangeSlider' | 'dxSelectBox' | 'dxSlider' | 'dxSwitch' | 'dxTagBox' | 'dxTextArea' | 'dxTextBox';
    /**
     * Specifies the help text displayed for the current form item.
     */
    helpText?: string;
    /**
     * Specifies whether the current form item is required.
     */
    isRequired?: boolean;
    /**
     * Specifies the item&apos;s type. Set it to &apos;simple&apos; to create a simple item.
     */
    itemType?: 'empty' | 'group' | 'simple' | 'tabbed' | 'button';
    /**
     * Specifies properties for the form item label.
     */
    label?: {
      /**
       * Specifies the label&apos;s horizontal alignment.
       */
      alignment?: 'center' | 'left' | 'right',
      /**
       * Specifies the location of a label against the editor.
       */
      location?: 'left' | 'right' | 'top',
      /**
       * Specifies whether or not a colon is displayed at the end of the current label.
       */
      showColon?: boolean,
      /**
       * Specifies the label text.
       */
      text?: string,
      /**
       * Specifies whether or not the label is visible.
       */
      visible?: boolean
    };
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string;
    /**
     * A template that can be used to replace the default editor with custom content.
     */
    template?: template | ((data: SimpleItemTemplateData, itemElement: DxElement) => string | UserDefinedElement);
    /**
     * An array of validation rules to be checked for the form item editor.
     */
    validationRules?: Array<RequiredRule | NumericRule | RangeRule | StringLengthRule | CustomRule | CompareRule | PatternRule | EmailRule | AsyncRule>;
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number;
}

/**
 * This article describes configuration properties of a tabbed form item.
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export interface dxFormTabbedItem {
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string;
    /**
     * Specifies the item&apos;s type. Set it to &apos;tabbed&apos; to create a tabbed item.
     */
    itemType?: 'empty' | 'group' | 'simple' | 'tabbed' | 'button';
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string;
    /**
     * Holds a configuration object for the TabPanel UI component used to display the current form item.
     */
    tabPanelOptions?: dxTabPanelOptions;
    /**
     * An array of tab configuration objects.
     */
    tabs?: Array<{
      /**
       * Specifies whether or not labels of items displayed within the current tab are aligned.
       */
      alignItemLabels?: boolean,
      /**
       * Specifies a badge text for the tab.
       */
      badge?: string,
      /**
       * The count of columns in the tab layout.
       */
      colCount?: number,
      /**
       * Specifies the relation between the screen size qualifier and the number of columns in the tabbed layout.
       */
      colCountByScreen?: any,
      /**
       * Specifies whether the tab responds to user interaction.
       */
      disabled?: boolean,
      /**
       * Specifies the icon to be displayed on the tab.
       */
      icon?: string,
      /**
       * Holds an array of form items displayed within the tab.
       */
      items?: Array<dxFormSimpleItem | dxFormGroupItem | dxFormTabbedItem | dxFormEmptyItem | dxFormButtonItem>,
      /**
       * The template to be used for rendering the tab.
       */
      tabTemplate?: template | ((tabData: any, tabIndex: number, tabElement: DxElement) => any),
      /**
       * The template to be used for rendering the tab content.
       */
      template?: template | ((tabData: any, tabIndex: number, tabElement: DxElement) => any),
      /**
       * Specifies the tab title.
       */
      title?: string
    }>;
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number;
}

export type Properties = dxFormOptions;

/**
 * @deprecated use Properties instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export type Options = dxFormOptions;

/**
 * @deprecated use Properties instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please describe your scenario in the following GitHub Issue, and we will suggest a public alternative: {@link https://github.com/DevExpress/DevExtreme/issues/17885|Internal Types}.
 */
export type IOptions = dxFormOptions;