Documentation of webui

Change-Id: I7dae5e5caca4461e4cc9a8d72b521198bf460f8b

doc/source/index.rst

@@ -9,9 +9,10 @@ Table of Contents:
 
    readme
    project_architecture
-   tutorials/index.rst
+   tutorials/index
    webapi/index
-   administration/index.rst
+   webui/index
+   administration/index
 
 Indices and tables
 ==================

doc/source/webui/configuration/application_configuration.rst

@@ -0,0 +1,37 @@
+Application configuration
+=========================
+
+Application configuration is found in ``config.json``.
+
+.. code-block:: javascript
+
+   {
+      "env": "production",
+      "username": "myDevUsername",
+      "password": "myDevPassword",
+      "useStoredConfig": true
+      "surveilApiUrl": "surveil/v2",
+      "surveilAuthUrl": "surveil/v2/auth",
+      "refreshInterval": -1
+   }
+
+env (required) [production || development]
+    WebUI environment setting. Used to skip login page in development.
+
+username
+    username used when development ``env`` is specified.
+
+password
+    password used when development ``env`` is specified.
+
+useStoredConfig [true || false]
+    Whether to fetch stored layout configuration from Surveil or to use local.
+
+surveilApiUrl
+    Surveil API URL.
+
+surveilAuthUrl
+    Surveil Auth URL.
+
+refreshInterval [-1 || 1 .. infinity]
+    The refresh interval for the page in second where -1 will not refresh.

doc/source/webui/configuration/layout_configuration.rst

@@ -0,0 +1,35 @@
+Layout configuration
+--------------------
+The layout configuration is a ``JSON`` file containing the configuration of
+every page.
+
+For example, the following page would be available at: /#/view?view=myPageUrl.
+
+.. code-block:: javascript
+
+  {
+      "myPageUrl": {
+          "template": "page",
+          "components": [...]
+    }
+  }
+
+
+Template [ page || drupal || drupal_dashboard ]
+    This corresponds to the template that will be loaded by the webUI.
+
+Components
+    Components is an array of custom directives that define the layout of
+    the page. See :ref:`webui_custom_directives`.
+
+    The available custom directives are:
+
+    * :ref:`webui_directives_panels`
+    * :ref:`webui_directives_title`
+    * :ref:`webui_directives_table`
+    * :ref:`webui_directives_actionbar`
+
+    Alternatively, you can use any custom directives but layout of the WebUI
+    can look a little off.
+
+

doc/source/webui/custom_directives/actionbar.rst

@@ -0,0 +1,113 @@
+.. _webui_directives_actionbar:
+
+Action Bar
+==========
+
+The action bar is the bar containing components that act on data. These
+components can apply filters, recheck selected data, etc. on specified datasourceId.
+
+.. code-block:: javascript
+
+    {
+        "type": "actionbar",
+        "attributes": { "datasourceId": [ 0, 1 ] },
+        "components": [...]
+    }
+
+datasourceId (required, type: array of int)
+    The datasources on which the actionbar components will act.
+
+Components
+    The list of actionbar components.
+
+Components of an actionbar
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Acknowledge
+***********
+
+Adds a button that will open an acknowledgement form for all selected entries. (see table checkbox attribute)
+
+.. code-block:: javascript
+
+  {
+      "type": "actionbar-acknowledge",
+      "attributes": {}
+  }
+
+
+Downtime
+********
+
+Adds a button that will open a downtime form for all selected entries. (see table checkbox attribute)
+
+.. code-block:: javascript
+
+  {
+      "type": "actionbar-downtime",
+      "attributes": {}
+  }
+
+Filter
+******
+
+Creates a customizable, collapsed menu of filters
+
+.. code-block:: javascript
+
+    {
+        "type": "actionbar-filter",
+        "attributes": {
+        "filters": [
+                {
+                    "location": "componentsConfig",
+                    "content": "componentsConfigFilterKey"
+                }
+            ]
+        }
+    }
+
+location (required) [ inline || componentsConfig ]
+    Where the filter is loaded. Inline will directly load content as a filter.
+
+content (required)
+    Depend on the value of location.
+
+    +-------------------+------------------------------------------------+
+    | location          | content                                        |
+    +-------------------+------------------------------------------------+
+    | inline            | An inline filter                               |
+    +-------------------+------------------------------------------------+
+    | componentsConfig  | A filters key defined on componentsConfig.json |
+    +-------------------+------------------------------------------------+
+
+More
+****
+
+Unused for the moment
+
+Recheck
+*******
+
+Adds a recheck button that will launch a recheck command for all selected items (see table checkbox attribute)
+
+.. code-block:: javascript
+
+  {
+      "type": "actionbar-recheck",
+      "attributes": {}
+  }
+
+Search-filter
+*************
+
+Adds a search field inside actionbar that allows to search on data linked with the mother actionbar by datasourceId
+
+.. code-block:: javascript
+
+    {
+        "type": "actionbar-search-filter",
+        "attributes": {}
+    }
+
+

doc/source/webui/custom_directives/containers.rst

