- CSS 54%
- HTML 19.5%
- Python 19%
- JavaScript 7.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| docs | ||
| frontend | ||
| src | ||
| .gitignore | ||
| COPYING | ||
| COPYING.LESSER | ||
| MANIFEST.in | ||
| pyproject.toml | ||
| README.md | ||
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.