wagtail-tw-blocks

Overview

wagtail-tw-blocks is a comprehensive library of production-ready StreamField components and UI elements designed for Wagtail CMS. Built on the foundation of Tailwind CSS and daisyUI, this package enables developers to rapidly deploy modern, accessible, and highly customizable layouts without the overhead of building foundational UI components from scratch.

Core Features

• Design-First Architecture: Leverages Tailwind CSS and daisyUI for clean, responsive, and professional aesthetics.
• Thematic Flexibility: Full support for all daisyUI themes, allowing for effortless brand alignment.
• Extensibility: Architected for easy subclassing and template overriding to meet specific project requirements.

Installation

1. Install via Pip

pip install wagtail-tw-blocks

2. Configure Django Settings

Add wagtail_blocks to your INSTALLED_APPS. Ensure it is placed after your core Wagtail configuration to ensure proper template loading.

# settings.py

INSTALLED_APPS = [
    # ...
    "wagtail_blocks",
    # ...
]

Available blocks & components

Blocks

• Accordion (Collapse): Interactive, collapsible sections ideal for FAQs and structured data.

  

• Alert: Visual indicators for status updates, warnings, or informational highlights.

  

• Carousel: A responsive content and image slider with intuitive navigation.

  

• Code: Syntax-highlighted code blocks with integrated "copy-to-clipboard" functionality. (Note: Requires highlight.js and clipboard.js).

  

• CodeSandbox embed: Embed CodeSandbox instances directly into your pages.

  

• CodePen embed: Provide seamless integration for embedding CodePen instances.

  

• Expo Snack embed: Add live mobile app coding environments directly into your pages.

  

• StackBlitz embed: Provide seamless integration for embedding StackBlitz instances.

  

• Document: Displays document info inside a card with download button.

  

• Diff: Side-by-side visual comparison tools for images.

  

• Hover Gallery: An immersive image gallery featuring sophisticated hover interactions.

  

• Tabs: Efficient organization of content into navigable tabbed interfaces.

  

Implementation Example

To integrate these blocks into your page models, import the block library into your models.py:

from wagtail_blocks import blocks
from wagtail.fields import StreamField
from wagtail.models import Page

class Article(Page):
    content = StreamField([
        ("accordion", blocks.AccordionBlock()),
        ("alert", blocks.AlertBlock()),
        ("carousel", blocks.CarouselBlock()),
        ("code", blocks.CodeBlock()),
    ])

    content_panels = Page.content_panels + [
        FieldPanel("content"),
    ]

To ensure full functionality (specifically for the Code Block), include the following assets in your base template:

<link rel="stylesheet" href="{% static 'wagtail_blocks/css/styles.css' %}" />
<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/github.min.css"
/>

<script src="https://unpkg.com/lucide@latest"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.11/clipboard.min.js"></script>

<script>
  // Initialization
  lucide.createIcons();
  hljs.highlightAll();
  new ClipboardJS(".btn-copy");
</script>

Extending

You can easily extend or customize the provided blocks by sub-classing them. For example, to create a custom alert block with additional styles:

from wagtail_blocks.blocks import AlertBlock

class CustomAlertBlock(AlertBlock):
    class Meta:
        icon = "warning"
        label = "Custom Alert"
        template = "path/to/your/custom_alert_template.html"

Components

Beyond StreamField blocks, this package includes reusable template components to enhance global site functionality.

Breadcrumbs

Automatic breadcrumb generation following the Wagtail page hierarchy.

• Context: a Wagtail page.

• Usage:

  {% extends 'app/base.html' %}
  
  <!---->
  {% block content %}
  <section class="container-prose">
    {% include 'wagtail/components/breadcrumbs.html' %}
  
    <h1>{{ page.title }}</h1>
  </section>
  {% endblock %}
  

• Demo:

  

Forms

Accessible, daisyUI-styled wrappers for standard Django forms.

• Context: A Django form.

• Options:

  • method: Form method attribute (Defaults to post).
  • action: Form action attribute (Defaults to '').
  • csrf: A boolean that indicates whether to include Django {% csrf_token %} in the form (Defaults to True).

• Usage:

  {% extends 'app/base.html' %}
  
  <!---->
  {% block content %}
  <section class="container-prose">
    <h1>New User</h1>
  
    {% include 'wagtail/components/form.html' %}
  
    <!-- Pass the options using `with` keyword: -->
    {% include 'wagtail/components/form.html' with method="get" csrf=False %}
  </section>
  {% endblock %}
  

• Demo:

  

Language switch

Seamless integration with Django/Wagtail i18n for multi-lingual sites.

• Context: LANGUAGES from django.template.context_processors.i18n or a Wagtail page.

• Usage:

  {% extends 'app/base.html' %}{% load static %}
  
  <!---->
  {% block content %}
  <header class="absolute inset-x-0 top-0 z-10 backdrop-blur-3xl">
    <nav class="navbar p-4">
      <ul class="navbar-start gap-4">
        <li
          class="tooltip tooltip-bottom tooltip-primary"
          data-tip="Your Brand"
        >
          <h1>
            <a href="https://your.domain.com">
              <img
                alt="Your Brand"
                class="lg:size-8 2xl:size-10"
                src="{% static 'path/to/logo.png' %}"
              />
            </a>
          </h1>
        </li>
      </ul>
  
      <ul class="navbar-end gap-4">
        {% include 'wagtail/components/languages.html' %}
      </ul>
    </nav>
  </header>
  {% endblock %}
  

