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,bs4andempty:<name>.stplonly, as before the driver API: a.bootstrap.stplor.bs3.stplfile 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 everyhtml5fw_*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,$CAPABILITIESand$CLASSES: one extendingyf_html5fw_bs5is in thebootstrapfamily and reads the.bs5.stplvariants 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; anothercss_frameworkvalue answers as the default (bs3) inhtml5fw().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 haveform_row(). - The driver methods are
form_row(),form_dd_row()andform_render_out(), as inyf_html5fw_empty; extend it (no framework classes) oryf_html5fw_bs3for Bootstrap-like markup. - A driver whose admin works (the layout
main, login and menus as.my_ui.stplvariants) declares'admin' => truein$CAPABILITIES: the admin's framework switcher then offers it (with itspublic $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.stplvariants of the templates whose markup differs (the layoutmain, menus, pagination), and the CSS / JS as assets of the plugin. - Code that differs per framework asks
html5fw()->has()orclasses();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,importantanderrorareerror,defaultandinversethe neutral colour (classes('btn', 'danger', ['size' => 'xs'])isbtn 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; thefloatingoption keeps a normal label. - Named variants in form2 and table2. Under a driver of a plugin, the
badgeandlabeloptions take the driver's entry for the colour name ('badge' => ['1' => 'default']isbadge badge-neutral, notbadge-default); a template a project set inCLASS_TPL_BADGE/CLASS_TPL_LABELkeeps its%name. - Templates.
main.tw.stpl(navbar, breadcrumbs, the three columns),style_css.tw.stpl/script_js.tw.stpl(the assetyf_tw) and the user menus (site_nav_bar/*.tw.stpl, submenus as<details>, no script). A site template without a.tw.stplvariant renders its own markup. - Stylesheet.
plugins/tailwind/assets/dist/yf_tw.min.cssis 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
alpinejsloads Alpine's CSP build (noeval, so a Content-Security-Policy needs no'unsafe-eval') with its focus and collapse plugins, deferred; the assetyf_alpineregisters 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
tooltipclass withdata-tip.yfPopoveris the dropdown without arrow keys.yf.hover_popover(selector, opts)puts oneyfPopoverbox next to the elements of a selector that no markup can wrap (links in a list): it opens afteropts.delay_showms of hover or on focus, closes when the pointer leaves or on Escape, and fills its title and body fromopts.title(el)andopts.load(el, set). - Widgets. Under the driver the framework's widgets take its class map:
html()'sbadge(),button(),panel()/card(),well(),navlist()(a daisyUI menu),tabs()(a daisyUI tab bar; vertical tabs a menu beside the panes) andtooltip()(daisyUI's tooltip with the text intooltip-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, andCLASS_TEXTAREA, which follows a site's ownCLASS_FORM_CONTROL), table2'sresponsivewrapper. New class map componentsform_textarea,well,tooltip,tooltip_content. Alsoalert()(a daisyUI alert,role="alert", the close button withdata-yf-dismiss),breadcrumbs()(daisyUI's breadcrumbs, the last itemaria-current="page";divideris not used),pagination()(ajoinof buttons, the current pagearia-current="page";alignworks,sizeis not used),progress_bar()(one coloured box per value, no stripes or animation) and the menus ofdropdown()/navbar(), with the componentsalert_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')isdata-yf-toggleunder the driver. A small script ofyf_twalso answers the Bootstrap markup the framework still writes:data-toggle/data-bs-toggle/data-yf-toggleof a dropdown, collapse, tab or modal anddata-dismissof an alert or modal (targets by#idonly); 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.