Component Attributes#

All components accept a number of attributes which dictate how it looks and functions.

value / defer#

All components use either a value or defer argument to define the data for rendering. This determines when the data is fetched and where from

value

A value or callable to fetch on initial load.

defer

A value or callable which is fetched after initial load via a HTMX trigger.

In the below example, when the page first loads only the components one and two are displayed. HTMX triggers are then used to fetch three and four after initial load since they are defined with defer.

from dashboards.component import Text
from dashboards.dashboard import Dashboard

def fetch_something(request, *args, **kwargs)
    return f"Hello {request.user.username}"

class ExampleDashboard(Dashboard)
    one = Text(value="One")
    two = Text(value=fetch_something)
    three = Text(defer=fetch_something)
    four = Text(
        defer=lambda **kwargs: "Deferred text",
    )

In the above example one returns the text One but two`, three & four use a function fetch_something as the value. This can be any callable that accepts kwargs.

Callable#

Whenever a callable is used it is passed a number of kwargs.

request
A Django HttpRequest
dashboard
The dashboards.Dashboard instance the component belongs to
filters
A dict containing any GET/POST params sent during the request

These can be used to control what is rendered

def get_welcome_message(self, **kwargs):
    request = kwargs["request"]
    if request.user.is_authenticated:
        return f"hello {request.user} welcome to the site."
    else:
        return "You are not logged in"

FOO attributes#

Instead of setting a value or defer on a component, you can define a function on the Dashboard class instead.

You do this by declaring a get_<FOO>_<method> function where FOO is the name of the component and method is either value or defer depending on when you want it rendered

from dashboards.component import Text
from dashboards.dashboard import Dashboard

class ExampleDashboard(Dashboard):
    value_from_method = Text()
    defer_from_method = Text()

    def get_value_from_method_value(self, **kwargs):
        return "I am defined as a FOO value."

    def get_defer_from_method_defer(self, **kwargs):
        request = kwargs["request"]
        return f"hello {request.user} I am defined as a FOO defer."

This will assign the value “I am defined as a FOO value.” to the value_from_method component and “hello <user> I am defined as a FOO defer.” to the defer_from_method component.

Other Attributes#

The following attributes are all optional but can be used to alter how a component functions.

defer_url#

By default a component renders the ComponentView during a defer call from HTMX. This is a builtin django-dashboards view which renders just that component to the screen. If required, you can create your own version of this. You do this by creating your own view and providing the url as a callable to defer_url. A use case for this is Async components .

...
custom_response = Text(
    defer_url=lambda reverse_args: reverse("custom-component-view", args=reverse_args)
)

defer_loading_template_name#

html template to show while the defer function is being called via ajax.

template_name#

While each components has its own default template, it’s possible to provide your own custom template on a component by component basis.

one = Text(template_name="custom/template/one.html")

cta#

A CTA component with a url. Using this creates an a href tag around the component div, allowing you to link to another page/dashboard from within a dashboard.

from django.urls import reverse_lazy
from dashboards.component import CTA

...
link = Text(
    value="Find out more!",
    cta=CTA(
        href=reverse_lazy(
            "dashboards:demo_demodashboard"
        ),
    ),
)

This expects there to be a DemoDashboard setup in the demo app.

This example generates the following html:

<a href="/dashboard/demo/demodashboard/">
    <div id="component-link-inner" class="dashboard-component-inner fade-in">
        Find out more!
    </div>
</a>

icon#

A HTML string to render as an icon.

one = Stat(value="Rendered on load", icon='<i class="fa-up"></i>')

icon is provided to the template and can be rendered using component.icon.

Currently only Stat utilizes icon but you can easily create your own custom templates to display them if required.

// customer_component_template.html
...
{% if component.icon %}
    <div>{{ component.icon|safe }}</div>
{% endif %}
...

// dashboard.py
...
one = Text(template_name="customer_component_template.html", icon='<i class="fa-up"></i>')

css_classes#

Override css classes used in the template. Components have default values but these can be changed to match your css file.

Default Values

Form
“form”: “form”

“table”: “table form-table”

“button”: “btn”
Table / BasicTable
“table”: “table”
Stat
“stat”: “stat”

“icon”: “stat__icon”

“heading”: “stat__heading”

“text”: “stat__text”

welcome_text = Stat(value=..., css_classes={"stat": "my-stat", "heading": "big-font"})

generates

<div id="welcome_text">
  <table id="welcome_text_table" class="table table-striped nowrap my-table" style="width:100%"></table>
</div>

grid_css_classes#

The css class applied to the component for its grid layout. This is separate to any css_classes defined. This should match the css grid layout setup in your project. See layout docs.

welcome_text = Text(value="Hello", grid_css_classes="span-6")

poll_rate#

Only works for components using defer. Frequency that the component is automatically reloaded (in seconds) using HTMX. Defaults to never

...
def poll_rate(*kwargs):
    // api call to get latest data and return
    return data

poll_data = Chart(defer=get_data, poll_rate=10)

This example reloads the poll_data component every 10 seconds, replacing the current component with the new value.

A use case for this is when doing Server Sent Events .

trigger_on#

Only works for components using defer. Populates the HTMX value for hx-trigger which specifies what triggers a AJAX reload of that component. See https://htmx.org/attributes/hx-trigger/ for more details.

welcome_text = Text(value="Hello", trigger_on="click")

This reloads the welcome_text component everytime a user clicks on it.

dependents#

List of components to refresh after the current component has reloaded.

...

def get_chart_data(self, **kwargs):
    filter = kwargs["filter"]

    if "start_date" in filter and filter["start_date"]:
        qs = SalesData.objects.filter(date__gt=filter["start_date"])

    data = convert_qs_table(qs)  // fake function
    return data

class ExampleDashboard(Dashboard):
    form_example = Form(
        form=FilterForm,
        method="get",
        dependents=["sales_data"],
    )
    sales_data = Table(defer=get_chart_data)

When FilterForm is submitted the sales_data component will automatically be reloaded. See the Form component docs for how forms function.

This example expects the FilterForm class to have a start_date field which provides a date. We use this value to filter down the SalesData queryset before it is passed to the component to be rendered.