Repository: incubator-zeppelin Updated Branches: refs/heads/master 8ee3667c6 -> daab1f7f7
[ZEPPELIN-742] Add documentation for front-end AngularJS AP ### What is this PR for? This JIRA: * add documentation for the new paragraphId display in the paragraph command dialog. Instead of just adding some description to the paragraphId, I took the opportunity to also document the entire Zeppelin UI Layout and added a menu entry **UI Layout** under menu **QuickStart**. It is inspired by the content of the talk on Zeppelin at different conferences * rename the menu **Display System** / **Angular** to **Display System** / **Back-end Angular Interactions** * add a new entry **Front-end Angular Interactions** under the menu **Display System** to describe the new front-end AngularJS API introduced by this epic _This is a sub-task of epic **[ZEPPELIN-635]**_ ### What type of PR is it? [Documentation] ### Todos * [ ] - Check documentation ### What is the Jira issue? **[ZEPPELIN-6742]** ### How should this be tested? Build Zeppelin documentation locally and check ### Screenshots (if appropriate) New **QuickStart** / **UI Layout** documentation which mentions the **paragraphId**  New **Display System** / **Front-end Angular Interactions** menu to describe the new front-end AngularJS API introduced by this epic  ### Questions: * Does the licenses files need update? --> No * Is there breaking changes for older versions? --> No * Does this needs documentation? --> No [ZEPPELIN-635]: https://issues.apache.org/jira/browse/ZEPPELIN-635 [ZEPPELIN-742]: https://issues.apache.org/jira/browse/ZEPPELIN-742 Author: DuyHai DOAN <[email protected]> Closes #865 from doanduyhai/ZEPPELIN-742 and squashes the following commits: fde4fb4 [DuyHai DOAN] Update menu name after code review 2a1fa9b [DuyHai DOAN] [ZEPPELIN-742] Add documentation for front-end AngularJS API 0b719d3 [DuyHai DOAN] [ZEPPELIN-742] Add documentation for Zeppelin UI Layout & paragraphId Project: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/commit/daab1f7f Tree: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/tree/daab1f7f Diff: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/diff/daab1f7f Branch: refs/heads/master Commit: daab1f7f7a71438e6ff122ee75f33f0c2a733cdd Parents: 8ee3667 Author: DuyHai DOAN <[email protected]> Authored: Sat Apr 30 14:44:45 2016 +0200 Committer: Lee moon soo <[email protected]> Committed: Wed May 4 06:25:54 2016 -0700 ---------------------------------------------------------------------- docs/_includes/themes/zeppelin/_navigation.html | 5 +- .../zeppelin/img/screenshots/z_angularBind.gif | Bin 0 -> 105893 bytes .../z_angularJs_overriding_dynamic_form.gif | Bin 0 -> 107693 bytes .../img/screenshots/z_angularUnbind.gif | Bin 0 -> 95774 bytes .../zeppelin/img/screenshots/z_runParagraph.gif | Bin 0 -> 136276 bytes .../zeppelin/img/ui-img/configuration_menu.png | Bin 0 -> 213717 bytes .../themes/zeppelin/img/ui-img/homepage.png | Bin 0 -> 351107 bytes .../zeppelin/img/ui-img/interpreter_menu.png | Bin 0 -> 237026 bytes .../zeppelin/img/ui-img/note_commands.png | Bin 0 -> 9381 bytes .../zeppelin/img/ui-img/note_configuration.png | Bin 0 -> 25071 bytes .../zeppelin/img/ui-img/note_import_dialog.png | Bin 0 -> 29798 bytes .../img/ui-img/note_paragraph_layout.png | Bin 0 -> 171337 bytes .../themes/zeppelin/img/ui-img/note_toolbar.png | Bin 0 -> 74843 bytes .../zeppelin/img/ui-img/notebook_menu.png | Bin 0 -> 39579 bytes .../zeppelin/img/ui-img/notes_management.png | Bin 0 -> 41160 bytes .../ui-img/paragraph_configuration_dialog.png | Bin 0 -> 50533 bytes .../zeppelin/img/ui-img/paragraph_layout.png | Bin 0 -> 603391 bytes docs/displaysystem/angular.md | 217 ------------------- docs/displaysystem/back-end-angular.md | 217 +++++++++++++++++++ docs/displaysystem/front-end-angular.md | 159 ++++++++++++++ docs/ui_layout/zeppelin_layout.md | 139 ++++++++++++ 21 files changed, 519 insertions(+), 218 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/_includes/themes/zeppelin/_navigation.html ---------------------------------------------------------------------- diff --git a/docs/_includes/themes/zeppelin/_navigation.html b/docs/_includes/themes/zeppelin/_navigation.html index c616107..53728a9 100644 --- a/docs/_includes/themes/zeppelin/_navigation.html +++ b/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">Angular (backend API)</a></li> + <li><a href="{{BASE_PATH}}/displaysystem/front-end-angular.html">Angular (frontend API)</a></li> </ul> </li> <li> http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/screenshots/z_angularBind.gif ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/screenshots/z_angularBind.gif b/docs/assets/themes/zeppelin/img/screenshots/z_angularBind.gif new file mode 100644 index 0000000..d3e5821 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/screenshots/z_angularBind.gif differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/screenshots/z_angularJs_overriding_dynamic_form.gif ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/screenshots/z_angularJs_overriding_dynamic_form.gif b/docs/assets/themes/zeppelin/img/screenshots/z_angularJs_overriding_dynamic_form.gif new file mode 100644 index 0000000..002eca5 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/screenshots/z_angularJs_overriding_dynamic_form.gif differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/screenshots/z_angularUnbind.gif ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/screenshots/z_angularUnbind.gif b/docs/assets/themes/zeppelin/img/screenshots/z_angularUnbind.gif new file mode 100644 index 0000000..ef6fe93 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/screenshots/z_angularUnbind.gif differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/screenshots/z_runParagraph.gif ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/screenshots/z_runParagraph.gif b/docs/assets/themes/zeppelin/img/screenshots/z_runParagraph.gif new file mode 100644 index 0000000..1c618bc Binary files /dev/null and b/docs/assets/themes/zeppelin/img/screenshots/z_runParagraph.gif differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/configuration_menu.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/configuration_menu.png b/docs/assets/themes/zeppelin/img/ui-img/configuration_menu.png new file mode 100644 index 0000000..935b81a Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/configuration_menu.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/homepage.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/homepage.png b/docs/assets/themes/zeppelin/img/ui-img/homepage.png new file mode 100644 index 0000000..d7ab88b Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/homepage.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/interpreter_menu.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/interpreter_menu.png b/docs/assets/themes/zeppelin/img/ui-img/interpreter_menu.png new file mode 100644 index 0000000..ea5212e Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/interpreter_menu.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/note_commands.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/note_commands.png b/docs/assets/themes/zeppelin/img/ui-img/note_commands.png new file mode 100644 index 0000000..7f1a869 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/note_commands.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/note_configuration.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/note_configuration.png b/docs/assets/themes/zeppelin/img/ui-img/note_configuration.png new file mode 100644 index 0000000..5ce54b0 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/note_configuration.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/note_import_dialog.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/note_import_dialog.png b/docs/assets/themes/zeppelin/img/ui-img/note_import_dialog.png new file mode 100644 index 0000000..4572dd4 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/note_import_dialog.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/note_paragraph_layout.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/note_paragraph_layout.png b/docs/assets/themes/zeppelin/img/ui-img/note_paragraph_layout.png new file mode 100644 index 0000000..1d9de9f Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/note_paragraph_layout.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/note_toolbar.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/note_toolbar.png b/docs/assets/themes/zeppelin/img/ui-img/note_toolbar.png new file mode 100644 index 0000000..b4c587b Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/note_toolbar.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/notebook_menu.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/notebook_menu.png b/docs/assets/themes/zeppelin/img/ui-img/notebook_menu.png new file mode 100644 index 0000000..c959333 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/notebook_menu.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/notes_management.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/notes_management.png b/docs/assets/themes/zeppelin/img/ui-img/notes_management.png new file mode 100644 index 0000000..8e0299f Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/notes_management.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/paragraph_configuration_dialog.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/paragraph_configuration_dialog.png b/docs/assets/themes/zeppelin/img/ui-img/paragraph_configuration_dialog.png new file mode 100644 index 0000000..72aba8a Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/paragraph_configuration_dialog.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/assets/themes/zeppelin/img/ui-img/paragraph_layout.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/ui-img/paragraph_layout.png b/docs/assets/themes/zeppelin/img/ui-img/paragraph_layout.png new file mode 100644 index 0000000..cfce069 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/ui-img/paragraph_layout.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/displaysystem/angular.md ---------------------------------------------------------------------- diff --git a/docs/displaysystem/angular.md b/docs/displaysystem/angular.md deleted file mode 100644 index 21ea44e..0000000 --- a/docs/displaysystem/angular.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -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%"> http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/displaysystem/back-end-angular.md ---------------------------------------------------------------------- diff --git a/docs/displaysystem/back-end-angular.md b/docs/displaysystem/back-end-angular.md new file mode 100644 index 0000000..4a06a08 --- /dev/null +++ b/docs/displaysystem/back-end-angular.md @@ -0,0 +1,217 @@ +--- +layout: page +title: "Angular (backend API)" +description: "Angular (backend API)" +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 %} + + +## Back-end Angular API 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%"> http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/displaysystem/front-end-angular.md ---------------------------------------------------------------------- diff --git a/docs/displaysystem/front-end-angular.md b/docs/displaysystem/front-end-angular.md new file mode 100644 index 0000000..b79d187 --- /dev/null +++ b/docs/displaysystem/front-end-angular.md @@ -0,0 +1,159 @@ +--- +layout: page +title: "Angular (frontend API)" +description: "Angular (frontend API)" +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 %} + + +## Front-end Angular API in Zeppelin + +In addition to the back-end API to handle Angular objects binding, Zeppelin also exposes a simple AngularJS **`z`** object on the front-end side to expose the same capabilities. + +This **`z`** object is accessible in the Angular isolated scope for each paragraph. + +<br /> +### Bind / Unbind Variables + +Through the **`z`**, you can bind / unbind variables to **AngularJS view** + +Bind a value to an angular object and a **mandatory** target paragraph: + +```html + +%angular + +<form class="form-inline"> + <div class="form-group"> + <label for="superheroId">Super Hero: </label> + <input type="text" class="form-control" id="superheroId" placeholder="Superhero name ..." ng-model="superhero"></input> + </div> + <button type="submit" class="btn btn-primary" ng-click="z.angularBind('superhero',superhero,'20160222-232336_1472609686')"> Bind</button> +</form> + +``` + +<img src="/assets/themes/zeppelin/img/screenshots/z_angularBind.gif" /> + +<hr/> + +Unbind/remove a value from angular object and a **mandatory** target paragraph: + +```html + +%angular + +<form class="form-inline"> + <button type="submit" class="btn btn-primary" ng-click="z.angularUnbind('superhero','20160222-232336_1472609686')"> UnBind</button> +</form> + +``` + +<img src="/assets/themes/zeppelin/img/screenshots/z_angularUnbind.gif" /> + +The signature for the **`z.angularBind() / z.angularUnbind()`** functions are: + +```javascript + +z.angularBind(angularObjectName, angularObjectValue, paragraphId); + +z.angularUnbind(angularObjectName, angularObjectValue, paragraphId); + +``` + +All the parameters are mandatory. + + +<br /> +### Run Paragraph + +You can also trigger paragraph execution by calling **`z.runParagraph()`** function passing the appropriate paragraphId: + +```html + +%angular + +<form class="form-inline"> + <div class="form-group"> + <label for="paragraphId">Paragraph Id: </label> + <input type="text" class="form-control" id="paragraphId" placeholder="Paragraph Id ..." ng-model="paragraph"></input> + </div> + <button type="submit" class="btn btn-primary" ng-click="z.runParagraph(paragraph)"> Run Paragraph</button> +</form> + +``` + +<img src="/assets/themes/zeppelin/img/screenshots/z_runParagraph.gif" /> + +<br /> +### Overriding dynamic form with Angular Object + +The front-end Angular Interaction API has been designed to offer richer form capabilities and variable binding. With the existing **Dynamic Form** system you can already create input text, select and checkbox forms but the choice is rather limited and the look & feel cannot be changed. + +The idea is to create a custom form using plain HTML/AngularJS code and bind actions on this form to push/remove Angular variables to targeted paragraphs using this new API. + +Consequently if you use the **Dynamic Form** syntax in a paragraph and there is a bound Angular object having the same name as the _${formName}_, the Angular object will have higher priority and the **Dynamic Form** will not be displayed. Example: + + +<img src="/assets/themes/zeppelin/img/screenshots/z_angularJs_overriding_dynamic_form.gif" /> + + +<br /> +### Feature matrix comparison + +How does the front-end AngularJS API compares to the back-end API ? Below is a comparison matrix for both APIs: + +<table> + <thead> + <tr> + <th>Actions</th> + <th>Front-end API</th> + <th>Back-end API</th> + </tr> + </thead> + <tr> + <td>Initiate binding</td> + <td>z.angularbind(var, initialValue, paragraphId)</td> + <td>z.angularBind(var, initialValue)</td> + </tr> + <tr> + <td>Update value</td> + <td>same to ordinary angularjs scope variable, or z.angularbind(var, newValue, paragraphId)</td> + <td>z.angularBind(var, newValue)</td> + </tr> + <tr> + <td>Watching value</td> + <td>same to ordinary angularjs scope variable</td> + <td>z.angularWatch(var, (oldVal, newVal) => ...)</td> + </tr> + <tr> + <td>Destroy binding</td> + <td>z.angularUnbind(var, paragraphId)</td> + <td>z.angularUnbind(var)</td> + </tr> + <tr> + <td>Executing Paragraph</td> + <td>z.runParagraph(paragraphId)</td> + <td>z.run(paragraphId)</td> + </tr> + <tbody> + <tbody> +</table> + +Both APIs are pretty similar, except for value watching where it is done naturally by AngularJS internals on the front-end and by user custom watcher functions in the back-end. + +There is also a slight difference in term of scope. Front-end API limits the Angular object binding to a paragraph scope whereas back-end API allows you to bind an Angular object at the global or note scope. This restriction has been designed purposely to avoid Angular object leaks and scope pollution. http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/daab1f7f/docs/ui_layout/zeppelin_layout.md ---------------------------------------------------------------------- diff --git a/docs/ui_layout/zeppelin_layout.md b/docs/ui_layout/zeppelin_layout.md new file mode 100644 index 0000000..d848722 --- /dev/null +++ b/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" /> + + +
