tailbone.grids.core

Core Grid Classes

class tailbone.grids.core.FieldList(iterable=(), /)

Convenience wrapper for a field list.

class tailbone.grids.core.Grid(key, data, columns=None, width='auto', request=None, model_class=None, model_title=None, model_title_plural=None, enums={}, labels={}, assume_local_times=False, renderers={}, invisible=[], raw_renderers={}, extra_row_class=None, linked_columns=[], url='#', joiners={}, filterable=False, filters={}, use_byte_string_filters=False, searchable={}, sortable=False, sorters={}, default_sortkey=None, default_sortdir='asc', pageable=False, default_pagesize=None, default_page=1, 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, component='tailbone-grid', expose_direct_link=False, **kwargs)

Core grid class. In sore need of documentation.

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_label(key)

Returns the label text for given field key.

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_setting(source, settings, key, normalize=<function Grid.<lambda>>, default=None)

Get the effective value for a particular setting, preferring source but falling back to existing settings and finally the default.

get_table_columns()

Return a list of dicts representing all grid columns. Meant for use with the client-side JS table.

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.

is_linked(name)

Should return True if the given column name is configured to be “linked” (i.e. table cell should contain a link to “view object”), otherwise False.

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.

load_settings(store=True)

Load current/effective settings for the grid, from the request query string and/or session storage. If store is true, then once settings have been fully read, they are stored in current session for next time. Finally, various instance attributes of the grid and its filters are updated in-place to reflect the settings; this is so code needn’t access the settings dict directly, but the more Pythonic instance attributes.

make_columns()

Return a default list of columns, based on model_class.

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.

make_filters(filters=None)

Returns an initial set of filters which will be available to the grid. The grid itself may or may not provide some default filters, and the filters kwarg may contain additions and/or overrides.

make_simple_sorter(key, foldcase=False)

Returns a function suitable for a sort map callable, with typical logic built in for sorting a data set comprised of dicts, on the given key.

make_sorter(model_property)

Returns a function suitable for a sort map callable, with typical logic built in for sorting applied to field.

make_sorters(sorters=None)

Returns an initial set of sorters which will be available to the grid. The grid itself may or may not provide some default sorters, and the sorters kwarg may contain additions and/or overrides.

make_visible_data()

Apply various settings to the raw data set, to produce a final data set. This will page / sort / filter as necessary, according to the grid’s defaults and the current request etc.

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.

paginate_data(data)

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

persist_settings(settings, to='session')

Persist the given settings in some way, as defined by func.

remove(*keys)

This removes some column(s) from the grid, altogether.

render_action(action, row, i)

Renders an action menu item (link) for the given row.

render_actions(row, i)

Returns the rendered contents of the ‘actions’ column for a given row.

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_filters(template='/grids/filters.mako', **kwargs)

Render the filters to a Unicode string, using the specified template. Additional kwargs are passed along as context to the template.

render_table_element(template='/grids/b-table.mako', data_prop='gridData', empty_labels=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.

request_has_settings(type_)

Determine if the current request (GET query string) contains any filter/sort settings for the 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.

sort_data(data)

Sort the given query according to current settings, and return the result.

update_filter_settings(settings, source)

Updates a settings dictionary according to filter settings data found in either the GET query string, or session storage.

Parameters:

• settings – Dictionary of initial settings, which is to be updated.

• source – String identifying the source to consult for settings data. Must be one of: ('request', 'session').

update_page_settings(settings)

Updates a settings dictionary according to pager settings data found in either the GET query string, or session storage.

Note that due to how the actual pager functions, the effective settings will often come from both the request and session. This is so that e.g. the page size will remain constant (coming from the session) while the user jumps between pages (which only provides the single setting).

Parameters:

settings – Dictionary of initial settings, which is to be updated.

update_sort_settings(settings, source)

Updates a settings dictionary according to sort settings data found in either the GET query string, or session storage.

Parameters:

• settings – Dictionary of initial settings, which is to be updated.

• source – String identifying the source to consult for settings data. Must be one of: ('request', 'session').

user_has_defaults()

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

class tailbone.grids.core.GridAction(key, label=None, url='#', icon=None, target=None, link_class=None, click_handler=None)

Represents an action available to a grid. This is used to construct the ‘actions’ column when rendering the grid.

Parameters:

• key – Key for the action (e.g. 'edit'), unique within the grid.

• label – Label to be displayed for the action. If not set, will be a capitalized version of key.

• icon – Icon name for the action.

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

get_url(row, i)

Returns an action URL for the given row.

render_icon()

Render the HTML snippet for the action link icon.

render_label()

Render the label “text” within the actions column of a grid row. Most actions have a static label that never varies, but you can override this to add e.g. HTML content. Note that the return value will be treated / rendered as HTML whether or not it contains any, so perhaps be careful that it is trusted content.

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