API: JS: Decorators

##Description The MWF provides a set of JavaScript decorators for developers who use JavaScript. These decorators aid in producing HTML markup programmatically with simple JavaScript code. They assist specifically in creating MWF applications because they provide an easy way to create the markup for several framework entities on client-side.

##Intent To facilitate the rapid production of HTML markup and specifically that required for MWF entities by offering a set of classes that represent different HTML markup entities. Use of the JavaScript decorators limits the necessity to code MWF markup on server side and allows automatic, client-side generation of MWF entities.

##Implementation The primary goal of the implementation was to create a simple, non-invasive, native JavaScript support for MWF entities without utilizing any 3rd party libraries such as JQuery etc. Current implementation of JavaScript decorators includes four main files: decorator.js, button.js, menu.js, and also content.js. decorators.js is generic collection of functionalities and has a primary goal of encapsulating common logic between the rest of classes and acting as a building block for various entities.

##Getting Started with JS Decorators

Before jumping into implementation details, please see below a simple script that produces a four item menu.

<script type="text/javascript" src="http://[domain]/mwf/decorator.js"> </script>
<script type="text/javascript" src="http://[domain]/mwf/menu.js"> </script>

<script type='text/javascript'>

    //Create a menu element with title 'Cool Title'.
    var menu = mwf.decorator.Menu("Menu Title");

    menu.addMenuLinkItem("Link to UCLA Mobile", "http://m.ucla.edu");
    menu.addMenuLinkItem("Link to Google Search", "http://www.google.com");
    
    //Create a simple checkbox with specified input name, value, and label.
    menu.addMenuCheckboxItem("name", "value", "label");

    //Create a radio button that also includes a detailed section. 
    menu.addMenuRadioItem("name", "value", "label", "Details about this radio button.");

    //At this point you change your mind about the title, and decide to change it.
    menu.setTitle("Better Menu Title");

    //Finally add the menu to the DOM.
    document.body.appendChild(menu);

</script>

##Creating Buttons

Currently, there are two different types of buttons that are supported - a SingleButton and a DoubleButton. The first and the most simple is the SingleButton decorator that creates a MWF button with a label, an optional URL, and an optional click callback value. The second type is the DoubleButton which creates two side-by-side buttons given the label, the URL and the click callback for both buttons. Given that the constructor for the DoubleButton is rather tedious to use with its six parameters, there is also a SimpleDoubleButton that has only two parameters which are the labels for the appropriate buttons.

<script type="text/javascript" src="http://[domain]/mwf/decorator.js"> </script>
<script type="text/javascript" src="http://[domain]/mwf/button.js"> </script>

<script type='text/javascript'>

    //Create an MWF button that links to Google.
    var button = mwf.decorator.SingleButton("Google", "http://google.com");

    //Set the button-light property.
    button.setLight(false);
    
    //Attach a mouse click event handler.
    button.click(function(){
        alert("Hi! I just got clicked.");
    });
   
    //Change the button's link to point to UCLA Mobile.
    button.setURL('http://m.ucla.edu');

</script>

##Creating Menus Menu decorator allows developers to create a menu with or without a title, customize look and feel, and add various types of menu items such as link items, detailed link items, checkboxes or radio button items, as well as any other arbitrary DOM element that is compatible with MWF menu entity. The decorator keeps track of the first and the last element of the menu and sets menu-last and menu-first class names appropriately for maximum compatibility.

Internally represented as <div> elements, once created, menu objects can be added to other DOM elements for rendering. List of attributes currently supported includes padded, full, and detailed. To set an attribute, utilize functions setPadded(bool), setFull(bool), and setDetailed(bool), respectively.

Below are a list of functions currently supported by Menu decorator:

• setTitle(string) and getTitle() - Setter and getter for current menu's title
• addMenuItem(DOM Element) - Adds arbitrary DOM element to the menu.
• addMenuTextItem(string) - Adds a simple text element.
• addMenuLinkItem(text, url, details) - Adds a link menu item with an appropriate text, URL, and also details
• addMenuCheckboxItem(name, value, label, details) - Creates a checkbox input element and ads it to the menu. Label is the visual content while name/value are the input parameters. Clicking on the menu item, will select the checkbox.
• addMenuRadioItem(name, value, label, details) - Similar to adding checkbox item, but adds a radio button to the menu.
• size() - Returns the number of elements in the current menu
• getFirstMenuItem() and getLastMenuItem() - Getters for the first and last items in the menu.
• getMenuItemAt(index) - Gets the menu item at the specified zero-based index.

For more information about functionality and parameter requirements, please reference Menu.js which has vary thorough documentation on each of these functions.

##Creating Content