View Widgets with jqWidgets

The jqWidgets wrapper classes have been provided to simplify the use of the jqWidgets framework. For more information on the widgets available and the widget API you can visit the jqWidgets website.
jqWidgets is FREE for non-commercial use but commercial use requires a licence. The jqWidgets library is included in Hazaar MVC for non-commercial use however if your Hazaar application goes commercial, please remember to purchase a jqWidgets licence from http://www.jqwidgets.com/licence

Overview

The PHP wrapper classes a really just JavaScript code generators. Because the web is, by (in)design, a mish-mash of many different languages it is a good idea to keep this in mind when using the widget classes. Sometimes you will want to mix yourPHP, HTML and JavaScript code by switching in and out of the PHP interpreter. Looking at the source of page may be required if you experience problems.

Displaying a Widget

There are two ways to use the widgets. You can either use the classes directly, which is only recommended if you have good reason to, or you can use the jqWidgets View Helper which has been provided to make it much simpler to create new objects.

Using the View Helper (Recommended)

You first need to add the view helper. See Adding a view helper for all the various methods available. For now, in yourController::init() method just add:
protected function init(){
    $this->view->addHelper('widget');
}
Now you are able to access the widget view helper from within your view.
Widgets are accessed as a method of the widget view helper. The method name is the same name as the widget as defined by jqWidgets except that it is all lowercase. So a Gauge widget can be created with $this->widget->gauge(), or a DropDownList widget can be created with $this->widget->dropdownlist().
To create a gauge widget with default settings and an initial value of 50, you would do this:
<?=$this->widget->gauge('objTest')->value(50));?>

Using the Widget Classes Directly

<?
$obj = new \<a href="http://old.hazaarmvc.com/docs/page/api_class_Hazaar_Widgets_Gauge">Hazaar\Widgets\Gauge</a>('objTest');
$obj->value(50);
echo $obj->renderObject();
/** OR **/
echo $obj;
?>

Using an existing HTML element (hashrefs)

It is possible to create the HTML element of the widget manually in your view then to tell the widget wrappers to use thatHTML instead. This allows for a lot more flexibility with complicated widgets such as Trees and Grids, etc.
To refer to an existing HTML element simply prefix the name of the widget with a hash (#). This tells the wrappers not to create an element and as such the id will refer to the existing element you have created.
<div id="myTree">
    <ul>
        <li item-expanded="true">
            <?=$this->fontawesome->icon('envelope');?> Mail
            <ul>
                <li><?=$this->fontawesome->icon('inbox');?> Inbox</li>
                <li><?=$this->fontawesome->icon('upload-alt');?> Outbox</li>
            </ul>
            </li>
        <li><?=$this->fontawesome->icon('calendar');?> Calendar</li>
        <li><?=$this->fontawesome->icon('rss');?> News Feeds</li>
    </ul>
</div>
<?=$this->widget->tree('#myTree')->width(200); ?>

Updating an Existing Widget

Widgets will have method available that can be called to update the widget after it has been created. You can use these methods to do things like update the value of the widget, trigger an event or many other things. Because the widget has already been created in JavaScript, calling these methods on the object will return the required JavaScript code to call the method as a string.
Keep in mind that this code will not terminate the code with a semicolon (;) as this code may want to be used inside another statement.
<?=$obj = $this->widget->gauge('objTest')->value(50));?>
<script>
    setTimeout(<?=$obj->value(120);?>, 3000);
</script>

Widget Events

Some widgets allow code to be executed on certain events. This is an example of how to trigger some JavaScript on a button click event.
<?
$code = "alert('You click me!');";
echo $this->widget->button('objTest', 'Test Button')->click($code);
?>

Widget Methods

Some widgets also allow methods to be called on them to return information from the widget itself. For example, calling thechecked() method will return true or false indicating if the CheckBox widget is checked or not.
To do this, you call the checked() method without any arguments.
<?
$checkbox = $this->widget->checkbox('myCheck');
$code = "var state = <?=$checkbox->checked();?>; alert('Your checkbox is ' + (state?null:'NOT ') + 'checked');";
echo $checkbox->click($code);
?>

Passing JavaScript variable names or objects

Because we’re really just generating JavaScript, sometimes you will want to refer to an existing variable in a widget method call, or even create a new object such as a date object. To allow this I have added the bang (!) prefix to denote JavaScript entities that should not be quoted.
In the below example we create a date object then refer to it in the setDate method of the Calendar widget.
<?=$calendar = $this->widget->calendar('myCalendar1');?>
<script>
var newdate = Date(1978, 12, 13);
<?=$calendar->setDate('!newdate')->bare();?>;
</script>
The bare() method call will generate the JavaScript method call WITHOUT the surrounding function(){} code.
This will output the JavaScript method call to set the date of the Calendar object.

Available Widgets