# # Dropdown component

## # Code examples

### # Basic example

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <dropdown icon-class="fv__icon-toolbar-shape" text="Dropdown">
                        <xbutton icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                        <li class="fv__ui-dropdown-separator"></li>
                        <file-selector>Select a file</file-selector>
                        <li class="my-dropdown-list-item">
                        </li>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .my-dropdown-list-item {
            padding: 10px 0;
            text-align: center;
        }
        .fv__ui-dropdown {
            width: auto;
        }
    </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"
        }
    }

### # Separation

A dropdown button can be divided into left and right parts. The left part consists of icons and text, and the right part is a drop-down arrow. When the `separate` parameter is set to false, you can click any one of the two parts to display the drop-down list. When the `separate` parameter is set to true, you can only click the right part (drop-down arrow) to display the drop-down list.

In the following demo, you will see two dropdown buttons as shown below:

Try to click the 'Separated Dropdown' button, you will notice the dropdown list can display only when the arrow is clicked. This is because the dropdown button has been separated, and only clicking-on-arrow can trigger the dropdown list. But you can make the dropdown list display by clicking any area on the `Un-separated Dropdown` button.

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <!-- By default, the value of dropdown's 'separate' option is true -->
                    <!-- Set selected="0" means when you click on the dropdown button, it will trigger the event for  the first item in the dropdown list -->
                    <dropdown name="separate-dropdown" icon-class="fv__icon-toolbar-square" text="Separated Dropdown" selected="0">
                        <xbutton name="separate-dropdown-square-btn" icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                        <file-selector>Select a file</file-selector>
                        <li class="my-dropdown-list-item">
                            html &lt;li&gt; tag
                        </li>
                    </dropdown>
                    <dropdown name="non-separate-dropdown" icon-class="fv__icon-toolbar-shape" text="Un-separated Dropdown" separate="false">
                        <xbutton icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .my-dropdown-list-item {
            padding: 10px 0;
            text-align: center;
        }
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            getDefaultFragments: function() {
                return [{
                    target: 'separate-dropdown-square-btn',
                    config: [{
                        callback: function() {
                            alert('Click on separate Dropdown');
                        }
                    }]
                }];
            },
            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"
        }
    }

### # Use as select component

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <!-- Specify selected="0" that is the initial value -->
                    <dropdown name="separate-dropdown" icon-class="fv__icon-toolbar-square" text="Separated Dropdown" selected="0">
                        <xbutton name="separate-dropdown-square-btn" icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                    </dropdown>
                    <dropdown name="not-separate-dropdown" icon-class="fv__icon-toolbar-shape" text="not separated Dropdown" separate="false" selected="0">
                        <xbutton icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .my-dropdown-list-item {
            padding: 10px 0;
            text-align: center;
        }
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            getDefaultFragments: function() {
                return [{
                    target: 'separate-dropdown @xbutton,not-separate-dropdown @xbutton',
                    config: [{
                        callback: function() {
                            this.component.parent.select(this.component);
                        }
                    }]
                }];
            },
            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"
        }
    }

### # Editable

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <dropdown name="font-editable-dropdown" editable>
                        <xbutton>Helvetica</xbutton>
                        <xbutton>Courier</xbutton>
                        <xbutton>Times-Bold</xbutton>
                        <xbutton>宋体</xbutton>
                    </dropdown>
                    <dropdown name="zoom-editable-dropdown" editable @controller="custom:ZoomPageController">
                        <xbutton @controller="custom:ScaleRatioController" scale="0.5">50%</xbutton>
                        <xbutton @controller="custom:ScaleRatioController" scale="0.75">75%</xbutton>
                        <xbutton @controller="custom:ScaleRatioController" scale="1">100%</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-dropdown {
            width: 80px;
        }
    </style>
    <script>
        UIExtension.PDFUI.module('custom', [])
        .controller('ScaleRatioController', {
            handle: function() {
                const scaleRatio = parseFloat(this.component.element.getAttribute('scale'));
                debugger;
                this.component.parent.setEditValue(scaleRatio);
            }
        })
        .controller('ZoomPageController', {
            mounted: function() {
                const component = this.component;
                const firstChild = component.childAt(0);
                const scaleRatio = parseFloat(firstChild.element.getAttribute('scale'))
                component.setEditValue(scaleRatio);
                component.on('change', function(newValue, oldValue) {
                    if(isNaN(parseFloat(newValue))) {
                        alert('Illegal scale value: ' + newValue);
                        component.setEditValue(oldValue);
                        return;
                    }
                    alert('scale value changed to: ' + newValue)
                })
            }
        });
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            getDefaultFragments() {
                return [{
                    target: 'zoom-editable-dropdown',
                    config: {
                        editOptions: {
                            type: 'number',
                            min: 0,
                            max: 10,
                            step: 0.01
                        }
                    }
                }];
            },
            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"
        }
    }

