tailbone.views.master

Model Master View

This module contains the “model master” view class. This is a convenience abstraction which provides some patterns/consistency for the typical set of views needed to expose a table’s data for viewing/editing/etc. Usually this means providing something like the following view methods for a model:

• index (list/filter)

• create

• view

• edit

• delete

The actual list of provided view methods will depend on usage. Generally speaking, each view method which is provided by the master class may be configured in some way by the subclass (e.g. add extra filters to a grid).

class tailbone.views.master.MasterView(request, context=None)

Base “master” view class. All model master views should derive from this.

index()

View to list/filter/sort the model data.

If this view receives a non-empty ‘partial’ parameter in the query string, then the view will return the rendered grid only. Otherwise returns the full page.

create(form=None, template='create')

View for creating a new model record.

view(instance=None)

View for viewing details of an existing model record.

edit()

View for editing an existing model record.

delete()

View for deleting an existing model record.

Attributes to Override

The following is a list of attributes which you can (and in some cases must) override when defining your subclass.

MasterView.model_class

All master view subclasses must define this attribute. Its value must be a data model class which has been mapped via SQLAlchemy, e.g. rattail.db.model.Product.

MasterView.normalized_model_name

Name of the model class which has been “normalized” for the sake of usage as a key (for grid settings etc.). If not defined by the subclass, the default will be the lower-cased model class name, e.g. ‘product’.

tailbone.views.master.grid_key

Unique value to be used as a key for the grid settings, etc. If not defined by the subclass, the normalized model name will be used.

MasterView.route_prefix

Value with which all routes provided by the view class will be prefixed. If not defined by the subclass, a default will be constructed by simply adding an ‘s’ to the end of the normalized model name, e.g. ‘products’.

MasterView.grid_factory

Factory callable to be used when creating new grid instances; defaults to tailbone.grids.Grid.

MasterView.results_downloadable_csv

Flag indicating whether the view should allow CSV download of grid data, i.e. primary search results.

MasterView.help_url

If set, this defines the “default” help URL for all views provided by the master. Default value for this is simply None which would mean the Help button is not shown at all. Note that the master may choose to override this for certain views, if so that should be done within get_help_url().

MasterView.version_diff_factory

Optional factory to use for version diff objects. By default this is not set but a subclass is free to set it. See also get_version_diff_factory().

Methods to Override

The following is a list of methods which you can override when defining your subclass.

MasterView.editable_instance(obj)

Returns boolean indicating whether or not the given object should be considered “editable”. Returns True by default; override as necessary.

Parameters:

obj – A top-level record/object, of the type normally handled by this master view.

Returns:

True if object is editable, else False.

MasterView.get_csv_fields()

Return the list of fields to be written to CSV download. Default field list will be constructed from the underlying table columns.

MasterView.get_csv_row(obj, fields)

Return a dict for use when writing the row’s data to CSV download.

MasterView.get_help_url()

May return a “help URL” if applicable. Default behavior is to simply return the value of help_url (regardless of which view is in effect), which in turn defaults to None. If an actual URL is returned, then a Help button will be shown in the page header; otherwise it is not shown.

This method is invoked whenever a template is rendered for a response, so if you like you can return a different help URL depending on which type of CRUD view is in effect, etc.

classmethod MasterView.get_model_key(as_tuple=False)

Returns the primary model key(s) for the master view.

Internally, model keys are a sequence of one or more keys. Most typically it’s just one, so e.g. ('uuid',), but composite keys are possible too, e.g. ('parent_id', 'child_id').

Despite that, this method will return a string representation of the keys, unless as_tuple=True in which case it returns a tuple. For example:

# for model keys: ('uuid',)

cls.get_model_key()                  # => 'uuid'
cls.get_model_key(as_tuple=True)     # => ('uuid',)

# for model keys: ('parent_id', 'child_id')

cls.get_model_key()                  # => 'parent_id,child_id'
cls.get_model_key(as_tuple=True)     # => ('parent_id', 'child_id')

Parameters:

as_tuple – Whether to return a tuple instead of string.

Returns:

Either a string or tuple of model keys.

MasterView.get_version_diff_enums(version)

This can optionally return a dict of field enums, to be passed to the version diff factory. This method is called as part of make_version_diff().

MasterView.get_version_diff_factory(**kwargs)

Must return the factory to be used when creating version diff objects.

By default this returns the tailbone.diffs.VersionDiff class, unless version_diff_factory is set, in which case that is returned as-is.

Returns:

A factory which can produce VersionDiff objects.

MasterView.make_version_diff(version, *args, **kwargs)

Make a version diff object, using the factory returned by get_version_diff_factory().

Parameters:

• version – Reference to a Continuum version object.

• title – If specified, must be as a kwarg. Optional override for the version title text. If not specified, title_for_version() is called for the title.

• *args – Additional args to pass to the factory.

• **kwargs – Additional kwargs to pass to the factory.

Returns:

A VersionDiff object.

MasterView.title_for_version(version)

Must return the title text for the given version. By default this will be the model title for the version’s data class.

Parameters:

version – Reference to a Continuum version object.

Returns:

Title text for the version, as string.

Support Methods

The following is a list of methods you should (probably) not need to override, but may find useful:

MasterView.default_edit_url(obj, i=None)

Return the default “edit” URL for the given object, if applicable. This first checks editable_instance() for the object, and will only return a URL if the object is deemed editable.

Parameters:

• obj – A top-level record/object, of the type normally handled by this master view.

• i – Optional row index within a grid.

Returns:

The “edit object” URL as string, or None.

MasterView.get_action_route_kwargs(obj)

Get a dict of route kwargs for the given object.

This is called from various other “convenience” URL generators, e.g. default_edit_url().

It inspects the given object, as well as the “model key” (as returned by get_model_key()), and returns a dict of appropriate route kwargs for the object.

Most typically, the model key is just uuid and so this would effectively return {'uuid': obj.uuid}.

But composite model keys are supported too, so if the model key is (parent_id, child_id) this might instead return {'parent_id': obj.parent_id, 'child_id': obj.child_id}.

Such kwargs would then be fed into route_url() as needed, for example to get a “view product URL”:

kw = self.get_action_route_kwargs(product)
url = self.request.route_url('products.view', **kw)

Parameters:

obj – A top-level record/object, of the type normally handled by this master view.

Returns:

A dict of route kwargs for the object.