The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CatalystX-ExtJS-0.08
River stage one • 1 direct dependent • 1 total dependent
++
/ CatalystX::Controller::ExtJS::REST

NAME

CatalystX::Controller::ExtJS::REST - RESTful interface to dbic objects

SYNOPSIS

  package MyApp::Controller::User;
  use base qw(CatalystX::Controller::ExtJS::REST);
  
  __PACKAGE__->config({ ... });
  1;
  
  # set the Accept header to 'application/json' globally
  
  Ext.Ajax.defaultHeaders = {
   'Accept': 'application/json'
  };

DESCRIPTION

This controller will make CRUD operations with ExtJS dead simple. Using REST you can update, create, remove, read and list objects which are retrieved via DBIx::Class.

CONFIGURATION

Local configuration:

  __PACKAGE__->config({ ... });

Global configuration for all controllers which use CatalystX::Controller::ExtJS::REST:

  MyApp->config( {
    CatalystX::Controller::ExtJS::REST => 
      { key => value }
  } );

find_method

The method to call on the resultset to get an existing row object. This can be set to the name of a custom function function which is defined with the (custom) resultset class. It needs to take the primary key as first parameter.

Defaults to 'find'.

default_rs_method

This resultset method is called on every request. This is useful if you want to restrict the resultset, e. g. only find objects which are associated to the current user.

Nothing is called if the specified method does not exist.

This defaults to extjs_rest_[controller namespace].

A controller MyApp::Controller::User expects a resultset method extjs_rest_user.

context_stash

To allow your form validation packages, etc, access to the catalyst context, a weakened reference of the context is copied into the form's stash.

    $form->stash->{context};

This setting allows you to change the key name used in the form stash.

Default value: context

form_base_path

Defaults to root/forms

list_base_path

Defaults to root/lists

no_list_metadata

If set to a true value there will be no meta data send with lists.

Defaults to undef. That means the metaData hash will be send by default.

model_config

schema

Defaults to DBIC

resultset

Defaults to "default_resultset"

namespace

Defaults to "namespace" in Catalyst::Controller

list_namespace

Defaults to the plural form of "namespace". If this is the same as "namespace" list_ is prepended.

LIMITATIONS

This module is limited to HTML::FormFu as form processing engine, DBIx::Class as ORM and Catalyst as web application framework.

USAGE

Required Files

Considering you create controller like this:

  package MyApp::Controller::User;
  
  use base 'CatalystX::Controller::ExtJS::REST';
  
  1;

Then you will want to create the following files:

  root/
       forms/
             user.yml
             user_get.yml
             user_post.yml
             user_put.yml
       lists/
             user.yml

Only root/forms/user.yml is required. All other files are optional. If ExtJS issues a GET request, this controller will first try to find the file root/forms/user_get.yml. If this file does not exist, it will fall back to the so called base file root/forms/user.yml.

This controller tries to guess the correct model and resultset. The model defaults to DBIC and the resultset is derived from the name of the controller. In this example we look for the resultset $c->model('DBIC::User').

You can override these values in the form config files:

  # root/forms/user.yml
  ---
    elements:
      - name: username
      - name: password
      - name: name
      - name: forename

  # root/forms/user.yml (exactly the same as the above)
  ---
    model_config:
      resultset: User
      schema: DBIC
    elements:
      - name: username
      - name: password
      - name: name
      - name: forename
      
  # root/forms/user_get.yml and friends
  ---
    load_config_file: root/forms/user.yml

Now you can fire up your Catalyst app and you should see two new chained actions:

  Loaded Chained actions:
  ...
  | /users/...                          | /user/list
  | /user/...                           | /user/object

You can access http://localhost:3000/users to get a list of users, which can be used to feed an ExtJS grid. If you access this URL with your browser you'll get a HTML representation of all users. If you access using a XMLHttpRequest using ExtJS the returned value will be a valid JSON string. Listing objects is very flexible and can easily extended. There is also a built in validation for query parameters. By default the following parameters are checked for sane defaults:

dir (either asc, ASC, c<desc> or DESC)
limit (integer, range between 0 and 100)
start (positive integer)

You can extend the validation of parameters by providing an additional file. Place it in root/lists/ and postfix it with _options (e. g. root/lists/user_options.yml). You can overwrite or extend the validation configuration there.

Any more attributes you add to the url will result in a call to the corresponding resultset.

  # http://localhost:3000/users/active/
  
  $c->model('DBIC::Users')->active($c)->all;

As you can see, the Catalyst context object is passed as first parameter. You can even supply arguments to that method using a komma separated list:

  # http://localhost:3000/users/active,arg1,arg2/
  
  $c->model('DBIC::Users')->active($c, 'arg1', 'arg2')->all;

