cwbit / cakephp-bootstrap-suite
A CakePHP plugin for the Bootstrap CSS and JS framework
Installs: 15
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 7
Type:cakephp-plugin
This package is not auto-updated.
Last update: 2024-04-27 12:34:31 UTC
README
readme.md
cakephp-bootstrap-suite
=======================
The CakePHP Bootstrap Suite (Bootstrap) is a plugin suite of CakePHP Helpers that attempt to make using the Bootstrap CSS and JS framework with CakePHP a lot easier.
It does this by providing helper classes that employ an Entity, Collection, and Wrapped Collection architecture to create and manipulate objects.
NOTE: Technically you can use the Entity architecture of this plugin to print out ANY valid HTML, XML and even preconfigure them with default, overrideable options. Want an entity that can handle perfectly formatted reponsive image tags? If you've typed more than 3 lines (from class to } ) then you've type too much. Want an infinitely expandable, perfectly formatted, bootstrap styled, manipulatable and on-the-fly modifiable unordered list collection? You should clock in at about ... 7 lines total code. 2 lines of which are class declarations and 2 lines of which are the close curly bracket for your class.
Let's create a complete, fully functional example in 7 lines or less.
//.. in app/Plugins/Bootstrap/View/Helper/ListCollectionHelper.php class ListCollectionHelper extends BootstrapHelperWrappedEntityCollection{ public $_options = ['tag'=>'ul','baseClass'=>'list-group']; public $_entityClass = 'ListItem'; } class ListItem extends BootstrapHelperEntity{ public $_options = ['tag'=>'ul','baseClass'=>'list-group-item']; }
YUP. 7 lines. Wanna use it? Let's add it as a helper and start using it
//.. in your controller public $uses = ['Bootstrap.ListCollection']; //.. in your view $l = $this->ListCollection->add(); $l->add('Hello'); $l->add('World');
Ok, how about we see what it looks like when told to print itself.
# anything that calls __toString() will work echo $l; # prints out the following <ul class='list-group'> <li class='list-group-item'>Hello</li> <li class='list-group-item'>World</li> </ul>
Perfectly formatting, classed and le sexy. Mindblown.
We (figuratively) just created a UL helper in 7 lines that oh, I dunno, is also a perfectly formatted, expandable, go-back-and-change-something-on-the-fly-if-you-want Bootstrap List Group.
To put it another way, this is an extremely powerful presentation system that just happens to come pre-bundled with Helpers that support Bootstrap.
Requirements
===
- CakePHP
- Bootstrap 3.x Technically you can support whatever version of bootstrap you want, just make/modify the appropriate helpers.
TOC
====
- Architecture
- Using the Plugin
- Glyphicon Example
- Table Example
- Create your Own
- Entity
- Entity Collection
- Wrapped Entity Collection
- Exceptions
- Plugin Installation
class ExamplesController extends AppController{
public $uses = ['Bootstrap.BootstrapGlyphicon'];
public function view(){}
}
//..view.ctp
echo $this->BootstrapGlyphicon->create('minus');
#will print out
<span class="glyphicon glyphicon-minus"></span>
That's it - that's how you use the GlyphiconHelper! Easy, eh?
<a name='how-ex-2'/>
### Table Example (more complicated)
===
Now let's look at a more complicated example, because this is where the setup will really start to shine.
```php
class ExamplesController extends AppController{
public $uses = ['Bootstrap.BootstrapTable'];
public function view(){
$this->set('examples', $this->Example->find('all'));
}
}
#../view.ctp
$t = $this->BootstrapTable->add();
$t->Header->add()->addMultiple(['Name'],['Description']);
foreach($examples as $example):
$t->Body->add()->addMultiple(
[$example['name']],
[$example['description']],
);
endforeach;
#print it out
echo $t;
#will give us
<table class='table table-hover table-striped table-notbordered table-notcondensed'>
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Example One</td>
<td>Description One</td>
</tr>
<tr>
<td>Example Two</td>
<td>Description Two</td>
</tr>
<tr>
<td>Example Three</td>
<td>Description Three</td>
</tr>
</tbody>
</table>
## Creating your own Helper (or understanding what's going on)
====
We take a look at each of those three and how/why/when to build your own.
### An example ENTITY An entity is, and should be, a single idea - A paragraph is an entity, a cell in a table is an entity, an image is an entity, etc. An entity can also be made up of other entities. Some entities are special collections of other entities, we will look at those in the next section.#example class configuration class ParagraphEntity extends BootstrapHelperEntity{ protected $_options = ['tag'=>'p']; } #example Paragraph creation with optional configuration $p = $this->ParagraphEntity->create('Hello World', ['htmlAttributes' => ['class' => 'foo']]) #any of the following will produce... echo $p; echo $p->toString(); echo (string) $p; #... this output <p class='foo'>Hello World!</p>### Continuing the Example with an ENTITY COLLECTION
There is a special case for Wrapped Entity Collections that we will look at in the next section.
#create a collection class that will use the ParagraphEntity class (from prev example) when it create()s new entities class ParagraphCollection extends BootstrapHelperEntityCollection{ public $_entityClass = 'ParagraphEntity'; } #now let's use it (and yes, it was that easy) $this->ParagraphCollection->add('I'); # calling add() will instantiate an $_entityClass $this->ParagraphCollection->add('LOVE'); # call create(...params...) on the new instance $this->ParagraphCollection->add('ME'); # and set up some other collection-specific stuff $this->ParagraphCollection->addMultiple( # you can also use addMultiple ['LOTS'], # to call add multiple times ['OF'], # by passing it an array of args for the add() function ['PARAGRAPHS', ['htmlAttributes'=>['class'=>'serious']] ] ); # we can do lots of other stuff with the collection, but let's just print it out for now echo $this->ParagraphCollection; # will produce the following <p>I</p> <p>LOVE</p> <p>ME</p> <p>LOTS</p> <p>OF</p> <p class='serious'>PARAGRAPHS</p>### Continuing the example with a Wrapped Entity Collection
#example of the old way echo $this->Nav->begin() echo $this->Nav->groupBegin(); echo //...lots of nav elements...// echo $this->Nav->groupEnd(); echo $this->Nav->end()
Thus wrapped entity collections were actually the drivers for the whole re-write.
#first, lets make a list item entity class ListEntity extends BootstrapHelperEntity{ public $_options = [ # bootstrap list items are just 'tag' => 'li', # <li>'s 'htmlAttributes' => [ # with a specific html class of 'class' => 'list-group-item', # 'list-group-item' ] # That's it! EASYMODE ]; # The parent class will handle } # the rest #next, we'll make a wrapped entity collection class ListEntityCollection extends BootstrapHelperWrappedEntityCollection{ public $_options = [ # The wrapped collection, unlike the 'tag' => 'ul', # regular collection, can actually take 'htmlAttributes' => [ # formatting options. 'class' => 'list-group' # we'll see how they're used in a sec ] ] } #Let's get our ListGroup object #this call won't work if you copy/paste this example, you'll need #to set up $view and $settings first #this is more to show you what Cake is normally passing your Helper $listGroup = new ListEntityCollection($View, $settings); #Now let's add some list items (like we saw earlier) $listGroup->add('Cras justo odio'); $listGroup->add('Dapibus ac facilisis in'); $listGroup->addMultiple( ['Morbi leo risus'], ['Porta ac consectetur ac'], ['Vestibulum at eros'] ); #now let's see why we bothered with a wrapped collection echo $listGroup; #if we echo the collection we will get the following! <ul class="list-group"> <li class="list-group-item">Cras justo odio</li> <li class="list-group-item">Dapibus ac facilisis in</li> <li class="list-group-item">Morbi leo risus</li> <li class="list-group-item">Porta ac consectetur ac</li> <li class="list-group-item">Vestibulum at eros</li> </ul>## Exceptions ==== There are a couple of classes that don't follow the Entity architecture yet. NavHelper is a big one. In order to get some of them to work there are peices of the architecture that need to be designed first (like pass-through entities) and I haven't figured out the best way to do them yet. So, for now, some Helpers follow a slightly older, entity-less pattern. ## Installation ====
[Using Composer]
Add the plugin to your project's composer.json
- something like this:
{
"require": {
"cwbit/cakephp-bootstrap-suite": "dev-master"
}
}
Because this plugin has the type cakephp-plugin
set in it's own composer.json
composer knows to install it inside your /Plugins
directory (rather than in the usual 'Vendor' folder). It is recommended that you add /Plugins/Bootstrap
to your cake app's .gitignore file. (Why? read this.)
[Manual]
- Download and unzip the repo (see the download button somewhere on this git page)
- Copy the resulting folder into
app/Plugin
- Rename the folder you just copied to
Bootstrap
[GIT Submodule]
In your app
directory type:
git submodule add -b master git://github.com/cwbit/cakephp-bootstrap-suite.git Plugin/Bootstrap
git submodule init
git submodule update
[GIT Clone]
In your app/Plugin
directory type:
git clone -b master git://github.com/cwbit/cakephp-bootstrap-suite.git Bootstrap
Enable plugin
In 2.0 you need to enable the plugin your app/Config/bootstrap.php
file:
CakePlugin::load('Bootstrap');
If you are already using CakePlugin::loadAll();
, then this is not necessary.