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.

property 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.

query_params

Convenient access to the query parameters of the current request.

Returns:

dict of the query parameters of the request URL.

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

Determine the path component of a Resource’s 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

route_url(route, *args, **kw)

Facade for Request.route_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

property options

Typically options to configure a corresponding JavaScript object.

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: Request, model: Type[Base], eid: str | None = 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().

Items in a table may have standard representations other than tabular data - e.g. sources may be more useful as BibTeX records. If so, and the custom serialization is registered as adapter for the model class, DataTables can provide access to the currently filtered items in this custom format through a download button. This can be configured by adding a key dl_formats to clld.web.datatables.base.DataTable.__toolbar_kw__ specifying a dict mapping registered extension strings to labels for the download button.

__init__(req: Request, model: Type[Base], eid: str | None = None, **kw)

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.

__repr__()

Return repr(self).

__str__()

Return str(self).

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.

get_default_options()

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

Returns:

JSON serializable dict

rdf_index_query(query)

Custom DataTables can overwrite this method to apply filters. They should however, not add any performance overhead like joins or joinedload options.

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='map')

Represents the configuration for a leaflet map.

Map options to be specified as items returned in get_options:

• info_route: Name of the route to request info window content [‘language_alt’]

• info_query: Query parameters to pass when requesting info window content [{}]

• overlays: list of dicts(name=, url=, options=), specifying tileOverlays [[]]

• exclude_from_zoom: list of layer names to exclude when zooming to extent [[]]

• base_layer: Name of base layer to use.

• no_popup: Flag to opt out of info window popups [False]

• no_link: Flag to opt out of turning markers into links [False]

• icons: Name of icons style as defined in CLLD.MapIcons [‘base’]

• icon_size: initial size of map markers in pixels [20]

• sidebar: Flag indicating whether the map is rendered in the sidebar [False]

• zoom: Integer specifying the initial zoom factor of the map [None]

• max_zoom: Integer specfying the maximal zoom factor allowed for a map [6]

• center: (latitutde, longitude) pair specifying the center of the map [None]

• hash: Flag indicating whether map center coords should be added to the URL [False]

• tile_layer: dict(url_pattern=, options=), specifying an alternative base layer [None]

• add_layers_to_control: Flag indicating whether map layers should be added to the layers control as overlays [False]

• show_labels: Flag indicating whether labels/tooltips should be initially open [False]

• on_init: function to run at the end of map initialization [None]

• resize_direction: ‘e’, ‘s’ or ‘se’, make map resizeable. see https://github.com/jjimenezshaw/Leaflet.Control.Resizer#api

• with_audioplayer: Flag indicating whether to add an AudioPlayer control on the map.

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

Initialize.

Parameters:

• ctx – context object of the current request.

• req – current pyramid request object.

• eid – Page-unique DOM-node ID.

get_default_options()

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

Returns:

JSON serializable dict

get_layers()

Generate the list of layers.

Returns:

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

get_options_from_req()

Override this method to define options derived from request properties.

Returns:

JSON serializable dict

property layers

The list of layers of the map.

Note

Since layers may be costly to compute, we cache them per map instance.

Returns:

list 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.Json(obj)

JavaScript Object Notation.

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.