You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zeppelin.apache.org by co...@apache.org on 2016/09/22 08:09:54 UTC
zeppelin git commit: [ZEPPELIN-1462] Zeppelin-Web Good Practices #3
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 <co...@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 <co...@gmail.com>
Authored: Thu Sep 22 10:06:12 2016 +0900
Committer: Damien CORNEAU <co...@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()`