The request object

clld registers a custom request factory, i.e. the request object available in view code or templates is an instance of clld.web.app.ClldRequest.

class clld.web.app.ClldRequest(environ, charset=None, unicode_errors=None, decode_param_names=None, **kw)

Custom Request class.

ctx_for_url(url)

Method to reverse URL generation for resources.

I.e. given a URL, tries to determine the associated resource.

Returns:model instance or None.

dataset

Convenient access to the Dataset object.

Properties of the clld.db.models.common.Dataset object an application serves are used in various places, so we want to have a reference to it.

db

Convenient access to the db session.

We make the db session available as request attribute, so we do not have to import it in templates.

get_datatable(name, model, **kw)

Convenient lookup and retrieval of initialized DataTable object.

Parameters:

• name – Name under which the datatable class was registered.
• model – model class to pass as initialization parameter to the datatable.
• kw – Keyword parameters are passed through to the initialization of the datatable.

Returns:

clld.web.datatables.base.DataTable instance, if a datatable was registered for name.

get_map(name=None, **kw)

Convenient lookup and retrieval of initialized Map object.

Parameters:name – Name under which the map was registered. Returns:clld.web.maps.Map instance, if a map was registered else None.

purl

Access the current request’s URL.

For more convenient URL manipulations, we provide the current request’s URL as purl.URL instance.

query_params

Convenient access to the query parameters of the current request.

Returns:dict of the query parameters of the request URL.

resource_url(obj, rsc=None, **kw)

Get the absolute URL for a resource.

Parameters:

• obj – A resource or the id of a resource; in the latter case rsc must be passed.
• rsc – A registered clld.Resource.
• kw – Keyword parameters are passed through to pyramid.request.Request.route_url

Returns:

URL

Page components

clld supports page components for web apps (i.e. parts of pages which require HTML code and JavaScript to define behavior) with the clld.web.util.component.Component virtual base class.

class clld.web.util.component.Component

Virtual base class for page components.

Components are objects that can be rendered as HTML and typically define behavior using a corresponding JavaScript object which accepts an options object upon initialization.

get_default_options()

Override this method to define default (i.e. valid across subclasses) options.

Returns:JSON serializable dict

get_options()

Override this method to define final-class-specific options.

Returns:JSON serializable dict

get_options_from_req()

Override this method to define options derived from request properties.

Returns:JSON serializable dict

The design rationale for components is the idea to build the bridge between server and client as cleanly as possible by putting the code to collect options for a client side object and the instantiation of a these objects into one Python class (plus a mako template referenced in this class).

DataTables

DataTables are implemented as Python classes, providing configuration and server-side processing for jquery datatables.

class clld.web.datatables.base.DataTable(req, model, eid=None, **kw)

DataTables are used to manage selections of instances of one model class.

Often datatables are used to display only a pre-filtered set of items which are related to some other entity in the system. This scenario is supported as follows: For each model class listed in clld.web.datatables.base.DataTable.__constraints__ an appropriate object specified either by keyword parameter or as request parameter will be looked up at datatable initialization, and placed into a datatable attribute named after the model class in lowercase. These attributes will be used when creating the URL for the data request, to make sure the same pre-filtering is applied.

Note

The actual filtering has to be done in a custom implementation of clld.web.datatables.base.DataTable.base_query().

__init__(req, model, eid=None, **kw)

Initialize.

Parameters:

• req – request object.
• model – mapper class, instances of this class will be the rows in the table.
• eid – HTML element id that will be assigned to this data table.

base_query(query)

Custom DataTables can overwrite this method to add joins, or apply filters.

Returns:sqlalchemy.orm.query.Query instance.

col_defs()

Must be implemented by derived classes.

Returns:list of instances of clld.web.datatables.base.Col.

xhr_query()

Get additional URL parameters for XHR.

Returns:a mapping to be passed as query parameters to the server when requesting table data via xhr.

class clld.web.datatables.base.Col(dt, name, get_object=None, model_col=None, format=None, **kw)

DataTables are basically a list of column specifications.

A column in a DataTable typically corresponds to a column of an sqlalchemy model. This column can either be supplied directly via a model_col keyword argument, or we try to look it up as attribute with name “name” on self.dt.model.

format(item)

Called when converting the matching result items of a datatable to json.

get_obj(item)

Get the object for formatting and filtering.

Note

derived columns with a model_col not on self.dt.model should override this method.

order()

Called when collecting the order by clauses of a datatable’s search query.

search(qs)

Called when collecting the filter criteria of a datatable’s search query.

Maps

Maps are implemented as subclasses of clld.web.maps.Map, providing configuration and server-side processing for leaflet maps.

The process for displaying a map is as follows:

1. In python view code a map object is instantiated and made available to a mako template (either via the registry or directly, as template variable).
2. In the mako template, the render method of the map is called, thus inserting HTML created from the template clld/web/templates/map.mako into the page.
3. When the browser renders the page, CLLD.map() is called, instantiating a leaflet map object.
4. During initialization of the leaflet map, for each clld.web.maps.Layer of the map a leaflet geoJson layer is instantiated, adding data to the map.

class clld.web.maps.Map(ctx, req, eid=u'map')

Represents the configuration for a leaflet map.

__init__(ctx, req, eid=u'map')

Initialize.

Parameters:

• ctx – context object of the current request.
• req – current pyramid request object.
• eid – Page-unique DOM-node ID.

get_layers()

Generate the list of layers.

Returns:list or generator of clld.web.maps.Layer instances.

class clld.web.maps.Layer(id_, name, data, **kw)

Represents a layer in a leaflet map.

A layer in our terminology is a FeatureCollection in geojson and a geoJson layer in leaflet, i.e. a bunch of points on the map.

__init__(id_, name, data, **kw)

Initialize a layer object.

Parameters:

• id – Map-wide unique string identifying the layer.
• name – Human readable name of the layer.
• data – A GeoJSON FeatureCollection either specified as corresponding Python dict or as URL which will serve the appropriate GeoJSON.
• kw – Additional keyword parameters are made available to the Layer as instance attributes.

__weakref__

list of weak references to the object (if defined)

CLLD.map(eid, layers, options)

Arguments:

• eid (string) – DOM element ID for the map object.
• layers (array) – List of layer specifications.
• options (object) – Map options.

Returns:

CLLD.Map instance.

Adapters

Base classes for adapters.

class clld.web.adapters.base.Index(obj)

Base class for adapters implementing IIndex.

class clld.web.adapters.base.Renderable(obj)

Virtual base class for adapters.

Adapters can provide custom behaviour either by specifying a template to use for rendering, or by overwriting the render method.

class clld.web.adapters.base.Representation(obj)

Base class for adapters implementing IRepresentation.

class clld.web.adapters.base.SolrDoc(obj)

Document for indexing with Solr encoded in JSON.