The shell every hub of the OpenHubs line shares: layout, header, sidebar, footer, error pages and styles
  • CSS 54%
  • HTML 19.5%
  • Python 19%
  • JavaScript 7.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 16:52:43 +00:00
docs docs: README, and the change that makes hub_shell mandatory in the line's model 2026-10-25 17:40:07 +01:00
frontend feat: the shell stands on Bootstrap 5.3 from npm, bundled with its skin, and AdminKit 3.3 and the copy of Bootstrap 5.2's components it left out are gone 2026-10-31 00:13:36 +01:00
src chore: release splent_io/splent_feature_hub_shell to v0.2.4 2026-11-17 16:52:43 +00:00
.gitignore feat: scaffold splent_feature_hub_shell with splent feature:create 2026-10-25 16:11:15 +00:00
COPYING feat: scaffold splent_feature_hub_shell with splent feature:create 2026-10-25 16:11:15 +00:00
COPYING.LESSER feat: scaffold splent_feature_hub_shell with splent feature:create 2026-10-25 16:11:15 +00:00
MANIFEST.in feat: scaffold splent_feature_hub_shell with splent feature:create 2026-10-25 16:11:15 +00:00
pyproject.toml chore: release splent_io/splent_feature_hub_shell to v0.2.4 2026-11-17 16:52:43 +00:00
README.md feat: Bootstrap and feather from npm, built into the shell's bundle 2026-10-25 18:30:56 +01:00

splent_feature_hub_shell

The shell every hub of the OpenHubs line shares: the application and public layouts of a SPLENT product, the sidebar drawn from the framework's menu registry, the header, the footer, the flashed messages and the error pages, with the stylesheets, scripts, fonts and icons they need.

It sits on splent_feature_theme: the hub's name, logo, tagline, icons and brand colours are theme's site object and tokens, and the shell adds only what theme has no key for. What this feature provides and requires is listed in the [tool.splent.contract] section of pyproject.toml, which splent feature:contract --write keeps in sync with the source. It requires theme and auth.

The look is a dark sidebar that folds to a rail, a white header, cards with a hairline and a soft shadow, and Inter, on Bootstrap 5.2. Its values were measured on uvlhub.io, the line's first hub.

The shells

The shell makes its layouts the framework's two shells (shell('app') and shell('public'), see the framework's layout/shells.py), unless the product names its own in SPLENT_SHELL_APP or SPLENT_SHELL_PUBLIC:

Shell Layout What it is
shell('app') hub_shell/app.html The frame: sidebar, header, the band with the page's title, the trail, the messages, the content and the footer
shell('public') hub_shell/public.html The public site's pages (the home, team's) in the same frame, where Bootstrap is: the title goes to the band, the hero block is not drawn, and the trail is the page's or theme's (SITE_BREADCRUMBS)

It also ships base_template.html, which extends hub_shell/app.html, for the pages that still extend the layout by that name. A product's own base_template.html comes first, as any product template does.

A page names itself in its title block, or with a title variable; theme's site_title() writes <title>, and the band shows the same name unless the page draws its own <h1>.

Slots

hub_shell/app.html opens these slots (register_template_hook):

Slot Where
layout.head.css End of <head>, after the registered stylesheets
layout.sidebar.top The sidebar's top entries, while the registry's site section is empty
layout.anonymous_sidebar A visitor's entries, while the registry's anonymous section is empty
layout.authenticated_sidebar The administration's entries, for administrators and staff (below)
layout.sidebar.authenticated.items An account's entries, while the registry's account section is empty
layout.header.menu The header's menu, where explore puts the search box: in the header on a desktop, a drawer from the right on a phone, with its button
layout.navbar.items Buttons after "Cite us!" in the header
layout.navbar.user Who is signed in, at the top of the account menu
layout.navbar.authenticated The account menu, while the registry has no user menu
layout.navbar.anonymous A visitor's header buttons, while the registry has no user menu
layout.footer After the footer's links
layout.scripts End of <body>, after the registered scripts

