paulredmond / chosen-cakephp
Chosen CakePHP plugin for CakePHP 2
Installs: 8 858
Dependents: 0
Suggesters: 0
Security: 0
Stars: 72
Watchers: 6
Forks: 17
Open Issues: 1
Language:JavaScript
Type:cakephp-plugin
Requires
- php: >=5.2.6
- composer/installers: 1.*
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.
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.