Skip to content

Latest commit

 

History

History
291 lines (208 loc) · 11.2 KB

view_components.md

File metadata and controls

291 lines (208 loc) · 11.2 KB

View Components

View Components (or just Components) allow you to create custom HTML elements to use within your views. The main description of their use and creating new ones is described within the Building Sites section of the guide. This page lists the components that are available within the default Admin theme.

Your app renders its own copy of these components, in themes/Admin/Components/, which composer update doesn't change. See Why Themes Are Published Into Your App.

Escape attribute values with esc() (title="<?= esc($user->name()) ?>"), as you would any HTML attribute. The renderer decodes them and the component escapes them again on output, so a quote in the data can't end the attribute early. On a paired tag (<x-…>…</x-…>) a value can't contain >. Slots are HTML and are output as given.

Page structure

<x-page-head>

The page header. Give it a title and it renders the design's head: an <h1>, an optional count badge or subtitle, an optional back link (backLabel names it, defaulting to "Back"), and the slot as actions on the right.

<x-page-head title="Users" count="<?= $total ?>">
    <a href="<?= url_to('user-new') ?>" class="btn btn-primary">New user</a>
</x-page-head>

<x-page-head title="<?= esc($user->displayName()) ?>" back="<?= esc(site_url(ADMIN_AREA . '/users')) ?>" backLabel="<?= esc(lang('Users.usersModTitle')) ?>" />

Without a title it wraps the slot as before, so existing <x-page-head><h2>…</h2></x-page-head> headers keep working.

<x-admin-box>

A card section. The optional title and description render a header. Setting rows and tables inside it run edge to edge; put buttons in a <div class="bf-card-footer"> as the last child for a footer.

<x-admin-box title="Site" description="How the site presents itself.">
    …
</x-admin-box>

<x-tabs>

Underline tabs. The slot holds Bootstrap nav-item list items, so service('resourceTabs')->renderTabsFor() output fits in it.

<x-tabs>
    <li class="nav-item"><a class="nav-link active" href="<?= $user->adminLink() ?>">Details</a></li>
    <?= service('resourceTabs')->renderTabsFor('user') ?>
</x-tabs>

<x-settings-layout>

The frame of a settings page: a "Settings" page head, a sub-nav of the sidebar's settings collection (only the pages the user may open, the current one marked), and the slot beside it. Register your module's settings page in that collection and wrap the page in it.

<x-settings-layout>
    <form action="<?= site_url(ADMIN_AREA . '/settings/blog') ?>" method="post">
        <?= csrf_field() ?>
        <x-admin-box title="Posts">…</x-admin-box>
        <x-save-bar />
    </form>
</x-settings-layout>

<x-sidebar>

The admin sidebar: the site's brand, a Dashboard link, then the sidebar menu's collections and items that the current user may see, with the current page marked. It takes no attributes. The Admin layout (master.php) renders it once, so you don't place it yourself: add your module's links to the sidebar menu instead (see Menus).

<x-sidebar />

Settings forms

<x-setting-row>

A label and description on the left, the control (the slot) on the right. Wraps on narrow screens. for points the label at the control's id.

<x-setting-row label="Site name" description="Shown in the admin." for="siteName">
    <input type="text" class="form-control" id="siteName" name="siteName" value="<?= esc($siteName) ?>">
</x-setting-row>

<x-switch>

An accessible role="switch" checkbox. A hidden input posts offValue (default 0) when it is off; value (default 1) posts when it is on. Give it an empty offValue to post nothing when off, as for an array name like permissions[] that should hold only the checked values. checked turns it on unless it is empty, 0 or false; label becomes its aria-label. Any other attribute (id, x-model, disabled, …) goes on the checkbox.

<x-switch name="siteOnline" label="Site online" checked="<?= setting('Site.siteOnline') ? '1' : '' ?>" />
<x-switch name="permissions[]" offValue value="users.edit" checked="<?= $canEdit ? '1' : '' ?>" />

<x-segmented>

A radio group styled as a segmented control. options is a JSON object of value => label; wrap it in single quotes.

<x-segmented name="timeFormat" label="Time format" value="<?= $timeFormat ?>"
    options='<?= json_encode(['g:i A' => '12-hour', 'H:i' => '24-hour'], JSON_HEX_APOS) ?>' />

<x-save-bar>

A sticky "Unsaved changes · Discard · Save" bar for long forms. Put it inside the <form>: it appears once a field changes, Discard resets the form, and Save submits it. save relabels the Save button. Without JavaScript it is always shown, so the form can still be submitted.

<form method="post" action="…">
    …
    <x-save-bar save="Save settings" />
</form>

Lists

<x-chip>

