[ZEPPELIN-742] Add documentation for Zeppelin UI Layout & paragraphId

docs/_includes/themes/zeppelin/_navigation.html

@@ -31,6 +31,8 @@
                 <!-- li><span><b>Tutorial</b><span></li -->
                 <li><a href="{{BASE_PATH}}/tutorial/tutorial.html">Tutorial</a></li>
                 <li role="separator" class="divider"></li>
+                <li><a href="{{BASE_PATH}}/ui_layout/zeppelin_layout.html">UI Layout</a></li>
+                <li role="separator" class="divider"></li>
                 <!-- li><span><b>Guide</b><span></li -->
                 <li><a href="{{BASE_PATH}}/manual/dynamicform.html">Dynamic Form</a></li>
                 <li><a href="{{BASE_PATH}}/manual/publish.html">Publish your Paragraph</a></li>
@@ -70,7 +72,8 @@
                 <li><a href="{{BASE_PATH}}/displaysystem/display.html">Text</a></li>
                 <li><a href="{{BASE_PATH}}/displaysystem/display.html#html">Html</a></li>
                 <li><a href="{{BASE_PATH}}/displaysystem/table.html">Table</a></li>
-                <li><a href="{{BASE_PATH}}/displaysystem/angular.html">Angular</a></li>
+                <li><a href="{{BASE_PATH}}/displaysystem/back-end-angular.html">Back-End Angular Variable Interactions</a></li>
+                <li><a href="{{BASE_PATH}}/displaysystem/front-end-angular.html">Front-End Angular Variable Interactions</a></li>
               </ul>
             </li>
             <li>

docs/displaysystem/front-end-angular.md

