# GvaScript.CustomButtons

Manage buttons creation, styling and keyboard navigation

### Table of contents

NAME
SYNOPSIS
DEPENDENCIES
DESCRIPTION
GvaScript.CustomButtons.Button
Javascript
DESTRUCTOR
button properties
HTML
GvaScript.CustomButtons.ButtonNavigation
Javascript
DESTRUCTOR
navigation properties
HTML
GvaScript.CustomButtons.ActionsBar
Javascript
DESTRUCTOR
actionsbar properties
HTML
CSS

## NAME

GvaScript.CustomButtons - Manage buttons creation, styling and keyboard navigation

## SYNOPSIS

Composed of three subclasses

- GvaScript.CustomButtons.Button
- GvaScript.CustomButtons.ButtonNavigation
- GvaScript.CustomButtons.ActionsBar

## DEPENDENCIES

This class depends on other GvaScript classes:

- GvaScript.KeyMap

## DESCRIPTION

Classes that take care of rendering and displaying application buttons.

Displayed buttons will support hovering effects through custom css classnames and keyboard navigation using RIGHT and LEFT arrows.

Buttons in their different states (idle, focus and hover) are easily styled using css classes.

## GvaScript.CustomButtons.Button

For rendering a Single Button

### Javascript

      var container = $('my_button_will_display_here');
      var button_properties = {
        id        : 'btn_'+(new Date()).getTime(),
        callback  : Prototype.emptyFunction, // btnClickHandler
        condition : true,                    // boolean indicating whether to render button
        width     : 'auto',                  // string value including unit. ex: '100px', '5em' ..
        type      : 'button',                // button|reset|submit
        style     : {borderWidth: '2px'}     // hash of inline style elemets to be set on the button container
        label     : 'GVA_SCRIPT_BUTTON'      // button label
      }

      // create a new button and display in container
      var mybutton = new GvaScript.CustomButtons.Buttons(container, button_properties);

### DESTRUCTOR

      mybutton.destory()

This method removes the click handler attached to the button. Call this method when the button is removed from the DOM.

#### button properties

properties hash describing the button behavior and display.

- id (string)

  unique identifier of the button - will be set to the <button> element.

  optional - system will provide one if none provided.

- tabindex (numeric)

  numeric value of the tabindex to set on the generated button element.

  optional - button will not have tabindex attribute if none provided.

- callback (function)

  onclick handler of the <button> element - will execute in the button context.

  optional - defaulted to empty function.

- condition (boolean|function)

  boolean value or a function that returns a boolean value indicating whether to render and display the button or not. Note that if condition is false, the button will not be a part of the DOM.

  optional - defaulted to true.

- width (string)

  string value to set on the style.width of the <button> element. string value must include the unit or else will be ignored.

  optional - defaulted to 'auto'.

- type (string)

  the type attribute of the <button> element. could be one of the following:

  - button

    generic behavior of the button.

  - submit

    submits containing <form> when clicked.

  - reset

    resets containing <form> when clicked.

  optional - default to 'button'

- style (hash)

  hash containing style elements to be set to the inline style attribute of the button container element.

  optional - defaulted to {}.

- label (string)

  label of the button.

  optional - defaulted to 'GVA_SCRIPT_BUTTON'.

### HTML

The button will be rendered and resulting HTML will be placed in th designated container.

      <div id="my_button_will_display_here" style="border-width: 2px;">
        <span class="gva-btn-container">
          <span class="left"/>
          <span class="center">
              <button type="button" class="btn" style="width: auto;" id="btn_1227001526005">
                  GVA_SCRIPT_BUTTON
              </button>
          </span>
          <span class="right"/>
        </span>
      </div>

## GvaScript.CustomButtons.ButtonNavigation

For adding support of keyboard navigation over a list of buttons. Mostly used internally with GvaScript.CustomButtons.ActionsBar class.

The class searches for <button> or <input type="button|submit|reset"> elements that has a predefined classname and that are contained in a provided container.

This class is used implicitly by the ActionsBar class.

### Javascript

      // container of the buttons we are looking for
      var container  = $('my_buttons_are_contained_here');

      // classname of the buttons we are looking for
      var className  = 'gva-btn-container';

      // initialize ButtonNavigation to activate keyboard map
      var mybuttonnavigator = new GvaScript.CustomButtons.ButtonNavigation(container, {
        selectFirstBtn  : true,
        className       : className,
        preventListBlur : false,
        flashClassName  : 'flash',
        flashDuration   : 100
      });

