# sfAdminSortByForeignNamePlugin

## Introduction

The Symfony admin generator provides an easy way to manage your tables,
including support for sorting the list view on any column. However,
when the user attempts to sort on a column that contains a foreign key
referencing another table, the rows are sorted numerically by foreign ID.
This is probably not what the user expects. Unfortunately the 
Symfony admin generator currently does not provide a way to sort on
the name field of a foreign table. This plugin fills that gap.

## Installation and Configuration

Let's assume your schema looks like this:

    event:
      id:
      name: varchar(100)
      venue_id:
      studio_id:
      instructor_id:
      # Other stuff
  
    venue:
      id:
      name: varchar(100)
      # Other stuff

    studio:
      id:
      name: varchar(100)
      # Other stuff

    instructor:
      id:
      name: varchar(100)
      # Other stuff

You have used the `symfony propel-init-admin backend event' command to
build an admin-generated module that manages the event class. Now you
want to allow users to sort the table by instructor, venue, or studio
name with a minimum of effort.

To do that, just:

 * 1. Install this plugin.
 * 2. Make sure your foreign tables have a field called "name" which
   contains the name you want to sort them by.
 * 3. Add the following
method to your `backend/modules/event/actions/actions.class.php` file:

    protected function addSortCriteria($c)
    {
      if (sfAdminSortByForeignName::addSortByForeignName($c, "Event"))
      {
        return;
      }
      parent::addSortCriteria($c);
    }

Note that you must pass the name of the class being managed as the second
parameter to the `addSortByForeignName` method.

Note also that when `addSortByForeignName` returns false, we keep going
and call the parent class version of `addSortCriteria`. Without this
code, it would no longer be possible to sort on non-foreign-key fields 
of the Event class itself.

## Changelog

### version 0.1 - 2008-09-20

Initial version.

## TODO

  * It would be nice to support field names other than NAME via
  app.yml.

## Contact 
sfTagtoolsPlugin was created by Tom Boutell at
[http://www.boutell.com/ Boutell.Com]. 
Please address questions, concerns and patches to [mailto:boutell@boutell.com Tom Boutell].