diff options
Diffstat (limited to 'doc/configuration.rst')
| -rw-r--r-- | doc/configuration.rst | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/doc/configuration.rst b/doc/configuration.rst new file mode 100644 index 0000000..a4d8f0b --- /dev/null +++ b/doc/configuration.rst @@ -0,0 +1,241 @@ +============= +Configuration +============= + +The description below assumes that you have installed Tipboard correctly and +use a default configuration that is the starting point for steps presented +below (see section :ref:`installation`). + +Default configuration +--------------------- + +Tipboard launched after installation present a basic, empty layout – empty +tiles in 2 lines with 4 columns each. If you want to modify them, create a +"clean" config, where your changes will be introduced. Use the command:: + + (tb-env)$ tipboard create_project <name_of_project> + +It will create the ``~/.tipboard`` dir with the following content: + +* ``settings-local.yaml`` file that defines the layout of tiles on the + dashboard you are creating; + +* ``settings-local.py`` file in which you can overwrite default (global) + application settings; a description of options and their default values has + been presented in `this file + <https://github.com/allegro/tipboard/blob/develop/tipboard/settings.py>`_; + +* ``custom_tiles`` subdir to place your own tiles. + +.. note:: + + Before you send anything to your tiles, you have to get your API key + first, which is described in the :ref:`api_key` section. + +Launching Tipboard app +---------------------- + +After you have logged in to your machine, you may launch Tipboard with the +command:: + + (tb-env)$ tipboard runserver [<host>] [<port>] + +...where ``host`` and ``port`` parameters are optional (by default these are +``localhost`` and ``7272``; if you want the application to listen on all the +network interfaces, set ``host`` to ``0.0.0.0``). + +Customising tile layout +----------------------- + +As mentioned previously, the layout of tiles in a dashboard is defined by +``layout_config.yaml`` file. The file is in the `YAML <http://yaml.org>`_ +format, the description of which is beyond the scope of this manual. However, +it is worth indicating that YAML has certain format requirements – +**indentation should have a unified structure** (be a multiplication of a +number, e.g. 4), when creating indentations **spaces should not be mixed with +tabs**. + +Below you can find a list of options that can be saved in the file. +Indentations indicate the position of a given option in the configuration (e.g. +``details`` are superior to ``page_title``). + +:: + + details + page_tile + layout + row_X_of_Y + col_X_of_Y + tile_template + tile_id + tile + timeout + +where: + +.. describe:: details + + A section that contains additional configuration parameters; for the time + being it is only ‘page_title’; depending on his needs, the users add other + elements. + +.. describe:: page_tile + + A section that defines the title of a page to appear in the web browser + after entering the dashboard. + +.. describe:: layout + + A section that contains a proper configuration of the tile layout. + +.. describe:: row_X_of_Y + + Defines a row hight; a sum of Xs should equal Y. + +.. describe:: col_X_of_Y + + Similar to above but concerns a column width in a given row. + +.. describe:: tile_template + + The name of a tile template to be displayed (e.g. ``pie_chart``, + ``line_chart``, ``cumulative_flow``) + +.. describe:: tile_id + + A tile identifier in a HTML document and key identifier in Redis. + +.. describe:: title + + A title to be displayed in the upper part of the tile. + +.. describe:: timeout + + The length (in seconds) of data life (if data is not sent during this time, + you will be informed that the data is stalled). Since interval used by the + application to check for those timeouts is 5 seconds, it doesn't make sense + to set this value smaller than this. + + .. versionadded:: 1.3.0 + +The method of using ``row_X_of_Y`` and ``col_X_of_Y`` has been presented in the +examples below. If you want to see how it's done "from the kitchen", and you +have some basic knowledge of CSS styling, have a look `here +<https://github.com/allegro/tipboard/blob/develop/tipboard/static/css/layout.css>`_; + +.. note:: + + If you want to present a lot of data on your dashboard, consider dividing + all your tiles into two (or more) separate dashboards. Tiles offer a limited + capacity and if you "feed" them with too much data (e.g. long lines of + text), it is possible the dashboard will get broken. + +Setting tiles' rotation +~~~~~~~~~~~~~~~~~~~~~~~ + +One of the most useful functions is defining tiles to rotate. In a single +container (i.e. in one of the fields indicated by ``col_X_of_Y`` and +``row_X_of_Y``), you may define a few tiles to be displayed in this location as +items rotating at intervals defined in the configuration (similar to ads +rotating on bus/tram stops, so-called *citylights*). To achieve that: + +* add the ``flip-time-xx`` class to a container, where ``xx`` is rotation + interval in seconds; +* add tile to the container. + +The example below presents a container with two tiles (one of the ``empty`` type, +the other of the ``text`` type) to rotate every 2 seconds (``flip-time-2``). +The rotation will start with the ``empty`` type tile:: + + layout: + - row_1_of_2: + - col_1_of_4 flip-time-2: + - tile_template: empty + tile_id: empty + title: Empty Tile 2 + + - tile_template: text + tile_id: text + title: Empty Tile + +Sample layout +~~~~~~~~~~~~~ + +Let's assume we want to define a layout as on the scheme below (i.e. a division +into 2 equal rows, with the upper one divided into 4 columns, and the lower one +divided into 3 columns):: + + +-------+--------+--------+-------+ + | | | | | + | | | | | + | | | | | + | | | | | + +-------+--+-----+----+---+-------+ + | | | | + | | | | + | | | | + | | | | + +----------+----------+-----------+ + +...its corresponding configuration file should look as follows (for brevity, I +will present only the ``layout`` section, skipping the ``tile_template``, +``title_id``, etc.):: + + layout: + row_1_of_2: + col_1_of_4: + col_1_of_4: + col_1_of_4: + col_1_of_4: + row_1_of_2: + col_1_of_3: + col_1_of_3: + col_1_of_3: + +Multiple dashboards per application's instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 1.3.0 + +It is possible to define multiple dashboards per application's instance. In +order to achieve that, you just create separate layout config files (one per +every dashboard) - having done that, your dashboards will be available at:: + + http://localhost:7272/<name_of_layout_config_file> + +For example, having two layout config files ``my_first_dashboard.yaml`` and +``my_second_dashboard.yaml``, the corresponding dashboards can be accessed +via:: + + http://localhost:7272/my_first_dashboard + http://localhost:7272/my_second_dashboard + +.. note:: + + You have to strip the ``.yaml`` file extension when constructing your URLs. + +When it comes to feeding those dashboards with data, the future data location +is specified by tile IDs (unique within application instance). Therefore, there +is no need to specify different URLs for different dashboards - having tiles' +IDs, Tipboard will make sure that your data is delivered where it should be. + +Multiple rotating dashboards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.3.0 + +If you have defined several dashboards (as described above), you may want to +rotate (flip) them periodically. If you are unsure what that means, think of +extensions like Revolver (Chrome) or Tab Slideshow (Firefox). + +To achieve that, you need: + +* at least two dashboards (well, that's kind of obvious) +* in the file ``settings-local.py`` add the variable ``FLIPBOARD_INTERVAL = + <seconds>`` (e.g. ``FLIPBOARD_INTERVAL = 5``) + +The above solution will make all your dashboards rotate - if you want to limit +this behavior and rotate only certain dashboards, just add another parameter +``FLIPBOARD_SEQUENCE`` which is just a list of dashboard names that should be +taken into account, e.g.:: + + FLIPBOARD_SEQUENCE = ['my_first_dashboard', 'my_third_dashboard'] |