Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

lino.core.actions

This module defines the Action class and some of the standard actions.

See Introduction to actions.

class lino.core.actions.Action

Abstract base class for all actions.

__init__()

The first positional argument is the optional label, other arguments should be specified as keywords and can be any of the existing class attributes.

label

The text to place on the button or menu item. A short descriptive text in user language. Used e.g. on menu items. Also on toolbar buttons if they have neither icon_name nor button_text.

button_text

The text to appear on buttons for this action. If this is not defined, the label is used.

required_roles

Permission requirements to specify for whom and under which conditions this action is available.

See lino.core.permissions.Permittable.required_roles.

help_text

The text to appear as tooltip when the mouse is over that button.

A help text that shortly explains what this action does. In a graphical user interface this will be rendered as a tooltip text.

If this is not given by the code, Lino will potentially set it at startup when loading the help_texts.py files.

hotkey

An instance of lino.core.keyboard.Hotkey. Used as a keyboard shortcut to trigger actions.

button_color

The color to be used on icon-less buttons for this action (i.e. which have no icon_name). See also lino.core.site.Site.use_silk_icons.

Not yet implemented. This is currently being ignored.

icon_name

The class name of an icon to be used for this action when rendered as toolbar button. Allowed icon names are defined in lino.core.constants.ICON_NAMES.

combo_group

The name of another action to which to “attach” this action. Both actions will then be rendered as a single combo button.

select_rows

True if this is a row action, False if this action is a list action.

A row action is an action that acts on a given a database row.

For example DeleteSelected is a row action while ShowInsert is a list action.

readonly

Whether this action claims to not change anything in the current database object.

See Read-only actions.

editable

Whether the parameter fields should be editable. Setting this to False seems nonsense.

disable_primary_key

Whether primary key fields should be disabled when using this action. This is True for all actions except ShowInsert.

keep_user_values

Whether the parameter window should keep its values between different calls. If this is True, Lino does not fill any default values and leaves those from a previous call.

Deprecated because it (1) is not used on any production site, (2) has a least two side effect: the fields never get a default value, even not on first execution, and you cannot explicitly specify programmatic field values. And (3) we actually wouldn’t want to specify this per action but per field.

parameters

See lino.core.utils.Parametrizable.parameters.

use_param_panel

Used internally. This is True for window actions whose window use the parameter panel: grid and emptytable (but not showdetail)

no_params_window

Set this to True if your action has parameters but you do not want it to open a window where the user can edit these parameters before calling the action.

Setting this attribute to True means that the calling code must explicitly set all parameter values. Usage example are the lino_xl.lib.polls.models.AnswersByResponse.answer_buttons and lino_xl.lib-tickets.Ticket.quick_assign_to virtual fields.

sort_index

Determines the sort order in which the actions will be presented to the user.

List actions are negative and come first.

Predefined sort_index values are:

value

action

-1

as_pdf

10

ShowInsert

11

duplicate

20

detail

30

delete

31

merge

50

Print

51

Clear Cache

52

lino.modlib.users.UserPlan.start_plan

53

lino.modlib.users.UserPlan.update_plan

60

ShowSlaveTable

90

default for all custom row actions

100

SubmitDetail

200

default for all workflow actions (ChangeStateAction)

auto_save

What to do when this action is being called while the user is on a dirty record.

  • False means: forget any changes in current record and run the action.

  • True means: save any changes in current record before running the action. None means: ask the user.

extjs_main_panel

Used by lino_xl.lib.extensible and lino.modlib.awesome_uploader.

Example:

class CalendarAction(dd.Action):
    extjs_main_panel = "Lino.CalendarApp().get_main_panel()"
    ...
js_handler

This is usually None. Otherwise it is the name of a Javascript callable to be called without arguments. That callable must have been defined in a lino.core.plugin.Plugin.site_js_snippets of the plugin.

Also can be defined as a class method, that takes the actor as the only argument and should return a JavaScript executable. An example use case is defined in lino.modlib.help.OpenHelpWindow where the return string follows the format:

return "let _ = window.open('URL')"

Callable Example:

def js_handler(self, actor):
    ...
    return JS_EXECUTABLE
action_name

Internally used to store the name of this action within the defining Actor’s namespace.

defining_actor

The lino.core.actors.Actor who uses this action for the first time. This is set during attach_to_actor(). This is used internally e.g. by lino.modlib.extjs when generating JavaScript code for certain actions.

default_format

Used internally.

hide_top_toolbar

This is set to True for ShowInsert.

As an application developer you don’t need this action attribute, but see lino.core.actors.Actor.hide_top_toolbar.

hide_navigator

Hide navigator actions on window opened by this action.

never_collapse

When True the action will always be visible, regardless of whether the toolbar collapsed or not.

show_in_toolbar

Whether the button for this action should be displayed in the toolbar.

In ExtJS this will also cause it to be in the context menu of a grid.

For example the CheckinVisitor, ReceiveVisitor and CheckoutVisitor actions have this attribute explicitly set to False because otherwise they would be visible in the toolbar.

show_in_plain

Whether the button for this action should be displayed in the toolbar of a plain html view.

show_in_side_toolbar

