# `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