PHPackages                             davidyell/listing - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. davidyell/listing

AbandonedArchivedCakephp-plugin[Database & ORM](/categories/database)

davidyell/listing
=================

Model behaviour to append a field into a list for a select box. The idea for this behaviour is that if you have a list of items which belong to another model, it will include that models name.

0.1.4.1(11y ago)82571PHP

Since Apr 26Pushed 11y ago1 watchersCompare

[ Source](https://github.com/davidyell/CakePHP-Listing)[ Packagist](https://packagist.org/packages/davidyell/listing)[ RSS](/packages/davidyell-listing/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (1)Versions (6)Used By (0)

\#CakePHP-Listing Model behaviour to append an [optgroup](http://www.w3schools.com/tags/tag_optgroup.asp) into a list for a select box. The idea for this behaviour is that if you have a list of items which belong to another model, it will include that models name. So if you are looking for a specific item by it's relation, this will make that easier. I have created a website for the plugin, with more detailed information.

So we change,

```
array(
    1 => 'First',
    2 => 'Second'
);
```

..into this..

```
array(
    'Cats' => array(
        1 => 'First',
    ),
    'Dogs' => array(
        2 => 'Second'
    )
);
```

..and you should end up with nice option groups in your selects.
[![Select box with optgroup](https://camo.githubusercontent.com/197a0e30ab037ba150c26c36493ea070e9145d2ac0bd53ae91b049aa4d32c6c3/687474703a2f2f692e696d6775722e636f6d2f51503742684d6c2e706e67)](https://camo.githubusercontent.com/197a0e30ab037ba150c26c36493ea070e9145d2ac0bd53ae91b049aa4d32c6c3/687474703a2f2f692e696d6775722e636f6d2f51503742684d6c2e706e67)

It works with multiselect too!
[![Multi select box with optgroup](https://camo.githubusercontent.com/11641c51fe5708f52c2bba3428bf9907ad44ccac86c47adb422c47d39f711d85/687474703a2f2f692e696d6775722e636f6d2f317431735276492e706e67)](https://camo.githubusercontent.com/11641c51fe5708f52c2bba3428bf9907ad44ccac86c47adb422c47d39f711d85/687474703a2f2f692e696d6775722e636f6d2f317431735276492e706e67)

\##Version This is something I'd consider `beta`.
I've created tests for this code and it achieves 96.88%.
[![Build Status](https://camo.githubusercontent.com/d5c0dc8b20c094e8edf6f4cad6ef18d78fa2d00e4d915d71bf70bf7c5c1966ee/68747470733a2f2f7472617669732d63692e6f72672f646176696479656c6c2f43616b655048502d4c697374696e672e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/davidyell/CakePHP-Listing)

\##Installation This is a standard CakePHP plugin, so it will need to extracted or submoduled into your `app/Plugin` folder. I call it `Listing`, so it should live in `app/Plugin/Listing`.

You will need to activate the plugin in your `app/Config/bootstrap.php` using `CakePlugin::load('Listing')`, unless you are already using `CakePlugin::loadAll()`

\##Requirements

- Cake 2
- Containable

The models you are using with this behaviour must have Containable enabled. `public $actsAs = array('Containable', 'Listing.Listable');`I tend to add Containable to my `AppModel` as it's handy to have everywhere!

\##Usage You can attach to the model using the `$actsAs` array. As you would normally. You **must** include the name of the related model that you want to join to when you configure the behaviour.

This is usually the parent model in the relationship, as the behaviour will attach to the child. So if you want to list `Broadband` by `Provider` you would attach the behaviour to the `Broadband` model, and configure the `relatedModelName` as `Provider`.

\###Configuration

You can also specify the fields that you want to use using, `primaryKey` and `displayField`.

```
public $actsAs = array(
    'Listing.Listable' => array(
       'relatedModelName' => 'Provider', // Example - this should be the parent model, the one you want to group by
       'relatedModelPrimaryKey' => 'id', // optional - default shown
       'relatedModelDisplayField' => 'name', // optional - default shown
    )
);
```

[More on Behaviours in the Book](http://book.cakephp.org/2.0/en/models/behaviors.html).

\###Getting a listing Then in order to attach the extra model, I have implemented a custom find called `listing` which will return the formatted list.

For example, `$broadbands = $this->Broadband->find('listing');`

\###Customising your listing The easiest way to customise the display of your listing is to use the models `$virtualFields` property to create new fields which you can then pass into the find. Let's look at an example.

We want a listing of all the Users grouped by role. However our database has both `first_name` and `last_name`, but we want to display a listing of the users full name. We can create a virtual field and select that.

```