Documentation

Keyword arguments ($kargs): controllerScan (callback) Function to return an array of valid controllers

redirect (callback) Function to perform a redirect for Horde_Routes_Utils->redirectTo()

directory (string) Path to the directory that will be passed to the controllerScan callback

alwaysScan (boolean) Should the controllerScan callback be called before every URL match?

explicit (boolean) Should routes be connected with the implicit defaults of array('controller'=>'content', 'action'=>'index', 'id'=>null)? When set to True, these will not be added to route connections.

Usage: $m = new Horde_Routes_Mapper(); $m->connect(':controller/:action/:id'); $m->connect('date/:year/:month/:day', array('controller' => "blog", 'action' => 'view'); $m->connect('archives/:page', array('controller' => 'blog', 'action' => 'by_page', ' requirements' => array('page' => '\d{1,2}'))); $m->connect('category_list', 'archives/category/:section', array('controller' => 'blog', 'action' => 'category', 'section' => 'home', 'type' => 'list')); $m->connect('home', '', array('controller' => 'blog', 'action' => 'view', 'section' => 'home'));

Usage: $m->generate(array('controller' => 'content', 'action' => 'view', 'id' => 10));

URL text or null

It will return null if no valid match is found.

Usage: $resultdict = $m->match('/joe/sixpack');

Array if matched, otherwise null

The $memberName name should be the appropriate singular version of the resource given your locale and used with members of the collection.

The $collectionName name will be used to refer to the resource collection methods and should be a plural version of the $memberName argument. By default, the $memberName name will also be assumed to map to a controller you create.

The concept of a web resource maps somewhat directly to 'CRUD' operations. The overlying things to keep in mind is that mapping a resource is about handling creating, viewing, and editing that resource.

All keyword arguments ($kargs) are optional.

controller If specified in the keyword args, the controller will be the actual controller used, but the rest of the naming conventions used for the route names and URL paths are unchanged.

collection Additional action mappings used to manipulate/view the entire set of resources provided by the controller.

Example::

    $map->resource('message', 'messages',
                   array('collection' => array('rss' => 'GET)));
    # GET /message;rss (maps to the rss action)
    # also adds named route "rss_message"

member Additional action mappings used to access an individual 'member' of this controllers resources.

 Example::

     $map->resource('message', 'messages',
                    array('member' => array('mark' => 'POST')));
     # POST /message/1;mark (maps to the mark action)
     # also adds named route "mark_message"

new Action mappings that involve dealing with a new member in the controller resources.

 Example::

     $map->resource('message', 'messages',
                    array('new' => array('preview' => 'POST')));
     # POST /message/new;preview (maps to the preview action)
     # also adds a url named "preview_new_message"

pathPrefix Prepends the URL path for the Route with the pathPrefix given. This is most useful for cases where you want to mix resources or relations between resources.

namePrefix Perpends the route names that are generated with the namePrefix given. Combined with the pathPrefix option, it's easy to generate route names and paths that represent resources that are in relations.

 Example::

     map.resource('message', 'messages',
                  array('controller' => 'categories',
                        'pathPrefix' => '/category/:category_id',
                        'namePrefix' => 'category_')));
         # GET /category/7/message/1
         # has named route "category_message"

parentResource An assoc. array containing information about the parent resource, for creating a nested resource. It should contain the $memberName and collectionName of the parent resource. This assoc. array will be available via the associated Route object which can be accessed during a request via request.environ['routes.route']

 If ``parentResource`` is supplied and ``pathPrefix`` isn't,
 ``pathPrefix`` will be generated from ``parentResource`` as
 "<parent collection name>/:<parent member name>_id".

 If ``parentResource`` is supplied and ``namePrefix`` isn't,
 ``namePrefix`` will be generated from ``parentResource`` as
 "<parent member name>_".

 Example::

     $m = new Horde_Routes_Mapper();
     $utils = $m->utils;

     $m->resource('location', 'locations',
                  array('parentResource' =>
                         array('memberName' => 'region',
                               'collectionName' => 'regions'))));
     # pathPrefix is "regions/:region_id"
     # namePrefix is "region_"

     $utils->urlFor('region_locations', array('region_id'=>13));
     # '/regions/13/locations'

     $utils->urlFor('region_new_location', array('region_id'=>13));
     # '/regions/13/locations/new'

     $utils->urlFor('region_location',
                   array('region_id'=>13, 'id'=>60));
     # '/regions/13/locations/60'

     $utils->urlFor('region_edit_location',
                   array('region_id'=>13, 'id'=>60));
     # '/regions/13/locations/60/edit'

Overriding generated pathPrefix::

 $m = new Horde_Routes_Mapper();
 $utils = new Horde_Routes_Utils();

 $m->resource('location', 'locations',
              array('parentResource' =>
                    array('memberName' => 'region',
                          'collectionName' => 'regions'),
                    'pathPrefix' => 'areas/:area_id')));
  # name prefix is "region_"

  $utils->urlFor('region_locations', array('area_id'=>51));
  # '/areas/51/locations'

Overriding generated namePrefix::

  $m = new Horde_Routes_Mapper
 $m->resource('location', 'locations',
              array('parentResource' =>
                    array('memberName' => 'region',
                          'collectionName' => 'regions'),
                    'namePrefix' => '')));
  # pathPrefix is "regions/:region_id"

  $utils->urlFor('locations', array('region_id'=>51));
  # '/regions/51/locations'

Note: Since Horde Routes 0.2.0 and Python Routes 1.8, this method is not compatible with earlier versions inasmuch as the semicolon is no longer used to delimit custom actions. This was a change in Rails itself (http://dev.rubyonrails.org/changeset/6485) and adopting it here allows us to keep parity with Rails and ActiveResource.

It will return null if no valid match is found, otherwise a result dict (array) and a route object is returned.

Usage: list($resultdict, $resultobj) = $m->match('/joe/sixpack');

Array if matched, otherwise null