`wuttaweb.grids.base`¶

Base grid classes

class wuttaweb.grids.base.Grid(request, vue_tagname='wutta-grid', model_class=None, key=None, columns=None, data=None, labels={}, renderers={}, row_class=None, actions=[], linked_columns=[], sortable=False, sort_multiple=True, sort_on_backend=True, sorters=None, sort_defaults=None, paginated=False, paginate_on_backend=True, pagesize_options=None, pagesize=None, page=1, searchable_columns=None, filterable=False, filters=None, filter_defaults=None, joiners=None, tools=None)[source]¶

Base class for all grids.

Parameters:

request – Reference to current request object.
columns – List of column names for the grid. This is optional; if not specified an attempt will be made to deduce the list automatically. See also columns.

Note

Some parameters are not explicitly described above. However their corresponding attributes are described below.

Grid instances contain the following attributes:

key¶: Presumably unique key for the grid; used to track per-grid sort/filter settings etc.

vue_tagname¶: String name for Vue component tag. By default this is 'wutta-grid'. See also render_vue_tag().

model_class¶: Model class for the grid, if applicable. When set, this is usually a SQLAlchemy mapped class. This may be used for deriving the default columns among other things.

columns¶

FieldList instance containing string column names for the grid. Columns will appear in the same order as they are in this list.

See also set_columns() and get_columns().

data¶

Data set for the grid. This should either be a list of dicts (or objects with dict-like access to fields, corresponding to model records) or else an object capable of producing such a list, e.g. SQLAlchemy query.

This is the “full” data set; see also get_visible_data().

labels¶

Dict of column label overrides.

See also get_label() and set_label().

renderers¶

Dict of column (cell) value renderer overrides.

See also set_sorter().

render_datetime(obj, key, value)[source]¶

Default cell value renderer for sqlalchemy.types.DateTime columns, which calls render_datetime() for the return value.

This may be used automatically per set_default_renderers() or you can use it explicitly for any datetime.datetime column with:

grid.set_renderer('foo', grid.render_datetime)

render_table_element(form=None, template='/grids/table_element.mako', **context)[source]¶

Render a simple Vue table element for the grid.

This is what you want for a “simple” grid which does require a unique Vue component, but can instead use the standard table component.

This returns something like:

<b-table :data="gridContext['mykey'].data">
  <!-- columns etc. -->
</b-table>

See render_vue_template() for a more complete variant.

Actual output will of course depend on grid attributes, key, columns etc.

Parameters:

form – Reference to the Form instance which “contains” this grid. This is needed in order to ensure the grid data is available to the form Vue component.
template – Path to Mako template which is used to render the output.

Note

The above example shows gridContext['mykey'].data as the Vue data reference. This should “just work” if you provide the correct form arg and the grid is contained directly by that form’s Vue component.

However, this may not account for all use cases. For now we wait and see what comes up, but know the dust may not yet be settled here.

render_vue_finalize()[source]¶

Render the Vue “finalize” script for the grid.

By default this simply returns:

<script>
  WuttaGrid.data = function() { return WuttaGridData }
  Vue.component('wutta-grid', WuttaGrid)
</script>

The actual output may depend on various grid attributes, in particular vue_tagname.

render_vue_tag(**kwargs)[source]¶

Render the Vue component tag for the grid.

By default this simply returns:

<wutta-grid></wutta-grid>

The actual output will depend on various grid attributes, in particular vue_tagname.

render_vue_template(template='/grids/vue_template.mako', **context)[source]¶

Render the Vue template block for the grid.

This is what you want for a “full-featured” grid which will exist as its own unique Vue component on the frontend.

This returns something like:

<script type="text/x-template" id="wutta-grid-template">
  <b-table>
    <!-- columns etc. -->
  </b-table>
</script>

<script>
    WuttaGridData = {}
    WuttaGrid = {
        template: 'wutta-grid-template',
    }
</script>

See render_table_element() for a simpler variant.

Actual output will of course depend on grid attributes, vue_tagname and columns etc.

Parameters:: template – Path to Mako template which is used to render the output.

set_columns(columns)[source]¶

Explicitly set the list of grid columns.

This will overwrite columns with a new FieldList instance.

Parameters:: columns – List of string column names.

set_default_renderers()[source]¶

Set default column value renderers, where applicable.

This will add new entries to renderers for columns whose data type implies a default renderer should be used. This is generally only possible if model_class is set to a valid SQLAlchemy mapped class.

This (for now?) only looks for sqlalchemy.types.DateTime columns and if any are found, they are configured to use render_datetime().

set_filter(key, filterinfo=None, **kwargs)[source]¶

Set/override the backend filter for a column.

Only relevant if filterable is true.

Parameters:

key – Name of column.
filterinfo – Can be either a GridFilter instance, or else a model property (see below).

If filterinfo is a GridFilter instance, it will be used as-is for the backend filter.

Otherwise make_filter() will be called to obtain the backend filter. The filterinfo will be passed along to that call; if it is empty then key will be used instead.

See also remove_filter(). Backend filters are tracked via filters.

set_filter_defaults(**defaults)[source]¶

Set default state preferences for the grid filters.

These preferences will affect the initial grid display, until user requests a different filtering method.

Each kwarg should be named by filter key, and the value should be a dict of preferences for that filter. For instance:

grid.set_filter_defaults(name={'active': True,
                               'verb': 'contains',
                               'value': 'foo'},
                         value={'active': True})

Filter defaults are tracked via filter_defaults.

set_joiner(key, joiner)[source]¶

Set/override the backend joiner for a column.

A “joiner” is sometimes needed when a column with “related but not primary” data is involved in a sort or filter operation.

A sorter or filter may need to “join” other table(s) to get at the appropriate data. But if a given column has both a sorter and filter defined, and both are used at the same time, we don’t want the join to happen twice.

