Alien::GvaScript::CustomButtons(3)

NAME
Alien::GvaScript::CustomButtons - Manage buttons creation, styling and keyboard navigation

DESCRIPTION
Composed of three subclasses that take care of rendering and displaying application buttons.

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

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

  Usage
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);

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>

  Methods
new

  var mybutton = new GvaScript.CustomButtons.Buttons(container, properties);

The "properties" hash describes the button behavior and display, with the following entries :

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'.

destroy

  mybutton.destroy()

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

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.

  Usage
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
  });

HTML

class does not produce any HTML

  Methods
new

The "properties" hash has the following entries :

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

destroy

  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.

GvaScript.CustomButtons.ActionsBar
For rendering a list of Buttons and adding support of keyboard navigation

  Usage
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);

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>

  Methodes
new

The "properties" hash has the following entries :

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'
  });

destroy

  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.

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}

DEPENDENCIES
This class depends on other GvaScript classes:

GvaScript.KeyMap