• Get Review Board
  • What's New
  • Products
  • Review Board Code review, image review, and document review
  • Documentation
  • Release Notes
  • Power Pack Enterprise integrations, reports, and enhanced document review
  • Try for 60 Days
  • Purchase
  • RBCommons Review Board as a Service, hosted by us
  • Pricing
  • RBTools Command line tools and Python API for Review Board
  • Documentation
  • Release Notes
  • Review Bot Automated code review, connecting tools you already use
  • Documentation
  • Release Notes
  • RB Gateway Manage Git and Mercurial repositories in your network
  • Documentation
  • Release Notes
  • Learn and Explore
  • What is Code Review?
  • Documentation
  • Frequently Asked Questions
  • Support Options
  • Third-Party Integrations
  • Demo
  • Review Board RBTools Power Pack Review Bot Djblets RB Gateway
    1. Djblets 2.x
    2. Version 5.x
    3. Version 4.x
    4. Version 3.x
    5. Version 2.x
    6. Version 2.0
    7. Version 1.0
    8. Version 0.9
    9. Djblets Documentation
    10. Module and Class References
    11. djblets.datagrid.grids
  • Home
  • Guides
  • Avatar Services Guides
  • Writing Avatar Services
  • Extension Guides
  • Writing Extensions
  • Testing Extensions
  • Feature Checks Guides
  • Introduction to Feature Checks
  • Writing Features
  • Writing Feature Checkers
  • Testing with Feature Checks
  • Integration Guides
  • Supporting Integrations
  • Writing Integrations
  • Privacy Compliance Guides
  • Getting and Checking Consent
  • Working with Personally Identifiable Information
  • Service Integrations
  • reCAPTCHA Guides
  • Using reCAPTCHA
  • Registries Guides
  • Writing Registries
  • Web API Guides
  • Writing Web API Resources
  • Adding OAuth2 Support
  • Module and Class References
  • djblets
  • djblets.deprecation
  • djblets.auth.forms
  • djblets.auth.ratelimit
  • djblets.auth.signals
  • djblets.auth.util
  • djblets.auth.views
  • djblets.avatars.errors
  • djblets.avatars.forms
  • djblets.avatars.registry
  • djblets.avatars.services
  • djblets.avatars.services.base
  • djblets.avatars.services.fallback
  • djblets.avatars.services.file_upload
  • djblets.avatars.services.gravatar
  • djblets.avatars.services.url
  • djblets.avatars.settings
  • djblets.cache.backend
  • djblets.cache.backend_compat
  • djblets.cache.context_processors
  • djblets.cache.errors
  • djblets.cache.forwarding_backend
  • djblets.cache.serials
  • djblets.cache.synchronizer
  • djblets.conditions
  • djblets.conditions.choices
  • djblets.conditions.conditions
  • djblets.conditions.errors
  • djblets.conditions.operators
  • djblets.conditions.values
  • djblets.configforms.forms
  • djblets.configforms.mixins
  • djblets.configforms.pages
  • djblets.configforms.registry
  • djblets.configforms.views
  • djblets.datagrid.grids
  • djblets.datagrid.templatetags.datagrid
  • djblets.db.backends.mysql.base
  • djblets.db.fields
  • djblets.db.fields.base64_field
  • djblets.db.fields.counter_field
  • djblets.db.fields.json_field
  • djblets.db.fields.modification_timestamp_field
  • djblets.db.fields.relation_counter_field
  • djblets.db.managers
  • djblets.db.query
  • djblets.db.validators
  • djblets.extensions.admin
  • djblets.extensions.errors
  • djblets.extensions.extension
  • djblets.extensions.forms
  • djblets.extensions.hooks
  • djblets.extensions.loaders
  • djblets.extensions.manager
  • djblets.extensions.middleware
  • djblets.extensions.models
  • djblets.extensions.packaging
  • djblets.extensions.resources
  • djblets.extensions.settings
  • djblets.extensions.signals
  • djblets.extensions.staticfiles
  • djblets.extensions.testing
  • djblets.extensions.testing.testcases
  • djblets.extensions.urls
  • djblets.extensions.views
  • djblets.extensions.templatetags.djblets_extensions
  • djblets.features
  • djblets.features.checkers
  • djblets.features.decorators
  • djblets.features.errors
  • djblets.features.feature
  • djblets.features.level
  • djblets.features.registry
  • djblets.features.testing
  • djblets.features.templatetags.features
  • djblets.feedview.views
  • djblets.feedview.templatetags.feedtags
  • djblets.forms.fields
  • djblets.forms.fieldsets
  • djblets.forms.forms
  • djblets.forms.forms.key_value_form
  • djblets.forms.widgets
  • djblets.gravatars
  • djblets.gravatars.templatetags.gravatars
  • djblets.http.middleware
  • djblets.integrations.errors
  • djblets.integrations.forms
  • djblets.integrations.hooks
  • djblets.integrations.integration
  • djblets.integrations.manager
  • djblets.integrations.mixins
  • djblets.integrations.models
  • djblets.integrations.templatetags.integrations
  • djblets.integrations.urls
  • djblets.integrations.views
  • djblets.log
  • djblets.log.middleware
  • djblets.log.siteconfig
  • djblets.log.urls
  • djblets.log.views
  • djblets.mail.dmarc
  • djblets.mail.message
  • djblets.mail.testing
  • djblets.mail.utils
  • djblets.markdown
  • djblets.markdown.extensions.escape_html
  • djblets.markdown.extensions.wysiwyg
  • djblets.markdown.extensions.wysiwyg_email
  • djblets.pipeline.compilers.es6.ES6Compiler
  • djblets.pipeline.compilers.less.LessCompiler
  • djblets.pipeline.settings
  • djblets.privacy.consent
  • djblets.privacy.consent.base
  • djblets.privacy.consent.common
  • djblets.privacy.consent.errors
  • djblets.privacy.consent.forms
  • djblets.privacy.consent.hooks
  • djblets.privacy.consent.registry
  • djblets.privacy.consent.tracker
  • djblets.privacy.models
  • djblets.privacy.pii
  • djblets.privacy.templatetags.djblets_privacy
  • djblets.recaptcha.mixins
  • djblets.recaptcha.siteconfig
  • djblets.recaptcha.templatetags.djblets_recaptcha
  • djblets.recaptcha.widgets
  • djblets.registries
  • djblets.registries.errors
  • djblets.registries.importer
  • djblets.registries.mixins
  • djblets.registries.registry
  • djblets.registries.signals
  • djblets.siteconfig
  • djblets.siteconfig.admin
  • djblets.siteconfig.context_processors
  • djblets.siteconfig.django_settings
  • djblets.siteconfig.forms
  • djblets.siteconfig.managers
  • djblets.siteconfig.middleware
  • djblets.siteconfig.models
  • djblets.siteconfig.signals
  • djblets.siteconfig.views
  • djblets.template.caches
  • djblets.template.context
  • djblets.template.loaders.conditional_cached
  • djblets.template.loaders.namespaced_app_dirs
  • djblets.testing.decorators
  • djblets.testing.testcases
  • djblets.testing.testrunners
  • djblets.urls.context_processors
  • djblets.urls.decorators
  • djblets.urls.patterns
  • djblets.urls.resolvers
  • djblets.urls.root
  • djblets.urls.staticfiles
  • djblets.util.compat.django.core.cache
  • djblets.util.compat.django.core.files.locks
  • djblets.util.compat.django.core.management.base
  • djblets.util.compat.django.core.validators
  • djblets.util.compat.django.shortcuts
  • djblets.util.compat.django.template.context
  • djblets.util.compat.django.template.loader
  • djblets.util.compat.django.utils.functional
  • djblets.util.compat.python.past
  • djblets.util.contextmanagers
  • djblets.util.dates
  • djblets.util.decorators
  • djblets.util.filesystem
  • djblets.util.html
  • djblets.util.http
  • djblets.util.humanize
  • djblets.util.json_utils
  • djblets.util.properties
  • djblets.util.serializers
  • djblets.util.templatetags.djblets_deco
  • djblets.util.templatetags.djblets_email
  • djblets.util.templatetags.djblets_forms
  • djblets.util.templatetags.djblets_images
  • djblets.util.templatetags.djblets_js
  • djblets.util.templatetags.djblets_utils
  • djblets.util.views
  • djblets.views.generic.base
  • djblets.views.generic.etag
  • djblets.webapi.auth
  • djblets.webapi.auth.backends
  • djblets.webapi.auth.backends.api_tokens
  • djblets.webapi.auth.backends.base
  • djblets.webapi.auth.backends.basic
  • djblets.webapi.auth.backends.oauth2_tokens
  • djblets.webapi.auth.views
  • djblets.webapi.decorators
  • djblets.webapi.encoders
  • djblets.webapi.errors
  • djblets.webapi.fields
  • djblets.webapi.managers
  • djblets.webapi.models
  • djblets.webapi.oauth2_scopes
  • djblets.webapi.resources
  • djblets.webapi.resources.base
  • djblets.webapi.resources.group
  • djblets.webapi.resources.registry
  • djblets.webapi.resources.root
  • djblets.webapi.resources.user
  • djblets.webapi.resources.mixins.api_tokens
  • djblets.webapi.resources.mixins.forms
  • djblets.webapi.resources.mixins.oauth2_tokens
  • djblets.webapi.resources.mixins.queries
  • djblets.webapi.responses
  • djblets.webapi.signals
  • djblets.webapi.testing
  • djblets.webapi.testing.decorators
  • djblets.webapi.testing.testcases
  • General Index
  • Python Module Index
  • Release Notes
  • This documentation covers Djblets 2.x. You can select a version above or view the latest documentation.

    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.

    exception SiteProfileNotAvailable[source]¶
    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='', shrink=False, expand=False, sortable=False, default_sort_dir=0, link=False, link_func=None, link_css_class=None, cell_clickable=False, css_class='')[source]¶

    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>. An image_url cannot also be defined.

    cell_template¶

    The path to a template. If this is not None, this will override the default cell_template for the DataGrid the column is in.

    Type

    unicode

    SORT_DESCENDING = 0[source]¶

    Descending sort order for columns.

    SORT_ASCENDING = 1[source]¶

    Ascending sort order for columns.

    cell_template_obj()[source]¶

    Return the cell template, if it exists.

    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

    unicode

    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

    unicode

    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]¶

    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.

    property 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.

    property header[source]¶

    The header of the column.

    This is a convenience used by templates to call Column.get_header() with the current state.

    class CheckboxColumn(checkbox_name='select', shrink=True, show_checkbox_header=True, detailed_label='Select Rows', *args, **kwargs)[source]¶

    A column that renders a checkbox.

    The is_selectable() and is_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 the checkbox_name parameter of its constructor.

    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

    unicode

    is_selectable(state, obj)[source]¶

    Returns whether an object can be selected.

    If this returns False, no checkbox will be rendered for this item.

    is_selected(state, obj)[source]¶

    Returns whether an object has been selected.

    If this returns True, the checkbox will be checked.

    class DateTimeColumn(label, format=None, sortable=True, timezone=<UTC>, *args, **kwargs)[source]¶

    A column that renders a date or time.

    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

    unicode

    class DateTimeSinceColumn(label, sortable=True, timezone=<UTC>, *args, **kwargs)[source]¶

    A column that renders a date or time relative to now.

    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

    unicode

    class DataGrid(request, queryset=None, title='', extra_context={}, optimize_sorts=True, model=None)[source]¶

    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¶

    The title of the grid.

    Type

    unicode

    profile_sort_field¶

    The variable name in the user profile where the sort order can be loaded and saved.

    Type

    unicode

    profile_columns_field¶

    The variable name in the user profile where the columns list can be loaded and saved.

    Type

    unicode

    paginate_by¶

    The number of items to show on each page of the grid. The default is 50.

    Type

    int

    paginate_orphans¶

    If this number of objects or fewer are on the last page, it will be rolled into the previous page. The default is 3.

    Type

    int

    page¶

    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.

    Type

    int

    listview_template¶

    The template used to render the list view. The default is datagrid/listview.html.

    Type

    unicode

    column_header_template¶

    The template used to render each column header. The default is datagrid/column_header.html.

    Type

    unicode

    cell_template¶

    The template used to render a cell of data. The default is datagrid/cell.html.

    Type

    unicode

    optimize_sorts¶

    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 is True.

    Type

    bool

    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

    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.

    property all_columns[source]¶

    All columns in the datagrid, sorted by label.

    property model[source]¶

    The model representing the objects shown in the grid.

    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, or False 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
    • template_name (unicode) – The template for the page.

    • extra_context (dict) – Extra context variables to use in the template.

    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.

    static link_to_object(state, obj, value)[source]¶

    Return a URL for the given object.

    This defaults to calling obj.get_absolute_url.

    Returns

    The URL for the object.

    Return type

    unicode

    static link_to_value(state, obj, value)[source]¶

    Return a URL for the given value.

    This defaults to calling value.get_absolute_url.

    Returns

    The URL for the value.

    Return type

    unicode

    class AlphanumericDataGrid(request, queryset, sortable_column, extra_regex='^[0-9].*', *args, **kwargs)[source]¶

    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.

    Keep up with the latest Review Board releases, security updates, and helpful information.

    About
    News
    Demo
    RBCommons Hosting
    Integrations
    Happy Users
    Support Options
    Documentation
    FAQ
    User Manual
    RBTools
    Administration Guide
    Power Pack
    Release Notes
    Downloads
    Review Board
    RBTools
    Djblets
    Power Pack
    Package Store
    PGP Signatures
    Contributing
    Bug Tracker
    Submit Patches
    Development Setup
    Wiki
    Follow Us
    Mailing Lists
    Reddit
    Twitter
    Mastodon
    Facebook
    YouTube

    Copyright © 2006-2025 Beanbag, Inc. All rights reserved.

    Terms of Service — Privacy Policy — AI Ethics Policy — Branding

    On this page

    • [Top]