Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

CakePHP: Transparently use Bootstrap

License

NotificationsYou must be signed in to change notification settings

FriendsOfCake/bootstrap-ui

Repository files navigation

Build StatusCoverage StatusTotal DownloadsLicense

Transparently useBootstrap 5 withCakePHP 5.

For version info seeversion map.

Requirements

  • CakePHP 5.x
  • Bootstrap 5.3.x
  • npm 6.x
  • Bootstrap Icons 1.11.x

What's included?

  • FlashHelper (element types:error,info,success,warning)
  • FormHelper (align:default,inline,horizontal)
  • BreadcrumbsHelper
  • HtmlHelper (components:badge,icon)
  • PaginatorHelper
  • Widgets (basic,button,datetime,file,select,textarea)
  • Example layouts (cover,signin,dashboard)
  • Bake templates

Table of contents

Installation

cd to the root of your app folder (where thecomposer.json file is) and run the followingComposercommand:

composer require friendsofcake/bootstrap-ui

Then load the plugin using CakePHP's console:

bin/cake plugin load BootstrapUI

Setup

You can either use the Bootstrap commands to make the necessary changes, or do them manually.

Using the Bootstrap commands

  1. To install the Bootstrap assets (Bootstrap's CSS/JS files) via npm you can use theinstallcommand, orinstall them manually:

    bin/cake bootstrap install

    This will fetch all assets, copy the distribution assets to the BootstrapUI plugin's webroot directory, and symlink(or copy) them to your application'swebroot directory.

    If you want to install the latest minor versions of the assets instead of the exact pinned ones, you can use the--latest option:

    bin/cake bootstrap install --latest

  2. You will need to modify yoursrc/View/AppView class to either extendBootstrapUI\View\UIView oruse the traitBootStrapUI\View\UIViewTrait. For doing this you can either use themodify_view command, orchange your view manually:

    bin/cake bootstrap modify_view

    This will rewrite yoursrc/View/AppView like described inAppView setup using UIView.

  3. BootstrapUI ships with some example layouts. You can install them using thecopy_layouts command, orcopy them manually:

    bin/cake bootstrap copy_layouts

    This will copy the three example layoutscover.php,dashboard.php andsignin.php to your application'ssrc/templates/layout/TwitterBootstrap.

Manual setup

Installing Bootstrap assets via npm

Thetheinstall command installs the Bootstrap assets vianpm, which you can alsodo manually if you wish to control which assets are being included, and where they are placed.

Assuming you are in your application's root:

npm install bootstrap@5 bootstrap-icons@1mkdir -p webroot/cssmkdir -p webroot/font/fontsmkdir -p webroot/jscp node_modules/bootstrap/dist/css/bootstrap.css webroot/css/cp node_modules/bootstrap/dist/css/bootstrap.min.css webroot/css/cp node_modules/bootstrap/dist/js/bootstrap.bundle.js webroot/js/cp node_modules/bootstrap/dist/js/bootstrap.bundle.min.js webroot/js/cp node_modules/bootstrap-icons/font/bootstrap-icons.css webroot/font/cp node_modules/bootstrap-icons/font/fonts/bootstrap-icons.woff webroot/font/fonts/cp node_modules/bootstrap-icons/font/fonts/bootstrap-icons.woff2 webroot/font/fonts/cp vendor/friendsofcake/bootstrap-ui/webroot/font/bootstrap-icon-sizes.css webroot/font/

AppView setup using UIView

For a quick setup, just make yourAppView class extendBootstrapUI\View\UIView. The base class will handlethe initializing and loading of the BootstrapUIdefault.php layout for your app.

Thesrc\View\AppView.php will look something like the following:

declare(strict_types=1);namespaceApp\View;useBootstrapUI\View\UIView;class AppViewextends UIView{/**     * Initialization hook method.     */publicfunctioninitialize():void    {// Don't forget to call parent::initialize()parent::initialize();    }}

AppView setup using UIViewTrait

If you're adding BootstrapUI to an existing application, it might be easier to use the trait, as it gives you morecontrol over the loading of the layout.

declare(strict_types=1);namespaceApp\View;useBootstrapUI\View\UIViewTrait;useCake\View\View;class AppViewextends View{use UIViewTrait;/**     * Initialization hook method.     */publicfunctioninitialize():void    {parent::initialize();// Call the initializeUI method from UIViewTrait$this->initializeUI();    }}

Copying example layouts

In order to be able to use the BootstrapUI example layouts (directly taken from the Bootstrap examples), they need to becopied to your application's layouts directory, either by usingthecopy_layouts command, or by copying the files manually:

cp -R vendor/friendsofcake/bootstrap-ui/templates/layout/examples templates/layout/TwitterBootstrap

BootstrapUI layouts

BootstrapUI comes with its owndefault.php layout file and examples taken from the Bootstrap framework.

When no layout for the view is defined, theBootstrapUI\View\UIViewTrait will load its owndefault.php layout file.You can override this behavior in two ways.

  • Assign a layout to the template with$this->setLayout('layout').
  • Disable auto loading of the layout inBootstrapUI\View\UIViewTrait by adding$this->initializeUI(['layout' => false]); to yourAppView'sinitialize() function.

Using the example layouts

Once copied into your application's layouts directory (being it viathecopy_layouts command ormanually), you can simplyextend the example layouts in your views like so:

$this->extend('../layout/TwitterBootstrap/dashboard');

Available types are:

  • cover
  • signin
  • dashboard

NOTE: Remember to set the stylesheets in the layouts you copy.

Including the Bootstrap framework

If you are usingthe BoostrapUI plugin's default layout, and you have installed the Bootstrapassets usingtheinstall command, the required assets should automatically beincluded.

If you wish to use your own layout template, then you need to take care of including the required CSS/JS files yourself.

If you have installed the assets usingtheinstall command, you can refer tothem using the standard plugin syntax:

// in the <head>echo$this->Html->css('BootstrapUI.bootstrap.min');echo$this->Html->css(['BootstrapUI./font/bootstrap-icons','BootstrapUI./font/bootstrap-icon-sizes']);echo$this->Html->script(['BootstrapUI.bootstrap.bundle.min']);

If you have installed the assets manually, you'll need to use paths accordingly. Withthe example copy commands you could use the standard short path syntax:

echo$this->Html->css('bootstrap.min');echo$this->Html->css(['/font/bootstrap-icons','/font/bootstrap-icon-sizes']);echo$this->Html->script(['bootstrap.bundle.min']);

If you're using paths that don't adhere to the CakePHP conventions, you'll have to explicitly specify them:

echo$this->Html->css('/path/to/bootstrap.css');echo$this->Html->css(['/path/to/bootstrap-icons.css','/path/to/bootstrap-icon-sizes.css']);echo$this->Html->script(['/path/to/bootstrap.bundle.js']);

Bake templates

For those of you who want even more automation, some bake templates have been included. Use them like so:

bin/cake bake [subcommand] -t BootstrapUI

Currently, bake templates for the following bake subcommands are included:

template

Additionally to the defaultindex,add,edit, andview templates, alogin template is available too. Whilethe default CRUD action view templates can be utilized like this:

bin/cake bake template ControllerName -t BootstrapUI

thelogin template has to be used explicitly by specifying the action name:

bin/cake bake template ControllerName login -t BootstrapUI

Usage

At the core of BootstrapUI is a collection of enhancements for CakePHP core helpers. Among other things, these helpersreplace the HTML templates used to render elements for the views. This allows you to create forms and components thatuse the Bootstrap styles.

The current list of enhanced helpers are:

  • BootstrapUI\View\Helper\FlashHelper
  • BootstrapUI\View\Helper\FormHelper
  • BootstrapUI\View\Helper\HtmlHelper
  • BootstrapUI\View\Helper\PaginatorHelper
  • BootstrapUI\View\Helper\BreadcrumbsHelper

When theBootstrapUI\View\UIViewTrait is initialized it loads the above helpers with the same aliases as theCakePHP core helpers. That means that when you use$this->Form->create() in your views, the helper being usedis from the BootstrapUI plugin.

Basic forms

echo$this->Form->create($article);echo$this->Form->control('title');echo$this->Form->control('published', ['type' =>'checkbox']);echo$this->Form->button('Submit');echo$this->Form->end();

will render this HTML:

<formmethod="post"accept-charset="utf-8"action="/articles/add"><!-- ... --><divclass="mb-3 text"><labelclass="form-label"for="title">Title</label><inputtype="text"name="title"id="title"class="form-control"></div><divclass="mb-3 form-check checkbox"><inputtype="hidden"name="published"value="0"><inputtype="checkbox"class="form-check-input"name="published"value="1"id="published"><labelclass="form-check-label"for="published">Published</label></div><buttontype="submit"class="btn btn-secondary">Submit</button><!-- ... --></form>

Horizontal forms

Horizontal forms automatically render labels and controls in separate columns (where applicable), labels in th firstone, and controls in the second one.

Alignment can be configured via thealign option, which takes either a list of column sizes for themdBootstrap screen-size/breakpoint, or a matrix ofscreen-size/breakpoint names and column sizes.

The following will use the defaultmd screen-size/breakpoint:

useBootstrapUI\View\Helper\FormHelper;echo$this->Form->create($article, ['align' => [        FormHelper::GRID_COLUMN_ONE =>4,// first column (span over 4 columns)        FormHelper::GRID_COLUMN_TWO =>8,// second column (span over 8 columns)    ],]);echo$this->Form->control('title');echo$this->Form->control('published', ['type' =>'checkbox']);echo$this->Form->submit();echo$this->Form->end();

It will render this HTML:

<formmethod="post"accept-charset="utf-8"class="form-horizontal"action="/articles/add"><!-- ... --><divclass="mb-3 row text"><labelclass="col-form-label col-md-4"for="title">Title</label><divclass="col-md-8"><inputtype="text"name="title"id="title"class="form-control"></div></div><divclass="mb-3 row checkbox"><divclass="offset-md-4 col-md-8"><divclass="form-check"><inputtype="hidden"name="published"value="0"/><inputtype="checkbox"name="published"value="1"id="published"class="form-check-input"/><labelclass="form-check-label"for="published">Published</label></div></div></div><!-- ... --><buttontype="submit"class="btn btn-secondary">Submit</button></form>

The following uses a matrix of screen-sizes/breakpoints and column sizes:

useBootstrapUI\View\Helper\FormHelper;echo$this->Form->create($article, ['align' => [// column sizes for the `sm` screen-size/breakpoint'sm' => [            FormHelper::GRID_COLUMN_ONE =>6,            FormHelper::GRID_COLUMN_TWO =>6,        ],// column sizes for the `md` screen-size/breakpoint'md' => [            FormHelper::GRID_COLUMN_ONE =>4,            FormHelper::GRID_COLUMN_TWO =>8,        ],    ],]);echo$this->Form->control('title');echo$this->Form->control('published', ['type' =>'checkbox']);echo$this->Form->button('Submit');echo$this->Form->end();

It will render this HTML:

<formmethod="post"accept-charset="utf-8"action="/articles/add"><!-- ... --><divclass="mb-3 row text"><labelclass="col-form-label col-sm-6 col-md-4"for="title">Title</label><divclass="col-sm-6 col-md-8"><inputtype="text"name="title"id="title"class="form-control"></div></div><divclass="mb-3 row checkbox"><divclass="offset-sm-6 offset-md-4 col-sm-6 col-md-8"><divclass="form-check"><inputtype="hidden"name="published"value="0"/><inputtype="checkbox"name="published"value="1"id="published"class="form-check-input"/><labelclass="form-check-label"for="published">Published</label></div></div></div><!-- ... --><buttontype="submit"class="btn btn-secondary">Submit</button></form>

The default alignment will use themd screen-size/breakpoint and the following column sizes:

[    FormHelper::GRID_COLUMN_ONE =>2,    FormHelper::GRID_COLUMN_TWO =>10,]

Inline forms

Inline forms will render controls on one and the same row, and hide labels for most controls.

echo$this->Form->create($article, ['align' =>'inline',]);echo$this->Form->control('title', ['placeholder' =>'Title']);echo$this->Form->control('published', ['type' =>'checkbox']);echo$this->Html->div('col-auto',$this->Form->button('Submit'));echo$this->Form->end();

will render this HTML:

<formmethod="post"accept-charset="utf-8"action="/articles/add"><!-- ... --><divclass="col-auto"><divclass="text"><labelclass="form-label visually-hidden"for="title">Title</label><inputtype="text"name="title"placeholder="Title"id="title"class="form-control"/></div></div><divclass="col-auto"><divclass="form-check checkbox"><inputtype="hidden"name="published"value="0"/><inputtype="checkbox"name="published"value="1"id="published"class="form-check-input"><labelclass="form-check-label"for="published">Published</label></div></div><!-- ... --><divclass="col-auto"><buttontype="submit"class="btn btn-secondary">Submit</button></div></form>

Spacing

Out of the box BootstrapUI applies some default spacing for form controls. For default and horizontal aligned forms,themb-3spacing class is being applied to all controls,while inline forms are using theg-3gutter class.

This can be changed using thespacing option, it applies on a per-helper and per-form basis for all alignments, andfor default/horizontal alignments it also applies on a per-control basis.

// for all formsecho$this->Form->setConfig(['spacing' =>'mb-6',]);
// for a specific formecho$this->Form->create($entity, ['spacing' =>'mb-6',]);
// for a specific control (default/horizontal aligned forms only)echo$this->Form->control('title', ['spacing' =>'mb-6',]);

To completely disable this behavior, set thespacing option tofalse.

Supported controls

BootstrapUI supports and generates Bootstrap compatible markup for all of CakePHP's default controls. Additionally itexplicitly supports Bootstrap specific markup for the following controls:

  • color
  • range
  • switch

Container attributes

Attributes of the outer control container can be changed via thecontainer option, cutting the need to use customtemplates for simple changes. Theclass attribute is a special case, its value will be prepended to the existinglist of classes instead of replacing it.

echo$this->Form->control('title', ['container' => ['class' =>'my-title-control','data-meta' =>'meta information',    ],]);

This would generate the following HTML:

<divdata-meta="meta information"class="my-title-control mb-3 text"><labelclass="form-label"for="title">Title</label><inputtype="text"name="title"id="title"class="form-control"></div>

Appending/Prepending content

Appending/Prepending content to input groups is supported via theappend andprepend options respectively.

echo$this->Form->control('email', ['prepend' =>'@',]);

This would generate the following HTML:

<divclass="mb-3 email"><labelclass="form-label"for="email">Email</label><divclass="input-group"><spanclass="input-group-text">@</span><inputtype="email"name="email"id="email"class="form-control"/></div></div>

Multiple addons

Multiple addons can be defined as an array for theappend andprepend options:

echo$this->Form->control('amount', ['prepend' => ['$','0.00'],]);

This would generate the following HTML:

<divclass="mb-3 text"><labelclass="form-label"for="amount">Amount</label><divclass="input-group"><spanclass="input-group-text">$</span><spanclass="input-group-text">0.00</span><inputtype="text"name="amount"id="amount"class="form-control"/></div></div>

Addon options

Addons support options that apply to the input group container. They can be defined by passing an array for theappendandprepend options, and adding an array with options as the last entry.

Options can contain HTML attributes as know from control options, as well as the specialsize option, whichautomatically translates to the corresponding input group size class.

echo$this->Form->control('amount', ['prepend' => ['$','0.00',        ['size' =>'lg','class' =>'custom','custom' =>'attribute',        ],    ],]);

This would generate the following HTML:

<divclass="mb-3 text"><labelclass="form-label"for="amount">Amount</label><divclass="input-group input-group-lg custom"custom="attribute"><spanclass="input-group-text">$</span><spanclass="input-group-text">0.00</span><inputtype="text"name="amount"id="amount"class="form-control"/></div></div>

Inline checkboxes and radio buttons

Inline checkboxes/switches and radio buttons (not to beconfused with inline aligned forms), can be created by setting theinline option totrue.

Inlined checkboxes/switches and radio buttons will be rendered on the same horizontal row. When using horizontal formalignment however, only multi-checkboxes will render on the same row!

echo$this->Form->control('option_1', ['type' =>'checkbox','inline' =>true,]);echo$this->Form->control('option_2', ['type' =>'checkbox','inline' =>true,]);

This would generate the following HTML:

<divclass="mb-3 form-check form-check-inline checkbox"><inputtype="hidden"name="option-1"value="0"/><inputtype="checkbox"name="option-1"value="1"id="option-1"class="form-check-input"><labelclass="form-check-label"for="option-1">Option 1</label></div><divclass="mb-3 form-check form-check-inline checkbox"><inputtype="hidden"name="option-2"value="0"/><inputtype="checkbox"name="option-2"value="2"id="option-2"class="form-check-input"><labelclass="form-check-label"for="option-2">Option 2</label></div>

Switches

Switch style checkboxes can be created by setting theswitch option totrue.

echo$this->Form->control('option', ['type' =>'checkbox','switch' =>true,]);

This would generate the following HTML:

<divclass="mb-3 form-check form-switch checkbox"><inputtype="hidden"name="option"value="0"/><inputtype="checkbox"name="option"value="1"id="option"class="form-check-input"><labelclass="form-check-label"for="option">Option</label></div>

Floating labels

Floating labels are supported fortext,textarea, and(non-multiple)select controls. They can be enabled via the label'sfloating option:

echo$this->Form->control('title', ['label' => ['floating' =>true,    ],]);

This would generate the following HTML:

<divclass="mb-3 form-floating text"><inputtype="text"name="title"id="title"class="form-control"/><labelfor="title">Title</label></div>

Help text

Bootstrap'sform help text is supported via thehelp option.

The help text is by default being rendered in between of the control and the validation feedback.

echo$this->Form->control('title', ['help' =>'Help text',]);

This would generate the following HTML:

<divclass="mb-3 text"><labelclass="form-label"for="title">Title</label><inputtype="text"name="title"id="title"class="form-control"aria-describedby="title-help"/><smallid="title-help"class="d-block form-text text-muted">Help text</small></div>

Attributes can be configured by passing an array for thehelp option, where the text is then defined in thecontentkey:

echo$this->Form->control('title', ['help' => ['id' =>'custom-help','class' =>'custom','data-custom' =>'attribute','content' =>'Help text',    ],]);

This would generate the following HTML:

<divclass="mb-3 text"><labelclass="form-label"for="title">Title</label><inputtype="text"name="title"id="title"class="form-control"aria-describedby="custom-help"/><smallid="custom-help"class="custom d-block form-text text-muted"data-custom="attribute">Help text</small></div>

Tooltips

Bootstrap tooltips can be added to labels via thetooltipoption. The tooltip toggles are by default being rendered as aBootstrap icon, whichis being included by default when installing the assets via theinstall command.

echo$this->Form->control('title', ['tooltip' =>'Tooltip text',]);

This would generate the following HTML:

<divclass="mb-3 text"><labelclass="form-label"for="title">        Title<spandata-bs-toggle="tooltip"title="Tooltip text"class="bi bi-info-circle-fill"></span></label><inputtype="text"name="title"id="title"class="form-control"/></div>

If you want to use a different toggle, being it a different Boostrap icon, or maybe a completely different iconfont/library, then you can do this byoverriding thetooltip templateaccordingly, being it globally, per form, or per control:

echo$this->Form->control('title', ['tooltip' =>'Tooltip text','templates' => ['tooltip' =>'<span data-bs-toggle="tooltip" title="{{content}}">info</span>',    ],]);

Error feedback style

BootstrapUI supports two styles of error feedback, theregular Bootstrap text feedback, andBootstrap tooltip feedback (not to be confused withlabel tooltips that are configured via thetooltip option!).

The style can be configured via thefeedbackStyle option, either globally, per form, or per control. The supportedstyles are:

  • \BootstrapUI\View\Helper\FormHelper::FEEDBACK_STYLE_DEFAULT Render error feedback as regular Bootstrap textfeedback.
  • \BootstrapUI\View\Helper\FormHelper::FEEDBACK_STYLE_TOOLTIP Render error feedback as Bootstrap tooltip feedback(inline forms are using this style by default).

Note that using the tooltip error style requires the form group elements to be non-static positioned! The form helperwill automatically add Bootstrapsposition utility classposition-relative to the form group elements when the tooltip error style is enabled.

If you need different positioning, use either CSS to override theposition rule on the.form-group elements, or usetheformGroupPosition option to set your desired position, either globally, per form, or per control. The optionsupports the following values:

  • \BootstrapUI\View\Helper\FormHelper::POSITION_ABSOLUTE
  • \BootstrapUI\View\Helper\FormHelper::POSITION_FIXED
  • \BootstrapUI\View\Helper\FormHelper::POSITION_RELATIVE
  • \BootstrapUI\View\Helper\FormHelper::POSITION_STATIC
  • \BootstrapUI\View\Helper\FormHelper::POSITION_STICKY
$this->Form->setConfig(['feedbackStyle' => \BootstrapUI\View\Helper\FormHelper::FEEDBACK_STYLE_TOOLTIP,'formGroupPosition' => \BootstrapUI\View\Helper\FormHelper::POSITION_ABSOLUTE,]);// ...echo$this->Form->control('title');

With an error on thetitle field, this would generate the following HTML:

<divclass="mb-3 position-absolute text is-invalid"><labelclass="form-label"for="title">Title</label><inputtype="text"name="title"id="title"class="is-invalid form-control"/><divclass="invalid-tooltip">Error message</div></div>

Flash Messages / Alerts

You can set Flash Messages using the default Flash component syntax. Supported types aresuccess,info,warning,error.

$this->Flash->success('Your Success Message.');

Alert styles

If you need to set other Bootstrap Alert styles you can do this with:

$this->Flash->set('Your Dark Message.', ['params' => ['class' =>'dark']]);

Supported styles areprimary,secondary,light,dark.

Icons

By default alerts use Bootstrap icons depending on the alert type. The mapped types aredefault,info,warning,error, andsuccess. You can disable/customize icons via theicon option/parameter, either globally for the flashhelper, or individually for a single message.

Message without icon:

$this->Flash->success('Message without icon.', ['params' => ['icon' =>false,    ],]);

Use a custom icon:

$this->Flash->success('Message with custom icon.', ['params' => ['icon' =>'mic-mute-fill',    ],]);

Pass icon options (the icon name is optional here, when omitted, the default icon map will be looked up):

$this->Flash->success('Message with custom icon options.', ['params' => ['icon' => ['name' =>'mic-mute-fill','size' =>'2xl','class' =>'foo bar me-2','data-custom' =>'attribute',        ],    ],]);
<iclass="foo bar me-2 bi bi-mic-mute-fill bi-2xl"data-custom="attribute"></i>

Use custom HTML:

$this->Flash->success('Message with custom icon HTML.', ['params' => ['icon' =>'<span>volume_off</span>',    ],]);

Disable icons for all flash messages:

$this->loadHelper('Flash', ['className' =>'BootstrapUI.Flash','icon' =>false,]);

Set icon options for all flash messages (the default icon map will be used, and the options will be applied to allicons):

$this->loadHelper('Flash', ['className' =>'BootstrapUI.Flash','icon' => ['size' =>'2xl','class' =>'foo bar me-2','data-custom' =>'attribute',    ],]);

Define a custom icon map:

$this->loadHelper('Flash', ['className' =>'BootstrapUI.Flash','iconMap' => ['default' =>'info-circle-fill','success' =>'check-circle-fill','error' =>'exclamation-triangle-fill','info' =>'info-circle-fill','warning' =>'exclamation-triangle-fill',    ],]);

Use a different icon set:

$this->Flash->success('Message with different icon set.', ['params' => ['icon' => ['namespace' =>'fas','prefix' =>'fa','name' =>'microphone-slash','size' =>'2xl',        ],    ],]);
<iclass="me-2 fas fa-microphone-slash fa-2xl"></i>

Use a different icon set for all flash messages:

$this->loadHelper('Html', ['className' =>'BootstrapUI.Html','iconDefaults' => ['namespace' =>'fas','prefix' =>'fa',    ],]);
$this->loadHelper('Flash', ['className' =>'BootstrapUI.Flash','iconMap' => ['default' =>'info-circle','success' =>'check-circle','error' =>'exclamation-triangle','info' =>'info-circle','warning' =>'exclamation-triangle',    ],]);

Badges

By default badges will render assecondary theme styled:

echo$this->Html->badge('Text');
<spanclass="badge bg-secondary">Text</span>

Background colors

Background colors can be changed by specifyingone of the Bootstrap theme color names via theclass option, the helper will make sure that the correct prefixesare being applied:

echo$this->Html->badge('Text', ['class' =>'danger',]);
<spanclass="badge bg-danger">Text</span>

Using a different HTML tag

By default badges are using the<span> tag. This can be changed via thetag option:

echo$this->Html->badge('Text', ['tag' =>'div',]);
<divclass="badge bg-secondary">Text</div>

Icons

By default the HTML helper is configured to useBootstrap icons.

echo$this->Html->icon('mic-mute-fill');
<iclass="bi bi-mic-mute-fill"></i>

Sizes

Sizes can be specified via thesize option, the passed value will automatically be prefixed:

echo$this->Html->icon('mic-mute-fill', ['size' =>'2xl',]);
<iclass="bi bi-mic-mute-fill bi-2xl"></i>

This plugin ships Bootstrap icon classes for the following sizes that center-align the icon vertically:2xs,xs,sm,lg,xl, and2xl, and the following ones that align the icons on the baseline:1x,2x,3x,4x,5x,6x,7x,8x,9x, and10x.

Using a different icon set

You can use a different icon set by configuring thenamespace andprefixoptions, either pericon() call:

echo$this->Html->icon('microphone-slash', ['namespace' =>'fas','prefix' =>'fa',]);

or globally for all usages ofHtmlHelper::icon() by configuring the HTML helper defaults:

$this->loadHelper('Html', ['className' =>'BootstrapUI.Html','iconDefaults' => ['namespace' =>'fas','prefix' =>'fa',    ],]);

Breadcrumbs

The breadcrumbs helper is a drop-in replacement, no additional configuration is available/required.

echo$this->Breadcrumbs    ->add('Home','/')    ->add('Articles','/articles')    ->add('View')    ->render();
<navaria-label="breadcrumb"><olclass="breadcrumb"><liclass="breadcrumb-item"><ahref="/">Home</a></li><liclass="breadcrumb-item active"><ahref="/articles"aria-current="page">Articles</a></li><liclass="breadcrumb-item"><span>View</span></li></ol></nav>

Pagination

The paginator helper generates bootstrap compatible/styles markup when using the helper's standard methods, and alsoincludes a convenience method that can generate a full set of pagination controls, that is first/previous/next/last aswell as page number links, all enclosed in a list wrapper.

echo$this->Paginator->first();echo$this->Paginator->prev();echo$this->Paginator->numbers();echo$this->Paginator->next();echo$this->Paginator->last();

This would generate the following HTML:

<liclass="page-item first"><aclass="page-link"aria-label="First"href="/articles/index"><spanaria-hidden="true">«</span></a></li><liclass="page-item"><aclass="page-link"rel="prev"aria-label="Previous"href="/articles/index"><spanaria-hidden="true">‹</span></a></li><liclass="page-item"><aclass="page-link"href="/articles/index">1</a></li><liclass="page-item active"aria-current="page"><aclass="page-link"href="#">2</a></li><liclass="page-item"><aclass="page-link"href="/articles/index?page=3">3</a></li><liclass="page-item"><aclass="page-link"rel="next"aria-label="Next"href="/articles/index?page=3"><spanaria-hidden="true">›</span></a></li><liclass="page-item last"><aclass="page-link"aria-label="Last"href="/articles/index?page=3"><spanaria-hidden="true">»</span></a></li>

Configuring the ARIA labels

When using the standard methods you can use thelabel option to pass a custom string to use forthearia-label attribute:

echo$this->Paginator->first('«', ['label' =>__('Beginning')]);echo$this->Paginator->prev('‹', ['label' =>__('Back')]);echo$this->Paginator->next('›', ['label' =>__('Forward')]);echo$this->Paginator->last('»', ['label' =>__('End')]);

This would generate the following HTML:

<liclass="page-item first"><aclass="page-link"aria-label="Beginning"href="/articles/index"><spanaria-hidden="true">«</span></a></li><liclass="page-item"><aclass="page-link"rel="prev"aria-label="Back"href="/articles/index"><spanaria-hidden="true">‹</span></a></li><liclass="page-item"><aclass="page-link"rel="next"aria-label="Forward"href="/articles/index?page=3"><spanaria-hidden="true">›</span></a></li><liclass="page-item last"><aclass="page-link"aria-label="End"href="/articles/index?page=3"><spanaria-hidden="true">»</span></a></li>

Generating a full set of controls

A full set of pagination controls, that is first/previous/next/last as well as page number links, all enclosed in a listwrapper, can be generated using thelinks() method.

By default it renders numbers only:

echo$this->Paginator->links();

This would generate the following HTML:

<ulclass="pagination"><liclass="page-item"><aclass="page-link"href="/articles/index">1</a></li><liclass="page-item active"aria-current="page"><aclass="page-link"href="#">2</a></li><liclass="page-item"><aclass="page-link"href="/articles/index?page=3">3</a></li></ul>
Configuring controls

The generated controls can be configured via thefirst,prev,next, andlast options, which each can take eitherbooleantrue to generate the control with the helper defaults, a string that is used as the control's text, or anarray that allows specifying the link text as well as the ARIA label.

The generated controls can be configured via thefirst,prev,next, andlast options, which each take eitherbooleantrue to indicate that the control should be generated using the helper defaults, a string that is used as thecontrol's text, or an array withlabel andtext options that determine the ARIA label value and the link text:

echo$this->Paginator->links(['first' =>'❮❮','prev' =>true,'next' =>true,'last' => ['label' =>'End','text' =>'❯❯',    ],]);

This would generate the following HTML:

<ulclass="pagination"><liclass="page-item first"><aclass="page-link"aria-label="First"href="/articles/index"><spanaria-hidden="true">❮❮</span></a></li><liclass="page-item"><aclass="page-link"rel="prev"aria-label="Previous"href="/articles/index"><spanaria-hidden="true">‹</span></a></li><liclass="page-item"><aclass="page-link"href="/articles/index">1</a></li><liclass="page-item active"aria-current="page"><aclass="page-link"href="#">2</a></li><liclass="page-item"><aclass="page-link"href="/articles/index?page=3">3</a></li><liclass="page-item"><aclass="page-link"rel="next"aria-label="Next"href="/articles/index?page=3"><spanaria-hidden="true">›</span></a></li><liclass="page-item last"><aclass="page-link"aria-label="End"href="/articles/index?page=3"><spanaria-hidden="true">❯❯</span></a></li></ul>
Sizing

The size can be specified via thesize option:

echo$this->Paginator->links(['size' =>'lg',]);

This would generate the following HTML:

<ulclass="pagination pagination-lg"><!-- ... --></ul>

Helper configuration

You can configure each of the helpers by passing in extra parameters when loading them in yourAppView.php.

Here is an example of changing theprev andnext labels for the Paginator helper.

$this->loadHelper('Paginator', ['className' =>'BootstrapUI.Paginator','labels' => ['prev' =>'previous','next' =>'next',    ],]);

Contributing

Patches & Features

  • Fork
  • Mod, fix
  • Test - this is important, so it's not unintentionally broken
  • Commit - do not mess with license, todo, version, etc. (if you do change any, put them into separate commits that canbe ignored when pulling)
  • Pull request - bonus point for topic branches

To ensure your PRs are considered for upstream, you MUST follow the CakePHP coding standards. Apre-commithook has been included to automatically run the code sniffs for you. From your project's root directory:

cp ./contrib/pre-commit .git/hooks/chmod 755 .git/hooks/pre-commit

Testing

When working on the plugin's code you can run the tests for BootstrapUI by doing the following:

composer install./vendor/bin/phpunit

Bugs & Feedback

https://github.com/friendsofcake/bootstrap-ui/issues

About

CakePHP: Transparently use Bootstrap

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors50

Languages

[8]ページ先頭
©2009-2025 Movatter.jp