A pill filter with an optional count. With an href it is a link (active marks the current one). With a name it is a radio input for a filter form, checked when active; give the chips one name and each its own value. With neither it is a toggle button. Other attributes (hx-get, hx-target, …) pass through.

<x-chip label="Admins" count="3" href="?group=admin" active="<?= $group === 'admin' ? '1' : '' ?>" />

<x-chip name="role" value="admin" label="Admins" count="3" active="<?= $role === 'admin' ? '1' : '' ?>" />

<x-status>

A coloured dot and a label. tone is ok, warn, danger, info or muted (the default).

<x-status tone="ok" label="Active" />

<x-empty-state>

A centered title and optional hint for a list with nothing in it.

<x-empty-state title="No users match" hint="Try a different search or group." />

<x-selection-bar>

A sticky bar showing "N selected" while any row checkbox (tbody input[type=checkbox]) in its form is checked. The slot holds the bulk actions; the ✕ clears the selection.

<form method="post">
    <?= csrf_field() ?>
    <table class="table">…</table>
    <x-selection-bar>
        <x-bulk-actions list="users" />
    </x-selection-bar>
</form>

<x-bulk-actions>

The bulk actions of the list, as buttons that post the form's checked selects[]. Place it inside <x-selection-bar>.

<x-row-actions>

A row's menu: its slot (links like Edit), then the row actions of the list for the record id.

<x-row-actions list="users" id="<?= $user->id ?>">
    <li><a href="<?= $user->adminLink() ?>" class="dropdown-item">Edit</a></li>
</x-row-actions>

<x-confirm-dialog> and <x-action-run>

Both sit once in the Admin layout (master.php). <x-confirm-dialog> asks before actions, hx-confirm requests and data-confirm links and buttons go ahead (see Confirmation), and renders the form <x-row-actions> submits, so row actions need it even without JavaScript. <x-action-run>, inside the toasts, shows the progress of an action run just queued.

Buttons and filters

<x-button>

A Bootstrap button with the slot as its label.

Attribute Default Description
color primary A Bootstrap colour (secondary, success, danger, …): btn-{color}.
type submit The button's type: submit, reset or button.
id The button's id.
name The button's name, posted with the form when it submits it.
onclick A JavaScript onclick handler.

It drops any other attribute, so for hx-*, Alpine or disabled write a <button class="btn …"> yourself.

<x-button>Save</x-button>
<x-button color="secondary" type="button" id="preview">Preview</x-button>

<x-button-container>

Wraps a form's buttons with uniform spacing. It takes no attributes.

<x-button-container>
    <x-button>Save</x-button>
</x-button-container>

<x-module-title>

A muted line of text for page headers, with the slot as its text. It takes no attributes.

<x-module-title>Manage the site's users</x-module-title>

<x-filter-link>

The "Filter" link that shows and hides the filters of a resource list. It takes no attributes and no slot. It toggles an Alpine filtered variable, so put it inside an element with x-data="{filtered: false}". See Filters.

<x-filter-list>

The panel that holds a resource list's filters, shown while filtered is true. It takes no attributes; the slot is the filters, usually the Filters::renderList cell.

<div x-data="{filtered: false}" hx-target="#content-list">
    <x-filter-link />

    <div class="row">
        <div class="col order-2 order-md-1" id="content-list">
            <?= $this->include('Blog\Views\_table') ?>
        </div>

        <x-filter-list>
            <?= view_cell('Bonfire\Core\Cells\Filters::renderList', 'model=PostFilter target=#content-list') ?>
        </x-filter-list>
    </div>
</div>

Pager templates

Bonfire registers six pager templates. Name one when you render the links:

<?= $pager->links('default', 'bonfire_list_hx') ?>
Template Renders htmx target
bonfire_full First, Previous, two page numbers either side, Next, Last. None (full page loads)
bonfire_full_hx The same links, loaded through htmx. #content-list
bonfire_simple Newer and Older links. None (full page loads)
bonfire_simple_hx Newer and Older links, loaded through htmx. #content-list
bonfire_list_hx The admin list footer: "Showing X of Y" with Previous and Next buttons, loaded through htmx. The nearest hx-target ancestor
bonfire_head <link rel="prev">, <link rel="canonical"> and <link rel="next"> tags. —

The page-link templates render nothing when there is only one page; bonfire_list_hx still shows its "Showing" line.

bonfire_full_hx and bonfire_simple_hx swap the response into #content-list, so give the element that holds your list that id. bonfire_list_hx sets no target of its own: put hx-target (and any hx-include) on an element that wraps the list, as in the Filters example.

bonfire_head belongs in the page's <head>, so search engines can follow the pages:

<?= $pager->links('default', 'bonfire_head') ?>

The templates are package views in src/Views/, not part of the published theme, so composer update updates them. To change one, register your own template in app/Config/Pager.php and use its name instead.