### DESTRUCTOR

      mybuttonnavigator.destroy()

This method removes the different handlers attached on the buttons container. Call this method when the buttons container is removed from the DOM.

### HTML

class does not produce any HTML

## GvaScript.CustomButtons.ActionsBar

For rendering a list of Buttons and adding support of keyboard navigation

### Javascript

      var container = $('my_buttons_bar_will_display_here');
      var actionsbar_properties = {
        actions     : [],    // array of button_properties
        selectfirst : false  // focus on first button
      }

      // create a new buttons list and display next to each other in container
      var myactionsbar = new GvaScript.CustomButtons.ActionsBar(container, actionsbar_properties);

### DESTRUCTOR

      myactionsbar.destory();

This method removes the different handlers attached on the buttons and their container. Call this method when the buttons container is removed from the DOM.

#### actionsbar properties

- actions array

  list of button_properties describing a Button.

  required.

- selectfirst boolean

  boolean indicating whether to give focus to the first button in the list when the actionsbar finished rendering.

  optional - defaulted to false.

ActionsBar implicitly initializes ButtonNavigation object with following properties

      new GvaScript.CustomButtons.ButtonNavigation(this.container, {
        selectFirstBtn : this.options.selectfirst,
        className      : 'gva-btn-container'
      });

### HTML

The list of buttons will be rendered one by one and the resulting HTML will be appended sequentially into the designated container.

      <div id="my_buttons_bar_will_display_here" class="gva-actionsbar">
        <span id="btn_1236083609358" class="gva-btn-container">
          <span class="left"/>
          <span class="center">
            <button class="btn" style="width: auto;" type="button">Modifier</button>
          </span>
          <span class="right"/>
        </span>
        <span id="btn_1236083609358" class="gva-btn-container">
          <span class="left"/>
          <span class="center">
            <button class="btn" style="width: auto;" type="button">Modifier</button>
          </span>
          <span class="right"/>
        </span>
      </div>

## CSS

Example CSS stylesheet for styling buttons.

By default, css classnames are prefixed by 'gva'.

This can be overloaded by a global js variable: CSS_PREFIX if declared before the inclusion of this Library

Notice the btn-focus, btn-hover and flash classnames that are used to style the buttons in their different states.

        /* IE fix: to the ridiculously wide buttons in IE */
        .gva-btn-container .btn {width:1pt;overflow:visible;}
        /* END: IE specific */

        .gva-actionsbar {background-color:#E8E8E8;border:1px solid #8c8c8c;border-width:1px 0px;height:25px;padding:4px 0 1px;}
        .gva-btn-container {display:inline;}
        .gva-btn-container .btn {margin:0 3px;font-size:12px;cursor:pointer;}
        .gva-btn-container .btn {
            font-family:verdana,geneva,lucida,'lucida grande',arial,helvetica,sans-serif;
            background:none;
            border:none;
            cursor:pointer;
            padding:1px 2px;
            color:#000;
            background-color:transparent !important;
        }
        .gva-btn-container .btn {float:left;}
        .gva-btn-container.btn-focus .btn {color:#aa0000;}
        .gva-btn-container span {display:block;float:left;height:21px;}
        .gva-btn-container span.left {background:transparent url(btn_sprite.gif) no-repeat scroll 0 0;padding:0 1px 0 2px;margin-left:4px;}
        .gva-btn-container span.center {background:transparent url(btn_sprite.gif) repeat-x scroll 0 -42px;padding:0 2px}
        .gva-btn-container span.right {background:transparent url(btn_sprite.gif) no-repeat scroll 0 -21px;padding:0 1px 0 2px;}
        .gva-btn-container.btn-hover span.left {background-position:0 -63px;}
        .gva-btn-container.btn-hover span.center {background-position:0 -105px;}
        .gva-btn-container.btn-hover span.right {background-position:0 -84px;}
        .gva-btn-container.btn-focus span.left {background-position:0 -63px;}
        .gva-btn-container.btn-focus span.center {background-position:0 -126px;}
        .gva-btn-container.btn-focus span.right {background-position:0 -84px;}
        .gva-btn-container.flash .btn {color:red !important}