Arguments Loaders

Grid arguments are run-time configuration for a grid instance. This includes filter operator/values, sort terms, search, paging, session key, etc.

Arguments may be provided to the grid directly, or else it pulls them from the assigned framework manager. The most common use case will use the manager.

Managed arguments

The grid manager uses “args loaders” (subclasses of ArgsLoader) to supply grid configuration. These loaders each represent a source of configuration. For instance, a loader can pull args from the GET query string, a POSTed form, etc.

The first loader on the list gets a blank MultiDict as input. Then, results from each loader are chained to the next one on the list. Each loader may accept or override the values from the previous output. The last loader gets the final word on configuration sent to the grid.

The default setup provides request URL arguments to the first loader, and then applies session information as needed. Some cases where you might want to do something different from the default: - The grid has options filters with a large number of options to select - The grid has a lot of complexity that would be cleaner as POSTs rather than GETs

To use managed arguments with the default loaders, simply call apply_qs_args or build to have the grid load these for use in queries and rendering:

class PeopleGrid(Grid):
    Column('Name', entities.Person.name)
    Column('Age', entities.Person.age)
    Column('Location', entities.Person.city)

grid = PeopleGrid()
grid.apply_qs_args()

Customizing the loader list on a managed grid requires setting the args_loaders iterable on the manager. This can be set as a class attribute or provided in the manager’s constructor.

As a class attribute:

from webgrid import BaseGrid
from webgrid.extensions import RequestArgsLoader, RequestFormLoader, WebSessionArgsLoader
from webgrid.flask import WebGrid

class GridManager(WebGrid):
    args_loaders = (
        RequestArgsLoader,    # part of the default, takes args from URL query string
        RequestFormLoader,    # use args present in the POSTed form
        WebSessionArgsLoader, # part of the default, but lower priority from the form POST
    )

class Grid(BaseGrid):
    manager = GridManager()

Using the manager’s constructor to customize the loader list:

from webgrid import BaseGrid
from webgrid.extensions import RequestArgsLoader, RequestFormLoader, WebSessionArgsLoader
from webgrid.flask import WebGrid

class Grid(BaseGrid):
    manager = WebGrid(
        args_loaders = (
            RequestArgsLoader,    # part of the default, takes args from URL query string
            RequestFormLoader,    # use args present in the POSTed form
            WebSessionArgsLoader, # part of the default, but lower priority from the form POST
        )
    )

class webgrid.extensions.ArgsLoader(manager)

Base args loader class.

When a grid calls for its args, it requests them from the manager. The manager will have one or more args loaders to be run in order. Each loader fetches its args from the request, then ensuing loaders have the opportunity to modify or perform other operations as needed.

class webgrid.extensions.RequestArgsLoader(manager)

Simple args loader for web request.

Args are usually passed through directly from the request. If the grid has a query string prefix, the relevant args will be namespaced - sanitize them here and return the subset needed for the given grid.

In the reset case, ignore most args, and return only the reset flag and session key (if any).

class webgrid.extensions.RequestFormLoader(manager)

Simple form loader for web request.

Form values are usually passed through directly from the request. If the grid has a prefix, the relevant args will be namespaced - sanitize them here and return the subset needed for the given grid.

In the reset case, ignore most args, and return only the reset flag and session key (if any).

class webgrid.extensions.RequestJsonLoader(manager)

JSON loader for web request.

See webgrid.types.GridSettings() for the expected JSON structure. The parsed arguments are converted to the querystring arg format and merged with any previous args.

class webgrid.extensions.WebSessionArgsLoader(manager)

Session manager for grid args.

Args are assumed to have been sanitized from the request already. But, args may be combined from the request and the session store for a number of cases.

• If session_override or no filter ops, load args from session store

• Having filter ops present will reset session store unless session_override is present

• Page/sort args will always take precedence over stored args, but not reset the store

• Export argument is handled outside of the session store

In the reset case, ignore most args, and return only the reset flag and session key (if any). And clear the session store for the given grid.

apply_session_overrides(session_args, previous_args)

Update session args as needed from the incoming request.

If session override case, wholesale update from the incoming request. This is useful if a single filter needs to be changed via the URL, but we don’t want to dump the rest of the stored filters from the session.

Otherwise, apply only page/sort if available in the request.

Export directive is passed through from the request, so a session store never triggers an export by itself.

Args:

session_args (MultiDict): Args loaded from the session store. previous_args (MultiDict): Args that came into this args loader.

Returns:

MultiDict: Args to be used in grid operations.

args_have_op(args)

Check args for containing any filter operators.

Args:

args (MultiDict): Request args.

Returns:

bool: True if at least one op is present.

args_have_page(args)

Check args for containing any page args.

Args:

args (MultiDict): Request args.

Returns:

bool: True if at least one page arg is present.

args_have_sort(args)

Check args for containing any sort keys.

Args:

args (MultiDict): Request args.

Returns:

List[str]: all args matching as sort args.

cleanup_expired_sessions()

Remove sessions older than a certain number of hours.

Configurable at the manager level, with the session_max_hours attribute. If None, cleanup is disabled.

get_args(grid, previous_args)

Retrieve args from session and override as appropriate.

Submitting the header form flushes all args to the URL, so no need to load them from session.

If that is not the path, then we either have filtering args on the URL, or not. Default behavior is currently to consider filtering args to be comprehensive and authoritative, UNLESS a session_override arg is present.

The special session_override arg causes the store to overlay request args against an existing session, and return the combination.

Args:

grid (BaseGrid): Grid used to get default grid key (based on grid class name). previous_args (MultiDict): Incoming args, assumed to be sanitized already.

Returns:

MultiDict: Args to be used in grid operations.

get_session_store(grid, args)

Load args from session by session_key, and return as MultiDict.

Args:

grid (BaseGrid): Grid used to get default grid key (based on grid class name). args (MultiDict): Request args used for session key.

Returns:

MultiDict: Args to be used in grid operations.

save_session_store(grid, args)

Save the args in the session under the session key and as defaults for this grid.

Note, export and reset args are ignored for storage.

Args:

args (MultiDict): Request args to be loaded in next session store retrieval.

Supplying arguments directly

Arguments may be provided directly to apply_qs_args or build as a MultiDict. If arguments are supplied in this fashion, other sources are ignored:

from werkzeug.datastructures import MultiDict

class PeopleGrid(Grid):
    Column('Name', entities.Person.name)
    Column('Age', entities.Person.age)
    Column('Location', entities.Person.city)

grid = PeopleGrid()
grid.apply_qs_args(grid_args=MultiDict([
    ('op(name)', 'contains'),
    ('v1(name)', 'bill'),
]))