README

ChosenHelper is a class for integrating HarvestHQ Chosen select boxes in CakePHP 2. Check out HarvestHQ's demo for documentation and usage.

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.

Installation

Chosen CakePHP 2 plugin supports Composer and Packagist. After you download composer.phar and put it in your path:

Composer will take care of installing the plugin into the correct location. Include the following composer.json file at path/to/app

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

Use a sensible stable version for the plugin. The above '*' is only intended as an example.

cd path/to/app
php composer.phar install

Bootstrap the plugin in app/Config/bootstrap.php:

<?php

// ...

CakePlugin::load('Chosen');

?>

Optional webroot symlink

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

Setup

In /app/Controller/AppController.php:

<?php

public $helpers = array(
    'Chosen.Chosen',
);

Out of the box, the ChosenHelper will work with jQuery; but you might want prototype or a custom class:

<?php

public $helpers = array(
    'Chosen.Chosen' => array(
        'framework' => 'prototype',
        'class'     => 'chosen-custom', // Deselect-enabled class would be 'chosen-custom-deselect'
    ),
);

Now all classes rendered with the helper, or other <select> 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

// One way in In default.ctp
echo $this->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 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

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

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

Examples

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

Multi-select:

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

Default selected:

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

Grouped:

<?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:

<?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.

paulredmond / chosen-cakephp

Maintainers

Details