horizon/docs/source/quickstart.rst

Horizon Quickstart

Horizon's Structure

This project is a bit different from other Openstack projects in that it is composed of two distinct components:

• horizon
• openstack-dashboard

The horizon directory holds the generic libraries and components that can be used in any Django project. In testing, this component is set up with buildout (see ref/run_tests), and any dependencies that need to be added to the horizon/buildout.cfg file.

The openstack-dashboard directory contains a reference Django project that uses horizon and is built with a virtualenv. If dependencies are added that openstack-dashboard requires they should be added to openstack- dashboard/tools/pip-requires.

Project

INSTALLED_APPS

At the project level you add Horizon and any desired dashboards to your settings.INSTALLED_APPS:

INSTALLED_APPS = (
    'django',
    ...
    'horizon',
    'horizon.dash',
    'horizon.syspanel',
)

URLs

Then you add a single line to your project's urls.py:

url(r'', include(horizon.urls)),

Those urls are automatically constructed based on the registered Horizon apps. If a different URL structure is desired it can be constructed by hand.

Templates

Pre-built template tags generate navigation. In your nav.html template you might have the following:

{% load horizon %}

<div class='nav'>
    {% horizon_main_nav %}
</div>

And in your sidebar.html you might have:

{% load horizon %}

<div class='sidebar'>
    {% horizon_dashboard_nav %}
</div>

These template tags are aware of the current "active" dashboard and panel via template context variables and will render accordingly.

Application

Structure

An application would have the following structure (we'll use syspanel as an example):

syspanel/
|---__init__.py
|---dashboard.py <-----Registers the app with Horizon and sets dashboard properties
|---templates/
|---templatetags/
|---overview/
|---services/
|---images/
    |---__init__.py
    |---panel.py <-----Registers the panel in the app and defines panel properties
    |---urls.py
    |---views.py
    |---forms.py
    |---tests.py
    |---api.py <-------Optional additional API methods for non-core services
    |---templates/
    ...
...

Dashboard Classes

Inside of dashboard.py you would have a class definition and the registration process:

import horizon


class Syspanel(horizon.Dashboard):
    name = "Syspanel" # Appears in navigation
    slug = 'syspanel' # Appears in url
    panels = ('overview', 'services', 'instances', 'flavors', 'images',
              'tenants', 'users', 'quotas',)
    default_panel = 'overview'
    roles = ('admin',) # Provides RBAC at the dashboard-level
    ...


horizon.register(Syspanel)

Panel Classes

To connect a ~horizon.Panel with a ~horizon.Dashboard class you register it in a panels.py file like so:

import horizon

from horizon.dashboard.syspanel import dashboard


class Images(horizon.Panel):
    name = "Images"
    slug = 'images'
    roles = ('admin', 'my_other_role',) # Fine-grained RBAC per-panel


# You could also register your panel with another application's dashboard
dashboard.Syspanel.register(Images)

By default a ~horizon.Panel class looks for a urls.py file in the same directory as panel.py to include in the rollup of url patterns from panels to dashboards to Horizon, resulting in a wholly extensible, configurable URL structure.