Widgets

Lets say a widget is a combination of HTML/JavaScript/CSS which interacts with the user to input data. It can be anything from a simple input to a complex jQuery plug-in.

If a class method is implemented to accept specific arguments and return the widget resources then it can be considered as a widget generator and be used inside models and form generators.

The default Widget class which comes with Artaengine contains all of the basic and essential widgets.

Structure of a widget class

A widget class has methods which create widgets, the methods get exactly three arguments, this is a convention so other classes such as form generators can use it:

  • If the widget needs to be fed with a data source. For example a drop-down or a multi-select needs to be fed with data which they will present as a list, but a time or wysiwyg editor do not need to be fed with such data. The data source can be:
    • null
    • Array of keys and values:
      $source = array('R' => 'Rabbit', 'C' => 'Cat', 'D' => 'Dog');
      
    • Array of keys and tuples of value and HTML attributes:
      $source = array(
          'R' => array('Rabbit', array('class' => 'brown',)),
          'C' => array('Cat',    array('class' => 'red',)),
          'D' => array('Dog',    array('class' => 'white',)),
      )
      
    • A string pointing to a static class property:
      /* Dictionaries::animals = {key: value,};
         Dictionaries::animals = {key: {value, {class atts}},};
       */
      $source = 'Dictionaries::pets';
      
    • A tuple of a database object and database table or view name:
      $source = array($dbo, 'pets');
      
    • A database object which already has executed a query, ready to fetch data:
      $dbo->query('SELECT * FROM pets;');
      $source = $dbo;
      
  • An array of HTML attributes to be applied to the widget tags.

    $atts = array(
        'class'     => 'widget required',
        'style'     => 'border: 1px solid red',
        'name'      => 'mywidget',
        'selected'  => 'R',
        'default'   => false,
        'maxlength' => 1,
    );
    
    selected and default are the only attributes which are not HTML attributes but can be used inside the attribute array.

    selected is the initial value put in the widget.

    default default selected value of a widget. For example the message or neutral option in a select list.

  • An array of configs and parameters which is used to setup the widget.

A widget method should always return a string value which is the HTML tags to be shown.

A example of a widget class method:

class MyWidgets implements IWidgets {

    /* constants to widget Class.method */
    const SPECIAL_DROPDOWN = 'MyWidgets.myDropdown';

    public function myDropdown($source, $atts=null, $params=null) {
        $html = '';
        /* define widget */
        return $html;
    }
}

To initialize and work properly a widget may need JavaScript and/or CSS file(s) to be loaded or few lines of JavaScript codes to be executed. This resources can be inject within the widget class and method, for example as shown below:

class MyWidgets implements IWidgets {

    const SPECIAL_DROPDOWN = 'MyWidgets.myDropdown';

    private function __addDependency($js, $css, $jsx) {
        /* Arta::$factory is a hook to the factory object */
        if ($js && !in_array($js, Arta::$factory->js)) {
            Arta::$factory->js[] = $js;
        }
        if ($css && !in_array($css, Arta::$factory->css)) {
            Arta::$factory->css[] = $css;
        }
        if ($jsx)) {
            Arta::$factory->jsx[] = $jsx;
        }
    }

    public function myDropdown($source, $atts=Null, $params=Null) {
        $html = '';
        // add JS/CSS/JS Code
        $this->__addDependency(
            'javascript/jquery/plugins/my.js',
            'javascript/jquery/plugins/my.css',
            "$($selector).specialdd($params);"
        );
        return $html;
    }
}

It is a good idea to create a class constant for each widget method to addresses the widget as Widget-Class.widget-method or Widget-Class::widget-method. The constants can be used in models and by form generators to address the widgets.

The default Widget class

With Artaengine comes class Widget which is used by the form generators when rendering forms from models.

For a complete reference see: Widget API

This example renders some widgets and assigns them to template variables:

class MyFactoryClass extends Response {

    public $js = array();
    public $css = array();

    public function showWidgets() {

        $widget = new Widget();

        /* DROP DOWN */
        $this->dropdownArray = $widget->dropDown(
            array('Rabbit', 'Cat', 'Dog'),
            array('selected' => 0, 'name' => 'pets')
        );

        $dbo = Database::get('dbo');  

        /* DROP DOWN */
        $this->dropdownDB = $widget->dropDown(
            array($dbo, 'pets'),
            array(
                'selected' => 1,
                'default'  => array(-1, 'no item selected')
            ),
            array(
                'id'   => 'pet_id',
                'text' => 'pet_name',
            ),
        );

        /* DROP DOWN */
        $dbo->query(
            'SELECT animal_id AS id, pet_type AS name, selected_id ROM pets;'
        );
        $this->dropdownDB = $widget->dropDown(
            $dbo,
            array(
                'selected' => 1,
                'default'  => array(-1, 'no item selected')
            ),
            array(
                'selected_id' => 'selected_id'
                'alias'       => 'no data available',
                'where'       => 'animal_id > 5',
                'sort'        => 'animal_name',
            ),
        );

        /* DATE TIME */
        $this->dateTime = $widget->dateTime(
            array(1979, 2011),
            array(
                'name'     => 'date1',
                'selected' => '2011/01/01 10:20:45',
                'style'    => 'color: blue',
            )
        );

        /* CKEDITOR */
        $this->ck = $widget->ck(
            Null,
            array('name' => 'myck'),
            array('uiColor' => '#eeeeee',) // ckeditor settings
        );

        /* SHOW TEMPLATE */
        $this->show('widget-show.xhtml');
    }
}

Example

Widgets
TOP