Alien::GvaScript::CustomButtons(3)

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.

navigation properties

selectFirstBtn (boolean)
    boolean indicating whether to give focus to the first button in the found list.

    optional - defaulted to true

className (string)
    classname to match with button elements that are a part of navigation

    optional - defaulted to 'BN_button'

preventListBlur (boolean)
    boolean indicating whether a user can use the TAB and S_TAB keys to prevent navigation outside the button list.

    optional - defaulted to false

flashClassName (string)
    classname to give to the button when in flashing mode

    optional - defaulted to 'flash'

flashDuration (numeric)
    value in millis indicating how long to keep the flashClassName set on the button

    optional - defaulted to 100

  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}