wq Configuration Object

wq Configuration Object

The wq Configuration object describes the URL structure of a website (/web app) and its corresponding REST API. The configuration object is typically generated by a REST service (e.g. wq.db) and provided to a JavaScript client (e.g. wq.app) in order to set common expectations on the layout of the application.

The basic format of the wq Configuration Object is:

{
    'pages': {
        '[model_name]': {'list': true, 'url': '[model_name]s', 'form': [...]},
        '[simple_page]': {'url': '[simple_page]'}
    }
}

The object is typically stored in the JavaScript module app/js/data/config.js. This module is imported by app/js/[myapp]/config.js, which can be used to add additional configuration sections, e.g. for wq/app.js plugins. Generally, you should not customize the pages configuration section directly, since doing so may cause wq.app and wq.db to become out of sync. Instead, you can provide arbitrary configuration parameters by supplying additional arguments to wq.db.rest.

# myapp/rest.py
from wq.db import rest
from .models import MyModel
rest.router.register_model(
    MyModel,
    fields="__all__",

    cache="all", # wq configuration

    my_custom_flag=True, # Custom configuration
)

Configuration Options

The primary configuration section in the wq configuration object is pages, which contains detailed information about the URL structure of the application. For example, the pages configuration is used by wq/app.js to map URL requests to page templates to render, and also to provide hints to wq/store.js and wq/model.js as to the structure of the REST API containing the actual data.

As its name implies, the pages section summarizes all of the available "pages" in the application. The section is a mapping of page "names" to simple configuration objects describing each respective page. Pages fall into two categories depending on whether or not they are backed by a database table (i.e. ORM model in a Django application).

• Pages backed by a database table are indicated with "list": true. The name of these pages is the name of the underlying database model. Marking a page as "list": true implies the presence of list, detail, and edit views for a database entity - all with corresponding URLs defined relative to the url property defined for the page. List pages are configured in wq.db with rest.router.register_model().

• Pages without a corresponding model do not have the list property set, and have only a single URL which is specified by the url property. By convention, the name of these pages is usually the same as the URL. These pages are configured in wq.db with rest.router.add_page().

The full listing of page configuration options is described below.

General Options

Additional Options for List Pages

As noted above, "list" pages are typically backed by ORM models which in turn correspond to database tables.

cache Configuration

The cache option (new in wq 1.0) configures which records from the model are cached for offline use. It fully replaces the partial, max_local_pages, and reversed options in older versions of wq (see Pagination and Caching). Four caching modes are available:

# myapp/rest.py
from wq.db import rest
from .models import MyModel

def user_filter(qs, request):
    if request.user.is_authenticated:
        return qs.filter(user=request.user)
    else:
        return qs.none()

rest.router.register_model(
    MyModel,
    fields="__all__",

    cache_filter=user_filter,

    # Implied:
    # cache="filter"
)

See the router registration documentation for more information about the cache_filter option and how it is interpreted by wq.db.

postsave and postdelete

By default, the next step after saving a record is to return to the list view / outbox (for background synced records) or to return to the detail view (for foreground synced records). This behavior can be customized with the postsave configuration option. postsave can take two forms: a template name, or a URL with Mustache-style placeholders.

Suppose there are two models, Site and Observation. The postsave for Observation might be any of the following:

postdelete has similar semantics as postsave, but does not support variable placeholders or returning to detail views, since the object has already been deleted by the time the postdelete action is executed. The default for postdelete is always to return to the list view.

Form Fields

As of wq 1.0, the configuration object for each list page includes an XLSForm-inspired representation of the schema for the model. This information can be used by the wq maketemplates command to automatically generate a Mustache HTML <form> template for editing a page. Certain properties are also used by wq/app.js to handle choice lookups and relationships between models (which are harder to bake into an HTML template). The form configuration thus replaces the parents, children, and choices page configuration options available in wq 0.8 and earlier.

The form attribute is an array of wq field definitions, which are JSON objects with any of the following attributes. Where applicable, the corresponding concepts in the XLSForm Question and Django Field definitions are listed.

FIXME: The nested/repeat stuff is pretty advanced (it requires custom DRF serializers on the wq.db side) - it should probably be moved to the patterns docs.