==============================
  Listing plugin for CakePHP
==============================


  If you have found any bugs, or you have any questions or feature requests,
  please email me at andrew (at) ondrejsimek (dot) com, thank you.


Features:
---------
 - multiple listings on one page (with their own pagination, search boxes, etc.)
 - pagination
 - searching in results
 - sorting
 - can use custom model method
 - scaffold
 - echos the code of the scaffold (just copy & paste the code in your view
   and modify it)
 - no ajax - that's not a bug :) - I just like having everything working without
   ajax first. Then I'm adding ajax where is needed. But I'll add ajax option in
   a future version.


TODO:
-----
 - make the code more readable :)
 - add an option for ajax


Author:
-------
Ondrej Simek
email: andrew@ondrejsimek.com
web: http://ondrejsimek.com


Github:
-------
http://github.com/angel333/listing


Tutorial:
---------
Let's say we have PostsController and Post model. We want to list all posts.

1) Load the component and the helper

   class PostsController extends AppController
   {
       public $components = array ('Listing.Listing');
       public $helpers = array ('Listing.Listing');
       ...

2) The information about current page, etc. are stored in a named parameter
   'listing'. If use default routing, you don't have to make any changes in
   your your routes.php file. If you use a custom routes for the controller,
   just make sure you have a star at the end of the route pattern.

   Router::connect('/all-posts/*', array ('controller' => 'posts', 'action' => 'index'));

   (Note: This is the main trick of this plugin - it uses only one parameter
   for everything - this parameter is actualy a serialized array, encoded with
   base64_encode(). It contains current page and sorting for all listings on the
   page. That's why you can use multiple listings easily.)

3) Now add to your index() method in PostsController something like this:

   (controllers/posts_controller.php)

   $this->set('data', $this->Listing->create($this->Post, array (
       'default' => array (
           'order' => 'Post.created DESC',
           'limit' => 10,
       ),
       'user' => array (
           'order' => array (
               'Post.title',
               'Post.name',
               'Post.modified',
           ),
           'limit' => array (10, 25, 50, 100),
           'search' => array (
               'Post.title',
               'Post.content',
           ),
       ),
   )));

   The parameters array contains parts 'default' and 'user'. In 'default' are
   just parameters for the find method. In 'user' you can specify, what the
   user can change and how.

4) Into the view just write this:

   <?=$listing->scaffold($data)?>

5) Now refresh your browser - you should see a table with results, search boxes,
   pagination and sort links, but the most important is the textarea at the end
   of the scaffold - just copy the code from it and paste it into your view
   (replace the line you've added in the previous step). Now you can easily
   modify the view code and make it look better.


Multiple listings on one page:
------------------------------
This plugin can handle as many listings as you like. Just pass them to your view.


Scaffolds:
----------
Scaffold is a very useful feature - when you're creating the listing (in controller),
use only scaffold in view ( $listing->scaffold($data) ), when your controller is ready,
just copy the code from the textarea to your view and modify it.

If your listing variable (in view) is not called $data, pass the name of the variable
as the second parameter to scaffold, e.g.:

  $listing->scaffold($activeUsers, 'activeUsers')

.. the code in textarea will use this name instead of $data.


Filters:
--------
Let's say you have 'published' field in your posts table. And you want to let the user
select if he wants to display published or not published posts. To your 'user' section of
Listing->create() method add this:

'filters' => array (
    'Published posts' => array (
        'Post.published' => true,
    ),
    'Not Published' => array (
        'Post.published' => false,
    ),
),

.. now check the links that appeared in your scaffold.


Custom method
-------------
Listing uses Model::find() by default. If you want to use your own method, just
add parameter 'method' to your parameters:

$this->set('data', $this->Listing->create($this->Post, array (
    'method' => 'myFind',
    'default' => array (
	    ...
    ),
    'user' => array (
	    ...
    ),
)));

Your method needs take paramters in the same form as the original find() -
$operation and $params. Listing requires only 'all' and 'count' operations:

public function myFind ($operation, $params)
{
    if ($operation == 'all')
    {
        ...
    }
    elseif ($operation == 'count')
    {
        ...
    }
}