# # `form-group` component

The `<form-group>` component is used to add certain controls with a specific structure to a form. It is the easy way to organize the layout of input components and labels, and to provide the help text.

Note: The `<form-group>` currently is used only for the "fv--comparison-select-pdf-file-dialog".

## # Codes Example

### # Label Text

The label text of the form component is used to provide a description of an innput component.

#### # Label Text Layout

The label text for the `form-group` component provides three types of form layouts, `ltr`, `rtl` and `ttb`:

- The `ltr` and `rtl` are horizontal layouts, and the label text and the input component display on the same line.
- The `ltr` in layout is that the label text appears on the left side of the input component.
- The `rtl` in layout is that the label text appears to the right of the input component.
- The `ttb` is a vertical layout, means Top-To-Bottom, where the label text appears above the input component.

The following example demonstrates the effect of these three layouts:

    <html>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <layer class="center" visible="true" backdrop style="width: 640px">
                        <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                        <layer-view>
                            <fieldset>
                                <legend>direction="ltr"</legend>
                                <form-group label="Name">
                                    <input>
                                </form-group>
                                <form-group label="Email">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="rtl"</legend>
                                <form-group label="Name" direction="rtl">
                                    <input>
                                </form-group>
                                <form-group label="Email" direction="rtl">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" direction="rtl">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="ttb"</legend>
                                <form-group label="Name" direction="ttb">
                                    <input>
                                </form-group>
                                <form-group label="Email" direction="ttb">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" direction="ttb">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                        </layer-view>
                    </layer>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group-label {
            width: 5em;
        }
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

#### # Label Delimiter

In the example above, the label delimiter `:` takes place automatically when the `direction` is set to `ltr` and `ttb`. If the delimiter sign is not required, you can include delimiter inside the `<legend>` tag but leave its value blank to hide it:

    <html>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <layer class="center" visible="true" backdrop style="width: 640px">
                        <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                        <layer-view>
                            <fieldset>
                                <legend>direction="ltr" delimiter=""</legend>
                                <form-group label="Name" delimiter="">
                                    <input>
                                </form-group>
                                <form-group label="Email" delimiter="">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" delimiter="">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="ttb" delimiter=""</legend>
                                <form-group label="Name" direction="ttb" delimiter="">
                                    <input>
                                </form-group>
                                <form-group label="Email" direction="ttb" delimiter="">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" direction="ttb" delimiter="">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                        </layer-view>
                    </layer>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group-label {
            width: 5em;
        }
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 400px"
        }
    }

### # Help Text

The help text is optional and is primarily used to display component descriptive information, and the content can be set through the `description` property, which supports i18n.

The following example shows the help text styles in the different layouts:

    <html>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <layer class="center" visible="true" backdrop style="width: 640px">
                        <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                        <layer-view>
                            <fieldset>
                                <legend>direction="ltr"</legend>
                                <form-group label="Name" description="Let us know your name">
                                    <input>
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="rtl"</legend>
                                <form-group label="Email" direction="rtl" description="To verify and receive reminders">
                                    <input type="email">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="ttb"</legend>
                                <form-group label="Address" direction="ttb" description="To mail">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                        </layer-view>
                    </layer>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group-label {
            width: 5em;
        }
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 400px"
        }
    }

### # Set Parameters Dynamically

The parameters of the `form-group` component can be dynamically modified via the template or js, see the following example:

    <html>
        <template id="example-dialog-template">
            <layer class="center" backdrop style="width: 640px" @var.comp="$component">
                <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                <layer-view>
                    <fieldset>
                        <legend>Parameter adjustments (Template Syntax)</legend>
                        <form-group label="Set up the signature">
                            <input @model="comp.label">
                        </form-group>
                        <form-group label="Set the help text">
                            <input @model="comp.description">
                        </form-group>
                        <form-group label="Set the delimiter">
                            <input @model="comp.delimiter">
                        </form-group>
                        <form-group label="Set the layout" tag="div">
                            <radio name="form-group-direction" @model="comp.direction" value="ltr" text="Horizontal - left"></radio>
                            <radio name="form-group-direction" @model="comp.direction" value="rtl" text="Horizontal - to the right"></radio>
                            <radio name="form-group-direction" @model="comp.direction" value="ttb" text="vertical"></radio>
                        </form-group>
                    </fieldset>
                    <fieldset>
                        <legend>Parameter adjustments（js API）</legend>
                        <button @on.click="comp.resetLabel()">Resets the label text</button>
                        <button @on.click="comp.resetDescription()">Reset the help text</button>
                        <button @on.click="comp.resetDirection()">Random layout</button>
                    </fieldset>
                    <fieldset>
                        <legend>Result preview</legend>
                        <form-group
                            @setter.label="comp.label"
                            @setter.description="comp.description"
                            @setter.delimiter="comp.delimiter"
                            @setter.direction="comp.direction"
                            @init="comp.formGroupComponent = $component"
                        >
                            <input>
                        </form-group>
                    </fieldset>
                </layer-view>
            </layer>
        </template>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <exp:example-dialog visible="true"></exp:example-dialog>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </style>
    <script>
        class ExampleDialog extends UIExtension.SeniorComponentFactory.createSuperClass({
            template: document.getElementById('example-dialog-template').innerHTML
        })  {
            static getName() {
                return 'example-dialog'
            }
            init() {
                super.init();
                this.delimiter = ':';
                this.description = 'Help Text';
                this.label = 'Label Text';
                this.direction = 'ltr';
            }
            resetLabel() {
                this.formGroupComponent.setLabel(
                    this.label = new Date().toUTCString()
                );
                this.digest();
            }
            resetDescription() {
                this.formGroupComponent.setDescription(
                    this.description = 'Help Text: ' + new Date().toUTCString()
                );
                this.digest();
            }
            resetDirection() {
                this.formGroupComponent.setDirection(
                    this.direction = ['ltr', 'rtl', 'ttb'][Math.floor(Math.random() * 3)]
                );
                this.digest();
            }
        }
        UIExtension.modular.module('exp', []).registerComponent(ExampleDialog);
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

## # API

### # `form-group` Component Templates

Example:

    <form-group delimiter=":" direction="ltr" label="" description="">
        <input>
    </form-group>

Descriptions for each property of the `form-group`:

Attribute | Description | Type | The default value | Version
--- | --- | --- | --- | ---
delimiter | The delimiter after the label text, invalid when `direction` is `rtl` | `string` | `':'` | 8.5.0
direction | The way to lay out the label text and input components. | `'ltr'` | `'rtl'` | `'ttb'` | `'ltr'` | 8.5.0
label | Label text | `string` | `''` | 8.5.0
description | The help text under the input component | `string` | `''` | 8.5.0

### # Methods

`form-group` componets' methods

Method | Description | Version
--- | --- | ---
`setDelimiter(delimiter: string)` | Modify the delimiter | 8.5.0
`setDirection(direction: 'ltr'|'rtl'|'ttb')` | Modify the layout way | 8.5.0
`setLabel(label: string)` | Modify the label text | 8.5.0
`setDescription(description: string)` | Modify the help text | 8.5.0

### # Event

The `form-group` component does not define events.