You can chain those method calls to any length. You cannot access resultset method which are inherited from DBIx::Class::ResultSet, except all. This is a security restriction because an attacker could call http://localhost:3000/users/delete which will lead to $c->model('DBIC::Users')->delete. This would remove all rows from DBIC::Users!

To define a default resultset method which gets called every time the controller hits the result table, set:

  __PACKAGE__->config({default_rs_method => 'restrict'});

This will lead to the following chain:

  # http://localhost:3000/users/active,arg1,arg2/
  
  $c->model('DBIC::Users')->restrict($c)->active($c, 'arg1', 'arg2')->all;

  # and even with GET, POST and PUT
  # http://localhost:3000/user/1234
  
  $c->model('DBIC::Users')->restrict($c)->find(1234);

The default_rs_method defaults to the value of "default_rs_method". If it is not set by the configuration, this controller tries to call extjs_rest_$class (i.e. extjs_rest_user).

To create, delete and modify user objects, simply POST, DELETE or PUT to the url /user. POST and DELETE require that you add the id to that url, e. g. /user/1234.

Handling Uploads

This module handles your uploads. If there is an upload and the name of that field exists in you form config, the column is set to an IO::File object. You need to handle this on the model side because storing a filehandle will most likely fail.

There a modules out there which can help you with that. Have a look at DBIx::Class::InflateColumn::FS. DBIx::Class:InflateColumn::File will not work as this module expects a hash with the file handler and the file name set. But you can still overwrite "handle_uploads" to your needs.

As an upload field is a regular field it gets set twice. First the filename is set and $row->update is called. This is entirely handled by HTML::FormFu::Model::DBIC. After that "handle_uploads" is called which sets the value of a upload field to the corresponding IO::File object. Make sure you test for that, if you plan to inflate such a column.

If you want to handle uploads yourself, overwrite "handle_uploads"

  sub handle_uploads {
      my ($self, $c, $row) = @_;
      if(my $file = c->req->uploads->{upload}) {
          $file->copy_to('yourdestination/'.$filename);
          $row->upload($file->filename);
      }
  }

But this should to be part of the model actually.

Since you cannot upload files with an XMLHttpRequest ExtJS creates an iframe and issues a POST request in there. If you need to make a PUT request you have to tunnel the desired method using a hidden field, by using the params config option of Ext.form.Action.Submit or extraParams in Ext.Ajax.request. The name of that parameter has to be x-tunneled-method.

Make sure you do not include a file field in your GET form definition. It will cause a security error in your browser because it is not allowed set the value of a file field.

PUBLIC METHODS

get_form

Returns a new HTML::FormFu::ExtJS class, sets the model config options and the request type to Catalyst.

list

List Action which returns the data for a ExtJS grid.

handle_uploads

Handles uploaded files by assigning the filehandle to the column accessor of the DBIC row object.

is_extjs_upload

Returns true if the current request looks like a request from ExtJS and has multipart form data, so usually an upload. This requires that you add a x-requested-by parameter to your form which has the value ExtJS. This can be done either by adding a hidden form field, by using the params config option of ExtJS Ext.form.Action.Submit or extraParams in Ext.Ajax.request.

default_resultset

Determines the default name of the resultset class from the Model / View or Controller class.

list_base_path

Returns the path in which form config files for grids will be searched.

list_base_file

Returns the path to the specific form config file for grids or the default form config file if the specfic one can not be found.

object

REST Action which returns works with single model entites.

object_PUT

REST Action to update a single model entity with a PUT request.

object_POST

REST Action to create a single model entity with a POST request.

object_PUT_or_POST

Internal method for REST Actions to handle the update of single model entity with PUT or POST requests.

This method is called before the form is being processed. To add or remove form elements dynamically, this would be the right place.

object_GET

REST Action to get the data of a single model entity with a GET request.

object_DELETE

REST Action to delete a single model entity with a DELETE request.

path_to_forms

Returns the path to the specific form config file or the default form config file if the specfic one can not be found.

base_path

Returns the path in which form config files will be searched.

base_file

Returns the path to the default form config file.

PRIVATE METHODS

These methods are private. Please don't overwrite those unless you know what you are doing.

begin

Run this code before any action in this controller. It sets the ActionClass to CatalystX::Action::ExtJS::Deserialize. This ActionClass makes sure that no deserialization happens if the body's content is a file upload.

end

If the request contains a file upload field, extjs expects the json response to be serialized and returned in a document with the Content-type set to text/html.

_parse_NSPathPart_attr

_parse_NSListPathPart_attr

_extjs_config

This accessor contains the configuration options for this controller. It is created by merging __PACKAGE__->config with the default values.

AUTHOR

  Moritz Onken
  
  Mario Minati

COPYRIGHT AND LICENSE

This software is Copyright (c) 2009 by Moritz Onken.

This is free software, licensed under:

  The (three-clause) BSD License