### # Position the dropdown list

    <html>
        <template id="layout-template">
            <webpdf>
                <div class="flex-with-gap">
                    <dropdown text="Align left,bottom(default position)" align="left" valign="bottom">
                        <li>left bottom</li>
                    </dropdown>
                    <dropdown text="Align right,bottom" align="right" valign="bottom">
                        <li>right bottom</li>
                    </dropdown>
                    <dropdown text="Align center,bottom" align="center" valign="bottom">
                        <li>center bottom</li>
                    </dropdown>
                </div>
                <div class="flex-with-gap">
                    <dropdown text="Align out-right,bottom" align="out-right" valign="bottom">
                        <li>out-right bottom</li>
                    </dropdown>
                    <dropdown text="Align client-center,bottom" align="client-center" valign="bottom">
                        <li>client-center bottom</li>
                    </dropdown>
                    <dropdown text="Align out-left,bottom" align="out-left" valign="bottom">
                        <li>out-left bottom</li>
                    </dropdown>
                </div>
                <div class="flex-with-gap">
                    <dropdown text="Align left,client-center" align="left" valign="client-center">
                        <li>left client-center</li>
                    </dropdown>
                    <dropdown text="Align client-center,client-center" align="client-center" valign="client-center">
                        <li>client-center</li>
                    </dropdown>
                    <dropdown text="Align left,top" align="left" valign="top">
                        <li>left top</li>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-dropdown {
            width: auto;
        }
        .flex-with-gap {
            display: flex;
            flex-direction: row;
            justify-content: center;
        }
        .flex-with-gap>.fv__ui-dropdown {
            margin: 0 20px;
            flex: 1 1 auto;
        }
    </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"
        }
    }

### # Dynamic dropdown list

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <dropdown separate="false" @controller="custom:DropdownItemListController as ctrl" text="Dynamic dropdown list">
                        <li style="padding-left: 1em;">Click button to create more</li>
                        <li @foreach="item in ctrl.items track by id">
                            <text @sync.text="item.text"></text>
                        </li>
                        <xbutton icon-class="fv__icon-toolbar-add-sign" @controller="custom:AddItemController">Add dropdown item</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        UIExtension.PDFUI.module('custom', [])
            .controller('DropdownItemListController', {
                init: function() {
                    this.items = [{
                        id: Date.now().toString(16),
                        text: new Date().toLocaleString()
                    }];
                },
                addItem: function(data) {
                    this.items = this.items.concat(data);
                    this.digest();
                }
            })
            .controller('AddItemController', {
                handle: function() {
                    const itemListCtrl = this.data.ctrl;
                    itemListCtrl.addItem({
                        id: Date.now().toString(16),
                        text: new Date().toLocaleString()
                    });
                }
            })
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll(){}
        });
        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

### # Dropdown component template

Template example:

    <dropdown text="" icon-class="" editable align="left" valign="bottom" separate="true" selected="0"></dropdown>

The template properties:

Property | Description | Type | Default Value | Version
--- | --- | --- | --- | ---
text | Set text for dropdown button | `string` | `''` | 7.0
icon-class | Set the icon's css class | `string` | `''` | 7.0
editable | If editable | `boolean` | `false` | 7.0
align | Horizontal alignment | `'left'|'right'|'out-right'|'out-left'|'center'|'client-center'` | `'left'` | 7.0
valign | Vertical alignment | `'top'|'bottom'|'center'|'client-center'` | `'bottom'` | 7.0
separate | If the dropdown button is separated | `boolean` | `true` | 7.0

#### # Configure dropdown properties using fragment

Besides the `editOptions`, the others are same as the template properties.

    {
        target: 'dropdown-name',
        config: {
            editOptions: {
                type: 'text',
                min: 0,
                max: 0,
                step: 0,
                vallue: ''
            }
        }
    }

Property | Description | Type | Default Value | Version
--- | --- | --- | --- | ---
editOptions.type | Set edit mode for dropdown. It supports both the `'text'` and `'number'` edit mode | `string` | `'text'` | 7.0
editOptions.min | The minimum value for the edit box. It is valid only when the edit mode is `'number'` | `number` |  | 7.0
editOptions.max | The maximum value for the edit box. It is valid only when the edit mode is `'number'` | `number` |  | 7.0
editOptions.step | The step for the edit box. It is valid only when the edit mode is `'number'` | `number` |  | 7.0
editOptions.value | The initial value of the edit box | `string|number` |  | 7.0

### # Dropdown object properties

Property | Description | Type
--- | --- | ---
disabled | Dropdown disabled status | `boolean`
isVisible | Dropdown visible status | `boolean`
isActive | Check if the dropdown list is active | `boolean`

### # Methods

Method | Description | Version
--- | --- | ---
`setEditValue(text:String|number): void` | Set the input value. This won't trigger the `change`event | 7.0
`disable(): void` | Disable dropdown. | 7.0
`enable(): void` | Enable the disabled dropdown | 7.0
`show(): void` | Show the hidden dropdown | 7.0
`hide(): void` | Hide the dropdown | 7.0
`active(): void` | Open the dropdown | 7.0
`deactive(): void` | Close the dropdown | 7.0
`destroy(): void` | Destroy the component | 7.0

## # Events

Name | Description | Example | Version
--- | --- | --- | ---
active | Triggered upon the dropdown expands | `dropdown.on('active', () => {})` | 7.0
deactive | Triggered upon the dropdown hides | `dropdown.on('deactive', () => {})` | 7.0
change | Triggered upon the mouse enters and focus loses | `dropdown.on('change', (newValue,oldValue) => {})` | 7.0