Hence we track joiners separately, also keyed by column name (as are sorters and filters). When a column’s sorter and/or filter is needed, the joiner will be invoked.

Parameters:

key – Name of column.
joiner – A joiner callable, as described below.

A joiner callable must accept just one (data) arg and return the “joined” data/query, for example:

model = app.model
grid = Grid(request, model_class=model.Person)

def join_external_profile_value(query):
    return query.join(model.ExternalProfile)

def sort_external_profile(query, direction):
   sortspec = getattr(model.ExternalProfile.description, direction)
   return query.order_by(sortspec())

grid.set_joiner('external_profile', join_external_profile)
grid.set_sorter('external_profile', sort_external_profile)

See also remove_joiner(). Backend joiners are tracked via joiners.

set_label(key, label, column_only=False)[source]¶

Set/override the label for a column.

Parameters:

key – Name of column.
label – New label for the column header.
column_only – Boolean indicating whether the label should be applied only to the column header (if True), vs. applying also to the filter (if False).

See also get_label(). Label overrides are tracked via labels.

set_link(key, link=True)[source]¶

Explicitly enable or disable auto-link behavior for a given column.

If a column has auto-link enabled, then each of its cell contents will automatically be wrapped with a hyperlink. The URL for this will be the same as for the “View” GridAction (aka. view()). Although of course each cell in the column gets a different link depending on which data record it points to.

It is typical to enable auto-link for fields relating to ID, description etc. or some may prefer to auto-link all columns.

See also is_linked(); the list is tracked via linked_columns.

Parameters:

key – Column key as string.
link – Boolean indicating whether column’s cell contents should be auto-linked.

set_renderer(key, renderer, **kwargs)[source]¶

Set/override the value renderer for a column.

Parameters:

key – Name of column.
renderer – Callable as described below.

Depending on the nature of grid data, sometimes a cell’s “as-is” value will be undesirable for display purposes.

The logic in get_vue_context() will first “convert” all grid data as necessary so that it is at least JSON-compatible.

But then it also will invoke a renderer override (if defined) to obtain the “final” cell value.

A renderer must be a callable which accepts 3 args (record, key, value):

record is the “original” record from data
key is the column name
value is the JSON-safe cell value

Whatever the renderer returns, is then used as final cell value. For instance:

from webhelpers2.html import HTML

def render_foo(record, key, value):
   return HTML.literal("<p>this is the final cell value</p>")

grid = Grid(request, columns=['foo', 'bar'])
grid.set_renderer('foo', render_foo)

Renderer overrides are tracked via renderers.

set_searchable(key, searchable=True)[source]¶

(Un)set the given column’s searchable flag for the Vue component.

See also is_searchable(). Flags are tracked via searchable_columns.

set_sort_defaults(*args)[source]¶

Set the default sorting method for the grid. This sorting is used unless/until the user requests a different sorting method.

args for this method are interpreted as follows:

If 2 args are received, they should be for sortkey and sortdir; for instance:

grid.set_sort_defaults('name', 'asc')

If just one 2-tuple arg is received, it is handled similarly:

grid.set_sort_defaults(('name', 'asc'))

If just one string arg is received, the default sortdir is assumed:

grid.set_sort_defaults('name') # assumes 'asc'

Otherwise there should be just one list arg, elements of which are each 2-tuples of (sortkey, sortdir) info:

grid.set_sort_defaults([('name', 'asc'),
                        ('value', 'desc')])

Note

Note that sort_multiple determines whether the grid is actually allowed to have multiple sort defaults. The defaults requested by the method call may be pruned if necessary to accommodate that.

Default sorting info is tracked via sort_defaults.

set_sorter(key, sortinfo=None)[source]¶

Set/override the backend sorter for a column.

Only relevant if both sortable and sort_on_backend are true.

Parameters:

key – Name of column.
sortinfo – Can be either a sorter callable, or else a model property (see below).

If sortinfo is a callable, it will be used as-is for the backend sorter.

Otherwise make_sorter() will be called to obtain the backend sorter. The sortinfo will be passed along to that call; if it is empty then key will be used instead.

A backend sorter callable must accept (data, direction) args and return the sorted data/query, for example:

model = app.model
grid = Grid(request, model_class=model.Person)

def sort_full_name(query, direction):
   sortspec = getattr(model.Person.full_name, direction)
   return query.order_by(sortspec())

grid.set_sorter('full_name', sort_full_name)

See also remove_sorter() and is_sortable(). Backend sorters are tracked via sorters.

set_tools(tools)[source]¶

Set the tools attribute using the given tools collection.

This will normalize the list/dict to desired internal format.

sort_data(data, sorters=None)[source]¶

Sort the given data and return the result. This is called by get_visible_data().

Parameters:: sorters – Optional list of sorters to use. If not specified, the grid’s active_sorters are used.

property vue_component¶

String name for the Vue component, e.g. 'WuttaGrid'.

This is a generated value based on vue_tagname.

class wuttaweb.grids.base.GridAction(request, key, label=None, url=None, icon=None, link_class=None)[source]¶

Represents a “row action” hyperlink within a grid context.

All such actions are displayed as a group, in a dedicated Actions column in the grid. So each row in the grid has its own set of action links.

A Grid can have one (or zero) or more of these in its actions list. You can call make_grid_action() to add custom actions from within a view.

Parameters:: request – Current request object.

Note

Some parameters are not explicitly described above. However their corresponding attributes are described below.

key¶: String key for the action (e.g. 'edit'), unique within the grid.

label¶

Label to be displayed for the action link. If not set, will be generated from key by calling make_title().

wuttaweb.grids.base¶

`wuttaweb.grids.base`¶