Thursday, 25 July 2013

AngularPrime release 0.4

Introduction

This release contains 2 new functionalities
  • Support for the ng-show and ng-hide angular directive in combination with the pui-input directive on checkbox and radio type
  • Integration of the datatable widget of PrimeUI 0.9.5
This may seem not much since the latest release of the project 2 months ago, but there is a lot of work done behind the scenes which is not yet ready to release.
The most important tasks which are in progress are
  • Automated integration testing
  • Developers guide

New features

ng-show/ng-hide and pui-input on checkbox and radio type

Using the pui-input directive on an input tag of type checkbox or radio, gave a nice themed representation of a checkbox and radiobutton style input field.
 
<input type="checkbox" id="chk1" ng-model="checkboxSelectedValue1" pui-input/><label id="lblchk1" for="chk1">Option 1</label>

For this type of element, the DOM structure is restructured and as a consequence, the ng-show and ng-hide directives doesn’t have any effect anymore.  Well they do have an effect but they are working on a hidden element so it useless.

With the 0.3 version, the workaround was to use the ng-show and ng-hide on a surrounding element, but the issue is solved in this version by creating a specific directive for checkbox and radio buttons functionality, called pui-checkbox and pui-raduibutton.
These new directives are also used to incorporate the label declaration, so that you have to type a lot less.
 
<div id="chk1" pui-checkbox="Option 1" ng-model="checkboxSelectedValue1" >

How does these new directives work? Well, it generates the corresponding longer version with the input element and pui-input directive and then the Angular ‘compilation’ is called on this generated HTML.

For now, only the prefix of the id of the label element can customized. The id is created by putting the characters ‘lbl’ in front of the id that you have specified on the element with the pui-checkbox or pui-radiobutton directive.  If you want to change this prefix value, you can redefine it with an angular decorator as shown in the following code snippet.
 
demo.config(function($provide) {
    $provide.decorator('angular.prime.config', function($delegate) {
        $delegate.labelPrefix = 'rudy';

        return $delegate;
    });
});

But the main advantage of the new directives is that when you specify the ng-show or ng-hide directives on the element, they work as expected and you can use them to hide the element conditionally.

Datatable widget


In the PrimeUI 0.9.5 release, there is a new widget available for showing data in a tabular format. And it has support for selection of rows and sorting of columns.

This widget is now also integrated in AngularPrime and I tried to make the use of it as easy as possible. Meaning that for some basic functionality you should write as less code as possible.

In the case we have an array of objects with the data we like to show available in the scope, the table can be encoded with this single line.
 
<div pui-datatable="fixedData"></div>

And in the controller we can have the following lines:
 
 $scope.fixedData =  [
        {'brand':'Volkswagen','year': 2012, 'color':'White', 'vin':'dsad231ff'},
        {'brand':'Audi','year': 2011, 'color':'Black', 'vin':'gwregre345'},
        {'brand':'Renault','year': 2005, 'color':'Gray', 'vin':'h354htr'},
    ];

And the result is

datatable1

The code does an inspection on the properties it finds of the first object of the array. In this case it finds 4 properties (brand, year, color and vin) and thus 4 columns are shown in the table.

Instead of fixed data, you can also supply a function that is responsible for returning the data, possible retrieving it from a remote resource.

If you want to control which columns are shown, you can specify them with the pui-column directive.
 
<div pui-datatable="fixedData">
   <div pui-column="brand"></div>
   <div pui-column="year"></div>
</div>

With this directive it is also possible to specify if the user can sort the data based on a column and the column header value.

Another feature which is available is the row selection. The first possibility is that a function is called whenever a row is selected (or deselected). The rowSelect function has the following structure:
 
 $scope.carTableData = {
        tableData : $scope.fixedData
        , rowSelect: function(event, data) {
            puiGrowl.showInfoMessage('Row selection', 'Selected a '+data.color+ ' '+data.brand+ ' of '+data.year +' (id = '+data.vin+')');
        }
    };

And instead of referring to fixedData in the pui-datatable directive, we have to refer to carTableData and we have implemented the row selection feature. Of course you have to do some more useful stuff in the selection function then just displaying it in a growl.

The second possibility for having the row selection functionality is to have a selectedData property in the object
 
 $scope.progSelectTableData = {
        tableData : $scope.fixedData
        , selectedData : []
    };

Now all row selections that are made on the screen, are reflected in the array of integers property called selectedData (array as we can have multiple rows selected). You can even modify the contents of this property programmatically and the change in the property is propagated back to the screen.
The only problem with this second approach is that it isn’t sorting safe as we are working with row indices and not the actual data objects.

The last feature that I want to mention here briefly is the pagination feature. By specify the paginatorRows property in the object, the data is displayed in chunks of the specified number of rows.
 
 $scope.paginatedData = {
        tableData : $scope.fixedData
        , paginatorRows : 4
        , rowSelect: function(event, data) {
            puiGrowl.showInfoMessage('Row selection', 'Selected a '+data.color+ ' '+data.brand+ ' of '+data.year +' (id = '+data.vin+')');
        }
    };

This feature is compatible with the sorting of columns. So when a (or more) rows are selected and then the data is sorted based on a column value, the correct rows stays highlighted.

For more detailed examples of the widget and some more use cases, have a look at the online version of the demo application.

In preparation


As mentioned, besides this rather limited new features list, I’m preparing other material.

There are already 79 automated integration tests created. They are based on the Selenium Webdriver framework and I’m using the technique described in this blog post to run the tests on multiple browsers.

A lot more tests needs to be created as I’m only covering 10 of the 25 available widgets for now. And even for those, not all possible use cases are covered. So in the next months, this number of tests will be increased a lot.

The second thing I have started is the developers guide. For now, there is only the demo application where the code is shown to have a certain example.  But for some widgets, some explanation could be very useful as they can be rather complex.

So I was investigating the possibilities to use asciiDoc as it uses a plain text format and thus it is ideal to use in an source control environment.  I hope to have some first basic version of the guide when I release the next version.

Conclusion


This release is a small one in relation to the amount of new features.

You can find new directives for checkbox and radio button input style to make the encoding easier as label and ng-show/ng-hide directivescan be placed on the element itself.

Further there is an integration of the datatable widget of PrimeUI 0.9.5.  There are numerous scenarios to allow very basic but fast definition of data to show to a version with complete control of which data is shown and which features are activated.

Just as important as the code itself, the work on the automated integration tests and the developer guide has started.

And stay tuned for more new announcements to be made in the (near) future.