API reference

Views

View support classes and functions for htmx-views.

class htmx_views.views.HTMXFormMixin(*args, **kwargs)

Bases: HTMXProcessMixin

Provide additional methods to adapt FormView and friends for htmx requests as well.

form_invalid(form)

Look for HTMX form valid handlers.

If request.htmx is not set, then return the parent class form_invalid, otherwise look for an element specific htmx_form_invalid_<name> method, or failing that just an htmx_form_invalid meothd. Fnally, give up and return the parent form_invalid.

Notes:

htmx_inform_valid* methods must not call super().form_valid - otherwise an infinite recursion happens!

form_valid(form)

Look for HTMX form valid handlers.

If request.htmx is not set, then return the parent class form_valid, otherwise look for an element specific htmx_form_valid_<name> method, or failing that just an htmx_form_valid meothd. Fnally, give up and return the parent form_valid.

Notes:

htmx_form_valid* methods must not call super().form_valid - otherwise an infinite recursion happens!

class htmx_views.views.HTMXProcessMixin(*args, **kwargs)

Bases: object

Provide versions of the htmx_`<http_verb>` methods that will delegate to trigger specific methods.

Each http verb DELETE,GET,PATCH,POST,PUT’s htmx_<verb> method will look at the request.htmx attriobute to see if htmx_<verb>_<trigger_name>, htmx_<verb>_<trigger>, htmx_<verb>_<target> is a method and then pass on to the first matching method. If no match is foumd, the http_method_not_allowed method is used instead.

get_context_data(**kwargs)

Get context data being aware of htmx views.

get_context_data_function(**kwargs)

Return the first callable element-specific context handler.

get_context_object_name(object_list)

Get context object name being aware of htmx elements.

If the get_context_name_<element> method needs to call usper, it should set a keyword argument, _default to be True to avoid a recursive loop.

get_template_names()

Look for htmx specific templates.

htmx_delete(request, *args, **kwargs)

Delegate HTMX DELETE requests.

Looks for the element that is related to the request by inspecting the request.htmx trigger_name, trigger and target attributes in turn. If no matching htmx_delete_<name> methods are found, return the method_not_allowed result instrad.

htmx_elements()

Iterate over possible htmx element sources.

htmx_get(request, *args, **kwargs)

Delegate HTMX GET requests.

Looks for the element that is related to the request by inspecting the request.htmx trigger_name, trigger and target attributes in turn. If no matching htmx_get_<name> methods are found, return the method_not_allowed result instrad.

htmx_patch(request, *args, **kwargs)

Delegate HTMX PATCH requests.

Looks for the element that is related to the request by inspecting the request.htmx trigger_name, trigger and target attributes in turn. If no matching htmx_patch_<name> methods are found, return the method_not_allowed result instrad.

htmx_post(request, *args, **kwargs)

Delegate HTMX POST requests.

Looks for the element that is related to the request by inspecting the request.htmx trigger_name, trigger and target attributes in turn. If no matching htmx_post_<name> methods are found, return the method_not_allowed result instrad.

htmx_put(request, *args, **kwargs)

Delegate HTMX PUT requests.

Looks for the element that is related to the request by inspecting the request.htmx trigger_name, trigger and target attributes in turn. If no matching htmx_put_<name> methods are found, return the method_not_allowed result instrad.

htmx_views.views.dispatch(self, request, *args, **kwargs)

Dispatch method that becomes htmx aware.

If the =`htmx` request attribute is set (by django-htmx) and the method name is in either self.http_method_names or self.htmx_method_names then try to locate the method htmx_<http_verb> method and call that or else fall back to the regular <http_verb> method.

If an approrpiate method can’t be located, call self.http_method_bot_allowed for error handline.

If the htmx request attrobute is not set or is False, then fall back to the original dispatch.

htmx_views.views.temp_attr(obj, attr, value)

Temporarily set the value of an attribute and restore it afterwards.

Linked-select endpoint

Linked-select endpoint backed by the optional django-ajax-selects package.

