wq Configuration Object

The wq Configuration object describes the global settings and navigation structure of a wq-powered website/app and its corresponding REST API. The configuration object is typically generated by the Python service (wq.db) and provided to the JavaScript client (wq.app) in order to set common expectations on the layout of the application.

The basic format of the wq Configuration Object is:

{
    // Global Settings
    "site_title": "[Project Name]",
    "logo": "/path/to/logo.png",
    "material": {
        "theme": {
            "primary": "#7500ae",
            "secondary": "#0088bd"
        }
    },
    "map": {
        "bounds": [[-180, -70], [180, 70]]
    },

    // Navigation Structure
    "router": {
        "base_url": ""
    },
    "store": {
        "service": "",
        "defaults": {
            "format": "json"
        }
    },
    "pages": {
        "[model_name]": {
            "list": true,
            "url": "[model_name]s",
            "form": [...]
        },
        "[simple_page]": {
            "url": "[simple_page]"
        }
    }
}

In the default project layout, wq.db exports the configuration object to the JavaScript module app/js/data/config.js. This module is imported by app/js/[myproject].js which passes it along to wq.init().

Global Settings

The following configuration options can be set by updating the corresponding WQ_CONFIG key (which is defined in db/[myproject]/settings/base.py in the default layout.)

Navigation Structure

In addition to the global settings, the wq configuration object also describes the URL structure of the application. This is done through the following sections:

These three sections of the wq configuration object are generated by wq.db automatically, and should not be specified manually except in advanced use cases. Page-specific configuration can be supplied when registering models and pages with the router, as described below.

Page Registration

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 to map URL requests to page templates to render, and also to provide hints to @wq/store and @wq/model 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().

# 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
)

• 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().

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

rest.router.add_page("about", {"url": "about"})

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 configures which records from the model are cached for offline use (by @wq/model). Five caching modes are available:

Note that the "filter" and "autoupdate" options assume that a cache_filter Python function will be registered with wq.db’s router to do the actual filtering:

# 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

The configuration object for each list page includes an XLSForm-inspired representation of the schema for the model. This information is used by the <AutoForm/> component to automatically generate the appropriate form inputs for editing a page. Certain properties are also used by @wq/app to handle choice lookups and relationships between models.

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.