Often in my programming gig, we maintain legacy applications and one of the common occurrences is that I see designers using the JQuery UI modal box in an angularJS application. So today’s article is for those who I will not name – I am going to show you how simple it is to open a modal box in angularJS. We shall touch upon how to define the modal box template, to open the modal window using the Angular UI Modal library, and to close the window gracefully using AngularJS scope events.
What you need to know!
- Scopes and Data bindings.
- What AngularJS Services are
- and Dependency injection
The Modal Box “Component” :
It helps to visualize the modal box as a reusable component that has a HTML template and a controller attached to it. The controller is responsible for maintaining and updating the state of the model bound to the modal box view. The HTML template for the modal box is shown below. Note the various input fields and the corresponding data model bindings that are used. The model properties are bound to the “vm” object, where vm signifies “view model” to indicate the tight binding between models defined(in the controller function) and the view.
The above modal box component template HTML is shown below on the left along with the angularJS controller code on the right.
[pastacode lang=”markup” manual=”%3Cdiv%20class%3D%22modal-header%22%3E%0A%20%20%20%3Ch3%20id%3D%22modal-title%22%20class%3D%22modal-title%22%3E%0A%20%20%20%20%20%20%7B%7Bvm.title%7D%7D%0A%20%20%20%3C%2Fh3%3E%0A%3C%2Fdiv%3E%0A%3Cdiv%20id%3D%22modal-desc%22%20class%3D%22modal-body%22%3E%0A%20%20%20%3Cp%3E%7B%7Bvm.body%7D%7D%3C%2Fp%3E%0A%20%20%20%3Cdiv%3E%0A%20%20%20%20%20%20%3Cform%3E%0A%20%20%20%20%20%20%20%20%20%3Cdiv%20class%3D%22form-group%22%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Clabel%20for%3D%22exampleInputEmail1%22%3EName%20%3A%3C%2Flabel%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cinput%20type%3D%22text%22%20class%3D%22form-control%22%20ng-model%3D%22vm.user.name%22%20placeholder%3D%22enter%20your%20name%22%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cbr%3E%0A%20%20%20%20%20%20%20%20%20%3C%2Fdiv%3E%0A%20%20%20%20%20%20%20%20%20%3Cdiv%20class%3D%22form-group%22%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Clabel%20for%3D%22exampleInputPassword1%22%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20Password%20%3A%3C%2Flabel%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cinput%20type%3D%22password%22%20class%3D%22form-control%22%20ng-model%3D%22vm.user.password%22%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20placeholder%3D%22enter%20your%20password%22%3E%0A%20%20%20%20%20%20%20%20%20%3C%2Fdiv%3E%0A%20%20%20%20%20%20%3C%2Fform%3E%0A%20%20%20%3C%2Fdiv%3E%0A%3C%2Fdiv%3E%0A%3Cdiv%20class%3D%22modal-footer%22%3E%0A%20%20%20%3Cbutton%20type%3D%22button%22%20class%3D%22btn%20btn-success%22%20ng-click%3D%22vm.ok(vm.user)%22%3EOk%3C%2Fbutton%3E%0A%20%20%20%3Cbutton%20type%3D%22button%22%20class%3D%22btn%20btn-danger%22%0A%20%20%20%20%20%20ng-click%3D%22vm.cancel(‘modal%20dismissed’)%22%3ECancel%3C%2Fbutton%3E%0A%20%20%20%3Cbutton%20type%3D%22button%22%20class%3D%22btn%20btn-danger%22%20ng-click%3D%22vm.destroy()%22%3EDestroy%20MEEEE!!!%3C%2Fbutton%3E%0A%3C%2Fdiv%3E%0A” message=”html part” highlight=”” provider=”manual”/]
[pastacode lang=”javascript” manual=”function%20ModalBoxCtrl(%24scope%2C%20%24uibModalInstance)%0A%7B%0A%09var%20vm%20%3D%20this%3B%0A%09vm.user%20%3D%20%7B%0A%09%09name%3A%20”%2C%0A%09%09password%3A%20”%0A%09%7D%0A%09vm.title%20%3D%20’Controller%20Modalbox’%3B%0A%09vm.body%20%3D%20’Enter%20your%20Details’%3B%0A%0A%09vm.ok%20%3D%20function%20(result)%20%7B%0A%09%09%2F%2F%24uibModalInstance.close(result)%3B%2F%2FThis%20also%20works%0A%09%09%24scope.%24close(result)%3B%20%20%20%0A%09%7D%0A%09vm.cancel%20%3D%20function%20(message)%20%7B%0A%09%09%2F%2F%24uibModalInstance.dismiss(message)%3B%2F%2FThis%20also%20works%0A%09%09%24scope.%24dismiss(message)%3B%0A%09%7D%0A%09vm.destroy%20%3D%20function%20()%20%7B%0A%09%09%24scope.%24destroy()%3B%0A%09%7D%0A%7D%0A” message=”Angular code” highlight=”” provider=”manual”/]
The Modal box controller function is supplied with two objects $uibModalInstance and $scope which are resolved and dependency injected by the angular js injector subsystem.
The $uibModalInstance of the modal box is special in that it is available to be injected when a modal box is created. It provides two methods open and dismisses which perform their namesake functions.
The $scope object has two similar methods $close and $dismiss appended to it in addition to the modal’s content. It is possible to close or dismiss the modal without the need for a dedicated controller. So far, we have defined a few buttons in our modal box views (close, dismiss and Destroy MEEE!) that invoke the respective functions vm.ok, vm.cancel, and vm.destroy. Their purpose is described in the table below:
[ninja_tables id=”1571″]
Next, we discuss how to tie the modal controller to the modal box template. Angular UI makes that real easy by calling on its $uibModal service whose sole purpose is to open Modal windows. Therefore, the service has only one method defined – open(options). The options object takes on the properties explained in the table below:
[ninja_tables id=”1581″]
So to open a modal box with our template and controller, we can say
[pastacode lang=”javascript” manual=”%24uibOpen.open(%7B%0A%09appendTo%3A%20angular.element(%24document%5B0%5D.querySelector(‘%23modalboxdiv’))%2C%0A%09bindToController%3A%20true%2C%0A%09controller%3A%20’ModalBoxCtrl’%2C%0A%09controllerAs%3A%20vm%2C%0A%09scope%3A%20%24scope%0A%7D)%3B” message=”” highlight=”” provider=”manual”/]
The $uibModal.open (options) will open the modal box and returns a $uibModalInstance object which can be passed around. This is very useful if we decide to use the $uibModal in our own services rather than the controllers as we are doing now.
Opening the Modal from the Main view
The main view that opens the modal box is as follows:
When we click the ModalBox button, it invokes the vm.openModalbox() function defined in the MainCtrl Controller function which in turn calls $uibModal.open(options). This MainCtrl is attached to our main view which also houses the template injection point <div id=”modalboxdiv”></div>
The main html template and the corresponding controller code are shown below:
[pastacode lang=”markup” manual=”%3Cdiv%20class%3D%22container%22%20ng-app%3D%22modalbox%22%20ng-controller%3D%22MainCtrl%20as%20vm%22%20ng-cloak%3E%0A%20%20%20%3Cdiv%20class%3D%22container%22%3E%0A%20%20%20%20%20%20%3Cdiv%20id%3D%22modalboxdiv%22%3E%3C%2Fdiv%3E%0A%20%20%20%3C%2Fdiv%3E%0A%20%20%20%3Cdiv%20class%3D%22container%22%3E%0A%20%20%20%20%20%20%3Cdiv%20class%3D%22col-md-12%22%3E%0A%20%20%20%20%20%20%20%20%20%3Cdiv%20class%3D%22row%22%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cdiv%20class%3D%22col-md-3%22%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3Cp%3ENormal%20Modal%20box%3C%2Fp%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3Cbutton%20type%3D%22button%22%20class%3D%22btn%20btn-primary%22%20ng-click%3D%22vm.openModalbox()%22%3EModalBox%3C%2Fbutton%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%3C%2Fdiv%3E%0A%20%20%20%20%20%20%20%20%20%3C%2Fdiv%3E%0A%20%20%20%20%20%20%3C%2Fdiv%3E%0A%20%20%20%3C%2Fdiv%3E%0A%3C%2Fdiv%0A” message=”Html Part” highlight=”” provider=”manual”/]
[pastacode lang=”javascript” manual=”function%20MainCtrl(%24uibModal%2C%20%24scope%2C%20%24document)%20%7B%0A%09var%20vm%20%3D%20this%3B%0A%09var%20options%20%3D%20%7B%0A%09%09appendTo%3A%20angular.element(%24document%5B0%5D.querySelector(‘%23modalboxdiv’))%2C%0A%09%09template%3A%20%2C%0A%09%09bindToController%3A%20true%2C%0A%09%09controller%3A%20’ModalBoxCtrl’%2C%0A%09%09controllerAs%3A%20vm%2C%0A%09%09scope%3A%20%24scope%0A%09%7D%0A%0A%09vm.openModalbox%20%3D%20function%20()%20%7B%0A%09%09%24uibModal.open(options)%3B%0A%09%7D%0A%7D%0A” message=”Angular part” highlight=”” provider=”manual”/]
The main controller function takes the $uibModal, $document and $scope objects which are dependency injected by the angularjs injector subsystem. The angular UI Modal service is avalable in the ui.bootstrap library and needs to be imported as module before we use it.
[pastacode lang=”javascript” manual=”%0Aangular.module(‘modalbox’%2C%20%5B’ui.bootstrap’%5D)%0A%09.controller(‘MainCtrl’%2C%20MainCtrl)%0A%0AMainCtrl.%24inject%20%3D%20%5B’%24uibModal’%5D%3B%0A%0Afunction%20MainCtrl(%24uibModal)%7B%0A%7D%0A” message=”Bringing in the ui.bootstrap module into angularJS” highlight=”” provider=”manual”/]
Thats it !!! A html runnable file that contains all the above code can be found here(Link)
A quick Note on bindToController in the options object of $uibModal(options)
‘vm’ is a javascript object which corresponds to an instance of the controller. Adding properties to the vm object instead of ‘this’ is good design practice. The ‘vm’ object can be used in the view template. In reality the vm object is added as a object property of the $scope object.
In general, $scope is used to bind the model between view and the controller. $scope itself has some inherited properties and methods from $rootScope. The methods manage important operations such as retrieval of DOM, event propagation and life cycle hooks.
When using the ng-controller directive, it injects the $scope object inside the DOM. The result is a messy object that consists of inherited properties and functions along with our own properties and methods that we attached in the controller. Not to mention when we start nesting controllers, we might end up using the same $scope model variables. Ex: $scope.heading in a panel and its a similar $scope.heading in the nested subpanel. This problem can be exacerabted in very complex applications. It would be helpful if we could namespace our methods and properties to an object besides $scope. This is why AngularJS introduced the controllerAs syntax so that the controller object is bound to the view instead of the $scope. We compare the two types of approaches below:
Using the messy $scope object in the view
[pastacode lang=”markup” manual=”%3Cdiv%20class%3D%22container%22%20ng-app%3D%22modalbox%22%20ng-controller%3D%22MainCtrl%22%3E%0A%09%7B%7Bname%7D%7D%0A%3C%2Fdiv%3E%0A” message=”” highlight=”” provider=”manual”/]
[pastacode lang=”javascript” manual=”function%20MainCtrl(%24scope)%20%7B%0A%09%24scope.name%20%3D%20%E2%80%9CScope%20code%20of%20MainCtrl%E2%80%9D%3B%0A%7D%0A” message=”angular part” highlight=”” provider=”manual”/]
Using the controller object in the View:
[pastacode lang=”markup” manual=”%3Cdiv%20class%3D%22container%22%20ng-app%3D%22modalbox%22%20ng-controller%3D%22MainCtrl%20as%20vm%22%3E%0A%09%7B%7Bvm.name%7D%7D%0A%3C%2Fdiv%3E%0A” message=”html part” highlight=”” provider=”manual”/]
[pastacode lang=”javascript” manual=”function%20MainCtrl()%20%7B%0A%09var%20vm%20%3D%20this%3B%0A%09vm.name%20%3D%20%20%E2%80%9CControllerAs%20code%20of%20MainCtrl%E2%80%9D%3B%0A%7D%0A” message=”angular part” highlight=”” provider=”manual”/]
The second method is better practice in order to prevent pollution of the $scope object with our methods and properties. So this pattern pretty much works, until we encounter directives. Take a look at the following code snippet:
[pastacode lang=”javascript” manual=”%0Afunction%20TestCtrl()%20%7B%0A%09this.age%20%3D%20’44’%3B%0A%7D%0A%20%20%20%20%0Afunction%20testDirective()%20%7B%0A%09return%20%7B%0A%09%09restrict%3A%20’E’%2C%0A%09%09scope%20%3A%20%7B%0A%09%09%09’scopeName’%20%3A%20’%3D’%0A%09%09%7D%2C%0A%09%09bindToController%3A%20%7B%0A%09%09%09’bindToName’%3A%20’%3D’%0A%09%09%7D%2C%0A%09%09controller%3A%20’TestCtrl’%2C%0A%09%09controllerAs%3A%20’vm’%2C%0A%09%09template%3A%20%60%0A%09%09%09%09%3Cdiv%3E%0A%09%09%09%09Name%20defined%20in%20scope%20%3A%20%7B%7BscopeName%7D%7D%20%3Cbr%2F%3E%0A%09%09%09%09Name%20defined%20in%20bindToController%20%3A%20%7B%7Bvm.bindToName%7D%7D%20%3Cbr%20%2F%3E%0A%09%09%09%09Age%20defined%20in%20controller%20%3A%20%7B%7Bvm.age%7D%7D%0A%09%09%09%09%3C%2Fdiv%3E%0A%09%09%09%09%60%0A%09%7D%3B%0A%7D%0A%0Afunction%20ParentCtrl()%20%7B%0A%09this.myName%20%3D%20’Peter’%3B%0A%7D%0A%0Aangular.module(‘app’%2C%20%5B%5D)%0A%09.directive(‘testDirective’%2C%20testDirective)%0A%09.controller(‘TestCtrl’%2C%20TestCtrl)%0A%09.controller(‘ParentCtrl’%2C%20ParentCtrl)%3B” message=”AngularJS ParentCtrl and testDirective” highlight=”” provider=”manual”/]
[pastacode lang=”markup” manual=”%3Cbody%20class%3D%22ng-cloak%22%20ng-controller%3D%22ParentCtrl%20as%20vm%22%3E%0A%20%20%20%20%3Ctest-directive%20scope-name%3D%22vm.myName%22%20bind-to-name%3D%22vm.myName%22%3E%3C%2Ftest-directive%3E%0A%3C%2Fbody%3E” message=”HTML View” highlight=”” provider=”manual”/]
Notice that the directive has three options for model binding – scope, bindToController and the ControllerAs method that binds properties to vm inside our controller. The scope object is reminiscent of the first method of binding(similar to the “using the messy $scope object in the view” snippet we showed earlier), whereas the ControllerAs is the second way – the proper way(similar to the “using the controller object in the view” snippet shown earlier). The bindToController property was introduced so that properties are directly bound to the controller object instead of the scope. So it is good practice to use bindToController instead of the scope property in the directive definition object. I hope to write a more complete article on this topic later.