paulredmond/chosen-cakephp

Chosen CakePHP plugin for CakePHP 2

ChosenHelper for CakePHP 2

ChosenHelper is a class for integrating HarvestHQ Chosen select boxes in CakePHP 2. Check out HarvestHQ's demo for documentation and usage., _(*1)

, _(*2)

Changelog

A Changelog Wiki page is now available. Review it carefully to make sure you do not upgrade permaturely. For example: the latest version (2.1.0) includes a backwards compatability break with CakePHP 2.0.x., _(*3)

Installation

Chosen CakePHP 2 plugin supports Composer and Packagist. After you download composer.phar and put it in your path:, _(*4)

Composer will take care of installing the plugin into the correct location. Include the following composer.json file at path/to/app, _(*5)

{
    "require": {
        "paulredmond/chosen-cakephp": "*"
    }
}

Use a sensible stable version for the plugin. The above '*' is only intended as an example., _(*6)

cd path/to/app
php composer.phar install

Bootstrap the plugin in app/Config/bootstrap.php:, _(*7)

Optional webroot symlink

cd /path/to/app/webroot
ln -s ../Plugin/Chosen/webroot chosen

Setup

In /app/Controller/AppController.php:, _(*8)

 array(
        'framework' => 'prototype',
        'class'     => 'chosen-custom', // Deselect-enabled class would be 'chosen-custom-deselect'
    ),
);
```

Now all classes rendered with the helper, or other `````` inputs with your configured class will be targeted.

### JQuery / Prototype
Make sure that you are loading JQuery (1.4+) or Prototype however you want:

```php
Html->script('jquery'); // sets src to /js/jquery.js
```

* Note: Chosen CSS/JS files are only loaded if the helper select method is called at least once.*

Pull Requests
-------------


Chosen CakePHP plugin has [contributions](https://github.com/paulredmond/chosen-cakephp/graphs/contributors) from the Github communitiy. I am grateful for the suggestions, fixes, and improvements. If you'd like to submit a pull request, follow these simple instructions:

  * Pull requests for the 2.1.x version should be submitted to the `2.1` branch
  * If the supported `2.0` branch (for CakePHP 2.0.x) could benefit from your Pull Request, consider opening another Pull Request for that branch.
  * The `master` branch reflects the latest stable version available.

Testing
-------
You can run tests for Chosen with phpunit from the ```app``` folder. Learn more about [Testing in CakePHP 2](http://book.cakephp.org/2.0/en/development/testing.html)

_Ensure that you have installed the vendor dependencies for this plugin through composer or some other means._

```console
./Console/cake testsuite Chosen View/Helper/ChosenHelper
```


Examples
--------
Chosen inputs behave identically to the FormHelper::input() method.

Multi-select:

```php
Chosen->select(
    'Article.category_id',
    array(1 => 'Category 1', 2 => 'Category 2'),
    array('data-placeholder' => 'Pick categories...', 'multiple' => true)
);
?>

Default selected:, _(*9)

<?php
echo $this->Chosen->select(
    'Article.category_id',
    array(1 => 'Category 1', 2 => 'Category 2'),
    array(
        'data-placeholder' => 'Pick categories...',
        'default' => 1,
    )
);
?>

Grouped:, _(*10)

<?php
echo $this->Chosen->select(
    'Profile.favorite_team',
    array(
        'NFC East' => array(
            'Dallas Cowboys',
            'New York Giants',
            'Philadelphia Eagles',
            'Washington Redskins'
        ),
        'NFC North' => array(
            'Chicago Bears',
            'Detroit Lions',
            'Greenbay Packers',
            'Minnesota Vikings'
        ),
        // ....
    ),
    array(
        'data-placeholder' => 'Pick your favorite NFL team...',
        'style' => 'width: 350px'
    )
);
?>

Deselect on Single Select:, _(*11)

<?php
echo $this->Chosen->select(
    'Profile.optional',
    $options,
    array('data-placeholder' => 'Please select...', 'deselect' => true),
);
?>

Do not use 'empty' => 'Please Select...' attribute with deselect, use 'data-placeholder' => 'Please Select...' instead., _(*12)

License

Copyright 2013 Paul Redmond. It is free software, and may be redistributed under the terms specified in the LICENSE file. License is also available online., _(*13)