James MaesandClaude Fable 5.2 e51605e0a4
maven / build (push) Successful in 2m37s
build / maven (push) Successful in 2m43s
feat: ship the qbit's own help, and a changelog a host can include
A host should take the CMS whole from this qbit: its tables, its help and
its schema. Two things forced a host to write CMS material of its own; both
are fixed here.

- Help: help/qbit-cms.yaml (643 entries) covers every app, home, table,
  section, field, child list and value list. The producer registers it when
  the host uses the default names. CmsHelpTest holds it to the core's
  coverage gate (HelpBundleAssertions) and to every section.
- Schema: the first guard changeset (1.0.0-guard-existing-tables) no longer
  has runAlways. It rewrote its DATABASECHANGELOG row on every migration,
  so a second migration was never a no-op and a rollback by count began with
  it; a host whose migrations must be repeatable had to copy the tables. It
  runs once now, with validCheckSum: ANY so an install that already ran it
  migrates on unchanged. This changes a released changeset on purpose;
  CmsInstallTest.testRerunIsNoop covers a second run and an install the
  earlier version recorded.
- Homes: text sizes in rem (labels 0.875rem instead of 13px), so they follow
  the reader's text size.

Tests: 40, Checkstyle 0, guardrails and coverage checks pass.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-18 15:33:54 -06:00

QBit CMS

License Java

QQQ QBit: a headless CMS (sites, pages, menus, blog, media, projects, photos and publishing) as standard QQQ tables.

Status: design approved in QRun-IO/qqq#1083 (see docs/DESIGN.md). CORE, MEDIA, BLOG, PROJECTS and PHOTOS are implemented as tables with their admin screens. File upload, storage and renditions, the publishing processes, the content stream and the Site API are not built yet; PUBLISHING and STREAM are next.

The CMS is extracted from the kof22 website, which runs it in production. Its data lives in ordinary QQQ tables in your own database, secured by QQQ permissions. It brings an admin app with one home per area, and a schema you run with your own Liquibase.

Requirements

  • Java 21.
  • QQQ 4.1 (built against 4.1.0-RC.4) with an RDBMS backend: PostgreSQL 14+ in production, H2 for tests.
  • QQQ Next UI 1.0 (1.0.0-RC.14 or later). Material is not supported.
  • Liquibase in your migration pipeline (or the reference DDL in docs/ddl/postgres.sql).

Install

  1. Add the dependency com.kingsrook.qbits:qbit-cms (once released).

  2. Run the schema. Put the qbit jar on your Liquibase classpath and include its changelog. Set its properties before the include (the first definition wins):

    databaseChangeLog:
      - property: { name: cms.tablePrefix, value: cms_ }      # must equal CmsQBitConfig.tableNamePrefix
      - property: { name: cms.features, value: "CORE,MEDIA,BLOG" }   # the features you install (default: all)
      - include:  { file: qbit-cms/db/changelog/qbit-cms.changelog.yaml }
    

    The changelog is safe to include in a migration that must be repeatable: a second run changes nothing, the migration history included. The changelog never touches a table it did not create. If a table with one of its names already exists, it halts with a message telling you to choose another prefix. It seeds only generic reference data (redirect, page, section, media and blog types); set cms.seedReferenceData to false to skip that.

  3. Produce the qbit after your backends (and the parent app, if any) are on the instance:

    new CmsQBitProducer()
       .withQBitConfig(new CmsQBitConfig()
          .withBackendName("rdbms")
          .withRole("cms-admins", CmsRole.ADMIN)
          .withRole("cms-editors", CmsRole.EDITOR))
       .produce(qInstance);
    
  4. Grant permissions from your authentication customizer: CmsSecurity.applySessionPermissions(session, userGroups, config).

At startup the producer checks that the changelog ran for every enabled feature and that the tables exist. startupMode FAIL_FAST (the default) refuses to start and lists what is missing. DEGRADED starts and shows the problem on the CMS home. SKIP does not check (unit tests without a database).

Configuration reference (CmsQBitConfig)

Setting Default Meaning
backendName required The RDBMS backend for every CMS table
tableNamePrefix cms_ Table name prefix (QQQ and SQL names are equal); must equal the changelog's cms.tablePrefix
namePrefix cms Prefix of app and widget names (cmsPages, cmsPagesHome)
permissionBaseName cms Base of qbit-wide permissions (cms.admin, cms.publish)
features every available feature CmsFeature set; CORE is required, and a feature this version does not implement yet is rejected
appName, appLabel, parentAppName cms, CMS, none The top app and where it nests in your app tree
openReads false When true, reading CMS tables needs no permission (writes always do)
startupMode FAIL_FAST FAIL_FAST, DEGRADED or SKIP (see above)
roleMapping empty Identity-provider group name to CmsRole