• Demo:

  

Theme switch

Switch between daisyUI themes with a single click.

• Usage:

  {% extends 'app/base.html' %}{% load static %}
  
  <!---->
  {% block content %}
  <header class="absolute inset-x-0 top-0 z-10 backdrop-blur-3xl">
    <nav class="navbar p-4">
      <ul class="navbar-start gap-4">
        <li
          class="tooltip tooltip-bottom tooltip-primary"
          data-tip="Your Brand"
        >
          <h1>
            <a href="https://your.domain.com">
              <img
                alt="Your Brand"
                class="lg:size-8 2xl:size-10"
                src="{% static 'path/to/logo.png' %}"
              />
            </a>
          </h1>
        </li>
      </ul>
  
      <ul class="navbar-end gap-4">
        {% include 'wagtail/components/themes.html' %}
      </ul>
    </nav>
  </header>
  {% endblock %}
  

• Demo:

  

Messages

Integrated support for the Django messages framework.

• Context: messages from django.contrib.messages.context_processors.messages.

• Usage:

  {% extends 'app/base.html' %}
  
  <!---->
  {% block content %}
  <section class="container-prose">
    {% include 'wagtail/components/messages.html' %}
  
    <h1>Messages</h1>
  
    ...
  </section>
  {% endblock %}
  

• Demo:

  

Pagination

Professional pagination controls for ListView and QuerySets.

• Context:

  • paginator: Django paginator instance.
  • page_obj: Page instance.
  • is_paginated: Boolean that indicates whether the content is paginated or not.
  • object_list: Paginated QuerySet.

• Usage:

  {% extends 'app/base.html' %}
  
  <!---->
  {% block content %}
  <section class="container-prose">
    <h1>Items</h1>
  
    <ol>
      {% for item in object_list %}
      <li>{{ item }}</li>
      {% endfor %}
    </ol>
  
    {% include 'wagtail/components/pagination.html' %}
  </section>
  {% endblock %}
  

• Demo:

  

Prev/Next

Smart pagination between sibling pages, with recursive fallback to parent pages.

• Context: A Wagtail page.

• Usage:

  {% extends 'app/base.html' %}
  
  <!---->
  {% block content %}
  <section class="container-prose">
    <h1>{{ page.title }}</h1>
  
    {% include 'wagtail/components/prev_next.html' %}
  </section>
  {% endblock %}
  

• Demo:

  

Tree

Recursive, tree-like navigation structures for documentation or complex sitemaps.

• Context: A Wagtail page.

• Usage:

  {% extends 'app/base.html' %}
  
  <!---->
  {% block content %}
  <div class="drawer lg:drawer-open">
    <input id="drawer" type="checkbox" class="drawer-toggle" />
  
    <section class="drawer-content">
      <main class="container-prose">
        <h1>{{ page.title }}</h1>
  
        <label
          for="drawer"
          aria-label="open drawer"
          class="btn btn-sm btn-primary lg:btn-md 2xl:btn-lg"
        >
          <i data-lucide="menu" class="size-4 lg:size-6"></i>
          Menu
        </label>
  
        ...
      </main>
    </section>
  
    <section class="drawer-side z-50">
      <label
        for="drawer"
        aria-label="close drawer"
        class="drawer-overlay"
      ></label>
  
      <div
        class="relative flex size-full flex-col overflow-hidden lg:min-w-sm lg:max-w-sm 2xl:min-w-md 2xl:max-w-md"
      >
        <header
          class="absolute inset-x-0 top-0 z-10 p-4 backdrop-blur-3xl lg:p-6"
        >
          <div class="flex items-center justify-between gap-4">
            <h1>Docs</h1>
  
            <div
              class="tooltip tooltip-left rtl:tooltip-right lg:hidden"
              data-tip="Close"
            >
              <label
                for="sidebar"
                aria-label="close sidebar"
                class="btn btn-sm btn-square btn-ghost lg:btn-md 2xl:btn-lg"
              >
                <i data-lucide="x" class="size-4 lg:size-6"></i>
                <span class="sr-only">Close</span>
              </label>
            </div>
          </div>
        </header>
  
        <div class="max-h-dvh overflow-y-auto py-16 lg:py-20">
          <ul class="menu menu-sm w-full grow lg:menu-md 2xl:menu-lg">
            {% include 'wagtail/components/tree.html' %}
          </ul>
        </div>
      </div>
    </section>
  </div>
  {% endblock %}
  

• Demo:

  

Contributing

We value community involvement. If you wish to contribute, please review our CONTRIBUTING.md for coding standards and setup procedures. For significant architectural changes, please open an issue first to discuss your proposed implementation.

Technical Support

• Bug Reports & Feature Requests: Please utilize the GitHub Issues tracker.
• General Inquiry: Join the community in GitHub Discussions.

License

This project is open-source software licensed under the MIT License. See the LICENSE file for further details.