@@ -0,0 +1,111 @@
+.. _webui_directives_containers:
+
+Components of a container
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+info
+****
+Show all information pf a Surveil objects
+    .. code-block:: javascript
+
+      {
+          "type": "info",
+          "attributes": {
+              "inputSource": {
+                  "MyTileTitle": "myInputSource"
+          }
+      }
+
+MyTileTitle (required)
+    Tile of the tile
+myInputSource
+    key of the var fillParams inside container.js file .This key select the type of object in the tile
+
+host main
+*********
+Show inside a tile the address and the alias of a host
+    .. code-block:: javascript
+
+      {
+          "type": "host-main",
+          "attributes": {}
+      }
+
+host live
+*********
+Show inside a tile the host state, its output and it's state icon
+    .. code-block:: javascript
+
+      {
+          "type": "host-live",
+          "attributes": {}
+      }
+
+host load
+*********
+Show inside a tile the load metrics state, its output and it's state icon for an host
+    .. code-block:: javascript
+
+      {
+          "type": "host-load",
+          "attributes": {}
+      }
+
+host cpu
+********
+Show inside a tile the cpu metrics state, its output and it's state icon for an host
+    .. code-block:: javascript
+
+      {
+          "type": "host-cpu",
+          "attributes": {}
+      }
+
+host service list
+*****************
+Show inside a tile the service description, its acknowledge and its status for all service hosts
+    .. code-block:: javascript
+
+      {
+          "type": "host-services-list",
+          "attributes": {}
+      }
+
+service main
+************
+Show inside a tile the host attached to a service
+    .. code-block:: javascript
+
+      {
+          "type": "service-main",
+          "attributes": {}
+      }
+service live
+************
+Show inside a tile the service state, its output and it's state icon
+    .. code-block:: javascript
+
+      {
+          "type": "service-live",
+          "attributes": {}
+      }
+
+service info
+************
+Show inside a tile the service description, its acknowledge and its status
+    .. code-block:: javascript
+
+      {
+          "type": "service-info",
+          "attributes": {}
+      }
+
+service graphs
+**************
+Show a grafana graph for each service metric
+    .. code-block:: javascript
+
+      {
+          "type": "service-graphs",
+          "attributes": {}
+      }

doc/source/webui/custom_directives/custom_directives.rst

@@ -0,0 +1,50 @@
+.. _webui_custom_directives:
+
+Custom directives
+=================
+
+Custom directives are use in WebUI mainly to create complex page layout.
+
+All injectable directives in a layout configuration file are found in
+```app/components/custom_directive/``` and have two properties: Attributes and
+Components.
+
+Attributes
+    Attributes are used to configure the current directive.
+
+    For example, in the table directive, we use attributes to specify the shown datasourceId,
+    whether the table header will follow on scroll and whether there is a checkbox column.
+
+.. code-block:: javascript
+
+    {
+        "type": "table",
+        "attributes": {
+            "datasourceId": 0,
+            "headerFollow": true,
+            "inputSource": "configServices",
+        },
+        "components": [...]
+    }
+
+
+Components
+    Components is a list of directives to inject in the current directive.
+    For example, in the table directive, we use components to specify columns.
+
+.. code-block:: javascript
+
+    {
+        "type": "table",
+        "attributes": {...},
+        "components": [
+            {
+                "type": "cell-host-state",
+                "attributes": {...}
+            },
+            {
+                "type": "cell-service-state",
+                "attributes": {...}
+            }
+        ]
+    }

doc/source/webui/custom_directives/index.rst

@@ -0,0 +1,14 @@
+=================
+Custom directives
+=================
+
+
+
+.. toctree::
+   :maxdepth: 2
+
+   custom_directive.rst
+   actionbar.rst
+   containers.rst
+   panels.rst
+   table.rst

doc/source/webui/custom_directives/panels.rst

@@ -0,0 +1,63 @@
+.. _webui_directives_panels:
+
+Tabpanel and panel
+==================
+
+Panels are used to put components in a section.
+
+Tabpanels are a mechanism to show and hide panels according to a panelId.
+
+Panel
+*****
+
+.. code-block:: javascript
+
+  {
+      "type": "panel",
+      "attributes": {
+          "panelId": "mySuperPanel"
+      },
+      "components": [...]
+  }
+
+
+panelId
+    The id of the panel use by tabpanel.
+
+Components
+    The list of components of the panel.
+
+Tabpanel
+********
+
+.. code-block:: javascript
+
+  {
+     "type": "tabpanel",
+     "attributes": {
+         "navigation": {
+             "mySuperPanel": {
+                 "title": "My super panel",
+                 "provider": "Provider"
+             },
+             "anotherPanelId": {
+                 "title": "All my problems",
+                 "provider": "nbProblemsProvider"
+             }
+         }
+     },
+     "components": [...]
+  }
+
+navigation (required)
+    Contains keys of every panelId managed by the tabpanel.
+
+    title
+        The title of the tab.
+
+    provider
+        A provider to show a number next to the title.
+
+components
+    The list of panels managed by the tabpanel.
+

doc/source/webui/custom_directives/table.rst

@@ -0,0 +1,208 @@
+.. _webui_directives_table:
+
+Components of a table
+~~~~~~~~~~~~~~~~~~~~~
+
+Table components represent its columns. The collumns are named after the types of cell they will contain. For example: cell-single.
+
+Common column attributes:
+*************************
+
+All columns may define the following attributes.
+
+title (required):
+    Title of the column
+
+class
+    width of the column. Choose between xsmart, smart, medium and large
+
+url
+    Creates a link to another bansho view
+   .. code-block:: javascript
+
+       "url": {
+                "view": "service",
+                "params": [
+                    {
+                        "urlParam": "host_name",
+                        "entryKey": "host_name"
+                    },
+                    {
+                        "urlParam": "service_description",
+                        "entryKey": "service_description"
+                    }
+                ]
+            }
+
+
+
+   view (required):
+       the view to redirect to
+
+   params:
+       a list of objects that will be used to generate the URL
+
+   urlParam:
+       name of the url parameter
+
+   entryKey (required):
+       a key of the father inputSource’s table object. Its value is the value of the url param in the URL
+
+cell-single
+***********
+Column for a specific value of the father inputSource’s table object
+
+    .. code-block:: javascript
+
+        {
+            "type": "cell-single",
+            "attributes": {
+                "title": "Service Description",
+                "entryKey": "service_description",
+                "url": {
+                    "view": "service",
+                    "params": [
+                        {
+                            "urlParam": "host_name",
+                            "entryKey": "host_name"
+                        },
+                        {
+                            "urlParam": "service_description",
+                            "entryKey": "service_description"
+                        }
+                    ]
+                },
+                "class": "medium"
+        }
+
+Attributes:
+
+entryKey(required):
+    Key of the father inputSource’s table object who’s the value is print in the column title
+
+
+
+cell-other-fields
+*****************
+A column that groups values from the parent inputSource’s table object.
+
+    .. code-block:: javascript
+
+        {
+            "type": "cell-other-fields",
+            "attributes": {
+                "title": "Period",
+                "skipFields": [
+                    "contact_name",
+                    "email",
+                    "host_notification_commands",
+                    "service_notification_commands"
+                ],
+                "class": "large",
+
+            }
+        }
+
+Attributes::
+
+skipFields:
+    Fields to exclude from the cell
+
+
+cell-status-duration
+********************
+Only used inside a status service object table. Prints the time of the last service check
+    .. code-block:: javascript
+
+      {
+          "type": "cell-status-duration",
+          "attributes": {
+              "title": "Duration"
+          }
+      }
+
+
+
+cell-status-last-check
+**********************
+Only used inside a status host object table. Prints the date of the last host check
+    .. code-block:: javascript
+
+      {
+          "type": "cell-status-last-check",
+          "attributes": {
+              "title": "Last Check"
+          }
+      }
+
+cell-status-host-status
+***********************
+Only used inside a status host object table. Prints the host state with a specific icon for his curent state
+    .. code-block:: javascript
+
+      {
+          "type": "cell-status-host-status",
+          "attributes": {
+              "title": "Host Status"
+          }
+      }
+
+cell-status-host
+****************
+Only used inside a status host object table. Prints the hostName with a specific icon for his curent state
+    .. code-block:: javascript
+
+      {
+          "type": "cell-status-host",
+          "attributes": {
+              "title": "Hosts",
+              "url": {
+                  "view": "host",
+                  "params": [
+                      {
+                          "urlParam": "host_name",
+                          "entryKey": "host_host_name"
+                      }
+                  ]
+              }
+          }
+      }
+
+cell-status-service-check
+*************************
+Only used inside a status service table. Prints a service name, its current output and an icon for his state
+    .. code-block:: javascript
+
+      {
+          "type": "cell-status-service-check",
+          "attributes": {
+              "title": "Service Check",
+              "url": {
+                  "view": "service",
+                  "params": [
+                      {
+                          "urlParam": "host_name",
+                          "entryKey": "host_host_name"
+                      },
+                      {
+                          "urlParam": "service_description",
+                          "entryKey": "service_service_description"
+                      }
+                  ]
+              }
+          }
+      }
+
+
+cell-config-host-register
+*************************
+Only used inside a config host object table. Prints a validate icon if the host is register, prints an unvalidate icon if the host is not registered
+    .. code-block:: javascript
+
+      {
+          "type": "cell-config-host-register",
+          "attributes": {
+              "title": "Register",
+              "class": "xsmall"
+          }
+      }

doc/source/webui/custom_directives/title.rst

@@ -0,0 +1,27 @@
+.. _webui_directives_title:
+
+Title
+*****
+
+Title writes a header.
+
+.. code-block:: javascript
+
+    {
+        "type": "title",
+        "attributes": {
+            "title": "My big title",
+            "item": "host",
+            "provider": "nbHostProblems"
+        }
+    }
+
+title (required)
+    the title to write.
+
+item
+    A string to print inside the orange banner representing the type of items that is counted by the provider.
+
+provider
+    A provider returning a number to write inside the banner. See providers for key.
+

doc/source/webui/index.rst

@@ -0,0 +1,9 @@
+======
+Web UI
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   configuration/layout_configuration.rst
+   custom_directives/index.rst