• 
      

    Add documentation on creating dashboard and datagrid columns.

    Review Request #15063 — Created May 15, 2026 and submitted

    Information

    Review Board
    release-8.x

    Reviewers

    This introduces a guide for extension authors on how to create columns
    for the Dashboard and other datagrids. This walks through creating a
    simple column and layering on custom rendering, linking, sorting, and
    queryset augmentation, along with registration.

    The DashboardColumnsHook and DataGridColumnsHook pages have been
    modernized to reflect how columns are created now, and to refer to the
    new guide for details on column creation.

    Built the docs. Checked for any obvious build or link errors.

    Summary ID
    Add documentation on creating dashboard and datagrid columns.
    This introduces a guide for extension authors on how to create columns for the Dashboard and other datagrids. This walks through creating a simple column and layering on custom rendering, linking, sorting, and queryset augmentation, along with registration. The `DashboardColumnsHook` and `DataGridColumnsHook` pages have been modernized to reflect how columns are created now, and to refer to the new guide for details on column creation.
    d80c1f7f9b3f7c0e76333008e7cd33b67e839441
    Description From Last Updated

    typo: in order they want -> in the order they want

    david david

    We need from django.utils.html import format_html in this too.

    david david

    This defaults to the same thing as label, so it's silly to show both being defined the same. We should …

    david david

    This is generic, so probably shouldn't be referring specifically to review requests. Maybe "The name of the attribute on the …

    david david

    Typo: extra ) at the end.

    david david

    Need to add from django.utils.translation import gettext_lazy as _ to these.

    david david

    This feels a little awkward. How about: Always use :py:func:~django.utils.html.format_html to build HTML with user-provided values, or :py:func:~django.utils.html.escape to convert …

    david david

    Typo: teh -> the

    david david

    escape should be imported from django.utils.html

    david david

    Need to add from django.utils.translation import gettext_lazy as _ to these.

    david david

    Seems like something got left off here. Could probably just do "To make the column's content a link:"

    david david

    Typo: define -> Define

    david david

    link_func is only used if self.link = True, so we need to add that attr to the class vars here.

    david david

    typos: ReviewRequestsDataGrid -> ReviewRequestDataGrid GroupsDataGrid -> GroupDataGrid

    david david

    ReviewRequestsDataGrid -> ReviewRequestDataGrid

    david david

    This should end in a period, not a colon.

    david david

    This should probably include the unused **kwargs argument for future expansion.

    david david

    There's a missing ) in here.

    david david

    We should either include render_data and augment_queryset_for_data implementations in here, or at least link back to that section. As-is this …

    david david

    One of these has a trailing period and one doesn't

    david david

    staticmethod is a builtin class, not a function. Can you check that this links correctly? If not, I suspect :py:class …

    david david

    Lets include the detailed_label here too, like we did in the other MilestoneColumn example.

    maubin maubin

    This should be grouped with the other django imports.

    david david
    david
    1. 
        
    2. Show all issues

      typo: in order they want -> in the order they want

    3. Show all issues

      We need from django.utils.html import format_html in this too.

    4. Show all issues

      This defaults to the same thing as label, so it's silly to show both being defined the same. We should probably either drop it from here or make it different.

    5. Show all issues

      This is generic, so probably shouldn't be referring specifically to review requests. Maybe "The name of the attribute on the object being displayed in the row"?

    6. Show all issues

      Typo: extra ) at the end.

    7. Show all issues

      Need to add from django.utils.translation import gettext_lazy as _ to these.

    8. docs/manual/extending/extensions/dashboard-columns.rst (Diff revision 1)
       
       
       
       
       
       
       
       
      Show all issues

      This feels a little awkward. How about:

      Always use :py:func:~django.utils.html.format_html to build HTML with user-provided values, or :py:func:~django.utils.html.escape to convert plain text to safe HTML. If the content already comes from a trusted source, you can wrap it with :py:func:~django.utils.safestring.mark_safe

    9. Show all issues

      Typo: teh -> the

    10. Show all issues

      escape should be imported from django.utils.html

    11. Show all issues

      Need to add from django.utils.translation import gettext_lazy as _ to these.

      1. Just removing those. In reality, extensions can't really add to our localization files anyway.

    12. Show all issues

      Seems like something got left off here. Could probably just do "To make the column's content a link:"

      1. This whole thing was one sentence at first, hence that and the lowercase "define". Reworking this.

    13. Show all issues

      Typo: define -> Define

    14. Show all issues

      link_func is only used if self.link = True, so we need to add that attr to the class vars here.

    15. Show all issues

      typos:
      ReviewRequestsDataGrid -> ReviewRequestDataGrid
      GroupsDataGrid -> GroupDataGrid

    16. Show all issues

      ReviewRequestsDataGrid -> ReviewRequestDataGrid

    17. 
        
    chipx86
    maubin
    1. 
        
    2. Show all issues

      Lets include the detailed_label here too, like we did in the other MilestoneColumn example.

    3. 
        
    david
    1. 
        
    2. Show all issues

      This should end in a period, not a colon.

    3. docs/manual/extending/extensions/dashboard-columns.rst (Diff revision 2)
       
       
       
       
       
       
       
       
      Show all issues

      This should probably include the unused **kwargs argument for future expansion.

    4. Show all issues

      There's a missing ) in here.

    5. docs/manual/extending/extensions/dashboard-columns.rst (Diff revision 2)
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
      Show all issues

      We should either include render_data and augment_queryset_for_data implementations in here, or at least link back to that section. As-is this example will create an N+1 query situation.

      1. Just going to add a comment so the focus on this code isn't lost.

    6. Show all issues

      One of these has a trailing period and one doesn't

    7. Show all issues

      staticmethod is a builtin class, not a function. Can you check that this links correctly? If not, I suspect :py:class would work.

    8. Show all issues

      This should be grouped with the other django imports.

    9. 
        
    chipx86
    david
    1. Ship It!
    2. 
        
    chipx86
    Review request changed
    Status:
    Completed
    Change Summary:
    Pushed to release-8.x (3c9fa12)