Repository: zeppelin Updated Branches: refs/heads/gh-pages 4280cba17 -> fd772df06
[ZEPPELIN-1462] Zeppelin-Web Good Practices #3 ### What is this PR for? This Good Practice Guide will focus on how to write a controller following the controller as vm concept, and how to provide a nice separation of the code. ### What type of PR is it? Documentation ### What is the Jira issue? https://issues.apache.org/jira/browse/ZEPPELIN-1462 ### How should this be tested? Check the `.md` file, or build the website to see the full rendering ### Questions: * Does the licenses files need update? No * Is there breaking changes for older versions? No * Does this needs documentation? No Author: Damien CORNEAU <cornead...@gmail.com> Closes #1443 from corneadoug/ZEPPELIN-1462 and squashes the following commits: 2dc04e0 [Damien CORNEAU] Address feedbacks a4a2645 [Damien CORNEAU] Add the new Practive Guide Page Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/fd772df0 Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/fd772df0 Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/fd772df0 Branch: refs/heads/gh-pages Commit: fd772df06ee2cd722349673185b4bc12a53c6d32 Parents: 4280cba Author: Damien CORNEAU <cornead...@gmail.com> Authored: Thu Sep 22 10:06:12 2016 +0900 Committer: Damien CORNEAU <cornead...@gmail.com> Committed: Thu Sep 22 17:09:30 2016 +0900 ---------------------------------------------------------------------- contribution/zeppelinweb/goodPracticeGuide02.md | 1 + contribution/zeppelinweb/goodPracticeGuide03.md | 143 +++++++++++++++++++ 2 files changed, 144 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zeppelin/blob/fd772df0/contribution/zeppelinweb/goodPracticeGuide02.md ---------------------------------------------------------------------- diff --git a/contribution/zeppelinweb/goodPracticeGuide02.md b/contribution/zeppelinweb/goodPracticeGuide02.md index b3d39f2..bf9a55f 100644 --- a/contribution/zeppelinweb/goodPracticeGuide02.md +++ b/contribution/zeppelinweb/goodPracticeGuide02.md @@ -56,6 +56,7 @@ Now, there are a few things to know about using it from `$rootScope`: * Usage of event dispatching should be limited if possible * We only use `$rootScope.$broadcast` and `$scope.$on` for event dispatching/catching +* We are grouping all the `$scope.$on` functions at the end of the compponent using it (controller or service) #### Performances http://git-wip-us.apache.org/repos/asf/zeppelin/blob/fd772df0/contribution/zeppelinweb/goodPracticeGuide03.md ---------------------------------------------------------------------- diff --git a/contribution/zeppelinweb/goodPracticeGuide03.md b/contribution/zeppelinweb/goodPracticeGuide03.md new file mode 100644 index 0000000..836271f --- /dev/null +++ b/contribution/zeppelinweb/goodPracticeGuide03.md @@ -0,0 +1,143 @@ +--- +layout: sideMenu +title: "3 - Making A Controller" +description: "" +group: nav-contrib-front +menu: nav-contrib-front +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# How to Write a Controller + +<br/> +Our main rule regarding writing a controller, is to use the `Controller as vm` style, however, we also have a few other style guidelines. + +You can see below a full example of what the controller would look like. + +``` +(function() { + 'use strict'; + + angular.module('zeppelinWebApp') + .controller('myNewController', myNewController); + + myNewController.$inject = ['$http']; + + function myNewController($http) { + + var vm = this; + + vm.publicVariable = {}; + + // Controller's public functions + vm.myControllerPublicFunction = myControllerPublicFunction; + + _init(); + + /************************************* + ** Public functions Implementation ** + *************************************/ + + function myControllerPublicFunction() { + + ... + + } + + function myOtherPublicFunction() { + + _utilFunction(); + ... + + } + + /************************************* + ** Private functions Implementation ** + *************************************/ + + function _init() { + + vm.myControllerPublicFunction(); + ... + + } + + function _utilFunction() { + + ... + + } + + /*************************************** + ** $scope.$on catchers Implementation ** + ***************************************/ + + $scope.$on('eventName', function(event) { + + ... + + }) + } +})(); +``` + +This might look like a lot of lines, but it is mainly to show all the rules at once. + + +#### Using the controller in a view + +Now let's see how we can use it inside our `.html` view in normal situations. + +``` +<div ng-controller="myNewController as newCtrl"> + <div ng-click="newCtrl.myControllerPublicFunction">{{ newCtrl.publicVariable }}</div> +</div> +``` + +#### Using the controller in a page + +In the case where your controller will be used on a view directly linked to a route + +For example: `localhost:8080/myPageName` + +The definition of the controller will take place in the `$routeProvider` section of the `app.js` file. + +``` +.when('/myPageName', { + templateUrl: 'app/myPageName/myPageName.html', + controller: 'myNewController', + controllerAs: 'newCtrl' +}) +``` + +Which will leave the `.html` view without any `ng-controller` property. + +``` +<div> + <div ng-click="newCtrl.myControllerPublicFunction">{{ newCtrl.publicVariable }}</div> +</div> +``` + +#### The rules in detail + +* Except `$scope.$on` and a few special cases, we do not use the `$scope` of that controller +* Only the functions and variables needed in the view should be linked to the `vm` +* The view is using the controller's variables and functions through the 'as' keyword you set +* Private functions' name start with a `_` +* Functions and variables are grouped by type in that order: +private variables, public variables, init function call, public functions, private functions, $scope.$on functions +* There is a nice comment separating all those groups +* Services are added to the controller using the `$inject` at the top of the component +* Inside the controller, you call the public functions using `vm.nameOfTheFunction()`
