Welcome | Get started | Dive into Lino | Contribute | Topics | Reference | More


This defines Actor and related classes.

See Introduction to actors.





Called during startup process to insert an actor class in the global actors_list and actors_dict.

resolve_action(spec[, action])


Actor(*args, **kw)

The base class for all actors (data view).

ActorMetaClass(classname, bases, classDict)


Called during startup process to insert an actor class in the global actors_list and actors_dict.

Special attention is given to the case when a plugin extends another plugin and redefines an actor of same name. In that case we want the ordering to remain as it was from the beginning. Actor overrides are not appended to the end but replaced, in order to not disturb the finding of _lino_default_table.

class lino.core.actors.Actor(*args, **kw)

Bases: Parametrizable, Permittable

The base class for all actors (data view). Subclassed by AbstractTable, Table, ChoiceList and Frame.


A dict of fieldname -> value pairs that specify "known values".

Requests will automatically be filtered to show only existing records with those values. This is like filter, but new instances created in this Table will automatically have these values set.


Set this to an integer (e.g. 0) to tell Lino to make a generic welcome message "You have X items in Y" when the number of rows in this table is greater than the given integer.

The following class methods are None in the default implementation. Subclass can define them.

classmethod get_handle_name(self, ar)

Most actors use the same UI handle for each request. But e.g. lino_welfare.modlib.debts.models.PrintEntriesByBudget and lino_xl.lib.events.EventsByType override this to implement dynamic columns depending on it's master_instance.

classmethod get_welcome_messages(self, ar)

If a method of this name is defined on an actor, then it must be a class method that takes an ar as single argument and returns or yields a list of welcome messages (messages to be displayed in the welcome block of admin_main.html).

Note that this handler will be called independently of whether the user has permission to view the actor or not.

required_roles = {<class 'lino.core.roles.SiteUser'>}

See Introduction to permissions.

model = None

The model on which this table iterates.

The application developer can specify either the model class itself or a string of type 'app.Model'.

If this is not None, it should be a subclass of lino.core.fields.TableRow.

app_label = 'core'

Specify this if you want to "override" an existing actor.

The default value is deduced from the module where the subclass is defined.

Note that this attribute is not inherited from base classes.

lino.core.dbtables.table_factory() also uses this.

master = None

The class of the "master" for this actor.

Application code usually doesn't need to specify this because it is automatically set on actors whose master_key is specified.

Setting this to something else than None will turn the table into a slave table.

If the master is something else than a database model (e.g. a ChoiceList), then the actor must also define a get_master_instance() method.

master_key = None

The name of a field of this table's model that points to its master.

The field named by master_key should usually be a ForeignKey field.

Special cases: lino_xl.lib.cal.EntriesByGuest shows the entries having a presence pointing to this guest.

Note that the master_key is automatically added to hidden_columns.

ignore_required_states = False

Whether to ignore the required states of workflow actions.

Set this to True on a workflow if you want to disable workflow control based on the state of the object.

Note that you must set this to True before importing any library workflows because permission handlers are defined when a workflow is imported.

sort_index = 60

The sort_index to be used when this table is being used by a ShowSlaveTable.

icon_name = None

The lino.core.actions.Action.icon_name to be used for a lino.core.actions.ShowSlaveTable action on this actor.

detail_html_template = 'bootstrap3/detail.html'

The template to be used for rendering a row of this actor as a detail html page.

list_html_template = 'bootstrap3/table.html'

The template to be used for rendering a collection of rows of this actor as a table html page.

auto_apply_params = True

Whether the parameter values of the parameter panel should be applied automatically when some value has been changed.

toolbar_location = 'top'

Not yet implemented. Should be one of 'top' (default), 'bottom', 'right', 'left'

hide_top_toolbar = False

See Actors with a modified toolbar.

hide_navigator = False

See How to remove the navigation buttons.

abstract = True

Set this to True to prevent Lino from generating useless JavaScript if this is just an abstract base class to be inherited by other actors.

Note that this class attribute is not inherited to subclasses.

handle_uploaded_files = None

Handler for uploaded files. Same remarks as for lino.core.actors.Actor.disabled_fields.

default_record_id = None

Turn this table into a single-row table.

When this is not None, you must also implement a custom version of get_row_by_pk() that returns the same database row regardless the given primary key.

This must currently be either None or 'row' (or 'myself').

TODO: Rename this to single_row and make it a simple boolean so that the application developer can say single_row = True instead of default_record_id = 'row'.

classmethod apply_cell_format(ar, row, col, recno, td)

Actor-level hook for overriding the formating when rendering this table as plain html.

For example lino_xl.lib.cal.Events overrides this.

classmethod get_pk_field()

Return the Django field used to represent the primary key when filling selected_pks.

classmethod get_row_by_pk(ar, pk)

Return the data row identified by the given primary key.

classmethod get_master_instance(ar, model, pk)

Return the master_instance corresponding to the specified primary key.

You need to override this on slave actors whose master is not a database model, e.g. the MessagesByChecker table.

ar is the action request on this actor. model is the master, except if master is ContentType (in which case model is the requested master).

classmethod get_disabled_fields(obj, ar)

Return the cached set of disabled fields for this obj and ar.

classmethod make_disabled_fields(obj, ar)

Used internally. Return a set of disabled fields for the specified object and request. See Disable elements of the user interface.

classmethod get_handle()

Return a static handle for this actor.

classmethod get_request_handle(ar)

Return the dynamic (per-request) handle for this actor for the renderer used by specified action request.

classmethod clear_handle()

