x/surveil
Code Issues Proposed changes

Documentation of webui

Browse Source 
Change-Id: I7dae5e5caca4461e4cc9a8d72b521198bf460f8b
This commit is contained in:
flavien peyre 2015-08-19 14:57:25 -04:00 committed by aviau
parent 864752876f
commit 81f8950e07
11 changed files with 670 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/source/index.rst
View File

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

37
doc/source/webui/configuration/application_configuration.rst Normal file
View File

@ -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.

35
doc/source/webui/configuration/layout_configuration.rst Normal file
View File

@ -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.

113
doc/source/webui/custom_directives/actionbar.rst Normal file
View File

@ -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": {}
}

111
doc/source/webui/custom_directives/containers.rst Normal file
View File

@ -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": {}
}

50
doc/source/webui/custom_directives/custom_directives.rst Normal file
View File

@ -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": {...}
}
]
}

14
doc/source/webui/custom_directives/index.rst Normal file
View File

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

63
doc/source/webui/custom_directives/panels.rst Normal file
View File

@ -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.

208
doc/source/webui/custom_directives/table.rst Normal file
View File

@ -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"
}
}

27
doc/source/webui/custom_directives/title.rst Normal file
View File

@ -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.

9
doc/source/webui/index.rst Normal file
View File

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