CSS Class Mapping
The CSS class mapping system decouples widget and plugin template markup from any specific CSS framework. Widgets render correctly under Bootstrap, Tailwind, Bulma, or custom CSS simply by switching themes.
How It Works
- Theme declares:
css_class_mappingintheme_info.jsonmaps semantic keys to CSS class strings - Templates use:
{{ cls.key_name }}in.tplfiles outputs the mapped class - ThemeService injects: the
clsobject is available as a global template variable
<div class="{{ cls.cls_widget }}">
<h3 class="{{ cls.cls_title }}">{{ title }}</h3>
<ul class="{{ cls.cls_list_group }}">
{% for item in items %}
<li class="{{ cls.cls_list_group_item }}">{{ item.title }}</li>
{% endfor %}
</ul>
</div>
Key Categories
The mapping covers 100+ keys in these categories:
- Widget shell:
cls_widget,cls_title,cls_widget_body - Layout:
cls_container,cls_row,cls_col,cls_col_main,cls_col_sidebar - Typography:
cls_h1–cls_h4,cls_lead,cls_text_muted - Buttons:
cls_btn_primary,cls_btn_secondary,cls_btn_sm,cls_btn_lg - Cards:
cls_card,cls_card_body,cls_card_title,cls_card_img_top - Lists:
cls_list_group,cls_list_group_item,cls_list_unstyled - Tables:
cls_table,cls_table_striped,cls_table_responsive - Forms:
cls_form_control,cls_form_label,cls_form_select - Alerts:
cls_alert_success,cls_alert_danger,cls_alert_warning - Pagination:
cls_pager_list,cls_pager_item,cls_pager_link - Badges:
cls_badge,cls_badge_primary - Navigation:
cls_nav,cls_nav_item,cls_breadcrumb - Display/flex:
cls_d_flex,cls_align_center,cls_justify_between - Spacing:
cls_mb_1–cls_mb_4,cls_mt_1–cls_mt_4,cls_p_3
Undefined Keys
Accessing an undefined mapping key returns an empty string — no error. Widgets using keys not in an older theme's mapping degrade gracefully (class is absent).
Extending the Mapping
If a widget needs a class not covered by standard keys, add a new key to the theme's css_class_mapping and document it as a theme requirement. Never hardcode classes from a specific theme — they will not work on other themes.