This plugin includes both lessjs and less.php parsers and allows you to easilly deploy CakePHP applications with twitter bootstrap.
With a component and some helpers it automatically replaces cakePHP's elements like form inputs and flash messages to be displayed with twitter bootstrap.
It also contains bake templates that will help you starting twitter-bootstraped CakePHP webapps.
- Parses less files using less.js or less.php.
- LessHelper to easily parse files.
- FormHelper to automatically style forms.
- FlashComponent to replace alerts.
- Bake templates.
You can easily install this plugin using composer as follows:
composer require elboletaire/twbs-cake-plugin
After doing it, composer will ask you for a version. Checkout the package on packagist to know every available version.
Latest version currently is 3.0.0-rc1
, but you can use dev-master
to use
the latest master HEAD
version.
After adding the plugin remember to load it in your config/bootstrap.php
file:
Plugin::load('Bootstrap');
If, for any reason, the psr-4
addition to the composer.json
file does not
work, try setting autoload
to true
when loading the plugin:
Plugin::load('Bootstrap', ['autoload' => true]);
After adding the plugin you can add the desired utilities:
// AppController.php
public $helpers = [
'Bootstrap.Less',
'Bootstrap.Form'
];
public function initialize() {
$this->loadComponent('Bootstrap.Flash');
}
There are two common usage ways when using twitter bootstrap and less:
- Directly using twitter bootstrap classes on your views.
- Using custom classes on your views and then extending that classes to twitter bootstrap components.
For the first case you can directly load the layout included with this plugin and bake your views with the also included bake templates.
For the second case you'll need to
create your own layout and load the included
webroot/less/cakephp/styles.less
file. It will extend the default baked views'
styles so they have a twitter bootstrap look and feel.
On both cases you can use the layout included with this plugin as a theme
(right now there's only the default
layout):
// AppController
public $theme = 'Bootstrap';
// or...
public $layout = 'Bootstrap.default';
You can also specify it as a layout directly from your template files:
// any .ctp Template file
$this->layout = 'Bootstrap.default';
Last but not least, you can also copy that template to your Template/Layout
folder and then extend the template from your view.
Read more about views on the CakePHP Cookbook
BTW it's recommended that you copy all the required files to your src folder (specially for assets), even if you won't modify them.
Take in mind that if you're loading this plugin in a fresh CakePHP installation
and you try to see the layout change in the home page, you won't see nothing.
The home.ctp
overwrites the layout to false
, to ensure it's loaded as it has
been designed.
You can bake your views using the twitter bootstrap templates bundled with this
plugin. To do so, simply specify the bootstrap
template when baking your files:
cake bake all articles --theme Bootstrap
Create a styles.less
file on your webroot/less
folder (also create
that folder if it does not exist) containing this line:
@import '/bootstrap/less/bootstrap.less';
Finally, load the less file from your view or layout:
echo $this->Less->less('styles.less');
If you want to extend twitter bootstrap styles I recommend you to copy both
bootstrap.less
and variables.less
files to your less
folder and customize
them to your needs.
If you'd like to see an example of this you can check the files included in
webroot/less/cakephp
specially made to extend the default CakePHP baked
templates.
The FlashComponent replaces all flash messages set with $this->Flash
to
automatically load the bootstrap flash message template located at
src/Template/Element/flash.ctp
.
By default the flash messages will show a close button. If you want to disable just specify it as param when setting the flash message:
$this->Flash->danger('Fatal error', ['params' => ['close' => false]]);
Used on your template or view to load the compressed CSS.
By default it will compress files using the php parser with cache enabled.
This will fill your css
folder with a bunch of files starting with lessphp_
used for the cache. I recommend you adding these files to your .gitignore
file
in order to prevent commiting them:
lessphp_*
Basically, you give the helper a less file to be loaded (from /less
directory)
and it returns the html link tag to the compiled CSS:
echo $this->Less->less('less/styles.less');
// will result in something like...
<link rel="stylesheet" href="/css/lessphp_8e07b9484a24787e27f9d71522ba53443d18bbd2.css" />
You can compile multiple files if you pass an array:
echo $this->Less->less(['less/myreset.less', 'less/styles.less']);
// They will be compiled in the same file, so the result will be the same as the previous one
<link rel="stylesheet" href="/css/lessphp_e0ce907005730c33ca6ae810d15f57a4df76d330.css"/>
And you can pass any option to both lessjs and less.php parsers:
echo $this->Less->less('less/styles.less', [
'js' => [
// options for lessjs (will be converted to a json object)
],
'parser' => [
// options for less.php parser
],
// The helper also has its own options
]);
If you want to use the less.js parser directly, instead of a fallback, or you want to use the #!watch method, you can do it so by setting the js parser to development:
echo $this->Less->less('less/styles.less', ['js' => ['env' => 'development']]);
This will output all the links to the less files and the needed js files to parse the content only using the less.js parser.
Beside the options for lessjs and less.php parsers you can set three options to the helper:
cache
: default's to true. If disabled, the output will be raw CSS wrapped with<style>
tags.tag
: default's to true. Whether or not return the code with its proper tag (with cache enabled will be a link tag, whilst without cache will be a style tag).less
: default's to/bootstrap/js/less.min
. You can use this var to set a custom lessjs file.
// Get the link to the resulting file after compressing
$css_link = $this->Less->less('less/styles.less', [
'tag' => false
]);
// Get the compiled CSS (raw)
$compiled_css = $this->Less->less('less/styles.less', [
'cache' => false,
'tag' => false
]);
As a default setting of the LessHelper, all the CSS generated by the less.php
parser is compresed. To override this set compress
to false
in the less.php
parser options:
echo $this->Less->less('less/styles.less', [
'parser' => ['compress' => false]
]);
Automatically adds some CSS classes to your form elements. Some of the input
replacements can be found at src/Config/forms.php
, but many need to be done
directly from the FormHelper.
All the form elements' classes have been replaced with the twitter bootstrap form classes.
* Buttons always have the
.btn
class added. If you want to remove the class you can pass an additionalbtnClass
param set tofalse
to the button's$options
.
- oyejorge/less.php version >= 1.7.0.2
Copyright 2013-2014 Òscar Casajuana (a.k.a. elboletaire)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
imitations under the License.