CSS-framework drivers: Bootstrap 3, Bootstrap 5 and your own

yf renders its widgets, forms (form2), tables (table2) and layouts for the CSS framework named in conf('css_framework'): bs3 (the default), bs4 (Bootstrap 3 markup), bs5 or empty (no framework classes). Each name is a driver, a class yf_html5fw_<name> in classes/html5fw/. html5fw() (class yf_html5fw, plugin html) is the API in front of them: code asks it which driver renders, what the driver can do and which classes it uses, instead of comparing conf('css_framework') with a name.

The API

html5fw()->name();                     // bs3, bs5, ...: the per-call css_framework, else conf('css_framework'), else bs3
html5fw()->is('bs5');                  // true under Bootstrap 5; is(['bs3', 'bs4']) for any of several
html5fw()->family();                   // bootstrap for bs3 / bs4 / bs5, '' for empty
html5fw()->is_bootstrap();
html5fw()->has('dropdown_js');         // the driver's CAPABILITIES
html5fw()->classes('btn', 'primary', ['size' => 'xs']);   // btn btn-primary btn-xs (bs3), btn btn-primary btn-sm (bs5)
html5fw()->classes('float', 'right');                     // pull-right (bs3), float-end (bs5)
html5fw()->classes('badge', 'default');                   // badge badge-default (bs3), badge text-bg-secondary (bs5)
html5fw()->classes('btn', 'default', ['css_framework' => 'bs5']);   // per call, like form2's css_framework param
html5fw()->classes('btn');            // btn: without a variant, the base classes only
html5fw()->attr('toggle');             // data-toggle (bs3), data-bs-toggle (bs5): the driver's DATA_ATTRS, else data-<name>
html5fw()->is_admin_driver('bs5');     // true: the driver declares admin support (CAPABILITIES['admin'])
html5fw()->admin_names();              // [bs3, bs5]: the loadable drivers with admin support (the admin switcher's list)
html5fw()->is_bs3_markup();            // true on bs3, bs4, empty (and a driver that cannot be loaded): the Bootstrap 3 markup of before
html5fw()->ui_classes('badge', 'info', $map);   // a module's own markup per driver: see "Module markup" below

A removed framework (Bootstrap 2, Foundation, ...) answers empty. The older helpers stay and call the API: _class('admin_ui')->is_bs5(), table2's _is_bs5(), the _bs5() helpers of the admin modules.

