Fo

rk
CakePHP 3, Bootstrap Helpers

m
eo
n
Gi
th
CakePHP 3.x helpers for the Bootstrap 3 HTML, CSS & JS framework by @Holt59.

ub
Code on Github Download (.zip)

Getting Started
Dependencies
This repository contains a set of helpers that will help you combine CakePHP and Bootstrap. These helpers do not require any
dependencies except the two obvious ones:
CakePHP 3.x - The helpers have been developped since CakePHP 3 beta, and will be kept up to date with the current
CakePHP developpment.
Bootstrap CSS

Installation
Composer Manual

Since v3, CakePHP uses composer, the easiest way to set up the Bootstrap helpers is by either running

composer require holt59/cakephp3-bootstrap-helpers:dev-master

or adding the following to your composer.json and run composer update :

"require": {
"holt59/cakephp3-bootstrap-helpers": "dev-master"
}

Do not forget to load the plugin by adding the following line into your /config/bootstrap.php file:

Plugin::load('Bootstrap');

Using the helpers

Once the plugin is loaded, you just need to enable them into your AppController like this:
 public $helpers = [
'Html' => [
'className' => 'Bootstrap.BootstrapHtml'
],
'Form' => [
'className' => 'Bootstrap.BootstrapForm'
],
'Paginator' => [
'className' => 'Bootstrap.BootstrapPaginator'
],
'Modal' => [
'className' => 'Bootstrap.BootstrapModal'
]
];

See CakePHP documentation for more information on how to enable helpers in your controllers (especially if you want to use the
default CakePHP helpers together with these helpers).
Tip! Do not forget to add bootstrap CSS (and javascript) files to your pages for the helpers to work.

HTML Helper
getCrumbList
Overload of Cake\View\Helper\HTMLHelper::getCrumbList .

PHP Markup Output

<?php
$this->Html->addCrumb('Home', '/');
$this->Html->addCrumb('Pages', ['controller' => 'pages']);
$this->Html->addCrumb('About', ['controller' => 'pages', 'action' => 'about']);
echo $this->Html->getCrumbList();
?>

Icons
PHP Markup

<?php
echo $this->Html->icon('pencil');
?>

Icons - Easy icons

Sometimes, you may want to use BootstrapHtmlHelper::icon in combination with other helpers such as
BootstrapPaginatorHelper or BootstrapFormHelper to insert icons in buttons or other elements. To ease the process, some
methods provide a shortcut to use icon:

<?php
// The following...
echo $this->Form->button($this->Html->icon('pencil'), ['escape' => false]);
// ...can be easily rewritten as:
echo $this->Form->button('i:pencil');
?>
The easy icon format is i:icon-name where icon-name is the name of the icon.
Warning! The above code may throw errors if the HTML helper defined for the view is not BootstrapHtmlHelper . The set of icons
used (Font Awesome or Glyphicon) is defined by the HTML helper settings.
Tip! To disable easy icon, simply do $this->Form->easyIcon = false; (replace Form by anything relevant).
Warning! The name of the icon is not checked, so you should not use non-existing icon names.
Places where you can use easy icon (if not specified, the target is $title ):

// BootstrapPaginatorHelper
BootstrapPaginatorHelper::prev($title, array $options = []);
BootstrapPaginatorHelper::next($title, array $options = []);
BootstrapPaginatorHelper::numbers(array $options = []); // For `prev` and `next` options.

// BootstrapFormatHelper
BootstrapFormHelper::button($title, array $options = []);
BootstrapFormHelper::input($fieldName, array $options = []); // For `prepend` and `append` options.
BootstrapFormHelper::prepend($input, $prepend); // For $prepend.
BootstrapFormHelper::append($input, $append); // For $append.

Icons - Font Awesome

public $helpers = [
'Html' => [
'className' => 'Bootstrap.BootstrapHtml',
'useFontAwesome' => true // Add this line to set font awesome as default
]
];

PHP Markup

