Resources are a central concept in
clld. While we may use the term resource
also for single instances, more generally a resource is a type of data implementing
an interface to which behaviour can be attached.
The default resources known in a
clld app are listed in
clld.RESOURCES, but it is
possible to extend this list when configuring a custom app (see Adding a resource).
Resources have the following attributes:
- a string naming the resource.
- class specifying the interface the resource implements.
- core model class for the resource.
Each resource is associated with a db model class and optionally with a custom db model derived from the default one using joined table inheritance.
Adapters are basically used to provide representations of a resource. Thus, if we want to
provide the classification tree of a Glottolog languoid in newick format, we have to write
and register an adapter. This kind of adapter is generally implemented as subclass of
For the builtin resources a couple of adapters are registered by default:
- a template-based adapter to render the details page,
- a JSON representation of the resource (based on
- a CSV representation of a resource index (
clld framework uses
to map default views to URLs for resources.
For each resource the following routes and views (and URLs) are registered by default:
- an index view for the route
<name>sand the URL
- an alternative index view for the route
<name>s_altand the URL pattern
- a details view for the route
<name>and the URL pattern
- an alternative details view for the route
<name>_altand the URL
We distinguish two classes of views for resources:
- index views, implemented in
clld.web.views.index_view(), serve rendered adapters registered for the interface
IIndexand a particular resource. They typically require a corresponding
DataTablesubclass to be instantiated as context object when the view is executed.
- detail views, implemented in
clld.web.views.detail_view(), serve rendered adapters registered for the interface
IRepresentationand a particular resource. The resource instance with the
idpassed in the request will be fetched from the database as context object of the view.
The adapters associated with resources may use templates to render the response. In particular this is the case for the HTML index and detail view.
Providing custom data for a reources details template¶
Since the view rendering a resources details representations is implemented in clld core code, clld applications may need a way to provide additional context for the templates. This can be done by implementing an appropriately named function in the app.util which will be looked up and called in a BeforeRender event subscriber.
Requesting a resource¶
The flow of events when a resource is requested from a
clld app is as follows
(we don’t give a complete rundown but only highlight the deviations from the general
pyramid request processing flow):
- When a route for a resource matches, the corresponding factory function is called to obtain the context of the request. For index routes this context object is an instance of a DataTable, for a details route this is an instance of the resource’s model class (or a custom specialization of this model).
- For index routes
clld.web.views.index_view()is called, for details routes
- Both of these look up the appropriate adapter registered for the context, instantiate it
and call its
render_to_responsemethod. The result of this call is returned as
- If this method uses a standard template renderer
the listener for the
BeforeRenderevent will look for a function in
myapp.utilwith a name of
dataset_detail_htmlfor the template
templates/dataset/detail_html.mako. If such a function exists, it will be called with the current template variables as keyword parameters. The return value of the function is expected to be a dictionary which will be used to update the template variables.