Initial draft of GUI user documentation under revision control.
Change-Id: I64eafd8e9129db3ac4d92145a1275bc5c00cfe7d
diff --git a/web/gui/doc/README.user.md b/web/gui/doc/README.user.md
new file mode 100644
index 0000000..cb7206f
--- /dev/null
+++ b/web/gui/doc/README.user.md
@@ -0,0 +1,231 @@
+ONOS Web UI - User Documentation
+================================
+
+#### Note to Reader
+
+This document provides a brief overview of the _User Documentation_ for
+the _ONOS Web UI_. For more detailed documentation (including screenshots),
+please see [The ONOS Web GUI][owg] on the ONOS wiki.
+
+Further content (subsections) may be found in files named `README.user.*.md`
+
+Placeholders for screenshots / images are marked thusly:
+
+![sample image placeholder][pic]
+
+[owg]: https://wiki.onosproject.org/display/ONOS/The+ONOS+Web+GUI
+[pic]: picture-icon.png
+
+
+
+Introduction
+------------
+
+#### Overview
+
+The ONOS GUI is a _single-page web application_, providing a visual
+interface to the ONOS controller (or cluster of controllers).
+
+For documentation on the design of the GUI, see [Web UI Architecture][ua] in
+the Architecture Guide.
+
+For documentation on how applications running on ONOS can inject content
+into the GUI at runtime, see the [Web UI Tutorials][ut] page.
+
+The [Developer Guide][dg] includes documentation on the Web UI framework
+libraries (for both _client-side_ and _server-side_ modules), to help app
+developers re-use common coding patterns.
+
+
+[ua]: https://wiki.onosproject.org/display/ONOS/Web+UI+Architecture
+[ut]: https://wiki.onosproject.org/display/ONOS/Web+UI+Tutorials
+[dg]: https://wiki.onosproject.org/display/ONOS/Appendix+F%3A+Web+UI+Framework+Libraries
+
+
+----
+#### Configuration Notes
+
+* The **_onos-gui_** feature must be installed in ONOS
+* The GUI listens on port **_8181_**
+* The base url is `/onos/ui`
+ + for example, to access the GUI on _localhost_, use
+ `http://localhost:8181/onos/ui`
+* The GUI has been developed to work on _Google Chrome_.
+ The GUI has been tested on _Safari_ and _Firefox_ and minor compatibility
+ adjustments have been made; these and other browsers may work, but have
+ not been extensively tested, and are not actively supported, at this time.
+* The key bindings associated with any view will work on any keyboard.
+ The "Cmd" (⌘) key on an Apple keyboard is bound to the same key as
+ the "Windows" or "Alt" keys on Windows or other keyboards.
+
+
+----
+#### Session Notes
+
+Note that the current version of the GUI does not fully support the concept
+of individual user accounts, however, login credentials are required.
+
+On launching the GUI you should see the login screen:
+
+![image of login screen][pic]
+
+Default username and password are `onos/rocks`.
+
+If ONOS was installed via `onos-install` and configured by `onos-secure-ssh`
+(developer / test tools), then the _username / password_ may be different;
+examine the `$ONOS_WEB_USER` and `$ONOS_WEB_PASS` environment variables to
+discover what they are.
+
+After a successful login, you should see a screen that looks like this:
+
+![image of topology view][pic]
+
+The dark bar at the top is the _Masthead_, which provides a location for
+general GUI controls:
+
+- Navigation Menu Button
+- ONOS logo and title
+- Context help button (click to open web URL specific to view)
+- User name (click to access `logout` action)
+
+(In future versions, the masthead may include session controls such as
+user preferences, global search, etc.)
+
+The remainder of the screen is the "view", which defaults to the
+Topology View when the GUI is first loaded – a cluster-wide view of the
+network topology.
+
+* The _ONOS Cluster Node Panel_ indicates the cluster members
+ (controller instances) in the cluster.
+* The _Summary Panel_ gives a brief summary of properties of the
+ network topology.
+* The _Topology Toolbar_ (initially hidden) provides
+ push-button / toggle-button actions that interact with the topology view.
+
+For more detailed information about this view, see the [Topology View][topo] page.
+
+
+----
+#### Navigation
+
+Other views can be "navigated to" by clicking on the _Navigation Menu Button_
+in the masthead, then selecting an item from the dropdown menu:
+
+![image of navigation menu][pic]
+
+----
+#### Views
+
+The GUI is cacapable of supporting multiple views. As new views are added
+to the base release, they will be documented here.
+
+> NOTE:
+> The capability of adding views to the GUI dynamically at run-time is also
+> available to developers, allowing, for example, an ONOS App developer to
+> create GUI content that works specifically with their application.
+> The content will be injected dynamically into the GUI when the app is
+> installed, and removed automatically from the GUI when the app is
+> uninstalled. For more details on this feature, see the
+> [Web UI tutorials][ut].
+
+The views currently included in the base release are:
+
+- Platform Category
+ + Applications
+ + The [Application View][app] provides a listing of installed
+ applications, as well as the ability to _install, start, stop
+ and uninstall_ them.
+ + Settings
+ + The [Settings View][set] provides information about all configurable
+ settings in the system. (Currently this is a readonly view, but
+ future releases may provide setting adjustments from here).
+ + Cluster Nodes
+ + The [Cluster Node View][cnode] provides a top level listing of all
+ the nodes (ONOS instances) in the cluster.
+ + Packet Processors
+ + The [Packet Processors View][pkt] shows the currently configured
+ components that participate in the processing of packets
+ sent to the controller.
+ + Partitions
+ + The [Partitions View][part] shows the cluster partitions.
+
+- Network Category
+ + Topology
+ + The [Topology View][topo] provides an interactive visualization of the
+ network topology, including an indication of which devices (switches)
+ are mastered by each ONOS controller instance.
+ + Topology 2 (experimental)
+ + The [Topology 2 View][topo2] is a "region aware" view of the topology
+ which can take advantage of an administrator configuring the network
+ into regions.
+ * Note that this view is _currently experimental_
+ + Devices
+ + The [Devices View][dev] provides a top level listing of the
+ devices in the network. Note that when a device in the table is
+ selected, additional views (not directly available from the navigation
+ menu) become available for that device:
+ + [Flows][flow]: shows all flows for the selected device
+ + [Ports][port]: shows all ports for the selected device
+ + [Groups][group]: shows all groups for the selected device
+ + [Meters][meter]: shows all meters for the selected device
+ + Links
+ + The [Links View][link] provides a top level listing of all the
+ links in the network.
+ + Hosts
+ + The [Hosts View][host] provides a top level listing of all the
+ hosts in the network.
+ + Intents
+ + The [Intents View][intent] provides a top level listing of all the
+ intents in the network.
+ + Tunnels
+ + The [Tunnels View][tunnel] provides a top level listing of all
+ tunnels defined in the network.
+
+[app]: https://wiki.onosproject.org/display/ONOS/GUI+Application+View
+[set]: https://wiki.onosproject.org/display/ONOS/GUI+Settings+View
+[cnode]: https://wiki.onosproject.org/display/ONOS/GUI+Cluster+Node+View
+[pkt]: https://wiki.onosproject.org/display/ONOS/ONOS+Packet+Processors+View
+[part]: https://wiki.onosproject.org/display/ONOS/GUI+Partitions+View
+
+[topo]: https://wiki.onosproject.org/display/ONOS/GUI+Topology+View
+[topo2]: https://wiki.onosproject.org/display/ONOS/GUI+Topology+2+View
+[dev]: https://wiki.onosproject.org/display/ONOS/GUI+Device+View
+[flow]: https://wiki.onosproject.org/display/ONOS/GUI+Flow+View
+[port]: https://wiki.onosproject.org/display/ONOS/GUI+Port+View
+[group]: https://wiki.onosproject.org/display/ONOS/GUI+Group+View
+[meter]: https://wiki.onosproject.org/display/ONOS/GUI+Meter+View
+[link]: https://wiki.onosproject.org/display/ONOS/GUI+Link+View
+[host]: https://wiki.onosproject.org/display/ONOS/GUI+Host+View
+[intent]: https://wiki.onosproject.org/display/ONOS/GUI+Intent+View
+[tunnel]: https://wiki.onosproject.org/display/ONOS/GUI+Tunnel+View
+
+Note that many of the views are table-based, and are similar in look
+and interaction. For a general overview of tabular usage, see the
+[Tabular View][table] page.
+
+[table]: https://wiki.onosproject.org/display/ONOS/GUI+Tabular+View
+
+> See `README.user.views.md` for view specific documentation.
+
+[README-user-views]: README.user.views.md
+
+
+----
+#### Web UI Applications
+
+ONOS applications may contain Web UI components - either custom views
+or topology overlay behaviors.
+For documentation on application-specific behavior, please see the
+[Web UI Application Index][appidx].
+
+> NOTE: For applications that are distributed with core ONOS, it is expected
+> that the developer provides a wiki page for documentation, and provides a
+> link in the index page.
+
+[appidx]: https://wiki.onosproject.org/display/ONOS/Web+UI+Application+Index
+
+----
+#### Release Nodes
+
+Please see `README.user.releases.md` for a summary of UI features introduced
+at each release of ONOS.
diff --git a/web/gui/doc/README.user.releases.md b/web/gui/doc/README.user.releases.md
new file mode 100644
index 0000000..6e3d005
--- /dev/null
+++ b/web/gui/doc/README.user.releases.md
@@ -0,0 +1,161 @@
+ONOS Web UI - User Documentation
+================================
+
+### Release Notes
+
+This section provides a reverse-chronological summary of changes
+to the GUI for each release.
+
+----
+#### Kingfisher -- 1.10.0 -- May 2017
++ (to be listed)
+
+----
+#### Junco -- 1.9.0 -- February 2017
++ Region aware topology view _(Topology 2)_
+ + Still WIP
+ + Region transition animation added
+ + Sprite layers added
++ Partitions View added
++ Support for viewing selected intent via topology overlays added
+
+----
+#### Ibis -- 1.8.0 -- November 2016
++ Region aware topology view _(Topology 2)_
+ + Network configurations added for _Regions_ and _TopoLayouts_
++ "Resubmit Intent" action added to _Intents View_
++ Topology View icons updated
++ Cluster View details panel added
++ Local filtering added to _Flow_, _Port_, _Group_, and _Meter_ views.
+
+----
+#### Hummingbird -- 1.7.0 -- August 2016
++ Region aware topology view _(Topology 2)_
+ + Server-side modeling implemented
++ "Brief" mode introduced to _Intent_, _Group_, and _Flow_ views
++ Continued work on re-theming the UI
+
+----
+#### Goldeneye -- 1.6.0 -- May 2016
++ Overhaul of the "Look-n-Feel" (re-skinned)
++ Applications view:
+ + Drag-n-drop of `.oar` files to install and activate, now supported
+ + Auto-prompt user to refresh the UI when components are added / removed
++ Topology view:
+ + "Cluster node ready" checkmark indicator added
+ + Geo-map selection dialog (`G` keystroke) added
+ + Support for topology overlays to provide custom link data
++ Dialog Service:
+ + Support for chained dialog operations added
++ Chart Service added
++ User preferences now persisted server side
++ Logged-in user name displayed in masthead
+
+----
+#### Falcon -- 1.5.0 -- February 2016
++ Topology View:
+ + "Reset node locations" command (`X` keystroke) added
+ + Topology overlay selection with `F1`, `F2`, `F3`, ... keystrokes added
++ Applications View:
+ + Confirmation dialog added for application activate / deactivate /
+ uninstall
+ + Application model enhancements supported:
+ + columns added for additional attributes
+ + details panel displayed when application row selected
+ + Note: applications can now define custom icon and URL (link to docs)
++ Dialog Service:
+ + `Enter` and `Escape` keys bound to _OK_ and _Cancel_ buttons
+
+----
+#### Emu -- 1.4.0 -- November 2015
++ Device View:
+ + Friendly name can be set on a device from the device detail panel
++ Intent View:
+ + Button added to navigate to _Topology View_ and display the
+ selected intent
++ Topology View:
+ + _Traffic Overlay_ now selected by default
+ + Topology overlays can now highlight devices and hosts with badges
+ (small number / text / glyph)
+ + Topology overlays can invoke a dialog box to interact with the user
++ ONOS-Branded "Loading..." animation added
++ Sample application (org.onosproject.uiref) featuring UI content
+ injection techniques added
++ GUI Archetypes (ui, uitab, uitopo) facilitating rapid development of
+ applications with custom UI content
+
+----
+#### Drake -- 1.3.0 -- August 2015
++ Authentication enabled by default (login screen; logout action)
++ _Settings_ and _Tunnels_ views added
++ Topology View:
+ + Traffic re-implemented as an "overlay"
+ + Overlay mechanism now programmable from ONOS apps
+ + highlighting / labeling topology links
+ + full control over summary panel content
+ + full control over details panel content
+
+----
+#### Cardinal -- 1.2.0 -- May 2015
++ Websocket mechanism promoted to be framework-wide; a shared resource
+ amongst the views
++ More tabular views added:
+ + Links
+ + Hosts
+ + Intents
+ + Applications
+ + Cluster Nodes
+ + Device Flows (hidden view)
+ + Device Ports (hidden view)
+ + Device Groups (hidden view)
++ Changes to the Topology View:
+ + links are now selectable.
+ + toolbar added (note, keystroke commands still available)
+ + node layer buttons moved from masthead to toolbar
+ + sprite layer added
+ + user selection choices persisted across sessions
+ + summary and detail panels adjust size to window height
++ Changes to the Device View:
+ + slide out details panel appears when a device is clicked on
++ Navigation Menu changes:
+ + glyphs next to links for navigation
+ + views organized into categories
++ Note that the legacy (Avocet) GUI has been deprecated, and that
+ the (Angular-based) GUI loads by default.
+
+----
+#### Blackbird -- 1.1.0 -- February 2015
++ GUI Framework migrated to use AngularJS
+ + View-agnostic features refactored as Angular Services
++ Topology View refactored to be an Angular module
+ + Topology source code broken out into multiple source files
+ + Port Highlighting on links added
++ Device View added
+ + Implemented as a simple table for now; one device per row,
+ sortable by column header clicks
++ Sample View added
+ + Skeletal example code
++ Light and Dark themes fully implemented
+ + Press the 'T' key to toggle theme
++ Beginnings of UIExtension mechanism implemented
+ + Over future releases, this will facilitate the ability of
+ Apps to inject their own content into the GUI
+
+> Note that the new (Angular-based) GUI currently co-exists with the
+> old (Avocet) GUI.
+> + By default, the Avocet GUI is launched;
+> the base URL `http://localhost:8181/onos/ui` is mapped to
+> `http://localhost:8181/onos/ui/legacy/index.html#topo`
+> + The new Angular-based GUI can be launched by manually adjusting
+> the URL to be: `http://localhost:8181/onos/ui/index.html#topo`,
+> (that is, remove "legacy/").
+
+----
+#### Avocet -- 1.0.0 -- November 2014
++ GUI implemented using a home-grown framework
++ Single view (_Topology View_) implemented, displaying network topology and
+ providing a certain level of interaction to show traffic & flow information
++ Although the `T` key-binding (toggle theme) is present, the "dark" theme
+ has not been implemented
+
+----
diff --git a/web/gui/doc/README.user.views.md b/web/gui/doc/README.user.views.md
new file mode 100644
index 0000000..ea09bab
--- /dev/null
+++ b/web/gui/doc/README.user.views.md
@@ -0,0 +1,148 @@
+ONOS Web UI - Views
+===================
+
+Documentation for the Web UI main views.
+
+> Note that each of these views should have their own wiki page.
+> For convenience, we are documenting them all here in a single document.
+
+[table]: https://wiki.onosproject.org/display/ONOS/GUI+Tabular+View
+[pic]: picture-icon.png
+
+# Platform Category Views
+
+
+Application View
+----------------
+
+### Overview
+The application view provides a top level listing of, and basic interaction
+with, all installed applications. The applications are displayed in
+[tabular form][table], where each row is a single application.
+
+![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.
+
+(to be completed)
+
+
+----
+
+Settings View
+-------------
+
+### Overview
+The settings view ... (to be completed)
+
+
+----
+
+Cluster Node View
+------------------
+
+### Overview
+The cluster node view ... (to be completed)
+
+
+----
+
+Packet Processors View
+----------------------
+
+### Overview
+The packet processors view ... (to be completed)
+
+----
+
+# Network Category Views
+
+Topology View
+-------------
+
+### Overview
+The topology view ... (to be completed)
+
+----
+
+Topology 2 View
+---------------
+
+### Overview
+The topology 2 view ... (to be completed)
+
+----
+
+Devices View
+------------
+
+### Overview
+The devices view ... (to be completed)
+
+----
+
+Flows View
+----------
+
+### Overview
+The flows view ... (to be completed)
+
+----
+
+Ports View
+----------
+
+### Overview
+The ports view ... (to be completed)
+
+----
+
+Groups View
+-----------
+
+### Overview
+The groups view ... (to be completed)
+
+----
+
+Meters View
+-----------
+
+### Overview
+The meters view ... (to be completed)
+
+----
+
+Links View
+----------
+
+### Overview
+The links view ... (to be completed)
+
+----
+
+Hosts View
+----------
+
+### Overview
+The hosts view ... (to be completed)
+
+----
+
+Intents View
+------------
+
+### Overview
+The intents view ... (to be completed)
+
+----
+
+Tunnels View
+------------
+
+### Overview
+The tunnels view ... (to be completed)
+
+----
\ No newline at end of file
diff --git a/web/gui/doc/picture-icon.png b/web/gui/doc/picture-icon.png
new file mode 100644
index 0000000..3b21d65
--- /dev/null
+++ b/web/gui/doc/picture-icon.png
Binary files differ