<?php
echo $this->Html->icon('pencil');
echo $this->Html->glIcon('pencil'); // Glyphicon icons are still available with BootstrapHtmlHelper::glIcon
echo $this->Html->faIcon('pencil'); // FontAwesome are always available using BootstrapHtmlHelper::faIcon
?>

Labels
PHP Markup Output

<?php
echo $this->Html->label('My Label', 'primary') ;
echo $this->Html->label('My Label', 'danger') ;
echo $this->Html->label('My Label', 'success') ;
?>

Badges
PHP Markup Output
 <?php
echo $this->Html->badge('1') ;
echo $this->Html->badge('2') ;
echo $this->Html->badge('3') ;
?>

Alerts
PHP Markup Output

<?php
echo $this->Html->alert('This is a warning alert!') ;
echo $this->Html->alert('This is a success alert!', 'success');
echo $this->Html->alert('This is a info alert with a specific id!', [
'id' => 'alert-info',
'type' => 'info'
]);
?>

Form Helper
Standard Use
Standard CakePHP code working with this helper, you do not need to worry about anything!

PHP Markup Output

<?php
echo $this->Form->create();
echo $this->Form->input('username', ['type' => 'text']) ;
echo $this->Form->input('password', ['type' => 'password']) ;
echo $this->Form->input('remember', ['type' => 'checkbox']) ;
echo $this->Form->submit('Log In') ;
echo $this->Form->end() ;
?>

Horizontal Forms
PHP Markup Output

<?php
echo $this->Form->create(null, ['horizontal' => true]);
echo $this->Form->input('username', ['type' => 'text']) ;
echo $this->Form->input('password', ['type' => 'password']) ;
echo $this->Form->input('remember', ['type' => 'checkbox']) ;
echo $this->Form->submit('Log In') ;
echo $this->Form->end() ;
?>

With horizontal , it is possible to specify the width of each columns:

 echo $this->Form->create(null, [
'horizontal' => true,
'cols' => [ // Total is 12, default is 2 / 6 / 4
'label' => 2,
'input' => 6,
'error' => 4
]
]);

You can also set column widths for different screens:

PHP Markup Output

<?php
echo $this->Form->create(null, [
'horizontal' => true,
'cols' => [
'sm' => [
'label' => 4,
'input' => 4,
'error' => 4
],
'md' => [
'label' => 2,
'input' => 6,
'error' => 4
]
]
]);
echo $this->Form->input('username', ['type' => 'text']) ;
echo $this->Form->input('password', ['type' => 'password']) ;
echo $this->Form->input('remember', ['type' => 'checkbox']) ;
echo $this->Form->submit('Log In') ;
echo $this->Form->end() ;
?>

To avoid compatibility issue with some bootstrap plugins, you can switch from horizontal layout to standard layout by using the
BootstrapFormHelper::setHorizontal method.

PHP Markup Output

<?php
echo $this->Form->create(NULL, ['horizontal' => true]) ;
echo $this->Form->input('horizontal_1');
echo $this->Form->setHorizontal (false) ;
echo $this->Form->input('non_horizontal');
echo $this->Form->setHorizontal (true) ;
echo $this->Form->input('horizontal_2');
echo $this->Form->end() ;
?>

Custom File Input

Bootstrap do not customize (ugly) file inputs, so you can choose to customize it with the helpers. To enable the custom file inputs
(see demo bellow), set useCustomFileInput to true when enabling the helper:
 public $helpers = [
'Form' => [
'className' => 'Bootstrap.BootstrapForm',
'useCustomFileInput' => true
]
];

PHP Markup Output

<?php
echo $this->Form->file('file');
?>

You can also pass custom options to the button and input generated by the helper via the _button and _input options. This
adds greater control over the elements
Note: Any classes you add here will be appended to the ones used by the Bootstrap helper and not override them. Also
readonly , onclick and id have special significance on the input and cannot be overridden. The same applies to type and
onclick on the button.

$this->Form->file('file', [
'_button' => ['class' => 'my-custom-button-class'],
'_input' => ['data-attr' => 'my-data-attr', 'class' => 'my-input-class']
]);

Button Group, Toolbar & Dropdown

