Routes

Quote:
[*IMP: The discussion in this section assumes you have already gone through the 'Custom routes' tutorial - /docs/custom-routes/]

The notes.php template makes use of the 'routes' module to implement custom URLs.
You'll notice that it does this by defining the template as 'routable'
Code:
<cms:template title='Notes' clonable='1'  routable='1'>

and then asking Couch not to apply the default URLS to it -
Code:
<?php COUCH::invoke( K_IGNORE_CONTEXT ); ?>

If you play around with Notejam, you'll see the various URLs that the 'notes' part of it responds to when listing, editing, creating or deleting the notes.

I'll list below all those URLs and the corresponding routes defining them in the template.

1. list_view
Shows a list of all the notes related to the logged-in user.

Sample URLs:
Quote:
http://www.yoursite.com/notes/
http://www.yoursite.com/notes.php (without prettyURLs)

Route definition:
Code:
<cms:route name='list_view' path='' filters='authenticated'/>

2. page_view
Shows the content of the note specified by the id ('16' in the sample URLs below).

Sample URLs:
Quote:
http://www.yoursite.com/notes/16
http://www.yoursite.com/notes.php?q=16 (without prettyURLs)

Route definition:
Code:
<cms:route
    name='page_view'
    path='{:id}'
    filters='authenticated | note_exists | owns_note'
    >
   
    <cms:route_validators
        id='non_zero_integer'
    />
</cms:route>

3. create_view
Shows a form that can be used to create a new note.

Sample URLs:
Quote:
http://www.yoursite.com/notes/create
http://www.yoursite.com/notes.php?q=create (without prettyURLs)

Route definition:
Code:
<cms:route name='create_view' path='create' filters='authenticated' />

4. create_with_pad_view
This is identical to 'create_view' above except that it automatically adds the new note to the pad specified by the id ('12' in the sample URLs below).
(Click on a pad in side bar to see the notes within it. Now press the 'New note' button to invoke this URL).

Sample URLs:
Quote:
http://www.yoursite.com/notes/12/create
http://www.yoursite.com/notes.php?q=12/create (without prettyURLs)

Route definition:
Code:
<cms:route
    name='create_with_pad_view'
    path='{:id}/create'
    filters='authenticated | pad_exists | owns_pad'
    >
   
    <cms:route_validators
        id='non_zero_integer'
    />
</cms:route>

5. edit_view
Shows a form that can be used to edit the note specified by the id ('16' in the sample URLs below).

Sample URLs:
Quote:
http://www.yoursite.com/notes/16/edit
http://www.yoursite.com/notes.php?q=16/edit (without prettyURLs)

Route definition:
Code:
<cms:route
    name='edit_view'
    path='{:id}/edit'
    filters='authenticated | note_exists | owns_note'
    >
   
    <cms:route_validators
        id='non_zero_integer'
    />
</cms:route>

6. delete_view
Shows a form that can be used to seek confirmation and subsequently delete the note specified by the id ('16' in the sample URLs below).

Sample URLs:
Quote:
http://www.yoursite.com/notes/16/delete
http://www.yoursite.com/notes.php?q=16/delete (without prettyURLs)

Route definition:
Code:
<cms:route
    name='delete_view'
    path='{:id}/delete'
    filters='authenticated | note_exists | owns_note'
    >
   
    <cms:route_validators
        id='non_zero_integer'
    />
</cms:route>

The routes above reflect the entire range of operations that are supported by notes.
Please notice in the route definitions above how we use 'cms:route_validators' to ensure only a valid ID is provided as URL parameter -
Code:
<cms:route_validators
    id='non_zero_integer'
/>

Notice also how the 'filters' used in the routes enforce that only a authenticated user can access the notes section and that she can see only notes that belong to her.

I think we should take a closer look at how the filters have been implemented.

Next: Filters