class htmx_views.linked_selects.LinkedSelectEndpointView(**kwargs)

Bases: TemplateView

Return linked-select options from an authorised lookup.

dispatch(request, *args, **kwargs)

Resolve the lookup and enforce its authorisation policy.

get_context_data(**kwargs)

Add the option list to the context.

Widgets

Create an htmx backed linked select widget.

class htmx_views.widgets.HTMXSelectWidget(lookup_channel, parent=None, *args, **kwargs)

Bases: Select

Override SelectWidget to allow the options to be updated on a linked change.

This uses the machinery of django-ajax-select lookups to derive the list of options, but uses htmx for the transfer mechanism.

get_context(name, value, attrs)

Customise the context.

Bootstrap template tags

Provide Bootstrap 5 template components and migration helpers.

The tags in this module generate button, modal, accordion, and lazy-pagination markup with related accessibility attributes. They do not load Bootstrap or Bootstrap Icons assets; the consuming application remains responsible for including the required CSS and JavaScript.

htmx_views.templatetags.htmx_views_bootstrap.bootstrap_button(content, icon=None, icon_position='start', icon_extra_classes='', icon_title=None, aria_label=None, button_class='btn-primary', size='', **kwargs)

Render a django-bootstrap5 button with optional legacy icon support.

Args:

content (str):

Visible button content.

Keyword Parameters:

icon (str):

Optional Bootstrap Icon or legacy Glyphicon name.

icon_position (str):

Place the icon at "start" or "end".

icon_extra_classes (str):

Additional icon CSS classes.

icon_title (str):

Optional accessible label for the icon.

aria_label (str):

Optional accessible label for the button, particularly useful for icon-only buttons.

button_class (str):

Bootstrap button variant. Legacy btn-default becomes btn-secondary.

size (str):

Bootstrap 5 size. Legacy size names are translated.

**kwargs:

Remaining arguments accepted by django-bootstrap5’s button renderer, including button_type, href, name, and arbitrary HTML attributes.

Returns:

(SafeString):

Bootstrap 5 button or link markup.

Raises:

TemplateSyntaxError:

If icon_position is invalid.

ImportError:

If the optional django-bootstrap5 dependency is unavailable.

Examples:

Port a Bootstrap 3 button containing a Glyphicon:

{% bootstrap_button "Save" button_type="submit" icon="floppy-disk" %}

htmx_views.templatetags.htmx_views_bootstrap.bootstrap_icon(icon, extra_classes='', title=None)

Render a Bootstrap Icon with Bootstrap 3-compatible arguments.

Args:

icon (str):

Bootstrap Icon or legacy Glyphicon name.

Keyword Parameters:

extra_classes (str):

Additional CSS classes for the icon.

title (str):

Accessible icon label and HTML title. Icons without a title are marked as decorative.

Returns:

(SafeString):

Bootstrap Icons font markup.

Raises:

TemplateSyntaxError:

If the icon name cannot form a safe CSS class.

Examples:

Render a labelled icon:

{% bootstrap_icon "info-sign" title="Information" %}

htmx_views.templatetags.htmx_views_bootstrap.bootstrap_lazy_page(url, page=None, when=True, method='get', element='div', element_id='next_batch', include=None, trigger='intersect once', target=None, swap='outerHTML', page_parameter='page', colspan=1, label='Loading...', extra_class='')

Render a Bootstrap loading sentinel for the next HTMX page.

Args:

url (str):

URL used to load the next batch.

Keyword Parameters:

page (Page):

Optional Django paginator page. The sentinel is omitted on the last page and the next page number is added to url.

when (bool):

Additional condition controlling whether the sentinel is rendered.

method (str):

HTMX request method, either "get" or "post".

element (str):

Outer element: "div", "li", or "tr".

element_id (str):

ID of the loading sentinel and default HTMX target.

include (str):

Optional hx-include selector, such as "form".

trigger (str):

HTMX trigger. Defaults to "intersect once".

