djblets.datagrid.grids¶
Components for creating customizable datagrids from database data.
Datagrids are used to display a table-based view of data from a database, complete with pagination, batch selection, sorting, and flexible column rendering.
Datagrids have one or more Column
subclasses associated, which will
render the data. The datagrid may display a subset of the rendered columns,
and users can choose which of those columns they want displayed, and in which
order.
There are two main types of datagrids:
DataGrid
is the base class for a datagrid, and will display the data with standard numerical page-based pagination.AlphanumericDataGrid
is similar, but uses a more specific paginator that allows the user to paginate by the first letter/number/symbol of the data in a given field. This is useful for lists of users, for example.
All datagrids are meant to be subclassed.
-
class
Column
(label=None, id=None, detailed_label=None, detailed_label_html=None, field_name=None, db_field=None, image_url=None, image_class=None, image_width=None, image_height=None, image_alt=u”, shrink=False, expand=False, sortable=False, default_sort_dir=0, link=False, link_func=None, cell_clickable=False, css_class=u”)[source]¶ Bases:
object
A column in a datagrid.
The column is the primary component of the datagrid. It is used to display not only the column header but the HTML for the cell as well.
Columns can be tied to database fields and can be used for sorting. Not all columns have to allow for this, though.
Columns can have an image, text, or both in the column header. The contents of the cells can be instructed to link to the object on the row or the data in the cell.
If a Column defines an
image_class
, then it will be assumed that the class represents an icon, perhaps as part of a spritesheet, and will display it in a<div>
. Animage_url
cannot also be defined.-
cell_template
¶ unicode – The path to a template. If this is not None, this will override the default cell_template for the DataGrid the column is in.
-
__init__
(label=None, id=None, detailed_label=None, detailed_label_html=None, field_name=None, db_field=None, image_url=None, image_class=None, image_width=None, image_height=None, image_alt=u”, shrink=False, expand=False, sortable=False, default_sort_dir=0, link=False, link_func=None, cell_clickable=False, css_class=u”)[source]¶ Initialize the column.
When initializing a column as part of a
DataGrid
subclass, a number of options can be provided.Parameters: - id (unicode) – The unique ID of the column on the datagrid.
- label (unicode) – The label to show in the column header.
- detailed_label (unicode) – A detailed label to display in the column customization
menu. Defaults to
label
. - detailed_label_html (unicode) – A detailed label in HTML form to display in the column
customization menu. This takes precedence over
detailed_label
. - field_name (unicode) – The name of the field on the model containing the data to render.
- db_field (unicode) – The name of the database field containing the field used
for sorting. Defaults to
field_name
. - image_url (unicode) – The URL to the image used in the header and navigation menu.
This cannot be used with
image_class
. - image_class (unicode) – The CSS class of a spritesheet icon to use in the header
and navigation menu. This cannot be used with
image_url
. - image_width (int) – The width of the image.
- image_height (int) – The height of the image.
- image_alt (unicode) – The alt text for the image.
- shrink (bool) – If
True
, the column’s width will be calculated to its minimum size. - expand (bool) – If
True
, the column’s width will be calculated to its maximum size. If there are other expanded columns, they’ll share the available width equally. - sortable (bool) – If
True
, the column can be sorted. This requires adb_field
that allows for sorting. - default_sort_dir (int) – The default sorting direction when the user activates sorting.
Either
SORT_DESCENDING
orSORT_ASCENDING
. - link (bool) – If
True
, the contents will be linked to the URL returned bylink_func
orDataGrid.link_to_object()
. - link_func (callable) – Optional function that returns a URL for the link.
- cell_clickable (bool) – If
True
, clicking anywhere on the cell will navigate to the URL defined, if any. - css_class (unicode) – The CSS class or classes to define on the cell.
-
setup_state
(state)[source]¶ Set up any state that may be needed for the column.
This is called once per column per datagrid instance.
By default, no additional state is set up. Subclasses can override this to set any variables they may need.
Parameters: state (StatefulColumn) – The state for the DataGrid instance.
-
get_sort_field
(state)[source]¶ Return the field used for sorting this column.
By default, this uses the provided db_field.
Parameters: state (StatefulColumn) – The state for the DataGrid instance. Returns: The field on the model used for sorting. Defaults to db_field
.Return type: unicode
-
get_toggle_url
(state)[source]¶ Return a URL to toggle this column’s visibility.
Parameters: state (StatefulColumn) – The state for the DataGrid instance. Returns: The URL used to toggle column visibility. Return type: unicode
-
get_header
(state)[source]¶ Render the header for the column.
The column header will include the current sort indicator, if it belongs in the sort list. It will also be made clickable in order to modify the sort order appropriately, if sortable.
Parameters: state (StatefulColumn) – The state for the DataGrid instance. Returns: The HTML for the header. Return type: unicode
-
collect_objects
(state, object_list)[source]¶ Iterate through the objects and builds a cache of data to display.
This optimizes the fetching of data in the grid by grabbing all the IDs of related objects that will be queried for rendering, loading them all at once, and populating the cache.
Parameters: - state (StatefulColumn) – The state for the DataGrid instance.
- object_list (list) – The list of objects being rendered on the datagrid.
-
render_cell
(state, obj, render_context)[source]¶ Render the table cell containing column data.
Parameters: - state (StatefulColumn) – The state for the DataGrid instance.
- obj (object) – The object being rendered for this row.
- render_context (Context) – The shared context used for cell renders.
Returns: The rendered cell as HTML.
Return type:
-
render_data
(state, obj)[source]¶ Render the column data within the cell.
Parameters: - state (StatefulColumn) – The state for the DataGrid instance.
- obj (object) – The object being rendered for this row.
Returns: The rendered data as HTML.
Return type:
-
augment_queryset
(state, queryset)[source]¶ Augment a queryset with new queries.
Subclasses can override this to extend the queryset to provide additional information, usually using queryset.extra(). This must return a queryset based on the original queryset.
This should not restrict the query in any way, or the datagrid may not operate properly. It must only add additional data to the queryset.
Parameters: - state (StatefulColumn) – The state for the DataGrid instance.
- queryset (QuerySet) – The queryset to augment.
Returns: The resulting QuerySet.
Return type: QuerySet
-
-
class
StatefulColumn
(datagrid, column)[source]¶ Bases:
object
A stateful wrapper for a Column instance.
Columns must be stateless, as they are shared across all instances of a particular DataGrid. However, some state is needed for columns, such as their widths or active status.
StatefulColumn wraps a
Column
instance and provides state storage, and also provides a convenient way to call methods on a Column and pass the state.Attributes owned by the Column can be accessed directly through the StatefulColumn.
Likewise, any functions owned by the Column can be accessed as well. The function will be invoked with this StatefulColumn as the first parameter passed.
-
toggle_url
[source]¶ The visibility toggle URL of the column.
This is a convenience used by templates to call
Column.get_toggle_url()
with the current state.
-
header
[source]¶ The header of the column.
This is a convenience used by templates to call
Column.get_header()
with the current state.
-
__getattr__
(name)[source]¶ Returns an attribute from the parent Column.
This is called when accessing an attribute not found directly on StatefulColumn. The attribute will be fetched from the Column (if it exists there).
In the case of accessing a function, a wrapper will be returned that will automatically pass this StatefulColumn instance as the first parameter.
Parameters: name (unicode) – The attribute to fetch from the column. Returns: The attribute value from the column.
-
-
class
CheckboxColumn
(checkbox_name=u’select’, shrink=True, show_checkbox_header=True, detailed_label=_(u’Select Rows’), *args, **kwargs)[source]¶ Bases:
djblets.datagrid.grids.Column
A column that renders a checkbox.
The
is_selectable()
andis_selected()
functions can be overridden to control whether a checkbox is displayed in a row and whether that checkbox is initially checked.The checkboxes have a
data-object-id
attribute that contains the ID of the object that row represents. This allows the JavaScript code to determine which rows have been checked, and operate on that accordingly.The checkboxes also have a
data-checkbox-name
attribute that contains the value passed in to thecheckbox_name
parameter of its constructor.-
__init__
(checkbox_name=u’select’, shrink=True, show_checkbox_header=True, detailed_label=_(u’Select Rows’), *args, **kwargs)[source]¶ Initialize the column.
Parameters:
-
-
class
DateTimeColumn
(label, format=None, sortable=True, timezone=<UTC>, *args, **kwargs)[source]¶ Bases:
djblets.datagrid.grids.Column
A column that renders a date or time.
-
class
DateTimeSinceColumn
(label, sortable=True, timezone=<UTC>, *args, **kwargs)[source]¶ Bases:
djblets.datagrid.grids.Column
A column that renders a date or time relative to now.
-
class
DataGrid
(request, queryset=None, title=u”, extra_context={}, optimize_sorts=True, model=None)[source]¶ Bases:
object
A paginated table of data based on queries from a database.
A datagriad represents a list of objects, sorted and organized by columns. The sort order and column lists can be customized. allowing users to view this data however they prefer.
This is meant to be subclassed for specific uses. The subclasses are responsible for defining one or more column types. It can also set one or more of the following optional variables:
-
title
¶ unicode – The title of the grid.
-
profile_sort_field
¶ unicode – The variable name in the user profile where the sort order can be loaded and saved.
-
profile_columns_field
¶ unicode – The variable name in the user profile where the columns list can be loaded and saved.
-
paginate_by
¶ int – The number of items to show on each page of the grid. The default is 50.
-
paginate_orphans
¶ int – If this number of objects or fewer are on the last page, it will be rolled into the previous page. The default is 3.
-
page
¶ int – The page to display. If this is not specified, the
?page=
variable passed in the URL will be used, or 1 if that is not specified.
-
listview_template
¶ unicode – The template used to render the list view. The default is
datagrid/listview.html
.
-
column_header_template
¶ unicode – The template used to render each column header. The default is
datagrid/column_header.html
.
-
cell_template
¶ unicode – The template used to render a cell of data. The default is
datagrid/cell.html
.
-
optimize_sorts
¶ bool – Whether or not to optimize queries when using multiple sorts. This can offer a speed improvement, but may need to be turned off for more advanced querysets (such as when using
extra()
). The default isTrue
.
-
classmethod
add_column
(column)[source]¶ Add a new column for this datagrid.
This can be used to add columns to a DataGrid subclass after the subclass has already been defined.
The column added must have a unique ID already set.
Parameters: column (Column) – The column to add.
-
classmethod
remove_column
(column)[source]¶ Remove a column from this datagrid.
This can be used to remove columns previously added through
add_column()
.Parameters: column (Column) – The column to remove.
-
classmethod
get_column
(column_id)[source]¶ Return the column with the given ID.
If not found, this will return None.
Parameters: column_id (int) – The index of the column to return. Returns: The resulting column at the given index. Return type: Column
-
classmethod
get_columns
()[source]¶ Return the list of registered columns for this datagrid.
Returns: The list of columns registered on this datagrid. Return type: list of Column
-
__init__
(request, queryset=None, title=u”, extra_context={}, optimize_sorts=True, model=None)[source]¶ Initialize the datagrid.
Parameters: - request (HttpRequest) – The HTTP request from the client.
- queryset (QuerySet) – A QuerySet returning the objects to render in the grid.
- title (unicode) – The displayed title of the datagrid.
- extra_context (dict) – Extra context variables to render on the datagrid template.
- optimize_sorts (bool) – If
True
, sorting will be optimized, reducing the complexity of the queries. This is the default. - model (Model) – The model for the objects in the datagrid. Defaults to the
model associated with
queryset
.
-
cell_template_obj
[source]¶ The rendered template used for cells on this datagrid.
This will only be generated once, and reused for all cells.
-
column_header_template_obj
[source]¶ The rendered template used for column headers on this datagrid.
This will only be generated once, and reused for all headers.
-
get_stateful_column
(column)[source]¶ Return a StatefulColumn for the given Column instance.
If one has already been created, it will be returned.
Parameters: column (Column) – The column associated with the stateful column. Returns: The column state associated with the column. Return type: StatefulColumn
-
load_state
(render_context=None)[source]¶ Load the state of the datagrid.
This will retrieve the user-specified or previously stored sorting order and columns list, as well as any state a subclass may need.
Parameters: render_context (Context) – Common template variable context to render on the datagrid.
-
get_user_profile
()[source]¶ Return the object, if any, to use for the user profile state.
Returns: The object, if any, used to store and retrieve persistent profile state for the datagrid.
-
load_extra_state
(profile)[source]¶ Load any extra state needed for this grid.
This is used by subclasses that may have additional data to load and save.
Parameters: profile (Model) – The profile model instance to load from, if any. Returns: Subclasses must return True
if any profile-stored state has changed, orFalse
otherwise.Return type: bool
-
precompute_objects
(render_context=None)[source]¶ Pre-compute all objects used to render the datagrid.
This builds the queryset and stores the list of objects for use in rendering the datagrid. It takes into consideration sorting, the current page, and augmented queries from columns.
Parameters: render_context (Context) – The common template variable context to render on the datagrid, provided in the constructor.
-
post_process_queryset
(queryset)[source]¶ Add column-specific data to the queryset.
Individual columns can define additional joins and extra info to add on to the queryset. This handles adding all of those.
Parameters: queryset (django.db.models.query.QuerySet) – The queryset to augment. Returns: The resulting augmented QuerySet. Return type: django.db.models.query.QuerySet
-
render_listview
(render_context=None)[source]¶ Render the standard list view of the grid.
This can be called from templates.
Parameters: render_context (Context) – The common template variable context to render on the datagrid, provided in the constructor. Returns: The rendered HTML for the datagrid page. Return type: unicode
-
render_listview_to_response
(request=None, render_context=None)[source]¶ Render the listview to a response.
The rendered result will not be cached by the browser.
Parameters: - request (HttpRequest) – The HTTP request from the client.
- render_context (Context) – The common template variable context to render on the datagrid, provided in the constructor.
Returns: The HTTP response to send to the client.
Return type: HttpResponse
-
render_to_response
(template_name, extra_context={})[source]¶ Render the entire datagrid page to a response.
This will render the entire page, given the specified template, with the datagrid as a part of it. This is the primary function a view will be using to render the page.
Parameters: Returns: The HTTP response to send to the client.
Return type: HttpResponse
-
render_paginator
(adjacent_pages=3)[source]¶ Render the paginator for the datagrid.
This can be called from templates.
Parameters: adjacent_pages (int) – The number of adjacent page numbers to show in the paginator. Returns: The paginator as HTML. Return type: unicode
-
build_paginator
(queryset)[source]¶ Build the paginator for the datagrid.
This can be overridden to use a special paginator or to perform any kind of processing before passing on the query.
Parameters: queryset (object) – A queryset-compatible object. Returns: A populated paginator object.
-
-
class
AlphanumericDataGrid
(request, queryset, sortable_column, extra_regex=u’^[0-9].*’, *args, **kwargs)[source]¶ Bases:
djblets.datagrid.grids.DataGrid
A DataGrid subclass for an alphanumerically-paginated datagrid.
This is useful for datasets that need to be queried alphanumerically, according to the starting character of their
sortable
column.-
__init__
(request, queryset, sortable_column, extra_regex=u’^[0-9].*’, *args, **kwargs)[source]¶ Initialize the datagrid.
Parameters: - request (HttpRequest) – The HTTP request from the client.
- queryset (QuerySet) – A QuerySet returning the objects to render in the grid.
- sortable_column (unicode) – The model field used for the alphanumeric prefixes.
- extra_regex (unicode) – A regex used for matching the beginning of entries in
sortable_column
.
-