A namespace (withNamespace("siteTwo")) fills in all three prefixes for a second install in the same instance (site_two_page, siteTwoPages, site_two.admin).

Features

Feature Tables Status
CORE site, domain, redirect, redirect type, page, page type, page section, page section type, snippet, menu, menu item available
MEDIA media, media type available: a media record points at a file by its address; upload, storage and renditions are not built yet
BLOG (needs MEDIA) blog, blog type, author, blog tag, blog post, blog post tag, blog post media, related version available
PROJECTS (needs MEDIA) project category, project, project update available
PHOTOS (needs MEDIA) album folder, photo album, photo, photo tag, photo tag link available
PUBLISHING, STREAM, DATA_HEALTH_RULES see the design planned

A feature that is off produces no tables, and its changesets are skipped until a later migration run names it in cms.features. Every content feature needs CORE, and blogs, projects and photos need MEDIA; a feature whose needs are not named installs nothing. What links two features (a related version of a project, a photo album of a project) keeps its column either way and gets its lookup, its list on the parent record and its foreign key only when both features are on.

Fixed lists (rendition format, cache class, content channel, content format, version status, project status) are possible-value sources named with the table prefix, for example cms_project_status. A write with a value that is not on the list is refused with an error on the record, and the database has a check constraint on the same column.

The admin

The qbit adds one app (CMS) with a home, and one sub-app per area, each with its own home:

  • Sites: sites (domains are a list on each site) and redirects; Settings has redirect types.
  • Pages: pages (sections and child pages are lists on each page) and snippets; Settings has page types and page section types.
  • Navigation: menus (items are a list on each menu).
  • Media: the media library; Settings has media types (upload rules, renditions, required text, cache and storage settings).
  • Blogs: blog posts (tags, media and related versions are lists on each post), blogs (their tags are a list on each blog) and authors; Settings has blog types.
  • Projects: projects (updates, photo albums and related versions are lists on each project) and project categories.
  • Photos: photo albums (photos are a list on each album), album folders and photo tags.

Fields that hold an image's or a file's address show it as a preview (QQQ's file preview).

The nav shows only main tables and reference data; child tables are edited on their parents' records. Each home shows only real data read as the current user: counts, drafts, inactive rows and recently changed records, readable at any width in light and dark mode. The qbit never sets the instance's home app.

Help

The qbit ships its own help for every app, home, table, section, field, child list and value list (help/qbit-cms.yaml). The producer registers it when you use the default names (cms_, cms); a host that has the QQQ help tables then shows it with nothing to write. With your own prefixes, write your own bundle from it. Bulk screens that QQQ generates per table are the host's, as for any table.

Permissions

Every CMS table has QQQ permission rules. The table permissions are <table>.read, .insert, .edit and .delete (for example cms_page.edit). The qbit-wide permissions are cms.admin and cms.publish.

Role Grants
ADMIN everything, including reference data, cms.admin and cms.publish
EDITOR read everything; write content tables
PUBLISHER EDITOR plus cms.publish
DRAFTER read everything; insert and edit content (no deletes, no publishing)
VIEWER read everything

The qbit is built for QQQ core permission enforcement (qInstance.setEnforcePermissionsInCoreActions(true), the default from QQQ 4.2).

Operational tables

All CMS data is in normal, visible QQQ tables. Nothing is hidden and there is no side store. The schema is in docs/ddl/postgres.sql (generated from the changelog).

Upgrading

Read the CHANGELOG's "Schema changes" before deploying. Run your migrations before the new app version. Released changesets never change; new versions only append changesets.

Adopting in another app

Follow the QQQ adoption checklist once the first release is published.

Build

./mvnw verify

Always use the Maven wrapper (Maven 3.9.11); Maven 3.10 cannot read the parent POM. The PostgreSQL tests use Testcontainers and are skipped when Docker is not available.

License

Apache License 2.0. See LICENSE and NOTICE.

S
Description
QQQ QBit: a headless CMS (sites, pages, menus, blog, media, projects, photos and publishing) as standard QQQ tables
Readme
1.3 MiB
0 Stars 3 Watchers 0 Forks
Languages
Java 100%