CakePHP: Transparently use Bootstrap
Transparently use [Bootstrap 5][bs] with [CakePHP 5][cakephp].
For version info see version map.
error, info, success, warning)default, inline, horizontal)badge, icon)data-bs-theme light/dark/auto support)basic, button, datetime, file, select, textarea)cover, signin, dashboard)cd to the root of your app folder (where the composer.json file is) and run the following [Composer][composer]
command:
composer require friendsofcake/bootstrap-uiThen load the plugin using CakePHP's console:
bin/cake plugin load BootstrapUIYou can either use the Bootstrap commands to make the necessary changes, or do them manually.
To install the Bootstrap assets (Bootstrap's CSS/JS files) via npm you can use the install
command, or install them manually:
bin/cake bootstrap installThis will fetch all assets, copy the distribution assets to the BootstrapUI plugin's webroot directory, and symlink
(or copy) them to your application's webroot 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 --latestYou will need to modify your src/View/AppView class to either extend BootstrapUI\View\UIView or
use the trait BootStrapUI\View\UIViewTrait. For doing this you can either use the modify_view command, or
change your view manually:
bin/cake bootstrap modify_viewThis will rewrite your src/View/AppView like described in AppView setup using UIView.
BootstrapUI ships with some example layouts. You can install them using the copy_layouts command, or
copy them manually:
bin/cake bootstrap copy_layoutsThis will copy the three example layouts cover.php, dashboard.php and signin.php to your application's
src/templates/layout/TwitterBootstrap.
The the install command installs the Bootstrap assets via [npm], which you can also
do manually if you wish to control which assets are being included, and where they are placed.
Assuming you are in your application's root:
…For a quick setup, just make your AppView class extend BootstrapUI\View\UIView. The base class will handle
the initializing and loading of the BootstrapUI default.php layout for your app.
The src\View\AppView.php will look something like the following:
declare(strict_types=1);
namespace App\View;
use BootstrapUI\View\UIView;
class AppView extends UIView
{
/**
* Initialization hook method.
*/
public function initialize(): void
{
// Don't forget to call parent::initialize()
parent::initialize();
}
}If you're adding BootstrapUI to an existing application, it might be easier to use the trait, as it gives you more control over the loading of the layout.
declare(strict_types=1);
namespace App\View;
use BootstrapUI\View\UIViewTrait;
use Cake\View\View;
class AppView extends View
{
use UIViewTrait;
/**
* Initialization hook method.
*/
public function initialize(): void
{
parent::initialize();
// Call the initializeUI method from UIViewTrait
$this->initializeUI();
}
}In order to be able to use the BootstrapUI example layouts (directly taken from the Bootstrap examples), they need to be
copied to your application's layouts directory, either by using
the copy_layouts command, or by copying the files manually:
cp -R vendor/friendsofcake/bootstrap-ui/templates/layout/examples templates/layout/TwitterBootstrapBootstrapUI comes with its own default.php layout file and examples taken from the Bootstrap framework.
When no layout for the view is defined, the BootstrapUI\View\UIViewTrait will load its own default.php layout file.
You can override this behavior in two ways.
$this->setLayout('layout').BootstrapUI\View\UIViewTrait by adding $this->initializeUI(['layout' => false]); to your AppView's initialize() function.Once copied into your application's layouts directory (being it via
the copy_layouts command or manually), you can simply
extend the example layouts in your views like so:
$this->extend('../layout/TwitterBootstrap/dashboard');Available types are:
coversignindashboardNOTE: Remember to set the stylesheets in the layouts you copy.
If you are using the BoostrapUI plugin's default layout, and you have installed the Bootstrap
assets using the install command, the required assets should automatically be
included.
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 using the install command, you can refer to
them using the standard plugin syntax:
// in the
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. With the 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']);For those of you who want even more automation, some bake templates have been included. Use them like so:
bin/cake bake [subcommand] -t BootstrapUICurrently, bake templates for the following bake subcommands are included:
templateAdditionally to the default index, add, edit, and view templates, a login template is available too. While
the default CRUD action view templates can be utilized like this:
bin/cake bake template ControllerName -t BootstrapUIthe login template has to be used explicitly by specifying the action name:
bin/cake bake template ControllerName login -t BootstrapUIAt the core of BootstrapUI is a collection of enhancements for CakePHP core helpers. Among other things, these helpers replace the HTML templates used to render elements for the views. This allows you to create forms and components that use the Bootstrap styles.
The current list of enhanced helpers are:
BootstrapUI\View\Helper\FlashHelperBootstrapUI\View\Helper\FormHelperBootstrapUI\View\Helper\HtmlHelperBootstrapUI\View\Helper\PaginatorHelperBootstrapUI\View\Helper\BreadcrumbsHelperWhen the BootstrapUI\View\UIViewTrait is initialized it loads the above helpers with the same aliases as the
CakePHP core helpers. That means that when you use $this->Form->create() in your views, the helper being used
is from the BootstrapUI plugin.
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:
Submit
Horizontal forms automatically render labels and controls in separate columns (where applicable), labels in th first one, and controls in the second one.
Alignment can be configured via the align option, which takes either a list of column sizes for the md
Bootstrap screen-size/breakpoint, or a matrix of
screen-size/breakpoint names and column sizes.
The following will use the default md screen-size/breakpoint:
use BootstrapUI\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:
Submit
The following uses a matrix of screen-sizes/breakpoints and column sizes:
…It will render this HTML:
Submit
The default alignment will use the md screen-size/breakpoint and the following column sizes:
[
FormHelper::GRID_COLUMN_ONE => 2,
FormHelper::GRID_COLUMN_TWO => 10,
]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:
Out of the box BootstrapUI applies some default spacing for form controls. For default and horizontal aligned forms,
the mb-3 [spacing cla
No open issues yet, or sync has not completed.