The Horizon Module

Horizon ships with a single point of contact for hooking into your project if you aren’t developing your own Dashboard or Panel:

import horizon

From there you can access all the key methods you need.

Horizon

horizon.urls

The auto-generated URLconf for horizon. Usage:

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

horizon.register(dashboard)

Registers a Dashboard with Horizon.

horizon.unregister(dashboard)

Unregisters a Dashboard from Horizon.

horizon.get_absolute_url()

Returns the default URL for Horizon’s URLconf.

The default URL is determined by calling get_absolute_url() on the Dashboard instance returned by get_default_dashboard().

horizon.get_user_home(user)

Returns the default URL for a particular user.

This method can be used to customize where a user is sent when they log in, etc. By default it returns the value of get_absolute_url().

An alternative function can be supplied to customize this behavior by specifying a either a URL or a function which returns a URL via the "user_home" key in HORIZON_CONFIG. Each of these would be valid:

{"user_home": "/home",}  # A URL
{"user_home": "my_module.get_user_home",}  # Path to a function
{"user_home": lambda user: "/" + user.name,}  # A function
{"user_home": None,}  # Will always return the default dashboard

This can be useful if the default dashboard may not be accessible to all users. When user_home is missing from HORIZON_CONFIG, it will default to the settings.LOGIN_REDIRECT_URL value.

horizon.get_dashboard(dashboard)

Returns the specified Dashboard instance.

horizon.get_default_dashboard()

Returns the default Dashboard instance.

If "default_dashboard" is specified in HORIZON_CONFIG then that dashboard will be returned. If not, the first dashboard returned by get_dashboards() will be returned.

horizon.get_dashboards()

Returns an ordered tuple of Dashboard modules.

Orders dashboards according to the "dashboards" key in HORIZON_CONFIG or else returns all registered dashboards in alphabetical order.

Any remaining Dashboard classes registered with Horizon but not listed in HORIZON_CONFIG['dashboards'] will be appended to the end of the list alphabetically.

Dashboard

class horizon.Dashboard(*args, **kwargs)

A base class for defining Horizon dashboards.

All Horizon dashboards should extend from this base class. It provides the appropriate hooks for automatic discovery of Panel modules, automatically constructing URLconfs, and providing permission-based access control.

name

The name of the dashboard. This will be displayed in the auto-generated navigation and various other places. Default: ''.

slug

A unique “short name” for the dashboard. The slug is used as a component of the URL path for the dashboard. Default: ''.

panels

The panels attribute can be either a flat list containing the name of each panel module which should be loaded as part of this dashboard, or a list of PanelGroup classes which define groups of panels as in the following example:

class SystemPanels(horizon.PanelGroup):
    slug = "syspanel"
    name = _("System")
    panels = ('overview', 'instances', ...)

class Syspanel(horizon.Dashboard):
    panels = (SystemPanels,)

Automatically generated navigation will use the order of the modules in this attribute.

Default: [].

Warning

The values for this attribute should not correspond to the name attributes of the Panel classes. They should be the names of the Python modules in which the panel.py files live. This is used for the automatic loading and registration of Panel classes much like Django’s ModelAdmin machinery.

Panel modules must be listed in panels in order to be discovered by the automatic registration mechanism.

default_panel

The name of the panel which should be treated as the default panel for the dashboard, i.e. when you visit the root URL for this dashboard, that’s the panel that is displayed. Default: None.

permissions

A list of permission names, all of which a user must possess in order to access any panel registered with this dashboard. This attribute is combined cumulatively with any permissions required on individual Panel classes.

urls

Optional path to a URLconf of additional views for this dashboard which are not connected to specific panels. Default: None.

nav

The nav attribute can be either a boolean value or a callable which accepts a RequestContext object as a single argument to control whether or not this dashboard should appear in automatically-generated navigation. Default: True.

public

Boolean value to determine whether this dashboard can be viewed without being logged in. Defaults to False.

allowed(context)

Checks for role based access for this dashboard.

Checks for access to any panels in the dashboard and of the dashboard itself.

This method should be overridden to return the result of any policy checks required for the user to access this dashboard when more complex checks are required.

get_absolute_url()

Returns the default URL for this dashboard.

The default URL is defined as the URL pattern with name="index" in the URLconf for the Panel specified by default_panel.

get_panel(panel)

Returns the Panel instance registered with this dashboard.

get_panel_group(slug)

Returns the specified :class:~horizon.PanelGroup.

Returns None if not registered.

get_panels()

Returns the Panel instances registered with this dashboard in order.

Panel grouping information is not included.

classmethod register(panel)

Registers a Panel with this dashboard.

classmethod unregister(panel)

Unregisters a Panel from this dashboard.

Panel

class horizon.Panel

A base class for defining Horizon dashboard panels.

All Horizon dashboard panels should extend from this class. It provides the appropriate hooks for automatically constructing URLconfs, and providing permission-based access control.

name

The name of the panel. This will be displayed in the auto-generated navigation and various other places. Default: ''.

slug

A unique “short name” for the panel. The slug is used as a component of the URL path for the panel. Default: ''.

permissions

A list of permission names, all of which a user must possess in order to access any view associated with this panel. This attribute is combined cumulatively with any permissions required on the Dashboard class with which it is registered.

urls

Path to a URLconf of views for this panel using dotted Python notation. If no value is specified, a file called urls.py living in the same package as the panel.py file is used. Default: None.

nav

The nav attribute can be either a boolean value or a callable which accepts a RequestContext object as a single argument to control whether or not this panel should appear in automatically-generated navigation. Default: True.

index_url_name

The name argument for the URL pattern which corresponds to the index view for this Panel. This is the view that Panel.get_absolute_url() will attempt to reverse.

static can_register()

This optional static method can be used to specify conditions that need to be satisfied to load this panel. Unlike permissions and allowed this method is intended to handle settings based conditions rather than user based permission and policy checks. The return value is boolean. If the method returns True, then the panel will be registered and available to user (if permissions and allowed runtime checks are also satisfied). If the method returns False, then the panel will not be registered and will not be available via normal navigation or direct URL access.

get_absolute_url()

Returns the default URL for this panel.

The default URL is defined as the URL pattern with name="index" in the URLconf for this panel.

Panel Group

class horizon.PanelGroup(dashboard, slug=None, name=None, panels=None)

A container for a set of Panel classes.

When iterated, it will yield each of the Panel instances it contains.

slug

A unique string to identify this panel group. Required.

name

A user-friendly name which will be used as the group heading in places such as the navigation. Default: None.

panels

A list of panel module names which should be contained within this grouping.