aboutsummaryrefslogtreecommitdiffstats
path: root/doc/configuration.rst
diff options
context:
space:
mode:
authorTomasz Mieszkowski <tomasz.mieszkowski@ext.allegro.pl>2014-08-28 08:54:15 +0200
committerTomasz Mieszkowski <tomasz.mieszkowski@ext.allegro.pl>2014-08-28 08:54:15 +0200
commit60c073a6ed451cf91d9877a3305407756b9ffdce (patch)
tree955542ec282745e31d78d1b2b9515d8cebe67e78 /doc/configuration.rst
downloadtipboard-60c073a6ed451cf91d9877a3305407756b9ffdce.tar.gz
tipboard-60c073a6ed451cf91d9877a3305407756b9ffdce.tar.bz2
tipboard-60c073a6ed451cf91d9877a3305407756b9ffdce.zip
Tipboard got open-sourced!1.4.0
Diffstat (limited to 'doc/configuration.rst')
-rw-r--r--doc/configuration.rst241
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']