zeppelin git commit: [Zeppelin 1415] - Adding Zeppelin-Web Good Practice Guide #2

[co...@apache.org]

Repository: zeppelin
Updated Branches:
  refs/heads/gh-pages e53101f87 -> 70e4ecdad


[Zeppelin 1415] - Adding Zeppelin-Web Good Practice Guide #2

### What is this PR for?
In this new Good Practice Guide for Zeppelin-web, we focus on how event dispatching($broadcast, $emit, $on) works, and how to correctly use it in the app

### What type of PR is it?
Documentation

### What is the Jira issue?
https://issues.apache.org/jira/browse/ZEPPELIN-1415

### How should this be tested?
You can check the markdown file for typos or bad sentences :)

### 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 #1412 from corneadoug/ZEPPELIN-1415 and squashes the following commits:

42cc497 [Damien CORNEAU] add comma
850b908 [Damien CORNEAU] Fix grammar errors
63313cc [Damien CORNEAU] Change uppercasing a bit
d551928 [Damien CORNEAU] Add event dispatching documentation
86bb512 [Damien CORNEAU] change page title for goodPracticeGuide01


Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo
Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/70e4ecda
Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/70e4ecda
Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/70e4ecda

Branch: refs/heads/gh-pages
Commit: 70e4ecdadfb5c41f136425eefe26bc71c05ea187
Parents: e53101f
Author: Damien CORNEAU <co...@gmail.com>
Authored: Fri Sep 9 13:51:39 2016 +0900
Committer: Damien CORNEAU <co...@gmail.com>
Committed: Tue Sep 13 16:48:15 2016 +0900

----------------------------------------------------------------------
 contribution/zeppelinweb/goodPracticeGuide01.md |  2 +-
 contribution/zeppelinweb/goodPracticeGuide02.md | 66 ++++++++++++++++++++
 2 files changed, 67 insertions(+), 1 deletion(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/zeppelin/blob/70e4ecda/contribution/zeppelinweb/goodPracticeGuide01.md
----------------------------------------------------------------------
diff --git a/contribution/zeppelinweb/goodPracticeGuide01.md b/contribution/zeppelinweb/goodPracticeGuide01.md
index 7580b77..317bd0f 100644
--- a/contribution/zeppelinweb/goodPracticeGuide01.md
+++ b/contribution/zeppelinweb/goodPracticeGuide01.md
@@ -1,6 +1,6 @@
 ---
 layout: sideMenu
-title: "Defining Components"
+title: "1 - Defining Components"
 description: ""
 group: nav-contrib-front
 menu: nav-contrib-front

http://git-wip-us.apache.org/repos/asf/zeppelin/blob/70e4ecda/contribution/zeppelinweb/goodPracticeGuide02.md
----------------------------------------------------------------------
diff --git a/contribution/zeppelinweb/goodPracticeGuide02.md b/contribution/zeppelinweb/goodPracticeGuide02.md
new file mode 100644
index 0000000..b3d39f2
--- /dev/null
+++ b/contribution/zeppelinweb/goodPracticeGuide02.md
@@ -0,0 +1,66 @@
+---
+layout: sideMenu
+title: "2 - Event Dispatching"
+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.
+-->
+
+# Event Dispatching in Angular
+
+<br/>
+AngularJS provides an Event dispatching system allowing the communication between controllers or services and controllers.
+
+`$broadcast` dispatches the event downwards through the child scopes
+
+`$emit` dispatches the event upwards through the scope hierarchy
+
+`$on` catches the event passing by that scope
+
+<br/>
+You can usually see it being used from `$rootScope` or `$scope`
+
+```
+$scope.$broadcast('eventName', arg);
+$rootScope.$broadcast('eventName', arg);
+
+$scope.$emit('eventName', arg);
+$rootScope.$emit('eventName', arg);
+
+$scope.$on('eventToCatch', function);
+$rootScope.$on('eventToCatch', function);
+```
+
+Now, there are a few things to know about using it from `$rootScope`:
+
+* Both `$rootScope.$emit` and `$rootScope.$broadcast` go through child scopes since `$rootScope` doesn't have a parent
+* `$rootScope.$emit` can only be received by `$rootScope.$on`
+* `$rootScope.$broadcast` can be received by `$rootScope.$on` and `$scope.$on`
+* `$rootScope.$on` listener needs to be removed by hand (Memory leak if forgotten)
+
+
+#### How we are using it in the project
+
+* Usage of event dispatching should be limited if possible
+* We only use `$rootScope.$broadcast` and `$scope.$on` for event dispatching/catching
+
+
+#### Performances
+
+Using `$broadcast` might not seem optimum if we consider the description we have above.
+
+However, it is optimized to only go through branches that have a matching event binding.
+(cf. [this post](http://www.bennadel.com/blog/2724-scope-broadcast-is-surprisingly-efficient-in-angularjs.htm))