@@ -0,0 +1,219 @@
+---
+layout: page
+title: "Angular Display System"
+description: ""
+group: display
+---
+<!--
+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.
+-->
+{% include JB/setup %}
+
+
+## Angular Display System in Zeppelin
+
+Angular display system treats output as a view template for [AngularJS](https://angularjs.org/).
+It compiles templates and displays them inside of Zeppelin.
+
+Zeppelin provides a gateway between your interpreter and your compiled **AngularJS view** templates.
+Therefore, you can not only update scope variables from your interpreter but also watch them in the interpreter, which is JVM process.
+
+### Print AngularJS view
+
+To use angular display system, you should start with `%angular`.
+<img src="/assets/themes/zeppelin/img/screenshots/display_angular.png" width="60%" />
+
+Since `name` is not defined, `Hello {{name}}` will display `Hello`.
+> **Please Note:** Display system is backend independent.
+
+<br />
+### Bind / Unbind Variables
+
+Through **ZeppelinContext**, you can bind / unbind variables to **AngularJS view**. Currently, it only works in **Spark Interpreter ( scala )**.
+
+```scala
+// bind my 'object' as angular scope variable 'name' in current notebook.
+z.angularBind(String name, Object object)
+
+// bind my 'object' as angular scope variable 'name' in all notebooks related to current interpreter.
+z.angularBindGlobal(String name, Object object)
+
+// unbind angular scope variable 'name' in current notebook.
+z.angularUnbind(String name)
+
+// unbind angular scope variable 'name' in all notebooks related to current interpreter.
+z.angularUnbindGlobal(String name)
+
+```
+
+Using the above example, let's bind `world` variable to `name`. Then you can see **AngularJs view** is immediately updated.
+
+<img src="/assets/themes/zeppelin/img/screenshots/display_angular1.png" width="60%" />
+
+
+<br />
+### Watch / Unwatch Variables
+
+Through **ZeppelinContext**, you can watch / unwatch variables in **AngularJs view**. Currently, it only works in **Spark Interpreter ( scala )**.
+
+```scala
+// register for angular scope variable 'name' (notebook)
+z.angularWatch(String name, (before, after) => { ... })
+
+// unregister watcher for angular variable 'name' (notebook)
+z.angularUnwatch(String name)
+
+// register for angular scope variable 'name' (global)
+z.angularWatchGlobal(String name, (before, after) => { ... })
+
+// unregister watcher for angular variable 'name' (global)
+z.angularUnwatchGlobal(String name)
+
+
+```
+
+Let's make a button. When it is clicked, the value of `run` will be increased 1 by 1.
+
+<img src="/assets/themes/zeppelin/img/screenshots/display_angular2.png" width="60%" />
+
+`z.angularBind("run", 0)` will initialize `run` to zero. And then, it will be also applied to `run` in `z.angularWatch()`.
+When the button is clicked, you'll see both `run` and `numWatched` are incremented by 1.
+
+<img src="/assets/themes/zeppelin/img/screenshots/display_angular3.png" width="60%" />
+
+## Let's make it Simpler and more Intuitive
+In this section, we will introduce a simpler and more intuitive way of using **Angular Display System** in Zeppelin. 
+
+### How can we use it?
+Here are some usages. 
+
+#### Import 
+
+#####  - In notebook scope
+```scala
+import org.apache.zeppelin.display.angular.notebookscope._
+import AngularElem._
+```
+
+#####  - In paragraph scope
+```scala
+import org.apache.zeppelin.display.angular.paragraphscope._
+import AngularElem._
+```
+
+
+#### Display Element
+```scala
+// automatically convert to string and print with %angular display system directive in front.
+<div><div>.display
+```
+#### Event Handler
+```scala
+// on click
+<div></div>.onClick(() => {
+   my callback routine
+}).display
+
+// on change
+<div></div>.onChange(() => {
+  my callback routine
+}).display
+
+// arbitrary event
+<div></div>.onEvent("ng-click", () => {
+  my callback routine
+}).display
+```
+
+#### Bind Model
+```scala
+// bind model
+<div></div>.model("myModel").display
+
+// bind model with initial value
+<div></div>.model("myModel", initialValue).display 
+```
+
+#### Interact with Model
+```scala 
+// read model
+AngularModel("myModel")()
+
+// update model
+AngularModel("myModel", "newValue")
+```
+
+<br/>
+### Example: Basic Usage
+Using the above basic usages, you can apply them like below examples. 
+
+#### Display Elements
+
+```scala
+<div style="color:blue">
+  <h4>Hello Angular Display System</h4>
+</div>.display
+```
+
+#### OnClick Event
+```scala
+<div class="btn btn-success">
+  Click me
+</div>.onClick{() =>
+  // callback for button click
+}.display
+```
+
+#### Bind Model
+
+{% raw %}
+```scala
+  <div>{{{{myModel}}}}</div>.model("myModel", "Initial Value").display
+```
+{% endraw %}
+
+#### Interact With Model
+```scala
+// read the value
+AngularModel("myModel")()
+
+// update the value
+AngularModel("myModel", "New value")
+```
+
+<img src="../assets/themes/zeppelin/img/docs-img/basic-usage-angular.png" width="70%">
+
+### Example: String Converter
+Using below example, you can convert the lowercase string to uppercase.
+ 
+{% raw %}
+```scala
+// clear previously created angular object.
+AngularElem.disassociate
+
+val button = <div class="btn btn-success btn-sm">Convert</div>.onClick{() =>
+  val inputString = AngularModel("input")().toString
+  AngularModel("title", inputString.toUpperCase)
+}
+
+<div>
+  { <h4> {{{{title}}}}</h4>.model("title", "Please type text to convert uppercase") }
+   Your text { <input type="text"></input>.model("input", "") }
+  {button}
+</div>.display
+```
+{% endraw %}
+
+<img src="../assets/themes/zeppelin/img/docs-img/string-converter-angular.gif" width="70%">
+
+ 

docs/ui_layout/zeppelin_layout.md

@@ -0,0 +1,139 @@
+---
+layout: page
+title: "Zeppelin UI Layout"
+description: "Description of Zeppelin UI Layout"
+group: ui_layout
+---
+<!--
+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.
+-->
+## Home Page
+
+The first time you connect to Zeppelin, you'll land at the main page similar to the below screen capture
+
+<img src="/assets/themes/zeppelin/img/ui-img/homepage.png" />
+
+On the left of the page are listed all existing notes. Those notes are stored by default in the `$ZEPPELIN_HOME/notebook` folder. 
+
+You can filter them by name using the input text form. You can also create an new note, refresh the list of existing notes 
+(in case you manually copy them into the `$ZEPPELIN_HOME/notebook` folder) and import a note
+  
+<img src="/assets/themes/zeppelin/img/ui-img/notes_management.png" />
+ 
+When clicking on `Import Note` link, a new dialog open. From there you can import your note from local disk or from a remote location
+if you provide the URL.
+ 
+<img src="/assets/themes/zeppelin/img/ui-img/note_import_dialog.png" />
+
+By default, the name of the imported note is the same as the original note but you can override it by providing a new name 
+
+<br />
+## Menus
+
+### 1. Notebook
+
+The `Notebook` menu proposes almost the same features as the note management section in the home page. From the drop-down menu you can:
+
+1. Open a selected note
+2. Filter node by name
+3. Create a new note
+
+<img src="/assets/themes/zeppelin/img/ui-img/notebook_menu.png" />
+
+### 2. Interpreter
+
+In this menu you can:
+
+1. Configure existing **interpreter instance**
+2. Add/remove **interpreter instances**
+
+<img src="/assets/themes/zeppelin/img/ui-img/interpreter_menu.png" />
+
+### 3. Configuration
+
+This menu displays all the Zeppelin configuration that are set in the config file `$ZEPPELIN_HOME/conf/zeppelin-site.xml`
+
+<img src="/assets/themes/zeppelin/img/ui-img/configuration_menu.png" />
+
+
+<br />
+## Note Layout 
+
+Each Zeppelin note is composed of 1 .. N paragraphs. The note can be viewed as a paragraph container. 
+ 
+<img src="/assets/themes/zeppelin/img/ui-img/note_paragraph_layout.png" />
+
+### Paragraph
+
+Each paragraph consists of 2 sections: `code section` where you put your source code and `result section` where you can see the result of the code execution.
+
+<img src="/assets/themes/zeppelin/img/ui-img/paragraph_layout.png" />
+ 
+On the top-right corner of each paragraph there are some commands to:
+ 
+* execute the paragraph code
+* hide/show `code section`
+* hide/show `result section`
+* configure the paragraph
+
+To configure the paragraph, just click on the gear icon:
+ 
+<img src="/assets/themes/zeppelin/img/ui-img/paragraph_configuration_dialog.png" />
+ 
+From this dialog, you can (in descending order):
+ 
+* find the **paragraph id** ( **20150924-163507_134879501** )
+* control paragraph width. Since Zeppelin is using the grid system of **Twitter Bootstrap**, each paragraph width can be changed from 1 to 12
+* move the paragraph 1 level up
+* move the paragraph 1 level down
+* create a new paragraph
+* change paragraph title
+* show/hide line number in the `code section`
+* disable the run button for this paragraph
+* export the current paragraph as an **iframe** and open the **iframe** in a new window
+* clear the `result section`
+* delete the current paragraph
+  
+### Note toolbar
+  
+At the top of the note, you can find a toolbar which exposes command buttons as well as configuration, security and display options
+  
+<img src="/assets/themes/zeppelin/img/ui-img/note_toolbar.png" />  
+   
+On the far right is displayed the note name, just click on it to reveal the input form and update it
+   
+In the middle of the toolbar you can find the command buttons:
+   
+* execute all the paragraphs **sequentially**, in their display order
+* hide/show `code section` of all paragraphs      
+* hide/show `result section` of all paragraphs
+* clear the `result section` of all paragraphs
+* clone the current note
+* export the current note to a JSON file. _Please note that the `code section` and `result section` of all paragraphs will be exported. If you have heavy data in the `result section` of some paragraphs, it is recommended to clean them before exporting
+* commit the current node content
+* delete the note
+* schedule the execution of **all paragraph** using a CRON syntax
+
+<img src="/assets/themes/zeppelin/img/ui-img/note_commands.png" />
+
+On the right of the note tool bar you can find configuration icons:
+ 
+* display all the keyboard shorcuts
+* configure the interpreters binding to the current note
+* configure the note permissions
+* switch the node display mode between `default`, `simple` and `report`
+
+<img src="/assets/themes/zeppelin/img/ui-img/note_configuration.png" />
+ 
+ 
+