The menus come from the menu registry section by section: a section with entries there is drawn from it, and one without from its slot. Never both, or a feature that registers its entries and keeps its hook for a minor would show each entry twice. The administration is the exception: it is drawn from the registry's admin section and then from layout.authenticated_sidebar, without the slot's entries whose every address the registry already shows (hub_shell.slot_beyond_menus). The sidebar uses each entry's feather icon name; the chrome draws the names it knows in Phosphor's duotone weight (below). "Cite us!" appears in the header when the product has citation.

Configuration

The identity is theme's, and the Appearance editor changes it at runtime:

Theme key What the shell does with it
SITE_NAME The sidebar's brand when there is no logo, a phone's header, the title, the logo's alt text
SITE_LOGO, SITE_LOGO_SIZE The sidebar's logo, on the dark sidebar, and its height
SITE_TAGLINE The meta description
the product's icon files The page's icons (theme's site.icons); the shell's own while the product ships none
SITE_BREADCRUMBS Where the public pages get a trail
the Menus editor's footer links The footer, after the repository

The shell's own parameters, in [tool.splent.config] with their types in [tool.splent.config_schema], are for what theme has no key for. All are derivation (the product decides them) and empty by default, and the shell then draws nothing in their place:

Key Type What it does
HUB_SHELL_LOGO_COMPACT str The small logo of a phone's header, a path inside the product's static folder. Empty draws the site's name
HUB_SHELL_FOOTER_YEAR str, a year or a span (2025, 2019-2025) The footer's copyright year, as in "2025©"
HUB_SHELL_FOOTER_CREDITS text Who the footer credits after the year; per language as es:…|en:…
HUB_SHELL_REPOSITORY_URL url The repository of the hub's code. The footer links it ("Repository on GitHub", "on GitLab", or "Source code" on another forge) and the sidebar's version links the release's notes there

The sidebar shows the release the site runs (the framework's get_app_version(), which a production image writes from its tag) as v<version>, and hides it while the site cannot tell.

# the product's pyproject.toml
[tool.splent.config]
SITE_NAME = "Rainfall Hub"
SITE_LOGO = "media/logos/rainfall-dark.svg"
HUB_SHELL_LOGO_COMPACT = "media/logos/rainfall.png"
HUB_SHELL_FOOTER_YEAR = "2026"
HUB_SHELL_FOOTER_CREDITS = "University of Somewhere"
HUB_SHELL_REPOSITORY_URL = "https://github.com/example/rainfall"

The brand and the skin

The skin (assets/css/hub_shell.css) writes the look as --hub-* tokens and styles Bootstrap's components and the frame with them, so the features, which draw plain Bootstrap, take the hub's look without knowing it. The brand comes from theme's tokens (THEME_TOKENS, then the Appearance editor), which the layout writes into the page before the skin as --hub-brand-*, with the r, g, b of the two colours. Only these, not theme's whole --brand-* block, so a feature's stylesheet that reads theme's variables keeps, in the app shell, the fallbacks it was written with:

Theme token Shell token Used for
primary --hub-primary Buttons, the current entry, focus rings
primary_contrast --hub-primary-inverse The label on the primary
accent --hub-link Links
font_body --hub-font-sans All the text
radius --hub-radius Corners; the small and large radii follow it

Every tone of the primary the shell draws (the active one, the light tint, the sidebar's current entry, its focus ring, the dark mode's) is mixed from it with color-mix(), so a hub that names one colour gets a coherent set. theme's font_url is never linked: the shell serves Inter itself. The rest of the palette (greys, the state colours, the sidebar, the dark mode) is the shell's. A product that wants other tones, a sidebar of another colour or exact shades registers a stylesheet of its own over the tokens, at order 200, as a skin does:

register_asset("css", "static", order=200, shell="app", filename="css/skin.css")
:root { --hub-primary-active: #056ee9; --hub-sidebar-bg: #1f2937; }
:root[data-bs-theme="dark"] { --hub-primary: #006ae6; }

The header's Mode menu sets the light, dark or system mode, kept in the browser (localStorage, hub-theme), and so is the sidebar folded to its rail (hub-sidebar-minimized).

Assets

The shell's bundle is built by the SPLENT toolchain from frontend/ (frontend/package.json, locked in frontend/package-lock.json), into assets/dist, which a release commits with its tag:

npm package Licence What the shell takes
@adminkit/core 3.3.0 MIT AdminKit's build of Bootstrap 5.2.0's stylesheet, css/app.css, which the look is drawn on. Copied as it is, byte for byte
bootstrap 5.2.0, @popperjs/core 2.11.8 MIT Bootstrap's JavaScript, in the shell's bundle as window.bootstrap; and Bootstrap's own rules for the components AdminKit's build leaves out (the alert, the breadcrumb, the modal, the tooltip, the popover, the toast, the spinners, the progress bar and the pagination), taken from its stylesheet as they are, in bootstrap/components.css
feather-icons 4.29.0 MIT The icons the features name, in the shell's bundle as window.feather, which draws every data-feather icon once the page is parsed
inter-ui 4.1.1 OFL-1.1 Inter's four weights (400, 500, 600, 700), which the skin's @font-face rules point at
@phosphor-icons/core 2.1.1 MIT The duotone icons of the chrome, built into one sprite, phosphor/duotone.svg (frontend/webpack.extra.js)

The shell registers them for its app shell, in this order:

Order Asset What it is
0 adminkit/css/app.css AdminKit's Bootstrap
5 bootstrap/components.css Bootstrap's components AdminKit's build leaves out
10 hub_shell.css, hub_shell.bundle.js The skin and legacy-features.css; Bootstrap's JavaScript and feather, then the sidebar's folding and drawers, the mode, the chrome's icons, the tooltips and popovers, the header's menus
200 hub_shell_error.css, public shell only theme's 404 as the hub's error card

The features' own assets sit at 100. As the provider of the page's shared libraries, the shell declares in splent.provides of frontend/package.json what features may take from it without bundling: bootstrap (window.bootstrap) and bootstrap-css 5.2.0, and the feather icons (window.feather). Being their provider, it is the one feature the toolchain lets bundle them; a product that has the shell provides nothing itself ("splent": {"provides": {}} in its package.json). Nothing loads from another site.

assets/css/legacy-features.css holds rules features still take from the shell (skeletons, the identifier pill, explore's filters, the monolith's spacing steps), each named by the features that use it; it shrinks as each feature carries its own.

The chrome's icons

The features name their icons in feather, in the menu registry and in their slot markup. hub_shell/_icons.html translates the names it knows into Phosphor's duotone weight for the sidebar, the header and the footer (chrome_icon(name)), and scripts.js does the same to the icons the features' slot markup brings into the chrome. A name it does not know is drawn with feather; one feather does not know either is drawn as a circle, and the console says which. To add an icon, add its line to CHROME_ICONS and its Phosphor name to ICONS in frontend/webpack.extra.js; tests/unit/test_icons.py checks the two agree.

Error pages

Error Page Drawn
400, 401, 500 400.html, 401.html, 500.html (hub_shell/errors/) A card in the middle of the screen, without the shell. It asks for nothing but its stylesheet and theme's tokens, so it renders whatever failed
404 theme's errors/404.html theme answers it, in its public shell, with the Appearance editor's words; the shell's stylesheet draws it as the same card
403 403.html Inside the app shell, so the account keeps its sidebar, with the framework's words

The framework renders them by name. A product that ships a page of the same name draws its own instead. Every error page says noindex.

In the OpenHubs line

The shell is mandatory in the line's model (openhubs_spl), under plataforma, with hub_shell => theme and hub_shell => auth. docs/openhubs_spl.uvl.patch is that change, against version 16 of the model. splent product:validate --only config --model <patched model> finds both hubs of the line satisfiable with it, and one that leaves the shell out not.

Use it in a product

splent feature:add splent_feature_hub_shell

Then remove the product's own layout and error pages, if it has them (templates/base_template.html, 400.html, 401.html, 500.html, and the SPLENT_SHELL_* of its config.py), and the copies of AdminKit, Bootstrap or Inter in its static folder, and set its name, logo, tokens and the shell's parameters.

Develop

splent feature:npm hub_shell install <package>@<version>
splent feature:compile hub_shell            # assets/dist, in development mode
splent feature:compile hub_shell --watch    # again on every change
splent feature:test splent_feature_hub_shell --neutral
splent feature:contract splent_feature_hub_shell --write

The tests render the shells and the error pages in a neutral app, with theme, auth and the session store every product has.