Horizon Tabs and TabGroups

Horizon includes a set of reusable components for programmatically building tabbed interfaces with fancy features like dynamic AJAX loading and nearly effortless templating and styling.

Tab Groups

For any tabbed interface, your fundamental element is the tab group which contains all your tabs. This class provides a dead-simple API for building tab groups and encapsulates all the necessary logic behind the scenes.

class horizon.tabs.TabGroup(request, **kwargs)

A container class which knows how to manage and render Tab objects.

slug

The URL slug and pseudo-unique identifier for this tab group.

template_name

The name of the template which will be used to render this tab group. Default: "horizon/common/_tab_group.html"

sticky

Boolean to control whether the active tab state should be stored across requests for a given user. (State storage is all done client-side.)

show_single_tab

Boolean to control whether the tab bar is shown when the tab group has only one tab. Default: False

param_name

The name of the GET request parameter which will be used when requesting specific tab data. Default: tab.

classes

A list of CSS classes which should be displayed on this tab group.

attrs

A dictionary of HTML attributes which should be rendered into the markup for this tab group.

selected

Read-only property which is set to the instance of the currently-selected tab if there is one, otherwise None.

active

Read-only property which is set to the value of the current active tab. This may not be the same as the value of selected if no specific tab was requested via the GET parameter.

get_default_classes()

Returns a list of the default classes for the tab group. Defaults to ["nav", "nav-tabs", "ajax-tabs"].

get_id()

Returns the id for this tab group. Defaults to the value of the tab group’s horizon.tabs.Tab.slug.

get_selected_tab()

Returns the tab specific by the GET request parameter.

In the event that there is no GET request parameter, the value of the query parameter is invalid, or the tab is not allowed/enabled, the return value of this function is None.

get_tab(tab_name, allow_disabled=False)

Returns a specific tab from this tab group.

If the tab is not allowed or not enabled this method returns None.

If the tab is disabled but you wish to return it anyway, you can pass True to the allow_disabled argument.

get_tabs()

Returns a list of the allowed tabs for this tab group.

load_tab_data()

Preload all data that for the tabs that will be displayed.

render()

Renders the HTML output for this tab group.

tabs_not_available()

In the event that no tabs are either allowed or enabled, this method is the fallback handler. By default it’s a no-op, but it exists to make redirecting or raising exceptions possible for subclasses.

Tabs

The tab itself is the discrete unit for a tab group, representing one view of data.

class horizon.tabs.Tab(tab_group, request=None)

A reusable interface for constructing a tab within a TabGroup.

name

The display name for the tab which will be rendered as the text for the tab element in the HTML. Required.

slug

The URL slug and id attribute for the tab. This should be unique for a given tab group. Required.

preload

Determines whether the contents of the tab should be rendered into the page’s HTML when the tab group is rendered, or whether it should be loaded dynamically when the tab is selected. Default: True.

classes

A list of CSS classes which should be displayed on this tab.

attrs

A dictionary of HTML attributes which should be rendered into the markup for this tab.

load

Read-only access to determine whether or not this tab’s data should be loaded immediately.

permissions

A list of permission names which this tab requires in order to be displayed. Defaults to an empty list ([]).

allowed(request)

Determines whether or not the tab is displayed.

Tab instances can override this method to specify conditions under which this tab should not be shown at all by returning False.

The default behavior is to return True for all cases.

enabled(request)

Determines whether or not the tab should be accessible (e.g. be rendered into the HTML on load and respond to a click event).

If a tab returns False from enabled it will ignore the value of preload and only render the HTML of the tab after being clicked.

The default behavior is to return True for all cases.

get_context_data(request, **kwargs)

This method should return a dictionary of context data used to render the tab. Required.

get_default_classes()

Returns a list of the default classes for the tab. Defaults to and empty list ([]), however additional classes may be added depending on the state of the tab as follows:

If the tab is the active tab for the tab group, in which the class "active" will be added.

If the tab is not enabled, the classes the class "disabled" will be added.

get_id()

Returns the id for this tab. Defaults to "{{ tab_group.slug }}__{{ tab.slug }}".

get_template_name(request)

Returns the name of the template to be used for rendering this tab.

By default it returns the value of the template_name attribute on the Tab class.

is_active()

Method to access whether or not this tab is the active tab.

post(request, *args, **kwargs)

Handles POST data sent to a tab.

Tab instances can override this method to have tab-specific POST logic without polluting the TabView code.

The default behavior is to ignore POST data.

render()

Renders the tab to HTML using the get_context_data() method and the get_template_name() method.

If preload is False and force_load is not True, or either allowed() or enabled() returns False this method will return an empty string.

class horizon.tabs.TableTab(tab_group, request)

A Tab class which knows how to deal with DataTable classes rendered inside of it.

This distinct class is required due to the complexity involved in handling both dynamic tab loading, dynamic table updating and table actions all within one view.

table_classes

An iterable containing the DataTable classes which this tab will contain. Equivalent to the table_classes attribute on MultiTableView. For each table class you need to define a corresponding get_{{ table_name }}_data method as with MultiTableView.

get_context_data(request, **kwargs)

Adds a {{ table_name }}_table item to the context for each table in the table_classes attribute.

If only one table class is provided, a shortcut table context variable is also added containing the single table.

load_table_data()

Calls the get_{{ table_name }}_data methods for each table class and sets the data on the tables.

TabView

There is also a useful and simple generic class-based view for handling the display of a TabGroup class.

class horizon.tabs.TabView

A generic class-based view for displaying a horizon.tabs.TabGroup.

This view handles selecting specific tabs and deals with AJAX requests gracefully.

tab_group_class

The only required attribute for TabView. It should be a class which inherits from horizon.tabs.TabGroup.

get_context_data(**kwargs)

Adds the tab_group variable to the context data.

get_tabs(request, **kwargs)

Returns the initialized tab group for this view.

handle_tabbed_response(tab_group, context)

Sends back an AJAX-appropriate response for the tab group if required, otherwise renders the response as normal.

class horizon.tabs.TabbedTableView(*args, **kwargs)

get_tables()

A no-op on this class. Tables are handled at the tab level.

handle_table(table_dict)

For the given dict containing a DataTable and a TableTab instance, it loads the table data for that tab and calls the table’s maybe_handle() method. The return value will be the result of maybe_handle.

load_tabs()

Loads the tab group, and compiles the table instances for each table attached to any horizon.tabs.TableTab instances on the tab group. This step is necessary before processing any tab or table actions.