# # Ribbon button component

`<ribbon-button>` has similar functions to XButton, but comparing to Xbutton, ribbon Button has a top-down structure of ICONS and text, and can be used as a Dropdown toggler.

## # Code examples

1. Simple ribbon-button example:

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button text="simple ribbon button without icon"></ribbon-button>
                   </div>
                   <div class="fv__ui-body">
                       <viewer></viewer>
                   </div>
               </webpdf>
           </template>
       </html>
       <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>

2. Customize icon

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button icon-class="fv__icon-toolbar-hand" text="button with built-in icon"></ribbon-button>
                       <ribbon-button icon-class="custom-icon-css-class" text="button with custom icon"></ribbon-button>
                   </div>
                   <viewer></viewer>
               </webpdf>
           </template>
       </html>
       <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>
       <style>
           .custom-icon-css-class {
               background-repeat: no-repeat;
               background-position: center;
               background-image: url(data:image/png;charset=utf-8;base64, );
           }
       </style>

3. Disabled ribbon-button

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button disabled="true" text="disabled button"></ribbon-button>
                   </div>
                   <viewer></viewer>
               </webpdf>
           </template>
       </html>
       <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>

4. Click event handler

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button name="alert-btn" text="Click Me!"></ribbon-button>
                   </div>
                   <viewer></viewer>
               </webpdf>
           </template>
       </html>
       <script>
           var CustomAppearance = UIExtension.appearances.Appearance.extend({
               getLayoutTemplate: function() {
                   return document.getElementById('layout-template').innerHTML;
               },
               getDefaultFragments: function() {
                   return [{
                       target: 'alert-btn',
                       config: {
                           callback: function() {
                               alert('click button!');
                           }
                       }
                   }];
               },
               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>

5. Use controller to handle click event

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button name="alert-btn" text="Click Me!"></ribbon-button>
                   </div>
                   <viewer></viewer>
               </webpdf>
           </template>
       </html>
       <script>
           var CustomAppearance = UIExtension.appearances.Appearance.extend({
               getLayoutTemplate: function() {
                   return document.getElementById('layout-template').innerHTML;
               },
               getDefaultFragments: function() {
                   return [{
                       target: 'alert-btn',
                       config: {
                           callback: UIExtension.controllers.Controller.extend({
                               handle: function() {
                                   alert("Click button!");
                               }
                           })
                       }
                   }];
               },
               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>

6. Use controller directive

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button name="alert-btn" text="Click Me!" @controller="custom-module:ClickButtonController"></ribbon-button>
                   </div>
                   <viewer></viewer>
               </webpdf>
           </template>
       </html>
       <script>
           var module = UIExtension.PDFUI.module('custom-module', []);
           module.controller('ClickButtonController', {
               handle: function() {
                   alert("Click button!");
               }
           });

           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>

7. Nested dropdown component

       <html>
           <template id="layout-template">
               <webpdf>
                   <div>
                       <ribbon-button icon-class="fx-icon-ribbon_view_read-32" text="read-aloud:read-aloud.read.text" class="inline">
                           <dropdown
                               icon-class="fv__icon-read-aloud-read"
                               separate="false"
                           >
                               <xbutton icon-class="fx-icon-ribbon_view_read-16" text="read-aloud:read-aloud.read.text"></xbutton>
                               <xbutton icon-class="fx-icon-ribbon_view_read_rate-32" text="read-aloud:read-aloud.rate.text"></xbutton>
                               <xbutton icon-class="fx-icon-ribbon_view_read-32" text="read-aloud:read-aloud.volume.text"></xbutton>
                               <xbutton icon-class="fx-icon-ribbon_view_read_pause-16" text="read-aloud:read-aloud.pause.text"></xbutton>
                           </dropdown>
                       </ribbon-button>
                   </div>
                   <viewer></viewer>
               </webpdf>
           </template>
       </html>
       <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: [
                       '/lib/uix-addons/read-aloud'
                   ]
           });
       </script>

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

## # API

### # Ribbon button properties

Properties | Description | Type
--- | --- | ---
disabled | ribbon-button disabled status | `boolean`
isVisible | ribbon-button visibility status | `boolean`

### # Methods

Method | Description | Version
--- | --- | ---
setText(text: String): void | Set ribbon-button text. It supports I18n entry. | 8.2.0
setIconCls(cssClass: String): void | Set icon's css-class of a ribbon-button | 8.2.0
disable(): void | Disable ribbon-button. The disabled ribbon-button will not respond to the click event | 8.2.0
enable(): void | Enable ribbon-button. The enabled ribbon-button will respond to the click event | 8.2.0
show(): void | Show the hidden ribbon-button | 8.2.0
hide(): void | Hide the ribbon-button | 8.2.0
destroy(): void | Destroy the ribbon-button component | 8.2.0

## # Events

Name | Description | Sample | Version
--- | --- | --- | ---
click | Click ribbon-button to trigger | `rbutton.on('click', () => {})` | 8.2.0