When an actor has dynamic columns which depend on database content, then its layout handle may not persist between different Django test cases because a handle from a first test case may refer to elements which no longer exist in a second test case.

classmethod get_navinfo(ar, obj)

Return navigation info for the given obj in the given ar.

The default implementation assumes that you navigate on the data_iterator.

lino_xl.lib.calview.DayNavigator overrides this.

classmethod class_init()

Called internally at site startup.

classmethod collect_virtual_fields()

Collect virtual fields from class attributes and register them as virtual fields.

classmethod hide_editing(user_type)

Whether users of the given user type can edit in this data window.

Returns False by default: a user who has view permission also has permission to edit the data they see.

If this returns True, then Lino won't even call disable_delete() or disabled_fields().

This is similar to editable, but it allows you to keep editing functionality for certain user types.

Usage examples see Disable editing of a whole table.

classmethod get_view_permission(user_type)

Return True if this actor as a whole is visible for users with the given user_type.

classmethod get_row_permission(obj, ar, state, ba)

Whether to allow the given action request ar on the given database row row.

classmethod get_request_detail_action(ar)

Return the detail action of this actor, respecting the user's view permissions.

This is equivalent to the actors's detail_action, except when the model's get_detail_action() method returns a table for which the user has no view permission. In that case we don't want Lino to give up too quickly because there is still a possibility that the same layout is used on other tables, to which the user does have permission.

An example is described in Who can see the detail of an activity?

classmethod get_detail_title(ar, obj)

Return the string to use when building the title of a detail window on a given row of this actor.

classmethod get_choices_text(obj, request, field)

Return the text to be displayed in a combo box for the field field of this actor to represent the choice obj. Override this if you want a customized representation. For example lino_voga.models.InvoiceItems

classmethod setup_request(ar)

Customized versions may e.g. set master_instance before calling super().

Used e.g. by lino_xl.lib.outbox.models.MyOutbox or lino.modlib.users.ByUser.

Other usages are more hackerish:

classmethod setup_parameters(params)

Inheritable hook for defining parameters. Called once per actor at site startup. The default implementation just calls setup_parameters of the model (if a model is set).

classmethod override_column_headers(ar, **kwargs)

A hook to dynamically override the column headers. This has no effect on a GridPanel, only in printed documents or plain html.

classmethod get_layout_aliases()

Yield a series of (ALIAS, repl) tuples that cause a name ALIAS in a layout based on this actor to be replaced by its replacement repl.

classmethod set_detail_layout(*args, **kw)

Update the detail_layout of this actor, or create a new layout if there wasn't one before.

This is maybe deprecated. See #526.

The first argument can be either a string or a FormLayout instance. If it is a string, it will replace the currently defined 'main' panel. With the special case that if the current main panel is horizontal (i.e. the layout has tabs), it replaces the 'general' tab.

Typical usage example:

def my_details(sender, **kw):
    contacts = sender.modules.contacts
classmethod set_insert_layout(*args, **kw)

Update the insert_layout of this actor, or create a new layout if there wasn't one before.

Otherwise same usage as set_detail_layout().

classmethod add_detail_panel(*args, **kw)

Adds a panel to the Detail of this actor. Arguments: see lino.core.layouts.BaseLayout.add_panel()

This is deprecated. Use mixins instead.

classmethod add_detail_tab(*args, **kw)

Adds a tab panel to the Detail of this actor. See lino.core.layouts.BaseLayout.add_tabpanel()

This is deprecated. Use mixins instead.

classmethod get_toolbar_actions(parent, user_type)

Return a list of actions for which a button should exist in the toolbar of the specified "parent" action.

classmethod get_button_actions(parent)

Return a sorted list of actions that should be available as buttons in the specified parent (a window action).

This is used (1) by get_toolbar_actions() and (2) to reduce the list of disabled actions in disabled_fields to those which make sense. dbtables.make_disabled_fields

classmethod get_actions()

Return a sorted list of all bound actions offered by this actor.

classmethod get_detail_elems()

Return a list of the widgets (layout elements) that make up the detail layout.

An optional first argument is the front end plugin, a Plugin instance. If this is None, use settings.SITE.kernel.web_front_ends.

classmethod get_data_elem(name)

Find data element in this actor by name.

classmethod param_defaults(ar, **kw)

Return a dict with default values for the parameters. This will be called per request.

Usage example. The Clients table has a parameter coached_since whose default value is empty:

class Clients(dd.Table):
    parameters = dd.ParameterPanel(

But NewClients is a subclass of Clients with the only difference that the default value is amonthago:

class NewClients(Clients):
    def param_defaults(self, ar, **kw):
        kw = super().param_defaults(ar, **kw)
        return kw
classmethod request(*args, **kw)

Return an action request on this actor.

classmethod request_from(ar, *args, **kwargs)

Return an action request on this actor which inherits from the given parent request.

Deprecated. Rather call cls.request(parent=ar)

classmethod to_html(**kw)
classmethod get_screenshot_requests(language)

Return or yield a list of screenshots to generate for this actor. Not yet stable. Don't override this.

classmethod slave_as_html(master, ar)

Execute this slave view on the given master and render it as plain html. Used when display_mode is DISPLAY_MODE_HTML.

classmethod get_table_summary(obj, ar)

Return the HTML <div> to be displayed by lino.core.elems.TableSummaryPanel. That is (1) in a detail form when display_mode is DISPLAY_MODE_SUMMARY or (2) in a grid.

Lino internally creates a virtualfield slave_summary on each table that invokes this method.

classmethod columns_to_paragraph(self, ar=None, fmt=None)

Represent the given row as a paragraph with a comma-separated list of the values of the fields in the column_names of this actor.