From 12ea220b8a331ca57947c1619a8d38cfadab4cdc Mon Sep 17 00:00:00 2001 From: Simon Hunt Date: Wed, 19 Apr 2017 15:58:24 -0700 Subject: [PATCH] More work on UI documentation. Change-Id: I0c1085d62f74f89db2cf6589861386b26bf4a709 --- web/gui/doc/README.user.topo.md | 103 ++++++++++++++++++++++++++++ web/gui/doc/README.user.views.md | 113 ++++++++++++++++++++++++++++--- 2 files changed, 208 insertions(+), 8 deletions(-) create mode 100644 web/gui/doc/README.user.topo.md diff --git a/web/gui/doc/README.user.topo.md b/web/gui/doc/README.user.topo.md new file mode 100644 index 0000000000..be89020fef --- /dev/null +++ b/web/gui/doc/README.user.topo.md @@ -0,0 +1,103 @@ +ONOS Web UI - Topology View +=========================== + +Documentation for the Web UI _Topology View_. + +[pic]: picture-icon.png +[topo]: https://wiki.onosproject.org/display/ONOS/GUI+Topology+View + +([Wiki Page][topo]) + +### Overview +The _topology view_ provides a visual (cluster-wide) overview of the network +topology controlled by ONOS. When the topology view is instantiated it +requests topology information from the server; on receipt of that information, +the view renders a visualization of devices, hosts, and the links between them. +The view uses the web-socket connection established by the UI framework to +allow the server to drive updates to the view via topology events +(such as _addHost_, _updateDevice_, etc.) + +![Sample image of 3-node cluster][pic] + + +### Quick help +Pressing slash `/` or backslash `\ ` will bring up the _Quick Help_ panel. +This gives an outline of the keystroke commands and mouse gestures available +to you in the _Topology View_. Pressing either of these keys again (or pressing +`Esc` will dismiss the panel). + +![Image of Quick Help panel][pic] + +* The top section lists global key-bindings (available on every view in the UI) +* The middle section lists view-specific bindings + * The first and second columns show general commands for the + _Topology View_ + * The third column shows commands for the currently active + "topology overlay" (if any) +* The bottom section lists view-specific mouse gestures and other notes + +### Toolbar +The key-bindings (listed in _Quick Help_) are also associated with buttons +on the toolbar. (This facilitates using the UI on a smart tablet). +The toolbar is initially hidden, but clicking on the arrow, or pressing +dot (`.`) will toggle its state. + +The toolbar has three rows of buttons: + +* The first row and half the second row provide basic functions +* The second half of the second row provides a radio-button-set + of installed "overlays" +* The third row contains buttons contributed by the currently-active "overlay" + +Hovering the mouse over a toolbar button will display a tooltip showing a +description of the button, and listing the key binding, e.g. +`Toggle Summary Panel (O)`. + +#### Toolbar First Row + +> note: wiki page should format this in a table, and include button icons + +* `I` - show/hide ONOS cluster instance panel +* `O` - show/hide ONOS summary panel +* `D` - disable/enable details panel + + The details panel is enabled by default, and is displayed when one or + more topology elements are selected. Disabling this panel keeps it + hidden even when something is selected. +* `H` - toggle host visibility + + Shows or hides the hosts (and their links). +* `M` - toggle offline-device visibility + + Devices that are offline (but that ONOS still knows about) are shown + by default. This toggle will hide offline devices (and any hosts/links) + connected to them). +* `P` - Toggle port highlighting + + Port highlighting displays port numbers on links when the mouse + hovers over the link. This feature can be disabled with this toggle. +* `B` - Toggle background geo map + + The background geo-based map (if one is selected) can be shown or hidden. +* `G` - Select background geo map + + Opens a dialog box which allows selection of a geographic region from + a pre-defined set. +* `S` - Toggle sprite layer + + The sprite layer (static shapes / text injected into the view) can be + shown or hidden with this toggle. + +#### Toolbar Second Row + +(tbd) + +#### Toolbar Third Row + +(tbd) + + +#### Overlays +The ONOS Web UI comes bundled with the _Traffic Overlay_, which provides +traffic visualization functionality. Other applications running on ONOS +may also register topology overlays, which can be used to provide alternate +visualizations on the topology view. + +> `F1` will select "no overlay active"; `F2` will select the traffic overlay. +> `F3`, `F4`, ... will select additional overlays, if they are registered and +> appear in the toolbar. + +(WIP --- to be completed) diff --git a/web/gui/doc/README.user.views.md b/web/gui/doc/README.user.views.md index 07b8082910..927946284c 100644 --- a/web/gui/doc/README.user.views.md +++ b/web/gui/doc/README.user.views.md @@ -43,10 +43,43 @@ with, all installed applications. The applications are displayed in ![screenshot of app view][pic] Selecting a row will display a detail panel, containing more information -about the selected application. Control buttons will also become available, -based on the current state of the application. +about the selected application, including: +* Basic properties: + * App ID + * State + * Category + * Version + * Origin + * Role +* URL -- to application documentation page +* Description +* Features, App dependencies, and Permissions (if any) -(to be completed) +![Image showing a selected application, and its detail panel][pic] + +Note that the first column will contain a checkmark, if the application is +currently active. + +As with all table views, clicking on a column header will sort entries +by that column. + +### Interacting with applications + +An application can be installed simply by dragging and dropping +an `.oar` file onto the application page. The page border will highlight +when the "drop target" has been acquired. + +Alternatively, pressing the "Install" (`+`) control button will bring up +a file selection dialog, with which you can select on `.oar` file. + +The "Activate" (`>`) control button will start the selected application. + +The "Deactivate" (`[]`) control button will stop the selected application. + +The "Uninstall" (`trashcan`) button will uninstall the application. + +In each case, a confirmation dialog will pop up, asking you to verify the +action. ---- @@ -57,7 +90,25 @@ Settings View ([Wiki Page][set]) ### Overview -The settings view ... (to be completed) +The settings view lists all the tunable settings by component, showing for each: + +* Component name +* Property name +* Property type +* Current value +* Description + +> Values that are _not_ currently the _default_ value +> will be shown in **bold type**. + +![Image showing settings view][pic] + +Selecting a table row will display a detail panel for the corresponding setting. + +Currently, this view is read-only; future versions of the UI may +support adjusting settings from this view. + +> Note: the detail panel is where parameter editing would take place ---- @@ -68,7 +119,21 @@ Cluster Node View ([Wiki Page][cnode]) ### Overview -The cluster node view ... (to be completed) +The cluster node view lists the cluster members, showing basic information +for each: + +* active +* started +* identifier +* IP address +* TCP port +* Last updated + +Selecting a table row will display a detail panel for the selected node, +listing each of the devices for which this node currently holds +"mastership". + +![Image showing selected node, and its detail panel][pic] ---- @@ -79,7 +144,19 @@ Packet Processors View ([Wiki Page][pkt]) ### Overview -The packet processors view ... (to be completed) +The packet processors view lists each component that participates in +the handling of incoming network packets, in the order that they are +configured. Each entry shows: + +* Priority +* Type _{advisor|director|observer}_ +* Implementing class +* Packets processed +* Average processing time per packet _(ms)_ + +![Image showing packet processors table][pic] + +Table row entries are not selectable. ---- @@ -89,7 +166,17 @@ Paritions View ([Wiki Page][part]) ### Overview -The partitions view ... (to be completed) +The partitions view shows how partitions are configured on the cluster, one +table row per partition: + +* Partition name +* Term +* Partition leader +* Partition members + +![Image showing partition table][pic] + +Table row entries are not selectable. ---- @@ -101,7 +188,17 @@ Topology View ([Wiki Page][topo]) ### Overview -The topology view ... (to be completed) +The _topology view_ provides a visual (cluster-wide) overview of the network +topology controlled by ONOS. When the topology view is instantiated it +requests topology information from the server; on receipt of that information, +the view renders a visualization of devices, hosts, and the links between them. +The view uses the web-socket connection established by the UI framework to +allow the server to drive updates to the view via topology events +(such as _addHost_, _updateDevice_, etc.) + +![Sample image of 3-node cluster][pic] + +See `README.user.topo.md` for details. ----