Note: This is a companion post to Example CRUD App – Starring AngularJS, Backbone, Parse, StackMob and Yeoman. If you haven’t read that yet, please do so, otherwise this might not make much sense.
The most prominent feature, by far, of AngularJS SignIt! is the signature pad. It’s a fixed-size canvas that can be drawn upon with a mouse pointer or finger. The code for this wonderful widget is provided as a jQuery plugin by Thomas Bradley. There are a few more features for the signature pad than I use in this app, and I encourage you to check out the full documentation if you get a chance. It’s pretty great.
In order to implement the signature pad into my form, It must be a required field, and have the data included with the other fields when the form is submitted. The sig pad works by creating objects of x/y coordinates that correspond to marks on the canvas. When drawing on the pad, all that data gets set into a hidden form field. The data from that field is what needs to get into the Angular scope, and get validated by Angular’s form validation routine. Oh, and Angular somehow needs to fire the custom validation function built into the signature pad.
Luckily, this is the type of thing directives were built for. Custom directives let you create custom html tags that get parsed and rendered by Angular. So to start out, I created a custom directive called sigpad that is used by placing <sigpad></sigpad> in my HTML. The sigpad tag then gets replaced by the directive’s template HTML. The template for the HTML5 signature pad is just the default snippet taken directly from the signature pad documentation. See below:
<div class="control sigPad">
<div class="sig sigWrapper">
<canvas class="pad" width="436" height="120" ng-mouseup="updateModel()"></canvas>
</div>
</div>
The logic for the directive is defined in a separate Angular module (see directives.js for full code). Take a look at the code below, and be sure to review Angular’s documentation on directives. The Angular docs give a great conceptual overview, but the examples are a bit lacking. I reviewed the docs many, many times, and still needed some help from the to get this working correctly (thanks P.B. Darwin!).
My biggest stumbling block was not using ngModelController, and instead trying to manipulate scope data directly. When working with a form, Angular provides all sorts of awesome code to work with data and do some validation. Basically, it all went down like this…
Insert the sigpad directive into the form with
<sigpad ng-model='user.signature' clearBtn=".clearButton" name="signature" required></sigpad>
Now Angular knows to replace the sigpad element with the template defined earlier. After this happens, Angular runs the linking function which contains all the logic for the directive. The little snippet shown below is in the linking function. It uses jQuery to select the template element (passed into the linking function as ‘element’) and runs the signaturePad function from the signature pad API. This is what creates the actual, drawable canvas.
var sigPadAPI = $(element).signaturePad({
drawOnly:true,
lineColour: '#FFF'
});
The ng-model=’user.signature’ bit is key. This is how data is shared between the signature pad and Angular. Also, go back up and look at the template. You will see ng-mouseup="updateModel() as an attribute of the canvas element. This tells Angular to run the updateModel() function when your mouse click ends on the signature pad. The updateModel() function is defined in the linking function of the sigpad directive.
When the updateModel() function is executed, it will wait for a split second so the signature pad can finish writing data to its hidden form field, then it will assign all that data to the Angular model value of the directive. Sounds confusing, and it is. The signature pad is off doing its own thing, completely oblivious to the fact that it is in an AngularJS app. It is Angular’s responsibility to grab data from the sigpad to get that data into its own scope. That is what $setViewValue is for. It hands the signature data over to Angular, so when the form is submitted, Angular has it available in scope.
Below is the entire directive for the drawable signature pad. You can see that it relies heavily on the signature pad API, but only after certain events handled by Angular have occurred.
.directive('sigpad', function($timeout){
return {
templateUrl: 'views/sigPad.html', // Use a template in an external file
restrict: 'E', // Must use <sigpad> element to invoke directive
scope : true, // Create a new scope for the directive
require: 'ngModel', // Require the ngModel controller for the linking function
link: function (scope,element,attr,ctrl) {
// Attach the Signature Pad plugin to the template and keep a reference to the signature pad as 'sigPadAPI'
var sigPadAPI = $(element).signaturePad({
drawOnly:true,
lineColour: '#FFF'
});
// Clear the canvas when the 'clear' button is clicked
$(attr.clearbtn).on('click',function (e) {
sigPadAPI.clearCanvas();
});
$(element).find('.pad').on('touchend',function (obj) {
scope.updateModel();
});
// when the mouse is lifted from the canvas, set the signature pad data as the model value
scope.updateModel = function() {
$timeout(function() {
ctrl.$setViewValue(sigPadAPI.getSignature());
});
};
// Render the signature data when the model has data. Otherwise clear the canvas.
ctrl.$render = function() {
if ( ctrl.$viewValue ) {
sigPadAPI.regenerate(ctrl.$viewValue);
} else {
// This occurs when signatureData is set to null in the main controller
sigPadAPI.clearCanvas();
}
};
// Validate signature pad.
// See http://docs.angularjs.org/guide/forms for more detail on how this works.
ctrl.$parsers.unshift(function(viewValue) {
if ( sigPadAPI.validateForm() ) {
ctrl.$setValidity('sigpad', true);
return viewValue;
} else {
ctrl.$setValidity('sigpad', false);
return undefined;
}
});
}
};
})
And what about the tiny signatures that show up in the signatories list? Also a custom directive. This one is smaller, but still tricky. The signature is displayed as an image on-screen, but a canvas element is still required to generate the signature from raw data before it can be converted to an image.
The directive is implemented with <regensigpad sigdata={{signed.get('signature')}}></regensigpad>. The ‘signed’ value is a single signature in the signature collection pulled from the back-end when the user picks a petition. the signature data from signed is passed into the directive scope using scope: {sigdata:'@'}.
When a list of signatures is retrieved, each signature record (including first & last name, email, and signature data) goes into a table row using ngRepeat. The regensigpad directive is executed for each row. The linking function will create a canvas element and make a displayOnly signature pad from it. The signature drawing is regenerated from the data, and then the canvas is converted to PNG format.
This PNG data is then used in the pic scope value, which is bound to the ng-src of an img tag. This img tag is the directive’s template, and will be inserted into the page. The full code for this directive is below.
.directive('regensigpad',function() {
return {
template: '<img ng-src="{{pic}}" />',
restrict: 'E',
scope: {sigdata:'@'},
link: function (scope,element,attr,ctrl) {
// When the sigdata attribute changes...
attr.$observe('sigdata',function (val) {
// ... create a blank canvas template and attach the signature pad plugin
var sigPadAPI = $('<div class="sig sigWrapper"><canvas class="pad" width="436" height="120"></canvas></div>').signaturePad({
displayOnly: true
});
// regenerate the signature onto the canvas
sigPadAPI.regenerate(val);
// convert the canvas to a PNG (Newer versions of Chrome, FF, and Safari only.)
scope.pic = sigPadAPI.getSignatureImage();
});
}
};
});
But that’s not all! You might have noticed that the select box holding the names of each petition looks kinda fancy, and allows you to type stuff to filter the list. This fancy form control is the select2 widget which is based of the Chosen library.
I didn’t have to write my own directive for it though. The Angular-UI project has already done the honors. Angular-UI is an open-source companion suite for AngularJS. It provides a whole pile of custom directives, and even a few extra filters. Many of the directives are wrappers for other widgets and open source projects, like CodeMirror, Google Maps, Twitter Bootstrap modal windows, and many more. It’s definitely worth looking into for any AngularJS project.
