OVERVIEW

Provides integration between Drupal and Ext JS ( http://www.sencha.com/products/extjs/ ).


REQUIREMENTS

Ext JS 4.x.


INSTALLATION

1. Download and extract the Ext JS library to sites/all/libraries, such that 
   the file ext-all.js is located at sites/all/libraries/ext/ext-all.js

2. Install and enable this module in the normal way.

3. The module may be configured at Admin > Site configuration > Ext. 


API

Developers who wish to alter and extend the functions and behaviour of this 
module can make use of the following naming conventions and hooks. See 
includes/ext.inc for examples of most of the hooks. This documentation assumes
knowledge of the Ext JS library (documenting some subset of Ext JS is beyond
the scope of this document and is better done in the actual Ext JS 
documentation). 

NAMING CONVENTIONS:

 * Model names should use a CamelCase format (eg Node or NodePage).
 
 * In Ext JS the Models defined via this module are defined in 
   Ext.drupal.[ModelName]
 
 * For the sake of simplicity it is suggested that Model field names be 
   identical to those used server-side.
 
 * All hook implementations can optionally be placed in a file named ext.inc 
   in a directory called includes in the implementing module
   (eg in sites/all/modules/my_module/includes/ext.inc)
   
 * This module provides Model definitions for content/node types and a user
   Model definition (more details below).
   It is assumed that any Model definitions with names starting with "Node" 
   or "User" extend these Models and can be validated by this module (that is, 
   if you don't want your Model data to be validated by this modules 
   validation function, don't use a Model name starting with Node or User, 
   and vice-versa).


HOOKS:

hook_ext_models(): 
  Allows modules to provide definitions of new Ext Models.
  A module providing Model definitions must also implement 
  hook_ext_load_model_data() and hook_ext_save_model_data().
  The return value should be an array, keyed by Model names, of arrays of model
  definitions that follow the same format as
  http://docs.sencha.com/ext-js/4-0/#!/api/Ext.data.Model , with the following
  caveats:
    * A Model definition is an associative array.
    
    * A Model definition may only specify a subset of the configuration options
      specified by the Ext Model API, at the moment these are:
      'associations', 'fields', 'idProperty', 'idgen', 'listeners', 
      'persistenceProperty', 'validations'. Other key/value pairs will be 
      ignored when generating the JS Model definition (this means you can
      safely put in any other key/value pairs for your own purposes).
      The 'proxy' config option cannot be specified as this is handled by the
      ext module via its RESTful API and the 
      hook_ext_[load|save|delete]_model_data hooks.
      
    
    * A Model may extend another Model by specifying an 'extends' member, eg a 
      a Model for a specific content type can extend a generic node Model.
      This module provides Model definitions for all content types and these 
      definitions include all CCK fields defined for the type. Thus a module 
      implementing a custom node type containing CCK fields can extend this 
      definition and does not have to include the CCK fields (or other 
      standard node fields) in its definition (and the definition provided 
      by this module can be altered via hook_ext_models_alter() if necessary).
      
      NOTE: It is assumed that a module extending an existing Model definition 
      will handle all processing for the save, load, validate and delete 
      operations. 
      Generally this can be handled by invoking the relevant hook on the module
      defining the base Model being extended, for example a module extending 
      the definition for some content type (as defined by this module) could 
      invoke ext_ext_[op]_model_data() to perform the basic processing.
      
    * A Model may specify that it requires server-side validation by setting
      the member 'server_validate' to TRUE (otherwise it may be left out or 
      set to FALSE). If this is set then the module defining the Model should
      implement hook_ext_validate_model_data(). If any Model in the 
      inheritance chain of a Model requires server-side validation then it 
      will automatically be set for the sub-Model.
    
    * Javascript code may be inserted for some values by wrapping it in 
      <jscode> tags (inside a string value for the model definition), eg:
      "<jscode>Drupal.settings.myModule.myExtModel.serverValidate</jscode>".
      Note: the tags must be right at the start and end of the string, with no 
      spaces or other characters before the opening tag or after the closing 
      tag (this is due to the way drupal_to_js() works).
      
  An example definition follows:
    $models = array(
      'NodeMyType' => array (
        'extends' => 'Node',
        'idProperty' => 'nid',
        'server_validate' => "<jscode>Drupal.settings.myModule.myExtModel.serverValidate</jscode>",
        'fields' => array ( 
          array ( 
            'name' => 'field_mynoderef', // This is a CCK nodereference field.
          ),
          ...
          array ( 
            'name' => 'my_user_ref', // A custom defined reference to a user.
          ),
        ),
        'associations' => array ( 
          array ( 
            'type' => 'hasMany',    // The CCK field allows multiple values,
            'model' => 'NodePage',  // so hasMany makes the most sense.
            'primaryKey' => 'field_mynoderef',
            'foreignKey' => 'nid',
          ),
          ...
          array ( 
            'type' => 'belongsTo', // Only a single value is allowed.
            'model' => 'User',
            'primaryKey' => 'my_user_ref',
            'foreignKey' => 'uid',
          ),
        ),
        'validations' => array ( 
          array ( 
            'field' => 'field_mynoderef',
            'type' => 'presence',
          ),
          ...
          array ( 
            'field' => 'my_user_ref',
            'type' => 'inclusion',
            'list' => array(1, 2 ,3),
          ),
        ),
      ),
    ),


hook_ext_models_alter(&$models):
  Allows modules to alter any aspect of existing Model definitions.
  The $models parameter contains an array in the same format as that returned 
  by hook_ext_models().


hook_ext_access_model_data($model_instance_id, $model_name, $op):
  Modules providing Model definitions must implement this hook to allow 
  the system to determine if the current or given user has permission to 
  perform the specified operation on the specified model data.
  The return value should be TRUE or FALSE, to allow or deny permission 
  respectively.
  The $model_instance_id parameter specifies the unique ID for the model 
  instance, for example for a Node Model this would be the node ID (nid).
  The ID will be null for the 'create' operation.
  The $op parameter specifies the operation to perform. This can be one
  'create', 'view', 'update' or 'delete'.
  

hook_ext_load_model_data($model_instance_id, $model_name):
  Modules providing Model definitions must implement this hook to allow 
  loading the data for an instance of any Model it defines. Other modules may
  alter the data via hook_ext_load_model_data_alter. This data will then be sent to 
  the Ext JS client.
  The return value should be an associative array containing keys matching 
  those defined in the Model $model_name. The returned array may also contain 
  other data, which will be ignored. FALSE should be returned if the load 
  failed.
  The $model_instance_id parameter specifies the unique ID for the model 
  instance, for example for a Node Model this would be the node ID (nid).


hook_ext_load_model_data_alter(&$data, $model_name):
  Allows any module to alter the data for a Model instance after it is loaded 
  and before it is sent to the Ext JS client.
  
  
hook_ext_save_model_data(&$data, $model_name, $new):
  Modules providing Model definitions must implement this hook to allow 
  saving the data for an instance of any Model it defines. Other modules may
  alter the data before it is saved via hook_ext_save_model_data_alter.
  The $data parameter will be an associative array containing keys matching 
  those defined in the Model $model_name.
  NOTE: all data sent from the Ext client is decoded as arrays (associative to 
  represent Javascript objects).
  If the $new parameter is set to TRUE then a new instance will be created, 
  otherwise an existing instance will be updated if $data has the primary ID 
  set.
  The return value should evaluate to FALSE if the save failed, otherwise TRUE.
  
  
hook_ext_save_model_data_alter(&$data, $model_name):
  Allows any module to alter the data for a Model instance before it is saved.
  
  
hook_ext_validate_model_data($data, $model_name):
  Modules providing Model definitions should implement this hook if any of 
  their Model definitions have the 'server_validate' member set to TRUE. Other 
  modules may also implement this hook to provide validation (particularly if
  they implement hook_ext_[load|save]_model_data_alter().
  NOTE: all data sent from the Ext client is decoded as arrays (associative to 
  represent Javascript objects).
  The return value should be an array keyed by field names containing 
  translated error messages (if there are no errors an empty array should be
  returned).
  
  
hook_ext_delete_model_data($model_instance_id, $model_name):
  Modules providing Model definitions must implement this hook to allow 
  deleting the data for an instance of any Model it defines.
  The $model_instance_id parameter specifies the unique ID for the model 
  instance, for example for a Node Model this would be the node ID (nid).

  
hook_ext_stores():
  Allows modules to provide definitions of new Ext Stores.
  The return value should be an array, keyed by Store names/IDs, of arrays of 
  Store definitions that follow the same format as
  http://docs.sencha.com/ext-js/4-0/#!/api/Ext.data.Store , with the following
  caveats:
    * A Store definition is an associative array.
    
    * The Store definition should not specify a 'storeId', this is set 
      automatically by the ext module to be the Store name/ID.
      
    * The 'proxy' config option cannot be specified as this is handled by the
      ext module via its RESTful API and the hook_ext_load_store_data hook.
      
  An example definition follows:
    $stores = array(
      'MyStore' => array (
        'model' => 'Node',
      ),
    ),


hook_ext_stores_alter(&$stores):
  Allows modules to alter any aspect of existing Store definitions.
  The $models parameter contains an array in the same format as that returned 
  by hook_ext_stores().
  
  
hook_ext_load_store_data($store_name, $options):
  Modules providing Store definitions must implement this hook to allow 
  loading the data for a Store it defines. Other modules may alter the data 
  via hook_ext_load_store_data_alter. This data will then be sent to 
  the Ext JS client.
  The return value should be an array of Model instance IDs (these will then 
  be passed to ext_load_model_data to retrieve the actual data). 
  FALSE should be returned if the load failed.
  The $options parameter is an associative array containing information that 
  the defining module needs to determine the result set (eg View arguments).