Installation and Usage

Prerequisites

1. You have downloaded and installed the lasted release of CakePHP 2.

2. You have downloaded the lastest release of ExtJS 4

    Note that while this project is under MIT license, ExtJS is only available in a different license model.
    See http://www.sencha.com/products/extjs/license/
   

Installation

1. Download the Bancha source and place it into the plugins folder of the existing CakePHP installation. (You should then have a folder plugins/Bancha).

2. Configure your bootstrap (app/Config/bootstrap.php) by adding at the end

    CakePlugin::load('Bancha'); 
    App::import('Controller', 'Bancha.Bancha'); 
    App::import('Behavior', 'Bancha.Bancha');
   

3. Configure routes (app/Config/routes.php) by adding following before CakePlugin::routes();:

    Router::parseExtensions('js');
    Router::connect('/bancha-api.js?models=*', array('controller' => 'Bancha', 'action' => 'index'));
   

4. Copy the Bancha API _plugins/Bancha/app/webroot/bancha.php into app/webroot/

5. Copy the Bancha JS plugins/Bancha/Lib/vendors/js/Bancha.js into app/webroot/js/

6. Place ext-all.js and ext-all-dev.js into app/webroot/js/ and the ExtJS ressources folder into app/webroot/css/

7. To use Bancha on a site include extjs, and the files bancha-api.js and js/Bancha.js into your layout. For production usage you may want to add a parameter to already load all metadata on startup: bancha-api.js?models=[all] or bancha-api.js?models=[Article,User]. Example:

    <!-- include ExtJS -->
    <script type="text/javascript" src="js/ext-all-dev.js"></script>
    
    <!-- include Bancha and the remote API -->
    <script type="text/javascript" src="js/Bancha.js"></script>
    <script type="text/javascript" src="bancha-api.js?models=[all]"></script>
   

8. Optional: Currently in the default scaffold configs we use images in the buttons. In the samples we use FamFamFam-icons, if you like them download them inside app/webroot/img/icons and add following css to your styles:

    .icon-add { background-image:url(/img/icons/add.png) ! important; }
    .icon-save { background-image:url(/img/icons/disk.png) ! important; }
    .icon-reset { background-image:url(/img/icons/arrow_undo.png) ! important; }
    .icon-upload { background-image:url(/img/icons/image_add.png) ! important; }
    .icon-edit-user { background-image:url(/img/icons/user_edit.png) ! important; }
   

Done.

For questions write me a mail: [email protected]

Usage

To expose the crud functions of an model to ExtJS follow these steps:

1. Add $actas = array("Bancha"); to the models you want to expose

2. Make sure that the primary's field of the model is called id (cake default)

3. Add validation rules, see Validation Rules

4. Bancha will expose only the crud function which are implemented in the controller. Please only augment the controller to always have a return statement in the function. Return value of TRUE/FALSE indicated if the operation was successfull or not, result standard cake data arrays will be transformed by Bancha to the appropriate ext format. For full list see Supported Controller-Method Results

   You can find the two preferred ways to extend the standard scaffolded controller [here](https://github.com/Bancha/Bancha/wiki/Controller-Augmentation-Alternative-1) and [here](https://github.com/Bancha/Bancha/wiki/Controller-Augmentation-Alternative-2) 
   
       Note: Currently Bancha can not handle Controller::setFlash() and Controller::redirect() 
   

   Side note: Bancha augments the models a bit, validations and save operations are only are executed on defined fields, validation will not fail if a field is missing - this is because ExtJS only send the changed fields in an edit request. If you don't like this set the BanchaBehavior setup config to array('useOnlyDefinedFields'=>false). Keep in mind to then use $model->saveFields($data,$options) instead of $model->save().

That's it, now you can write normal ExtJS code using Bancha.onModelReady(modelName,fn) and Bancha.getModel(modelName) or you take a look at our powerfull scaffolding classes which are using all the served meta data from cake to have create e.g. grids liks this: Ext.create("Ext.grid.Panel",{scaffold:'User'});

Tip: In development use an error-handler like this to more easily see server-side errors in extjs.

Bancha JavaScript API Docs

Bancha Samples

Have fun and enjoy your coffee ;)