target (str):

HTMX target. Defaults to the sentinel’s own ID.

swap (str):

HTMX swap mode. Defaults to "outerHTML".

page_parameter (str):

Query-string parameter used for the page number.

colspan (int):

Number of columns spanned when element="tr".

label (str):

Visually hidden accessible loading label.

extra_class (str):

Additional class or classes for the outer element.

Returns:

(SafeString):

Loading-sentinel markup, or an empty string when there is no next page.

Raises:

TemplateSyntaxError:

If an option would produce invalid markup.

Examples:

Render the next row for a paginated django-tables2 table:

{% bootstrap_lazy_page url=path page=page method="post" element="tr" colspan=columns %}

htmx_views.templatetags.htmx_views_bootstrap.bootstrap_modal_target(modal_id='modal', target_id='dialog', title_id='dialog-title', size='lg', centred=True, scrollable=False)

Render the empty target into which an HTMX modal response is swapped.

Keyword Parameters:

modal_id (str):

ID of the outer Bootstrap modal.

target_id (str):

ID of the HTMX swap target inside the modal.

title_id (str):

ID used by the modal content heading.

size (str):

Bootstrap modal size: "sm", "lg", or "xl".

centred (bool):

Whether to centre the dialog vertically.

scrollable (bool):

Whether the modal body should be independently scrollable.

Returns:

(SafeString):

Bootstrap modal target markup.

Raises:

TemplateSyntaxError:

If an ID or modal size is invalid.

Examples:

Load the tag library and create a large modal target:

{% load htmx_views_bootstrap %}
{% bootstrap_modal_target size="lg" %}

htmx_views.templatetags.htmx_views_bootstrap.do_bootstrap_accordion(parser, token)

Compile a bootstrap_accordion block.

Args:

parser (Parser):

Active Django template parser.

token (Token):

Opening template-tag token.

Returns:

(_BootstrapAccordionNode):

Compiled accordion node.

Examples:

Create an accordion containing item tags:

{% bootstrap_accordion id="documents" %}
    ...
{% endbootstrap_accordion %}

htmx_views.templatetags.htmx_views_bootstrap.do_bootstrap_accordion_item(parser, token)

Compile a bootstrap_accordion_item block.

Args:

parser (Parser):

Active Django template parser.

token (Token):

Opening template-tag token.

Returns:

(_BootstrapAccordionItemNode):

Compiled accordion-item node.

Examples:

Render an initially expanded item:

{% bootstrap_accordion_item id="manuals" title="Manuals" expanded=True %}
    ...
{% endbootstrap_accordion_item %}

htmx_views.templatetags.htmx_views_bootstrap.do_bootstrap_buttons(parser, token)

Parse a Bootstrap 3-compatible button-row block.

Args:

parser (Parser):

Active Django template parser.

token (Token):

Template token containing the tag arguments.

Returns:

(_BootstrapButtonsNode):

Compiled button-row node.

Raises:

TemplateSyntaxError:

If an unsupported or positional argument is supplied.

Examples:

Render form actions:

{% buttons submit="Save" reset="Cancel" %}
{% endbuttons %}

htmx_views.templatetags.htmx_views_bootstrap.do_bootstrap_modal_content(parser, token)

Compile a bootstrap_modal_content block.

Args:

parser (Parser):

Active Django template parser.

token (Token):

Opening template-tag token.

Returns:

(_BootstrapModalContentNode):

Compiled modal-content node.

Examples:

Wrap an HTMX form response in Bootstrap modal markup:

{% bootstrap_modal_content title="Manage document" %}
    <form hx-post="{{ post_url }}">
        ...
    </form>
{% endbootstrap_modal_content %}

Application configuration

class htmx_views.apps.EquipmentConfig(app_name, app_module)

Bases: HTMXViewsConfig

Compatibility name for code importing the former app config.

class htmx_views.apps.HTMXViewsConfig(app_name, app_module)

Bases: AppConfig

Django App config object for the htmx_views app.