Please note: the entity concept was devised quite separately from what is apparently coming in Cake3 for models, so any similarity is not intentional and does not imply a similar usage or implementation.

There are a number of Helper Classes already provided. If you know what a Test Case is you should check out the Test cases already provided to see examples of how each helper is used.

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> 

Not bad! See how it provided default Bootstrap formatting, wrapped all your data in the proper elements, and still only required a few calls?

That's a pretty basic example. There are lots more things you can do, even with tables. But that should give you the gist of what's going on in each Helper.

Remember to take a look in the classes, the test cases provided, and any other examples (even the ones later in this doc) to figure out what's going on.

The whole system uses three main peices. An Entity (something like a list item), and either a plain Entity Collection (to hold the list items) or a Wrapped Entity Collection (to hold the list items and wrap them in a <ul> when it prints itself.) or any and all combinations of all three.

If you're looking for a good example of a completx setup, check out the BootstrapTableHelper - it has all three!

We take a look at each of those three and how/why/when to build your own.

For our example we will make a completely useless Paragraph entity. A Paragraph entity, for example, would know that it uses the <p> tag, that it has a class of foo and that in between its tags is the content Hello World!. When anything attempts to get the string representation of it the Paragraph entity will convert itself into a full-formed paragraph that looks like this

 #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>

An EntityCollection is simply that, a collection of entities with no special relation to each other. Most of the Helpers in this plugin are Entity Collections; for example GlyphiconHelper extends BootstrapHelperEntityCollection and simply holds any glyphs you create in case you need to get to them later on.

There is a special case for Wrapped Entity Collections that we will look at in the next section.

Continuing on with our Paragraph entity, let's make the following adjustments. Let's make a paragraph collection that stores all the paragraphs we add.

 #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>

Next we'll take a look at the special case of a Wrapped Entity Collection. Oddly enough, this class was what actually drove me to implement the entity architecture of the plugin.

It is often the case that you have an arbitrary number of items (1 or more) that all need to go together AND need to be wrapped in something else. The previous design required that you call a begin() ... all your elements... end() - cumbersome and iffy.

 #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()

This old was was very cumbersome and required you to not only keep track of where you were, but more importantly, required you to intimately know the details of how each Helper worked, what groups needed to be called when, and what items could (or had to) go in what groups. It was a pain in the butt.

Thus wrapped entity collections were actually the drivers for the whole re-write.

Let's take a look.

Let's change our example from before to make a little more sense. Instead of dealing with Paragraphs lets create a ListGroupHelper. We'll use it to make a properly formatted Bootstrap List Group

 #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>

See how it wrapped all the list items for us? No need for us to remember how they're supposed to go - it does that all for us!

WIN.

It's actually interesting to compare them to see how much work the newer design does automatically for you. Compare NavHelper and TableHelper - both do about the same amount of complexity/work, but one is vastly easier to read and maintain than the other.