PHP Markup Output

<?php
echo $this->Form->buttonGroup([$this->Form->button('1'), $this->Form->button('2')]) ;
?>

PHP Markup Output

<?php
echo $this->Form->buttonToolbar([
$this->Form->buttonGroup([$this->Form->button('1'), $this->Form->button('2')]),
$this->Form->buttonGroup([$this->Form->button('3'), $this->Form->button('4')])
]) ;
?>

PHP Markup Output

<?php
echo $this->Form->dropdownButton('My Dropdown', [
$this->Html->link('Link 1', '#'),
$this->Html->link('Link 2', '#'),
'divider',
$this->Html->link('Link 3', '#')
]);
?>
New input options
PHP Markup Output

<?php
echo $this->Form->input('mail', [
'prepend' => '@',
'help' => 'Hey guy, you need some help?',
'append' => $this->Form->button('Send')
]) ;
?>

You can also easily append dropdown menu to your input:

PHP Markup Output

<?php
echo $this->Form->input('mail', [
'append' => [
$this->Form->button('Button'),
$this->Form->dropdownButton('Dropdown', [
$this->Html->link('A', '#'),
$this->Html->link('B', '#'),
'divider',
$this->Html->link('C', '#')
])
]
]) ;
?>

Modal Helper
The Bootstrap 3 modal helper allow you to easily create modal without having to write bunch of html code. There is 3 ways of
using this helper, the first one being the most simple and common.

Example 1 - Standard Use

PHP Markup Show Modal

<?php
// Start a modal with a title, default value for 'close' is true
echo $this->Modal->create("My Modal Form", ['id' => 'MyModal1', 'close' => false]) ;
?>
<p>Here I write the body of my modal !</p>
<?php
// Close the modal, output a footer with a 'close' button
echo $this->Modal->end() ;
// It is possible to specify custom buttons:
echo $this->Modal->end([
$this->Form->button('Submit', ['bootstrap-type' => 'primary']),
$this->Form->button('Close', ['data-dismiss' => 'modal'])
]);
?>

Example 2 - Without HTML

This one allow you to directly specify the modal body content when calling Modal::body . It is useful when the body you want to
render is a PHP string.

PHP Markup Show Modal

<?php
$content = "<p>My body... !</p>";
echo $this->Modal->create(['id' => 'MyModal2']) ;
echo $this->Modal->header('Example 2 - No HTML', ['close' => false]) ;
echo $this->Modal->body($content, ['class' => 'my-body-class']) ;
echo $this->Modal->footer([
$this->Form->button('Submit', ['bootstrap-type' => 'primary']),
$this->Form->button('Close', ['data-dismiss' => 'modal'])
]) ;
echo $this->Modal->end() ;
?>

Example 3 - Custom Modal

If you want a custom modal, you can start each sestion manually and add whatever you want:

PHP Markup Show Modal

<?php
echo $this->Modal->create(['id' => 'MyModal3']) ;
echo $this->Modal->header(['class' => 'my-header-class']) ;
?>
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
<h4>My Header!</h4>
<?php
echo $this->Modal->body() ;
?>
<p>My body!</p>
<?php
echo $this->Modal->footer(['close' => false]) ;
?>
<p>My footer... Oops, no buttons!</p>
<?php
echo $this->Modal->end() ;
?>

Notice that you can omit a section if you want:

PHP Markup

<?php
echo $this->Modal->create(['id' => 'MyModal4']) ;
echo $this->Modal->body() ; // No header
echo $this->Modal->footer() ; // Footer with close button (default)
echo $this->Modal->end() ;
?>

Creating a toggle button

You can use the BootstrapFormHelper to create a toggle button for your modal:
 echo $this->Form->button('Toggle Form', [
'data-toggle' => 'modal',
'data-target' => '#MyModal'
]) ;

Getting Started
HTML Helper
Form Helper
Modal Helper
Back to top

2016, Mikal Capelle (@Holt59) - Designed and built by Holt59 & contributors.
Code licensed under Apache License, Version 2.0.
Code & Documentation hosted by Github.