From 81f8950e07817aa92fc8fc6aa8362f296bb1d236 Mon Sep 17 00:00:00 2001 From: flavien peyre Date: Wed, 19 Aug 2015 14:57:25 -0400 Subject: [PATCH] Documentation of webui Change-Id: I7dae5e5caca4461e4cc9a8d72b521198bf460f8b --- doc/source/index.rst | 5 +- .../application_configuration.rst | 37 ++++ .../configuration/layout_configuration.rst | 35 +++ .../webui/custom_directives/actionbar.rst | 113 ++++++++++ .../webui/custom_directives/containers.rst | 111 ++++++++++ .../custom_directives/custom_directives.rst | 50 +++++ doc/source/webui/custom_directives/index.rst | 14 ++ doc/source/webui/custom_directives/panels.rst | 63 ++++++ doc/source/webui/custom_directives/table.rst | 208 ++++++++++++++++++ doc/source/webui/custom_directives/title.rst | 27 +++ doc/source/webui/index.rst | 9 + 11 files changed, 670 insertions(+), 2 deletions(-) create mode 100644 doc/source/webui/configuration/application_configuration.rst create mode 100644 doc/source/webui/configuration/layout_configuration.rst create mode 100644 doc/source/webui/custom_directives/actionbar.rst create mode 100644 doc/source/webui/custom_directives/containers.rst create mode 100644 doc/source/webui/custom_directives/custom_directives.rst create mode 100644 doc/source/webui/custom_directives/index.rst create mode 100644 doc/source/webui/custom_directives/panels.rst create mode 100644 doc/source/webui/custom_directives/table.rst create mode 100644 doc/source/webui/custom_directives/title.rst create mode 100644 doc/source/webui/index.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 3e2b4c2..2822dcf 100644 --- a/doc/source/index.rst +++ b/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 ================== diff --git a/doc/source/webui/configuration/application_configuration.rst b/doc/source/webui/configuration/application_configuration.rst new file mode 100644 index 0000000..48943d2 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/source/webui/configuration/layout_configuration.rst b/doc/source/webui/configuration/layout_configuration.rst new file mode 100644 index 0000000..41eefab --- /dev/null +++ b/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. + + diff --git a/doc/source/webui/custom_directives/actionbar.rst b/doc/source/webui/custom_directives/actionbar.rst new file mode 100644 index 0000000..c3cc014 --- /dev/null +++ b/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": {} + } + + diff --git a/doc/source/webui/custom_directives/containers.rst b/doc/source/webui/custom_directives/containers.rst new file mode 100644 index 0000000..ad67d0a --- /dev/null +++ b/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": {} + } diff --git a/doc/source/webui/custom_directives/custom_directives.rst b/doc/source/webui/custom_directives/custom_directives.rst new file mode 100644 index 0000000..18d1b7f --- /dev/null +++ b/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": {...} + } + ] + } diff --git a/doc/source/webui/custom_directives/index.rst b/doc/source/webui/custom_directives/index.rst new file mode 100644 index 0000000..0804c84 --- /dev/null +++ b/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 diff --git a/doc/source/webui/custom_directives/panels.rst b/doc/source/webui/custom_directives/panels.rst new file mode 100644 index 0000000..a2a7d99 --- /dev/null +++ b/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. + diff --git a/doc/source/webui/custom_directives/table.rst b/doc/source/webui/custom_directives/table.rst new file mode 100644 index 0000000..0802591 --- /dev/null +++ b/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" + } + } diff --git a/doc/source/webui/custom_directives/title.rst b/doc/source/webui/custom_directives/title.rst new file mode 100644 index 0000000..1c18d03 --- /dev/null +++ b/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. + diff --git a/doc/source/webui/index.rst b/doc/source/webui/index.rst new file mode 100644 index 0000000..06f4eb7 --- /dev/null +++ b/doc/source/webui/index.rst @@ -0,0 +1,9 @@ +====== +Web UI +====== + +.. toctree:: + :maxdepth: 2 + + configuration/layout_configuration.rst + custom_directives/index.rst