Capabilities of the built-in drivers: dropdown_js, modal_js, tab_js, collapse_js, tooltip_js, popover_js, carousel_js (the framework's own JavaScript behaviour) on bs3 and bs5; jquery (that JavaScript needs jQuery) on bs3; toasts, color_modes, floating_labels, switches on bs5; admin (the admin renders under the driver) on bs3 and bs5, not on bs4 and empty. An unknown capability is false.

A css_framework whose driver cannot be loaded (its UI plugin is disabled or removed) renders, as before, without form rows. $PROJECT_CONF['html5fw']['MISSING_DRIVER_FALLBACK'] = true (off by default) renders it with bs3 instead (MISSING_DRIVER_FALLBACK_TO) and warns once a request; before the templates load, conf('css_framework') becomes bs3 too, so the layout and the assets agree.

The class map

Each driver lists the classes of the components yf emits in $CLASSES, a plain array (the lookup sits on hot paths). An entry is a string, whose %name takes the variant, or an array of variant => classes, where '' is the plain component and '%name' the template of the other variants. <component>_size holds the sizes that the size option appends. The components:

  • buttons: btn (variant: default, primary, success, info, warning, danger, link), btn_size (xs, sm, lg, mini, compact), btn_mini, btn_submit, btn_group;
  • badge, label (with a colour), highlight; alert (with a type), alert_dismissible, alert_close;
  • tables: table, table_condensed, table_row (a row colour), table_responsive;
  • forms: form_group, form_label, form_controls, form_input, form_input_size, form_select, form_select_size, form_radio, form_radio_inline, form_checkbox, form_checkbox_inline, form_check_input, form_help, form_state (error, success, warning, info), form_feedback, form_error, form_range_wrap, form_range_value, input_group, input_group_addon;
  • navigation: nav, nav_tabs, nav_pills, nav_item, nav_link, active, pagination, page_item, page_link;
  • cards (Bootstrap 3 panels): card (with a colour), card_header, card_title, card_body, card_footer; grid: row, col, col_offset (a column count);
  • modal, modal_dialog, modal_content, modal_header, modal_title, modal_body, modal_footer; dropdown, dropdown_toggle, dropdown_menu, dropdown_menu_right, dropdown_item, dropdown_divider;
  • utilities: float (left, right), hidden, sr_only, text (a colour).

The bs3 and bs5 maps hold the same values as the Bootstrap 3 / Bootstrap 5 class pairs of html, form2 and table2 (BS5_CLASSES), so a component looks the same whichever way it is asked for. An unknown component, or a variant that an array entry without %name does not list, is ''. A site changes one entry with $PROJECT_CONF['html5fw_bs5']['CLASSES'] (the whole array: copy it from the driver).

Template variants

A template <name>.stpl can have variants for a driver. The driver's chain, html5fw()->tpl_variants(), says which ones tpl reads, most specific first:

  • a driver of a plugin: <name>.<driver>.stpl, then <name>.<family>.stpl, then <name>.stpl (a driver sets its own chain in $TPL_VARIANTS; a driver without a family reads none);
  • bs5: <name>.bs5.stpl, then <name>.stpl; bs3, bs4 and empty: <name>.stpl only, as before the driver API: a .bootstrap.stpl or .bs3.stpl file is not read. $PROJECT_CONF['tpl']['CSS_VARIANT_CHAIN_BOOTSTRAP'] = true (off by default) gives them the generic chain: bs5 reads <name>.bs5.stpl, then <name>.bootstrap.stpl; bs3 <name>.bs3.stpl, then <name>.bootstrap.stpl (bs4 the same with bs4), so a site keeps one Bootstrap override for both.

A variant wins only when it comes from a place at least as specific as the base template (site, app, project, framework): a site's own main.stpl still beats a framework main.bs5.stpl. A variant that does not resolve for the current theme is skipped for the next one. Compiled templates carry the chain in their file names (_bs5 under Bootstrap 5). $PROJECT_CONF['tpl']['CSS_FRAMEWORK_VARIANTS'] = false turns variants off.

Writing a driver

A driver is a plugin. Put the class in the plugin's classes/html5fw/ and name it after the driver:

// plugins/my_ui/classes/html5fw/yf_html5fw_my_ui.class.php (framework or site plugin; a site plugin drops the yf_ prefix)
load('html5fw_empty', '', 'classes/html5fw/');
class yf_html5fw_my_ui extends yf_html5fw_empty
{
    public $FAMILY = 'my_family';          // templates: name.my_ui.stpl, then name.my_family.stpl, then name.stpl
    public $CAPABILITIES = ['dropdown_js' => true, 'modal_js' => true];
    public $CLASSES = [
        'btn' => ['' => 'ui-btn', '%name' => 'ui-btn ui-btn-%name'],
        'btn_size' => ['xs' => 'ui-btn-xs', 'sm' => 'ui-btn-sm'],
        'alert' => 'ui-alert ui-alert-%name',
        // ... every component of the list above
    ];

    public function form_row($content, $extra = [], $replace = [], $form = null)
    {
        // the row markup of form2 for this framework (see yf_html5fw_bs3::form_row() and yf_html5fw_bs5::form_row())
    }
}
  • Then conf('css_framework', 'my_ui') (or $CONF['css_framework'] = 'my_ui') selects it. No core list names it: html5fw()->names() finds every html5fw_* class of the framework and the plugins.
  • A class with another name or folder is added with html5fw()->register('my_ui', 'my_ui_driver', 'classes/') (from an init hook of the plugin), or $PROJECT_CONF['html5fw']['DRIVERS'] = ['my_ui' => ['my_ui_driver', 'classes/']].
  • A driver that extends another inherits its $FAMILY, $TPL_VARIANTS, $CAPABILITIES and $CLASSES: one extending yf_html5fw_bs5 is in the bootstrap family and reads the .bs5.stpl variants until it sets its own (public $TPL_VARIANTS = null; gives the generic chain of its name and family).
  • Driver names are lower case letters, digits and _, starting with a letter; another css_framework value answers as the default (bs3) in html5fw(). register() refuses such a name, a class name with other characters and a path that is absolute or holds ... names() lists only classes that load and have form_row().
  • The driver methods are form_row(), form_dd_row() and form_render_out(), as in yf_html5fw_empty; extend it (no framework classes) or yf_html5fw_bs3 for Bootstrap-like markup.
  • A driver whose admin works (the layout main, login and menus as .my_ui.stpl variants) declares 'admin' => true in $CAPABILITIES: the admin's framework switcher then offers it (with its public $LABEL, else its name), and the admin UI kit takes its buttons, badges and tables from its class map. A driver without it never reaches the switcher, and the admin kit uses the Bootstrap 3 classes under it.
  • Ship <name>.my_ui.stpl variants of the templates whose markup differs (the layout main, menus, pagination), and the CSS / JS as assets of the plugin.
  • Code that differs per framework asks html5fw()->has() or classes(); is('bs5') stays for markup that only Bootstrap 5 has.

Module markup

Markup a module writes itself keeps its classes in a map of driver => component => classes (the $CLASSES format), usually a public $UI_CLASSES property a project can override, and asks ui_classes():

public $UI_CLASSES = [
    'bs3' => ['badge' => 'label label-%name'],
    'bs5' => ['badge' => ['%name' => 'badge text-bg-%name', 'default' => 'badge text-bg-secondary']],
    '*' => ['badge' => 'label'],      // the html5fw component any other driver takes
];
html5fw()->ui_classes('badge', 'info', $this->UI_CLASSES);   // label label-info (bs3, bs4, empty), badge text-bg-info (bs5)

The driver's own entry comes first; bs4, empty and a driver that cannot be loaded (is_bs3_markup()) then take the bs3 entry, else the bs3 class map; a driver a plugin ships takes its own $CLASSES, for the component named by '*' or the component itself, so a driver can also define a module's component (login_form, search_group). $opts takes size and css_framework, as classes(). The login form, the messages of show_messages(), the FAQ search box, the user dashboard badges and table2's live filter use it; admin modules use the admin kit's classes() with map instead.

The admin UI kit (buttons, badges, tables, tab bars, small inputs and selects) takes its classes from the driver. The widgets of html(), form2 and table2 keep their classes in public properties with a Bootstrap 3 / 5 pair each (BS5_CLASSES); under a plugin driver each such property takes the driver's class map entry that the widget's CLASS_MAP names (CLASS_SELECT_BOX is form_select, table2's CLASS_CONDENSED is table_condensed, the badge templates keep their %name), the Bootstrap 3 value when the map has no such component. A value a project set itself stays. The rest of their markup still carries Bootstrap class names.

The Tailwind CSS driver (preview)

The plugin tailwind ships the driver tw (yf_html5fw_tw, family tailwind): daisyUI 5 component classes on Tailwind CSS 4 (both MIT) and Alpine.js 3 (MIT) for the behaviour Bootstrap's JavaScript gives. It is opt-in:

$CONF['css_framework'] = 'tw';   // the user side; Bootstrap 3 and 5 sites render as before
  • Class map. Every component of the list above, the Bootstrap colour names mapped to daisyUI's: danger, important and error are error, default and inverse the neutral colour (classes('btn', 'danger', ['size' => 'xs']) is btn btn-error btn-xs, classes('badge', 'default') badge badge-neutral). The form rows are those of Bootstrap 5 (the error state on the control) on a 12-column grid; the floating option keeps a normal label.
  • Named variants in form2 and table2. Under a driver of a plugin, the badge and label options take the driver's entry for the colour name ('badge' => ['1' => 'default'] is badge badge-neutral, not badge-default); a template a project set in CLASS_TPL_BADGE / CLASS_TPL_LABEL keeps its %name.
  • Templates. main.tw.stpl (navbar, breadcrumbs, the three columns), style_css.tw.stpl / script_js.tw.stpl (the asset yf_tw) and the user menus (site_nav_bar/*.tw.stpl, submenus as <details>, no script). A site template without a .tw.stpl variant renders its own markup.
  • Stylesheet. plugins/tailwind/assets/dist/yf_tw.min.css is prebuilt and committed: nothing is built on a site. It holds the classes of the driver, of the plugin's templates and of a short list of Bootstrap class names the framework's markup still writes (form-control, panel, col-md-*, label label-*, nav-tabs, pagination, ...) styled the daisyUI way; a rule of that layer goes once nothing that renders under the driver writes its names (table2's table, no-records and very-condensed classes and html's input class are on the class map). A class that is not in the file has no style: write classes of the class map, or a project stylesheet of your own. Light and dark themes follow the browser.
  • Behaviour. The asset alpinejs loads Alpine's CSP build (no eval, so a Content-Security-Policy needs no 'unsafe-eval') with its focus and collapse plugins, deferred; the asset yf_alpine registers the components. The markup names a component and binds its objects, never inline JavaScript:
<div x-data="yfModal"><button type="button" x-bind="opener">Open</button>
  <dialog x-ref="dialog" class="modal"><div class="modal-box">... <button type="button" x-bind="closer">Close</button></div></dialog></div>
<div class="dropdown" x-data="yfDropdown" x-bind="root"><button type="button" x-bind="trigger">Menu</button>
  <ul class="dropdown-content menu" x-ref="menu" x-bind="menu"><li><a href="/a">A</a></li></ul></div>
<div x-data="yfTabs"><div role="tablist" class="tabs tabs-border">
  <a role="tab" class="tab" data-yf-tab="a" x-bind="tab">A</a><a role="tab" class="tab" data-yf-tab="b" x-bind="tab">B</a></div>
  <div data-yf-panel="a" x-bind="panel">...</div><div data-yf-panel="b" x-bind="panel">...</div></div>
<div x-data="yfCollapse"><button type="button" x-bind="trigger">More</button><div x-show="open" x-collapse>...</div></div>
  • Tooltips need no script: daisyUI's tooltip class with data-tip. yfPopover is the dropdown without arrow keys. yf.hover_popover(selector, opts) puts one yfPopover box next to the elements of a selector that no markup can wrap (links in a list): it opens after opts.delay_show ms of hover or on focus, closes when the pointer leaves or on Escape, and fills its title and body from opts.title(el) and opts.load(el, set).
  • Widgets. Under the driver the framework's widgets take its class map: html()'s badge(), button(), panel() / card(), well(), navlist() (a daisyUI menu), tabs() (a daisyUI tab bar; vertical tabs a menu beside the panes) and tooltip() (daisyUI's tooltip with the text in tooltip-content, no script; the text keeps <b>, <i>, <code> and <br> without attributes, every other tag and attribute is dropped and the rest escaped, html()->tooltip_html()), form2's input and textarea classes (CLASS_FORM_CONTROL, and CLASS_TEXTAREA, which follows a site's own CLASS_FORM_CONTROL), table2's responsive wrapper. New class map components form_textarea, well, tooltip, tooltip_content. Also alert() (a daisyUI alert, role="alert", the close button with data-yf-dismiss), breadcrumbs() (daisyUI's breadcrumbs, the last item aria-current="page"; divider is not used), pagination() (a join of buttons, the current page aria-current="page"; align works, size is not used), progress_bar() (one coloured box per value, no stripes or animation) and the menus of dropdown() / navbar(), with the components alert_heading, breadcrumb, page_active, page_disabled, pagination_align, progress, progress_bar, text_align (left, center, right, justify; bs5 right = text-end). For markup a module writes itself, html()->_ui_or($bootstrap, $component, $variant) gives the classes it wrote under the Bootstrap drivers and the driver's component under a UI plugin's driver. Under bs3 / bs5 the widgets write what they wrote before.
  • Bootstrap data attributes. html5fw()->attr('toggle') is data-yf-toggle under the driver. A small script of yf_tw also answers the Bootstrap markup the framework still writes: data-toggle / data-bs-toggle / data-yf-toggle of a dropdown, collapse, tab or modal and data-dismiss of an alert or modal (targets by #id only); open <details> menus close on a click outside or Escape. On a page with jQuery, $(el).modal('show' | 'hide') opens and closes a Bootstrap modal box; the other Bootstrap jQuery plugins (tooltip, popover, dropdown, tab, collapse, alert, button) exist but do nothing, so code that calls them does not fail.
  • htmx. Alpine initialises the components htmx swaps in. A component inside a swapped target loses its state (keep the state outside the target); open dialogs close before htmx saves a history snapshot.
  • Admin. The driver declares admin support: the admin's Interface switcher offers Tailwind CSS next to Bootstrap 3 and 5 (a site that wants only Bootstrap there sets $PROJECT_CONF['ui_prefs']['ADMIN_CSS_FRAMEWORKS_DISCOVER'] = false). The demo html/tailwind shows the components; the framework switcher of the docs site offers the driver as a preview.

Contributors rebuild the stylesheet with make tailwind (the pinned Tailwind CSS standalone CLI of make tools and the daisyUI tarball pinned with its sha512 in plugins/tailwind/tailwind.lock); make tailwind-check rebuilds it and compares, and a unit test fails when a class of the driver is missing from the committed file.