# Themes Package — Developer Notes ## Top navbar menu Each package self-registers via `$gBitSystem->registerAppMenu()` in its `bit_setup_inc.php`. Rendered by `kernel/templates/top_bar.tpl` — no built-in role gate at the dropdown level. Config switches (stored in kernel_config, set via Themes > Admin > Menus): - `menu_$pkg = 'n'` — disable dropdown for all users - `${pkg}_menu_text` — custom dropdown label - `${pkg}_menu_position` — sort position For role-based visibility, override `top_bar.tpl` in `config/themes/merg/kernel/`. ## CSS load order `BitThemes::loadStyleData()` loads CSS in this order: 1. Package CSS (around position 300) — each package's `html_head_inc.tpl` 2. `themes/css/config.css` — position 300 (default); canonical floaticon/icon/actionicon rules 3. Style CSS (`getStyleCssFile()`, position 998) — the active theme's main CSS 4. Browser CSS (`getBrowserStyleCssFile()`, position 999) Site-specific CSS lives in `/etc/webstack/domains/{site}/themes/{site}/{site}.css` and is the active theme file for that site (position 998). Site theme images go in `themes/{site}/images/` within that domain dir — referenced via `{$gBitThemes->getStyleUrl()}images/`. **`.floaticon` / `.icon` audit note** — `themes/css/config.css` defines `.floaticon { float:right }` at position 300. Site theme CSS at position 998 **wins** over this. If a site theme has `.icon { float:left }` (common in older themes for sprite icon layout), it breaks `.floaticon` by causing child icons to float left and collapse the container. **Fix**: strip the bare `.icon { float:left }` from the site CSS — do not scope it or patch it elsewhere. ## Asset locations - **Site-specific images** — `/etc/webstack/domains/{site}/themes/{site}/images/`; referenced in templates as `{$gBitThemes->getStyleUrl()}images/filename.ext` - **Cross-site org assets** (RDM logo, cookie-consent images) — `util/images/`; referenced as `{$smarty.const.UTIL_PKG_URL}images/filename.ext` or `/util/images/filename.ext` in CSS - **Fonts** — `util/fonts/{family}/`; referenced as `/util/fonts/...` in `@font-face` CSS - `config/css/`, `config/js/`, `config/fonts/`, `config/images/` are all dead and removed from servers — do not recreate them ## Smarty notes - `{tr}...{/tr}` for translation in templates; `KernelTools::tra()` in PHP - `tra` is NOT a Smarty modifier — `"string"|tra` will throw a compiler error - `{form}` block plugin auto-injects `` (CSRF ticket) - **`form-search` hides Bootstrap submit buttons** — Bootstrap 2 `.form-search` suppresses the submit control. Use `class="minifind"` alone on floaticon filter forms; never add `form-search`. - `{strip}` removes whitespace between HTML tags; keep `•` separators inside valid `
  • ` elements to avoid detachment - **`{textarea}` / CKEditor** — omit `id`; the plugin defaults to `LIBERTY_TEXT_AREA` which is what CKEditor searches for. Passing a custom `id` breaks CKEditor attachment. Do NOT wrap `{textarea}` in an outer `form-group`/`{formlabel}`/`{forminput}` — it provides its own via `edit_textarea.tpl`. Pass `label="..."` directly to `{textarea}`. Default field name is `edit`; PHP reads `$_POST['edit']`. Do not pass `name=` unless you also change the PHP to match. PHP must call `invokeServices('content_edit_function')` for CKEditor to load. - Per-site footer scripts belong in `kernel/footer_inc.tpl`, NOT `kernel/footer.tpl`. `footer_inc.tpl` is picked up by the `mAuxFiles` loop in `html.tpl` reliably. `footer.tpl` as a theme override only loads if the active style matches exactly — fragile and easy to miss. ## Module / Layout system Modules are placed in layout areas via the `THEMES_LAYOUTS` table: - `LAYOUT_AREA` — column position: `t` (top), `l` (left), `r` (right), `b` (bottom) - `POS` — sort order within the column - `MODULE_RSRC` — the Smarty template to render, e.g. `bitpackage:kernel/mod_top_banner.tpl` - `ROLES` — role_id that can see this module (empty = all users); use `-1` for anonymous-only The 't' column is rendered inside `
    ` via `displayLayoutColumn('t')`. Bootstrap grid columns (`col-sm-*`) inside modules MUST be wrapped in a `clearfix` parent; without it, subsequent modules in the same column float up and overlay earlier ones. Managed via Admin > Themes > Layout. Template includes resolve via `bitpackage:` prefix. Column visibility is controlled by feature flags in `kernel_config` checked in `BitThemes::loadLayout()`: - `{display_mode}_hide_{area}_col` (e.g. `edit_hide_left_col`) - `{package}_hide_{area}_col` - `{package}_{display_mode}_hide_{area}_col` The old hardcoded `display_mode != 'edit'` guard in `html.tpl` has been removed — columns now always follow these flags. All flags off = columns show on all pages including edit pages. ## Standard content header pattern (merg theme) The merg theme applies `background-color: #5da7e1` to every `
    ` element. The standard pattern for display pages uses a semantic `
    ` with floaticons and breadcrumbs as separate included templates (matching the stock assembly pattern): ```html
    {include file="bitpackage:pkg/foo_icons_inc.tpl"} {* floaticons — float right *}

    Title

    {include file="bitpackage:pkg/foo_breadcrumb_inc.tpl"} {* trail *}
    ``` - `foo_icons_inc.tpl` — contains `
    ` with action icons (edit, delete, etc.) - `foo_breadcrumb_inc.tpl` — contains `` with `›`-separated ancestor links - Use `
    ` (semantic element), never `
    ` — the latter gets no blue background - Do not use a separate `
    ` or `