Whether the button for this action should be displayed in the side toolbar.

side toolbar

A floating toolbar on the right side used on mobile devices.

show_in_workflow

Whether the button for this action should be displayed in the workflow_buttons column. If this is True, then Lino will automatically set custom_handler to True.

buddy_name

Whether this action should be displayed after the label of a given field.

custom_handler

Whether this action is implemented as Javascript function call. This is necessary if you want your action to be callable using an “action link” (html button).

http_method

HTTP method to use when this action is called using an AJAX call.

preprocessor

Name of a Javascript function to be invoked on the web client when this action is called.

window_type

On actions that opens_a_window this must be a unique one-letter string expressing the window type.

See constants.WINDOW_TYPES.

Allowed values are:

  • None : opens_a_window is False

  • ‘t’ : ShowTable

  • ‘d’ : ShowDetail

  • ‘i’ : ShowInsert

This can be used e.g. by a summary view to decide how to present the summary data (usage example lino.modlib.uploads.AreaUploads.get_table_summary()).

callable_from

A string that specifies from which window_type this action is callable. None means that it is only callable from code.

Default value is ‘td’ which means from both table and detail (including ShowEmptyTable which is subclass of ShowDetail). But not callable from ShowInsert.

__get__(self, instance, owner)

When a model has an action “foo”, then getting an attribute “foo” of a model instance will return an InstanceAction.

classmethod decorate(cls, *args, **kw)

Return a decorator that turns an instance method on a model or a class method on an actor into an action of this class.

The decorated method will be installed as the actions’s run_from_ui method.

All arguments are forwarded to Action.__init__().

is_callable_from(self, caller)

Return True if this action makes sense as a button from within the specified caller (an action instance which must have a window_type). Do not override this method on your subclass ; rather specify callable_from.

is_window_action(self)

Return True if this is a “window action” (i.e. which opens a GUI window on the client before executing).

get_label(self)

Return the label of this action, or the action_name if the action has no explicit label.

attach_to_actor(self, owner, name)

Called once per actor and per action on startup before a BoundAction instance is created. If this returns False, then the action won’t be attached to the given actor.

The owner is the actor which “defines” the action, i.e. uses that instance for the first time. Subclasses of the owner may re-use the same instance without becoming the owner.

get_action_permission(self, ar, obj, state)

Return (True or False) whether the given ActionRequest ar should get permission to run on the given Model instance obj (which is in the given state).

Derived Action classes may override this to add vetos. E.g. the MoveUp action of a Sequenced is not available on the first row of given ar.

This should be used only for light-weight tests. If this requires a database lookup, consider disabling the action in disabled_fields where you can disable multiple actions and fields at once.

get_view_permission(self, user_type)

Backwards-compatibility for ext_renderer, which does:

for ds in lh.layout.get_datasources():
    if ds.get_view_permission(user_type):
        return True
get_action_view_permission(self, actor, user_type)

Return True if this action is visible on the given actor for users of the given user_type.

run_from_ui(self, ar, **kwargs)

Execute the action. ar is a BaseRequest object.

run_from_code(self, ar=None, *args, **kwargs)

Probably to be deprecated. Execute the action. The default calls run_from_ui(). You may override this to define special behaviour

action_param_defaults(self, ar, obj, **kw)

Same as lino.core.actors.Actor.param_defaults(), except that on an action it is a instance method.

Note that this method is not called for actions which are rendered in a toolbar (#1336).

Usage examples: lino.modlib.users.actions.SendWelcomeMail

get_layout_aliases(self)

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

Standard actions

class lino.core.actions.ShowEmptyTable

The default action for lino.utils.report.EmptyTable.

class lino.core.actions.SaveGridCell

Called when user edited a cell of a non-phantom record in a grid. Installed as update_action on every Actor.

class lino.core.actions.SubmitDetail

Save changes in the detail form.

This is rendered as the “Save” button of a detail window.

Installed as submit_detail on every actor.

class lino.core.actions.CreateRow

Called when user edited a cell of a phantom record in a grid.

class lino.core.actions.ShowSlaveTable

An action that opens a window showing another table (to be specified when instantiating the action).

class lino.core.actions.WrappedAction

On instantiation it takes a BoundAction as a positional argument and returns an action instance that behaves as a wrapper around the given BoundAction.action useful when binding to another Actor.

class lino.core.actions.MultipleRowAction

Base class for actions that update something on every selected row.

class lino.core.actions.DeleteSelected

Delete the selected row(s).

This action is automatically installed on every editable actor.

class lino.core.actions.ShowTable

Open a window with a tabular grid editor on this table. The grid editor is the main widget of that window (otherwise it would be a slave table).

Most items of the main menu are ShowTable actions.

class lino.core.actions.ShowDetail

Open the detail window on a table actor.

class lino.core.actions.ShowInsert

Open an insert window on this actor. A new row will be inserted only when this window gets submitted, which is a separate action named SubmitInsert.

class lino.core.actions.SubmitInsert

Create a new database row using the data specified in the insert window. Called when the Create button of an insert window was clicked.

Most database models share the same action instance of this, which is stored in the submit_insert class attribute.