Implementation for the [wiki:BluePrintREST BluePrintREST] before extension into [wiki:RESTController JoinedResourceController]:

== Model ==
This is how Module writers need to add tables to their {{{models/module.py}}}:
{{{
resource = 'shelter'
table = module + '_' + resource
db.define_table(table, timestamp, uuidstamp,
                SQLField('name'))
s3.crud_fields[table] = ['name']
db[table].exposes = s3.crud_fields[table]
db[table].uuid.requires = IS_NOT_IN_DB(db, '%s.uuid' % table)
s3.crud_strings[table] = Storage(
    title_create = T('Add Shelter'),
    title_display = T('Shelter Details'),
    title_list = T('List Shelters'),
    title_update = T('Edit Shelter'),
    subtitle_create = T('Add New Shelter'),
    subtitle_list = T('Shelters'),
    label_list_button = T('List Shelters'),
    label_create_button = T('Add Shelter'),
    msg_record_created = T('Shelter added'),
    msg_record_modified = T('Shelter updated'),
    msg_record_deleted = T('Shelter deleted'),
    msg_list_empty = T('No Shelters currently registered'))
}}}

The supporting functions are in {{{models/00_db.py}}}:
 * http://trac.sahanapy.org/browser/models/00_db.py

== Controller ==
If using a single table for a resource, Developers just need to add this to their Controllers to provide all necessary CRUD functions with support for multiple representations:
{{{
def shelter():
    "RESTful CRUD controller"
    return shn_rest_controller(module, 'shelter')
}}}
These optional settings can also be set, if-desired:
{{{
# Don't allow resources to be creatable from List view
return shn_rest_controller(module, 'shelter', listadd=False)
# Don't allow resources to be deletable from List/Display views
return shn_rest_controller(module, 'shelter', deletable=False)
# Display extra field in the list view
return shn_rest_controller(module, 'shelter', extra='epsg')
}}}

== Views ==
If using a single table for a resource, Developers don't normally need to create any special views for CRUD. Default ones work fine.

If needing to create custom views (e.g. GIS Layer currently) then can extend these to add extra information in a maintainable way.

Custom views to replace the create.html, display.html, etc for each module and its resource(s) can be created in the regular 'views/module' directory as '<resource-name>_create.html' for example to replace create.html. If this view is not found for that module/resource, it will revert to the default one.

For example, to make a custom list_create view for the 'cr' module's 'shelter' resource, you would make a new view template file in 'views/cr/shelter_list_create.html' and make it look how you want. It will get picked up automatically if it exists, else the default one will be used.

{{{create.html}}}
{{{
{extend 'layout.html'}}
{{try:}}
 {{=H2(title)}}
{{except:}}
{{pass}}
{{include 'key.html'}}
<div class='form-container'>
{{try:}}
 {{=form}}
{{except:}}
  {{include}}
{{pass}}
</div>
<p>&nbsp;</p>
{{try:}}
 {{=list_btn}}
{{except:}}
{{pass}}
}}}

{{{display.html}}}
{{{
{{extend 'layout.html'}}
{{try:}}
 {{=H2(title)}}
{{except:}}
{{pass}}
{{try:}}
 {{=edit}}
{{except:}}
{{pass}}
<div class='item-container'>
{{try:}}
 {{=item}}
{{except:}}
  {{include}}
{{pass}}
</div>
{{try:}}
 {{=delete}}
{{except:}}
{{pass}}
<p>&nbsp;</p>
{{try:}}
 {{=list_btn}}
{{except:}}
{{pass}}
}}}

{{{list.html}}}
{{{
{{extend 'layout.html'}}
{{try:}}
 {{=H2(title)}}
{{except:}}
{{pass}}
{{try:}}
 {{=H3(subtitle)}}
{{except:}}
{{pass}}
<div id='list-container'>
{{try:}}
 {{=list}}
{{except:}}
  {{include}}
{{pass}}
</div>
<p>&nbsp;</p>
{{try:}}
 {{=add_btn}}
{{except:}}
{{pass}}
}}}

{{{list_create.html}}}
{{{
{{extend 'layout.html'}}
{{try:}}
 {{=H2(title)}}
{{except:}}
{{pass}}
{{try:}}
 {{=H3(subtitle)}}
{{except:}}
{{pass}}
<div id='list-container'>
{{try:}}
 {{=list}}
{{except:}}
{{pass}}
</div>
<p>&nbsp;</p>
{{try:}}
 {{=H3(addtitle)}}
{{except:}}
{{pass}}
<div class='form-container'>
{{try:}}
 {{=form}}
{{except:}}
{{pass}}
</div>
{{include 'key.html'}}
}}}

{{{update.html}}}
{{{
{{extend 'layout.html'}}

{{try:}}
 {{=H2(title)}}
{{except:}}
{{pass}}
{{include 'key.html'}}
<div class='form-container'>
{{try:}}
 {{=form}}
{{except:}}
  {{include}}
{{pass}}
</div>
<p>&nbsp;</p>
{{try:}}
 {{=list_btn}}
{{except:}}
{{pass}}
}}}

{{{key.html}}}
{{{
<p><b>{{=T('Key')}}:</b><b class='red'> * </b> - {{=T('Fields tagged with a star')}} &#040;<span class='red'> * </span>&#041; {{=T('are mandatory and must be filled')}}.</p>
}}}

{{{plain.html}}}
{{{
{{=item}}
}}}