view release on metacpan or  search on metacpan

lib/CatalystX/Controller/ExtJS/REST.pm  view on Meta::CPAN

per controller

If you create a controller C<MyApp::Controller::User>:

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

Forms can be defined either in files or directly in the controller.
To see how to define forms directly in the controller see L</forms>.

If you are creating files, you need at least one file called C<root/forms/user.yml>.
For a more fine grained control over object creation, deletion, update or listing, you 
have to create some more files.

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

Only C<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 C<root/forms/user_get.yml>.
If this file does not exist, it will fall back to the so called I<base file>
C<root/forms/user.yml>.

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

You can override these values in the form config files:

  ---
    model_config:
      resultset: User
      schema: DBIC
    elements:
      - name: username
      - name: password
      - name: name
      - name: forename
      
  # root/forms/user_put.yml
  # make username and password required an object is created
  ---
    load_config_file: root/forms/user.yml
	constraints:
	  - type: Required
	    name: username
	  - type: Required
	    name: password

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

=head2 Accessing objects

To access an object, simply request the controller's url with the desired method.
A C<POST> request to C</user> will create a new user object. The response will include
the id of the new object. You can get the object by requesting C</user/$id> via GET
or remove it by using the C<DELETE> method. 

To update an object, use C<PUT>. PUT is special since it also allows for partial 
submits. This means, that the object is loaded into the form before the request parameters
are applied to it. You only need to send changed columns to the server.

=head2 Accessing a list of objects

You can access L<http://localhost:3000/users> or L<http://localhost:3000/user> to get a list 
of users, which can be used to populate an ExtJS store. 
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 be extended.
There is also a built-in validation for query parameters. By default the following 
parameters are checked for sane defaults:

=over

=item * dir (either C<asc>, C<ASC>, C<desc> or C<DESC>)

=item * limit (integer, range between 0 and 100)

=item * start (positive integer)

=back

You can extend the validation of parameters by providing an additional file. Place it in
C<root/lists/> and add the suffix C<_options> (e. g. C<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 comma 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. Though, you cannot access resultset method which are
inherited from L<DBIx::Class::ResultSet>. This is a security restriction because
an attacker could call C<http://localhost:3000/users/delete> which will lead to 
C<< $c->model('DBIC::Users')->delete >>. This would remove all rows from C<DBIC::Users>!

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