lino.core.actors¶
This defines Actor
and related classes.
(This module's source code is available here.)
Functions
|
|
|
|
Internally called during startup process to insert a actor class in the global actors_list and actors_dict. |
|
|
Return the BoundAction object corresponding to the given specifier spec. |
Classes
|
The base class for all actors. |
|
-
lino.core.actors.
register_actor
(a)¶ Internally called during startup process to insert a 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:
lino.core.actors.NewBase
The base class for all actors. Subclassed by
AbstractTable
,Table
,ChoiceList
andFrame
.-
label
¶ The text to appear e.g. on a button that will call the default action of an actor. This attribute is not inherited to subclasses. For
Actor
subclasses that don't have a label, Lino will callget_actor_label()
.
-
known_values
¶ 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.
-
welcome_message_when_count
¶ 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
andlino_xl.lib.events.EventsByType
override this to implement dynamic columns depending on it's master_instance.
-
classmethod
get_row_classes
(self, ar)¶ If a method of this name is defined on an actor, then it must be a class method which takes an
ar
as single argument and returns either None or a string "red", "green" or "blue" (todo: add more colors and styles). Example:@classmethod def get_row_classes(cls,obj,ar): if obj.client_state == ClientStates.newcomer: return 'green'
Defining this method will cause an additional special RowClassStoreField field in the
lino.core.Store
objects of this actor.
-
classmethod
get_welcome_messages
(self, ar)¶ If a method of this name is defined on an actor, then it must be a class method which takes an
ar
as single argument and returns or yields a list of welcome messages (messages to be displayed in the welcome block ofadmin_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'>}¶
-
model
= None¶ The model on which this table iterates.
The application programmer can specify either the model class itself or a string of type
'app.Model'
.This should be None on all tables which are not subclass of
lino.core.dbtables.Table
.
-
actions
= None¶ An
AttrDict
containing the actions available on this actor.
-
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.table.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 aget_master_instance()
method.
-
master_key
= None¶ The name of a field of this table's
model
that points to itsmaster
.The field named by
master_key
should usually be aForeignKey
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 tohidden_columns
.
-
parameters
= None¶
-
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 aShowSlaveTable
.
-
icon_name
= None¶ The
lino.core.actions.Action.icon_name
to be used for alino.core.actions.ShowSlaveTable
action on this actor.
-
simple_parameters
= None¶ A tuple of names of filter parameters which are handled automatically.
Application developers should not set this attribute directly, they should rather define a
get_simple_parameters()
on the model.
A set of names of layout elements which are hidden by default.
The default is an empty set except for
lino.core.dbtables.Table
where this will be populated fromhidden_elements
of thelino.core.model.Model
.Note that these names are not being verified to be names of existing fields. This fact is being used by UNION tables like
lino_xl.lib.vat.IntracomInvoices
-
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.
-
window_size
= None¶ Set this to a tuple of (height, width) to have this actor display in a modal non-maximized window.
height must be either an integer expressing a number of rows or the string "auto". If it is auto, then the window should not contain any v-flexible component.
width must be either an integer expressing a number of rows or a string of style "90%".
Note that a relative width will be converted to a number of pixels when the window is rendered for the first time. That is, if you close the window, resize your browser window and reopen the same window, you will get the old size.
-
editable
= None¶ Set this explicitly to True or False to make the whole table editable or not. Otherwise Lino will guess what you want during startup and set it to False if the actor is a Table and has a get_data_rows method (which usually means that it is a virtual table), otherwise to True.
Non-editable actors won't even call
get_view_permission()
for actions whosereadonly
is False.The
changes.Changes
table is an example where this is being used: nobody should ever edit something in the table of Changes. The user interface uses this to generate optimized JS code for this case.
-
auto_apply_params
= True¶ Whether the parameter values of the parameter panel should be applied automatically when some value has been changed.
-
insert_layout_width
= 60¶ When specifying an
insert_layout
using a simple a multline string, then Lino will instantiate a FormPanel with this width.
-
hide_window_title
= False¶ This is set to True e.h. in home pages (e.g.
lino_welfare.modlib.pcsw.models.Home
).
-
allow_create
= True¶ If this is False, the table won't have any insert_action.
-
hide_headers
= False¶ Set this to True in order to hide the column headers.
This is ignored when the table is rendered in an ExtJS grid.
-
hide_top_toolbar
= False¶ Whether a Detail Window should have navigation buttons, a "New" and a "Delete" buttons. In ExtJS UI also influences the title of a Detail Window to specify only the current element without prefixing the Tables's title.
If used in a grid view in React will remove the top toolbar and selection tools.
This option is True in
lino.models.SiteConfigs
,lino_welfare.pcsw.models.Home
,lino.modlib.users.desktop.MySettings
,lino_xl.cal.CalenderView
.
-
simple_slavegrid_header
= False¶ If True the slave grid in a detail will be simplified
-
paginator_template
= None¶ Paginator elements can be customized using the template property using the predefined keys, default value is "FirstPageLink PrevPageLink PageLinks NextPageLink LastPageLink RowsPerPageDropdown". Here are the available elements that can be placed inside a paginator.
FirstPageLink PrevPageLink PageLinks NextPageLink LastPageLink RowsPerPageDropdown CurrentPageReport
-
title
= None¶ The text to appear e.g. as window title when the actor's default action has been called. If this is not set, Lino will use the
label
as title.
The text to appear on buttons of a ShowSlaveTable action for this actor.
-
detail_layout
= None¶ Define the layout to use for the detail window. Actors with
detail_layout
will get a show_detail action.When you define a
detail_layout
, you will probably also want to define ainsert_layout
.The
detail_layout
is normally an instance ofDetailLayout
or a subclass thereof. For example:class FooDetail(dd.DetailLayout): ... class Foos(dd.Table): ... detail_layout = FooDetail()
It is possible and recommended to specify
detail_layout
as a string, in which case it will be resolved at startup as follows:If the string contains at least one newline (or no newline and also no dot) then it is taken as the
main
of aDetailLayout
. For example:class Foos(dd.Table): ... detail_layout = """ id name description """
If the string contains a dot ('.') and does not contain any newlines, then Lino takes this as the name of the class to be instantiated and used.
For example:
class Courses(dd.Table): ... detail_layout = 'courses.CourseDetail'
This feature makes it possible to override the detail layout in an extended plugin. Before this you had to define a new class and to assign an instance of that class to every actor which uses it. But e.g. in
lino_xl.lib.courses
we have a lot of subclasses of theCourses
actor.
-
insert_layout
= None¶ Define the form layout to use for the insert window.
If there's a
detail_layout
but noinsert_layout
, the table won't have any (+) button to create a new row via a dialog window, but users can still create rows by writing into the phantom row. Example of this islino_xl.lib.courses.Topics
which has a detail layout with slave tables, but the model itself has only two fields (id and name) and it makes no sense to have an insert window.
-
card_layout
= None¶ Define a layout for a card view of the table.
-
help_text
= None¶ A help text that shortly explains what the default action of this actor 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.
-
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.
-
sum_text_column
= 0¶ The index of the column which should hold the text to display on the totals row (returned by
get_sum_text()
).
-
preview_limit
= None¶ For non-table actors this is always None, otherwise see
lino.core.tables.AbstractTable.preview_limit
.
-
handle_uploaded_files
= None¶ Handler for uploaded files. Same remarks as for
lino.core.actors.Actor.disabled_fields
.
-
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
ml.cal.Events
overrides this.
-
classmethod
get_pk_field
()¶ Return the Django field used to represent the primary key when filling selected_pks.
-
classmethod
get_actions_hotkeys
()¶ Return or yield a list of hotkeys to be linked to named actions.
[{'key': key, 'ctrl': Bool, 'shift': Bool, 'ba': action_name}]
-
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. theProblemsByChecker
table.ar is the action request on this actor. model is the
master
, except ifmaster
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)¶ Return a set of disabled fields for the specified object and request.
-
classmethod
get_request_handle
(ar)¶ Return the dynamic (per-request) handle for this actor for the renderer used by specified action request.
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.cal.CalendarView
overrides this.
-
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
summary_row
(ar, obj, **kw)¶ Return a HTML representation of the given data row obj for usage in a summary panel.
The default implementation calls
lino.core.model.Model.summary_row()
.
-
classmethod
get_handle
()¶ Return a static handle for this actor.
-
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
get_view_permission
(user_type)¶ Return True if this actor as a whole is visible for users with the given user_type.
-
classmethod
get_create_permission
(ar)¶ Dynamic test per request. This is being called only when
allow_create
is True.
-
classmethod
get_row_permission
(obj, ar, state, ba)¶ Returns True or False whether the given action request ActionRequest ar is allowed on the given row instance 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'sget_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_actor_label
()¶ Compute the label of this actor.
-
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
get_title
(ar)¶ Return the title of this actor for the given action request ar.
The default implementation calls
get_title_base()
andget_title_tags()
and returns a string of type BASE [ (TAG, TAG...)].Override this if your table's title should mention for example filter conditions. See also
Table.get_title
.
-
classmethod
get_title_base
(ar)¶ Return the base part of the title. This should be a translatable string. This is called by
get_title()
to construct the actual title.It is also called by
lino.core.dashboard.DashboardItem.render_request()
Yield a list of translatable strings to be added to the base part of the title. This is called by
get_title()
to construct the actual title.
-
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
orlino.modlib.users.ByUser
.Other usages are more hackerish:
lino_xl.lib.households.models.SiblingsByPerson
lino_welfare.modlib.cal.EntriesByClient
lino_welfare.pcsw.models.Home
,lino.modlib.users.MySettings
.
-
classmethod
setup_parameters
(params)¶ Inheritable hook for defining parameters. Called once per actor at site startup. The default implementation just calls
setup_parameters
of themodel
(if amodel
is set).
-
classmethod
get_simple_parameters
()¶ Inheritable hook for defining which parameters are simple. Expected to return a list of names of parameter fields.
-
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_sum_text
(ar, sums)¶ Return the text to display on the totals row. The default implementation returns "Total (N rows)".
-
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:
@dd.receiver(dd.post_analyze) def my_details(sender, **kw): contacts = sender.modules.contacts contacts.Partners.set_detail_layout(PartnerDetail())
-
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)¶ Return a list of actions for which a button should exist in the toolbar of the specified "parent" action.
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
(*args)¶ An optional first argument is the front end plugin, a
Plugin
instance. If this is None, usesettings.SITE.kernel.default_ui
.Returns a list of the widgets (layout elements) that make up the detail layout.
-
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( ... coached_since=models.DateField(blank=True))
But NewClients is a subclass of Clients with the only difference that the default value is amonthago:
class NewClients(Clients): @classmethod def param_defaults(self,ar,**kw): kw = super(NewClients,self).param_defaults(ar,**kw) kw.update(coached_since=amonthago()) 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. Don't worry if you don't understand.
-
classmethod
slave_as_html
(master, ar)¶ Creates and returns the method to be used when
display_mode
is html.
-
summary_sep
= functools.partial(<lxml.builder.ElementMaker object>, 'br')¶
-
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 whendisplay_mode
is summary or (2) in a grid.Lino internally creates a virtualfield
slave_summary
on each table that invokes this method.
-
-
lino.core.actors.
resolve_action
(spec, action=None)¶ Return the BoundAction object corresponding to the given specifier spec. The specifier can be:
a model or a table
a bound action
an action instance
a string of the form
myapp.MyModel
(i.e. resolving to a model)a string of the form
myapp.MyModels
(i.e. resolving to a table)
If it is an action instance, Lino will use the
definiing_actor
of that action.