Installing Bootstrap5 Theme for Django-Cast
This document provides the instructions on how to install the Bootstrap5 theme for Django-Cast. Please follow the steps below.
Installation
1. Install the theme
To install the Bootstrap5 theme, you will need to run the following command in your command line:
pip install cast-bootstrap5
2. Add to INSTALLED_APPS and set CRISPY_TEMPLATE_PACK
You will need to add crispy_bootstrap5 and cast_bootstrap5.apps.CastBootstrap5Config
to your INSTALLED_APPS in your Django settings. Also, if crispy_forms is not
yet added, add it to INSTALLED_APPS.
Then, set the CRISPY_TEMPLATE_PACK and CRISPY_ALLOWED_TEMPLATE_PACKS like so:
INSTALLED_APPS = [
...,
'crispy_forms',
'crispy_bootstrap5',
'cast_bootstrap5.apps.CastBootstrap5Config',
...
]
CRISPY_TEMPLATE_PACK = "bootstrap5"
CRISPY_ALLOWED_TEMPLATE_PACKS = "bootstrap5"
3. Set the theme in Wagtail admin
You can set the theme to bootstrap5 in the Wagtail admin for the
complete site or just one blog.
End
That's it! You have successfully installed and set up the Bootstrap5 theme
for django-cast.
The metadata-sharing template contract requires django-cast 0.2.62 or newer.
Release and deploy django-cast before upgrading cast-bootstrap5; older versions
do not ship cast/includes/post_social_meta.html.
With django-cast 0.2.64 or newer, the search modal progressively enhances the existing GET search form with recent-first title suggestions. The destination list supports pointer, touch, and keyboard navigation and leaves ordinary form submission available when JavaScript or the suggestion endpoint fails, or when the current filter combination has no matching posts. While destinations are visible, they take visual priority over the live full-text no-results message. When a longer query refreshes an open list, the settled destinations remain visible but temporarily non-selectable until the matching response arrives. IME input is supported: suggestions wait until composition ends, and composition keys retain their input-method behavior. This also means keyboards that keep Latin words in an active composition session show suggestions after the word is committed (for example, by a space), rather than while composing it. Plain suggestion clicks open in the current page; Ctrl/Meta and middle clicks open a new tab, and Shift clicks request a separate window (the browser controls the final presentation). Suggestion destinations must resolve against the current origin to HTTP(S) URLs on that same origin, without credentials. Relative post links remain supported; invalid destinations (including executable schemes and foreign origins) reject the whole response before caching or rendering, leaving ordinary search usable. Suggestion IDs must be positive safe integers and unique within each response, so keyboard focus always identifies exactly one option. Invalid identities reject the whole response before caching or rendering. Each suggestion request accumulates at most 64 KiB of response-body bytes through a standard stream reader before JSON parsing, independently of Content-Length (including absent or understated lengths). Exceeding the budget cancels the body and uses the same unavailable/fallback behavior; oversized responses are never cached. This also bounds large suggestion titles and each cached response. Each suggestion request has a five-second total deadline, including reading the JSON response. Cancellation also cancels the body reader. A timeout clears the loading indicator and announces that suggestions are unavailable; ordinary Enter and submit-button searches remain usable. Superseded requests are cancelled silently. Removing the modal element from the page disconnects typeahead and cancels its request and deadline timer. Closing the modal cancels queued and in-flight facet and suggestion requests, clears loading indicators and closes the suggestion list. Late responses cannot change filters or announce results. Reopening reconnects suggestions once and preserves the current query and selected filters. Interrupted facet updates and suggestions refresh on reopening without needing another input event. Suggestion status messages are announced only while the search input has focus. As with other endpoint failures, two consecutive timeouts suspend suggestions until the modal is reopened. With an older django-cast version the endpoint URL is absent and the modal keeps its submit-only search behavior.
Gallery captions
Gallery thumbnails display an optional plain-text caption for each gallery entry,
using semantic figure/figcaption markup with HTML escaping. Both the JavaScript
and HTMX gallery templates accept django-cast’s gallery_entries context
(image and caption per entry), while continuing to render the legacy images
context without captions. The core must supply gallery_entries, images, and
image_pks in the same order and length, retaining duplicate occurrences; HTMX
uses each entry’s position to select its modal image, and passes django-cast’s
signed gallery_token with every modal request (required since django-cast
0.2.61; the modal endpoint answers 400 without it). Repeated uses of one image can have different captions;
the shared image itself is unchanged. Captions appear below thumbnails, not in
the enlarged-image modal.
Page transitions
With django-cast 0.2.67 or newer (the minimum this theme requires), ordinary
same-origin page loads use cross-document view transitions of the cast-page
type shared with django-cast's built-in themes. The page crossfades while the
sticky navbar stays in place, and a post's title and first overview image morph
between the post list and its detail page in both directions. The theme loads
django-cast's cast/js/post-view-transition.js in the <head> of base.html
for the morph; audio player cover art is never used as the post image. The post
list is rendered during these transitions so a post can morph back into it
despite content-visibility: auto.
Readers who prefer reduced motion, and browsers without cross-document view
transitions, get plain page loads. HTMX pagination keeps its own fade. Sites
that override post_body.html keep the morph as long as each post is an
<article> whose direct <header> contains a heading and a link to the post,
and whose overview section has the block-overview class; see django-cast's
frontend documentation for the full contract.
Podlove player loading and retry
The shared embed script load has a ten-second deadline. If it times out, fails to load or register, or the player initializer throws synchronously, the loading indicator clears, a visible failure message is announced, and the player offers a button labelled “Retry loading player”. Activate it with a pointer or keyboard to try again; hover and focus do not automatically retry failed loads while the facade remains connected. Keyboard focus returns to the retry action when its button triggered the load and focus has not moved to another element in the meantime; focus is never taken away from elsewhere on the page. If a theme change reinitializes a facade player that was still being revealed and that attempt fails, the facade is shown again with the retry action. Both facade modes allow one initialization at a time. Failed or unusable embed scripts are discarded so the next attempt can fetch them again. A timeout fails every waiting player and removes the attempt's script and event handlers; late events from it cannot settle or remove a retry's script. A failed initializer discards its partial player host, and recovery from an older attempt cannot reset a newer player.
HTMX pagination with Podlove players
On HTMX history restoration, the theme queues a scroll to the top after HTMX's
own deferred saved-position scroll. A later restoration cancels the previous
theme scroll, and destroyPagingContentVisibility() cancels it during teardown.
The callback only scrolls while its original paging area is still connected and
current in the same initialized lifecycle; removing or replacing that area
makes the queued callback a no-op.
While an HTMX pagination request for #paging-area is running, a list that
contains Podlove players is masked so the players do not flash during the swap.
The mask and the fade state are removed again when the new content has settled.
If the request does not complete, the current content is restored at once: the
mask, the fade state and the pending unmask timer are cleared for an HTTP error
response, a network failure (htmx:sendError), a timeout (htmx:timeout), an
aborted request and a failed swap. The reader keeps the page they were on and
can try again. Failures of HTMX requests that target other elements leave the
paging state alone.
Post link prefetching
Links marked data-cast-prefetch request a speculative document fetch on hover,
focus or touch. Only same-origin HTTP(S) URLs without a username or password
are eligible; the current page is excluded. Prefetch identity ignores fragments
(including when checking existing prefetch links), while paths and query strings
remain distinct. Anchor destinations, including fragments, and ordinary browser
navigation are unchanged. The theme retains at most 32 owned prefetch nodes/cache
entries across HTMX swaps, evicting the oldest entry before admitting a new URL.
Eviction and teardown remove only theme-owned nodes; foreign head links stay in
place and are reused without adding cache entries. Revisiting an evicted URL may
prefetch it again. A failed owned fetch removes its node and allows one further
user-triggered attempt, with no automatic retry. After two attempts, failures
remain suppressed until eviction or teardown resets that URL's budget. In-flight
and successful retained nodes deduplicate further triggers.
The focused regressions run with
cd javascript && npx vitest run src/tests/post-link-prefetch.test.ts src/tests/paging-content-visibility.test.ts.
Dynamic search facets
Dynamic facet requests have a five-second total deadline covering both fetch and JSON body parsing. Expiry clears loading and announces “Could not refresh filters. You can still search.” The current filters and ordinary form submission remain usable, and a later filter or query change can retry. Superseding a request, closing the modal or removing it cancels pending work silently.
Before caching or changing any filter selection, the modal validates the entire
response: mode must be "modal", result_count must be finite and nonnegative,
and groups must be an object containing only date_facets, tag_facets and
category_facets (configured subsets, including an empty object, are supported).
Each group requires a string selected, a finite nonnegative all_count, and an
options array whose entries have string slug/name and finite nonnegative
count. An invalid response leaves every group and hidden form input unchanged,
is never cached, and uses the same failure announcement. Valid responses update
all selections before building facet links so the links share the new state.
Collapsed facet groups keep selected options visible even past the configured
limit (twelve by default), including after a dynamic refresh. Use “All” to remove
the group's selected filter. “Show all” / “Show fewer” controls only the remaining
overflow options, with matching aria-expanded; the toggle is hidden when no
options need collapsing.
Keyboard focus in the search modal
While the search modal is open, Tab and Shift+Tab stay inside it and wrap
between its first and last control. The controls that count are the visible,
enabled input (except type="hidden"), button, select and textarea
elements, links with an href, summary elements and elements with a
non-negative tabindex. Hidden controls, disabled controls (including those
inside a disabled fieldset) and controls with a negative tabindex are
skipped, along with inert descendants and CSS visibility-hidden controls. Visible
fixed-position controls are included. Positive tabindex values come first in
ascending order (ties retain DOM order), then zero/default controls. When positive
values are present, every Tab step follows this modal-local order so outside
controls cannot intrude. In this mode, each enabled radio input is a separate
stop; radio groups are not collapsed to a single stop. Controls in closed
details content are skipped. The trap
rechecks layout, disabled state and tabindex on each keypress. A template override may therefore
end the modal with any of these controls, including a textarea. This is a bounded
control set, not a general focus manager for shadow DOM or embedded documents.
If replacement, hiding, or disabling leaves focus outside the current set, the
next Tab enters the first control (Shift+Tab enters the last). If no supported
stops remain, Tab stays on the modal container until controls return. The trap
makes an otherwise non-focusable container temporarily focusable while active
and removes that attribute on deactivation. Focus on the dialog background
also restarts at the first/last control on the next Tab/Shift+Tab.
Development
Install javascript dependencies
All javascript stuff lives in the javascript folder. So the first thing
to do is to change to that folder.
cd javascript
Use Node.js 24.15 or newer in the 24.x line, matching CI, then install the locked dependencies:
npm ci
npm run audit # full locked tree, including developer dependencies; moderate or higher fails
TypeScript is pinned in javascript/package.json. The strict typecheck uses
bundler module resolution to match Vite, includes Vitest globals and Node types,
and checks dependency declarations without skipLibCheck. Run it before
committing frontend changes; it does not emit or rebuild assets.
Build javascript
npx vite build
After that you have to copy the contents of the dist folder
to the cast_bootstrap5/static/cast_bootstrap5/vite folder. Including
the manifest file from dist/.vite/manifest.json.
cp dist/* ../cast_bootstrap5/static/cast_bootstrap5/vite
cp dist/.vite/manifest.json ../cast_bootstrap5/static/cast_bootstrap5/vite
Purge unused Bootstrap CSS
After upgrading bootstrap.min.css, re-run PurgeCSS to strip unused rules:
npm run purge:bootstrap
This scans templates and JS from cast-bootstrap5 plus sibling repos to determine which Bootstrap classes are actually used. Requirements:
- Required:
../django-castmust be cloned alongside cast-bootstrap5 - Optional:
../homepageand../python-podcast— if missing, a warning is printed (classes only used in those repos may be incorrectly purged)
The purged CSS is written back to
cast_bootstrap5/static/cast_bootstrap5/css/bootstrap5/bootstrap.min.css.
Run tests
just test # strict TypeScript, JavaScript and Python/template tests
just js-audit # full-lock moderate/high/critical advisory gate
just js-browser-test # native Chromium keyboard/layout regressions
# First install the browser: cd javascript && npx playwright install chromium
just js-typecheck # strict sources, tests and Vite config (tsc --noEmit)
# Or, from javascript/: npm run typecheck
uv run --extra test pytest # Python/template contract tests only
npx vitest run # JavaScript tests once
npx vitest watch # JavaScript tests in watch mode
just check-assets # rebuild Vite bundle and cast.css, fail on drift
# Testing against a sibling django-cast worktree instead of the develop branch:
PYTHONPATH=../django-cast/src uv run --extra test pytest
django-cast 0.2.67 is not on PyPI yet, so [tool.uv.sources] in
pyproject.toml tracks the django-cast develop branch for uv, matching the
source used by homepage and python-podcast. A commit-specific source here
conflicts with those consumers' branch source when uv resolves Git dependencies.
Published package metadata keeps the plain django-cast>=0.2.67 requirement.
Remove the source block once 0.2.67 is released.
Sites can upgrade the theme by setting their cast-bootstrap5 Git rev to the
new theme commit and running uv lock --upgrade-package cast-bootstrap5; keep
their django-cast source at branch = "develop".
CI (.github/workflows/ci.yml) runs just js-audit immediately after the locked
install, then just js-typecheck, just js-test, just check-assets,
just js-browser-test, the pytest suite and just check-messages on every push and pull request.
The audit includes build/test dependencies, even packages that never ship in the browser bundle. Registry or scanner failures also fail the job; no lockfile is rewritten by the audit. The tooling refresh requires Vitest 4.1.12 or newer and jsdom 30.1.3 or newer; the lock resolves mocker 4.1.12 and undici 8.12.4. The unused Vue test utilities were removed, including their vulnerable formatting dependencies; this theme uses Vitest and DOM fixtures. The audit addresses development tooling exposure.
Rendered metadata behavior and JSON-LD parsing are covered by django-cast's post and episode detail tests; this theme's tests guard the shared-template and minimum-version contract.
Translations
The theme ships a German catalog in cast_bootstrap5/locale/de/LC_MESSAGES/.
Both django.po and the compiled django.mo are committed and included in the
package, so sites with USE_I18N = True and a German active language render the
translated theme strings without running compilemessages themselves. Strings
without a German translation fall back to English.
The <html lang> attribute of base.html follows the active language
(get_current_language), so a German request renders lang="de". With
USE_I18N = False it is the site's LANGUAGE_CODE.
After adding or changing {% translate %} / {% blocktranslate %} strings in
the templates, regenerate the catalog with GNU gettext installed:
just messages # makemessages + compilemessages for the theme package
just check-messages # fail if django.po no longer matches the templates (CI)
just messages keeps existing translations, adds new msgids untranslated (no
fuzzy guesses) and drops strings the templates no longer use. The pytest suite
checks that django.mo matches the translated entries in django.po.
Run development server
npx vite
Ordering dropdown outside the search modal
Outside the search modal, the enhanced ordering dropdown preserves the native select's disabled options
and disabled optgroups. Disabled selects (including those in disabled fieldsets)
remain visible as native controls when disabled at initialization. The option list
and disabled attributes should be established before enhancement; later attribute
changes on an enhanced select require a native input or change event to refresh
the dropdown state. A select disabled at initialization stays native until
enhancement is run again.
Search-modal ordering pills share the same disabled-option policy and native
event/reset synchronization. A disabled select remains native at initialization;
after enhancement, disabled attributes are refreshed through native input or
change events, and click handling always checks the current disabled state.
Establish the option list before enhancement. An empty native value defaults to
newest first only when that option is enabled. Clear all also preserves disabled
selects and skips unavailable reset choices. Enabled selections retain ordinary form
submission and emit one bubbling input followed by change when the selection
changes. External changes dispatched through input or change, and form
resets, synchronize the displayed label and active option. Initialization is
idempotent. The replacement button's accessible name includes both the field
label and the current selected value, including after selection changes and reset.
initFilterEnhancementsBootstrap() owns one pending DOMContentLoaded callback
and one HTMX swap listener. destroyFilterEnhancementsBootstrap() cancels pending
initialization and removes the swap listener, leaving already rendered controls
in place. Reinitialization is supported after teardown.
Enlarged gallery images
Ordinary primary clicks and keyboard activation open the enlarged-image modal. Modified clicks, non-primary clicks, cancelled events, and links with a download or another browsing target keep their native browser behavior. After Escape or the close button finishes hiding the modal, focus returns to the opening thumbnail if it is still connected. Removing the gallery clears that focus ownership; another active modal keeps its focus.
Each enlarged image has a ten-second loading deadline. A failed or timed-out load clears the spinner and busy state and announces “Could not load image.” Use “Retry loading image” to try the selected image again, or “Open original image” to follow its full-size link. Switching images, closing the modal, or removing the gallery cancels pending listeners and deadlines; old attempts cannot change a later image's state.
The enlarged image copies the selected thumbnail's full-size image metadata, including empty alternative text. Attributes absent from the selected image are removed from the shared modal, so navigation cannot reuse another image's alternative text or responsive sources. Image loading and aspect-ratio sizing continue to follow the selected thumbnail.
Removing a gallery (including an HTMX swap) closes its owned Bootstrap modal through the public hide lifecycle, waits for an opening or closing transition to finish, then disposes the instance and removes the modal. Its backdrop and focus trap are released and Bootstrap restores scrolling. Without Bootstrap, the gallery removes its fallback modal and clears the body lock when no other modal is active. Teardown preserves an active modal's body lock.
Scroll to top
Activating the scroll-to-top button focuses the first main-content heading, falling back to the main landmark. It reads the current reduced-motion preference at activation: reduced motion jumps immediately; otherwise it scrolls smoothly. Template overrides using a link keep native link navigation. Ordinary scrolling never moves focus, and a focused scroll-to-top button stays visible and exposed to assistive technology until focus leaves it. Viewport updates own at most one animation frame. Teardown or a button replacement cancels and invalidates that frame; rebinding starts fresh.
Post content enhancements
Consecutive plain blockquotes merge into one quote with lines in their original
order. Only blockquotes without semantic attributes, separated by ASCII HTML whitespace,
are eligible. The editor’s data-block-key and the enhancement’s own
data-cast-blockquote-merged marker are allowed; intervening prose, comments, and other quote attributes (including cite,
id, class, and language) keep quotes separate and preserve attribution and anchors.
initPostContentEnhancements() initializes once, waiting for DOMContentLoaded
when necessary, and enhances HTMX swap targets. Repeated calls are idempotent.
destroyPostContentEnhancements() cancels pending initialization and removes the
swap listener; it leaves already rendered content in place. Initialization can
be called again after teardown.
Theme preference
The color mode (Auto, Light, or Dark) is stored in localStorage under
cast-theme. If the browser refuses the write (private or restricted contexts,
exceeded quota), the choice still applies for the rest of the page session,
including system color-scheme changes and HTMX swaps; the next full page load
falls back to the stored value, or Auto when none is readable. Other open tabs
synchronize on localStorage changes (including clearing storage), updating the
root and all switchers. A denied-write session choice remains authoritative.
Destroying the switcher unregisters storage synchronization.
Every element marked data-cast-theme-switcher (the navigation menu and the
styleguide's floating toggle) is driven by src/theme/theme-switcher.ts, so all
of them show the same mode. Do not add a second script that reads cast-theme.
Metadata
Release files for cast-bootstrap5 0.0.78
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cast_bootstrap5-0.0.78.tar.gz | 578.4 kB | Without provenance | Details for cast_bootstrap5-0.0.78.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cast_bootstrap5-0.0.78-py3-none-any.whl | Python 3 | none | any | Details for cast_bootstrap5-0.0.78-py3-none-any.whl |
Total release size: 1.2 MB
Release files / cast_bootstrap5-0.0.78.tar.gz
| Download URL | cast_bootstrap5-0.0.78.tar.gz |
|---|---|
| Size | 578.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca372b0f85e4ba2348538966fb0d3f856637af35269f8a7f381af1e04267cdc8
|
|
BLAKE2b-256 checksum How to use checksums |
f1c9a29e379ea093c79845a117815e3add859459f048b13c08ab762456c2595b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / cast_bootstrap5-0.0.78-py3-none-any.whl
| Download URL | cast_bootstrap5-0.0.78-py3-none-any.whl |
|---|---|
| Size | 602.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6f11ac1d08f5d90963ce09a74e693cf719533225f4f5b328adf4a1bfd09b81e2
|
|
BLAKE2b-256 checksum How to use checksums |
45516b494a737a48b42be1ca23ce0f5d189e01c4663cc414e070df7d8a097504
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for cast-bootstrap5 0.0.78
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.