`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.

lino.core.actions¶

Standard actions¶

`lino.core.actions`¶