tailbone.grids.core

Core Grid Classes

class tailbone.grids.core.Grid(request, key=None, data=None, width='auto', model_title=None, model_title_plural=None, enums={}, assume_local_times=False, invisible=[], raw_renderers={}, extra_row_class=None, url='#', use_byte_string_filters=False, checkboxes=False, checked=None, check_handler=None, check_all_handler=None, checkable=None, row_uuid_getter=None, clicking_row_checks_box=False, click_handlers=None, main_actions=[], more_actions=[], delete_speedbump=False, ajax_data_url=None, expose_direct_link=False, **kwargs)

Base class for all grids.

This is now a subclass of wuttaweb.grids.base.Grid, and exists to add customizations which have traditionally been part of Tailbone.

Some of these customizations are still undocumented. Some will eventually be moved to the upstream/parent class, and possibly some will be removed outright. What docs we have, are shown here.

checkable

Optional callback to determine if a given row is checkable, i.e. this allows hiding checkbox for certain rows if needed.

This may be either a Python callable, or string representing a JS callable. If the latter, according to the Buefy docs:

Custom method to verify if a row is checkable, works when is
checkable.

Function (row: Object)

In other words this JS callback would be invoked for each data row in the client-side grid.

But if a Python callable is used, then it will be invoked for each row object in the server-side grid. For instance:

def checkable(obj):
    if obj.some_property == True:
        return True
    return False

grid.checkable = checkable

check_handler

Optional JS callback for the @check event of the underlying Buefy table component. See the Buefy docs for more info, but for convenience they say this (as of writing):

Triggers when the checkbox in a row is clicked and/or when
the header checkbox is clicked

For instance, you might set grid.check_handler = 'rowChecked' and then define the handler within your template (e.g. /widgets/index.mako) like so:

<%def name="modify_this_page_vars()">
  ${parent.modify_this_page_vars()}
  <script type="text/javascript">

    TailboneGrid.methods.rowChecked = function(checkedList, row) {
        if (!row) {
            console.log("no row, so header checkbox was clicked")
        } else {
            console.log(row)
            if (checkedList.includes(row)) {
                console.log("clicking row checkbox ON")
            } else {
                console.log("clicking row checkbox OFF")
            }
        }
        console.log(checkedList)
    }

  </script>
</%def>

raw_renderers

Dict of “raw” field renderers. See also set_raw_renderer().

When present, these are rendered “as-is” into the grid template, whereas the more typical scenario involves rendering each field “into” a span element, like:

<span v-html="RENDERED-FIELD"></span>

So instead of injecting into a span, any “raw” fields defined via this dict, will be injected as-is, like:

RENDERED-FIELD

Note that each raw renderer is called only once, and without any arguments. Likely the only use case for this, is to inject a Vue component into the field. A basic example:

from webhelpers2.html import HTML

def myrender():
    return HTML.tag('my-component', **{'v-model': 'props.row.myfield'})

grid = Grid(
    # ..normal constructor args here..

    raw_renderers={
        'myfield': myrender,
    },
)

apply_user_defaults(settings)

Update the given settings dict with user defaults, if any exist.

checkbox(item)

Returns boolean indicating whether a checkbox should be rendererd for the given data item’s row.

filter_data(data)

Filter and return the given data set, according to current settings.

get_default_filters()

Returns the default set of filters provided by the grid.

get_filters_data()

Returns a dict of current filters data, for use with index view.

get_filters_sequence()

Returns a list of filter keys (strings) in the sequence with which they should be displayed in the UI.

get_renderer_for_column_type(coltype)

Returns an appropriate renderer according to the given SA column type.

get_row_key(item)

Must return a unique key for the given data item’s row.

get_table_data()

Returns a list of data rows for the grid, for use with client-side JS table.

has_static_data()

Should return True if the grid data can be considered “static” (i.e. a list of values). Will return False otherwise, e.g. if the data is represented as a SQLAlchemy query.

hide_column(key)

This removes a column from the grid, altogether.

This method is deprecated; use remove() instead.

hide_columns(*keys)

This removes columns from the grid, altogether.

This method is deprecated; use remove() instead.

iter_active_filters()

Iterate over all active filters for the grid. Whether a filter is active is determined by current grid settings.

iter_filters()

Iterate over all filters available to the grid.

make_default_renderers(renderers)

Make the default set of column renderers for the grid.

We honor any existing renderers which have already been set, but then we also try to supplement that by auto-assigning renderers based on underlying column type. Note that this special logic only applies to grids with a valid model_class.

make_filter(key, column, **kwargs)

Make a filter suitable for use with the given column.

obtain_value(obj, column_name)

Try to obtain and return the value from the given object, for the given column name.

Returns:

The value, or None if no value was found.

render_checkbox(item)

Renders a checkbox cell for the given item, if applicable.

render_complete(template='/grids/complete.mako', **kwargs)

Render the grid, complete with filters. Note that this also includes the context menu items and grid tools.

render_datetime(obj, column_name)

Default cell value renderer for sqlalchemy: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 python:datetime.datetime column with:

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

render_table_element(template='/grids/b-table.mako', data_prop='gridData', empty_labels=False, literal=False, **kwargs)

This is intended for ad-hoc “small” grids with static data. Renders just a <b-table> element instead of the typical “full” grid.

session_has_settings()

Determine if the current session contains any settings for the grid.

set_action_urls(row, rowobj, i)

Pre-generate all action URLs for the given data row. Meant for use with client-side table, since we can’t generate URLs from JS.

set_filters_sequence(filters, only=False)

Explicitly set the sequence for grid filters, using the sequence provided. If the grid currently has more filters than are mentioned in the given sequence, the sequence will come first and all others will be tacked on at the end.

Parameters:

• filters – Sequence of filter keys, i.e. field names.

• only – If true, then only those filters specified will be kept, and all others discarded. If false then any filters not specified will still be tacked onto the end, in alphabetical order.

set_invisible(key, invisible=True)

Mark the given column as “invisible” (but do not remove it).

Use remove() if you actually want to remove it.

set_raw_renderer(key, renderer)

Set or remove the “raw” renderer for the given field.

See raw_renderers for more about these.

Parameters:

• key – Field name.

• renderer – Either a renderer callable, or None.

user_has_defaults()

Check to see if the current user has default settings on file for this grid.

class tailbone.grids.core.GridAction(request, key, target=None, click_handler=None, **kwargs)

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

This is a subclass of wuttaweb.grids.base.GridAction.

Warning

This class remains for now, to retain compatibility with existing code. But at some point the WuttaWeb class will supersede this one entirely.

Parameters:

• target – HTML “target” attribute for the <a> tag.

• click_handler –

  Optional JS click handler for the action. This value will be rendered as-is within the final grid template, hence the JS string must be callable code. Note that props.row will be available in the calling context, so a couple of examples:

  • deleteThisThing(props.row)

  • $emit('do-something', props.row)

class tailbone.grids.core.URLMaker(request)

URL constructor for use with SQLAlchemy grid pagers. Logic for this was basically copied from the old webhelpers.paginate module