`system` : Site-wide settings¶

The lino.modlib.system plugin defines some general-purpose concepts, especially the SiteConfig model, which is used for storing site parameters that are editable by a site administrator in the web front end.

It gets automatically installed by lino.modlib.users and therefore is present in most Lino sites.

It also defines the Lockable mixin, the DomainSpecific mixin, the Genders, TimeZones and DateFormats choicelists.

The SiteConfig model is also used for hosting multiple domains with a same Lino site.

This page contains code snippets (lines starting with >>>), which are being tested during our development workflow. The following snippet initializes the demo project used throughout this page.

>>> import lino
>>> lino.startup('lino_book.projects.min9.settings')
>>> from lino.api.doctest import *

Plugin settings ¶

lino.modlib.system.site_config_id¶: The primary key of the SiteConfig instance to use by default on this site.

lino.modlib.system.host2config¶

A dictionary that maps the return value of HttpRequest.get_host() to the primary key of the SiteConfig instance to use.

When host2config is set, Lino also automatically fills the Django setting ALLOWED_HOSTS at startup.

See The ``host2config` setting`__

lino.modlib.system.with_mptt¶: Whether Hierarchical should use django-mptt to optimize database access when navigating in hierarchical trees. See Recursive filtering in Hierarchical.

The `host2config` setting ¶

lino.modlib.system has a setting host2config. and a mixin DomainSpecific.

The verbose_name of the SiteConfig model is “Domain”, the label “Site configuration” is still used for MySiteConfigs.

BaseRequest has an

On a site with a non-empty host2config, Lino sets the site_config_id attribute for every incoming web request.

He does so by looking up the return value of HttpRequest.get_host() in host2config.

The `Lockable` mixin ¶

class lino.modlib.system.Lockable¶

Mixin to add row-level edit locking to any model.

Models with row-level edit locking are not editable in detail view by default. All form fields are disabled. The user must click Edit in order to request an edit lock for that row. This will enable all fields (except those which are disabled for some other reason).

Caveats: locking a row and then navigating away without changing anything will leave the row locked.

The `DomainSpecific` mixin ¶

class lino.modlib.system.DomainSpecific¶

Model mixin for database objects that can be specific per domain.

my_domain¶

The domain to which this database row belongs.

This is a pointer to a SiteConfig instance. Rows with an empty my_domain are shared (visible) in all domains.

This field is a dummy field when host2config is empty.

Site configuration parameters ¶

class lino.modlib.system.SiteConfig¶

A singleton database object used to store persistent site parameters.

This model has exactly one instance, which is accessible as the settings.SITE.site_config property.

default_build_method¶

The default build method to use when rendering printable documents.

If this field is empty, Lino uses the value found in lino.core.site.Site.default_build_method.

simulate_today¶

A constant user-defined date to be substituted as current system date.

This should be empty except in situations such as a posteriori data entry in a prototype.

site_company¶

The site operator, i.e. the legal person that operates this Lino site.

See How to specify the site operator.

If no plugin named ‘contacts’ is installed, then this is a dummy field and always contains None.

hide_events_before¶

If this is not empty, any calendar events before that date are being hidden in certain places.

For example OverdueEvents, EventsByController, …

Injected by lino_xl.lib.cal.

class lino.modlib.system.SiteConfigManager¶: Returns the cached instance, which holds the one and only database instance.

class lino.modlib.system.BuildSiteCache¶: Rebuild the site cache. This action is available on About.

class lino.modlib.system.SiteConfigs¶

The table used to present the SiteConfig row in a Detail form.

See also lino.core.site.Site.get_site_config().

Recurrences in the system ¶

class lino.modlib.system.RecurrenceSet¶

Mixin for database models that express a set of repeating (“recurrent”) events. Example usage can be found in Event generators.

start_date¶: The start date of the first meeting to be generated.

end_date¶: The end date of the first meeting to be generated. Leave this field empty if the meetings last less than one day.

start_time¶

end_time¶

every¶: The frequency of periodic iteration: daily, weekly, monthly or yearly.

every_unit¶

The interval between each periodic iteration.

For example, when every is yearly, an every_unit of 2 means once every two years. The default value is 1.

positions¶

Space-separated list of one or several positions within the recurrency cycle.

Each position is a positive or negative integer expressing which occurrence is to be taken from the recurrency period. For example if positions is -1 and every_unit is monthly, we get the last day of every month.

Inspired by dateutil.rrule.

max_events¶: Maximum number of calendar entries to generate.

monday¶

tuesday¶

wednesday¶

thursday¶

friday¶

saturday¶

sunday¶

weekdays_text¶

A virtual field returning the textual formulation of the weekdays where the recurrence occurs.

Usage examples see cal : Calendar functionality.

class lino.modlib.system.Recurrences¶

List of possible choices for a ‘recurrency’ field.

A recurrency (an item of this choicelist) is also a DurationUnit.

easter¶

Repeat events yearly, moving them together with the Easter data of that year.

Lino computes the offset (number of days) between this rule’s start_date and the Easter date of that year, and generates subsequent events so that this offset remains the same.

The days of the week ¶

class lino.modlib.system.Weekdays¶: A choicelist with the seven days of a week.

The available values in the system are.

>>> rt.show(system.Weekdays)
======= =========== ===========
 value   name        text
------- ----------- -----------
 1       monday      Monday
 2       tuesday     Tuesday
 3       wednesday   Wednesday
 4       thursday    Thursday
 5       friday      Friday
 6       saturday    Saturday
 7       sunday      Sunday
======= =========== ===========

lino.modlib.system.WORKDAYS¶: The five workdays of the week (Monday to Friday).

Duration units ¶

The system plugin defines DurationUnits choicelist, a site-wide list of duration units.

class lino.modlib.system.DurationUnits¶

The list of possible duration units defined by this application.

This is used as the selection list for the duration_unit field of a calendar entry.

Every item is an instance of DurationUnit.

class lino.modlib.system.DurationUnit¶

Base class for the choices in the DurationUnits choicelist.

add_duration(unit, orig, value)¶

Return a date or datetime obtained by adding value times this unit to the specified value orig. Returns None is orig is empty.

This is intended for use as a curried magic method of a specified list item:

The available values in the system are:

>>> rt.show(system.DurationUnits)
======= ========= =========
 value   name      text
------- --------- ---------
 s       seconds   seconds
 m       minutes   minutes
 h       hours     hours
 D       days      days
 W       weeks     weeks
 M       months    months
 Y       years     years
======= ========= =========

DurationUnits can be used for arithmetic operation on durations. For example:

>>> from lino.modlib.system.choicelists import DurationUnits
>>> start_date = i2d(20111026)
>>> DurationUnits.months.add_duration(start_date, 2)
datetime.date(2011, 12, 26)

>>> from lino.utils import i2d
>>> start_date = i2d(20111026)
>>> DurationUnits.months.add_duration(start_date, 2)
datetime.date(2011, 12, 26)
>>> DurationUnits.months.add_duration(start_date, -2)
datetime.date(2011, 8, 26)

>>> start_date = i2d(20110131)
>>> DurationUnits.months.add_duration(start_date, 1)
datetime.date(2011, 2, 28)
>>> DurationUnits.months.add_duration(start_date, -1)
datetime.date(2010, 12, 31)
>>> DurationUnits.months.add_duration(start_date, -2)
datetime.date(2010, 11, 30)

>>> start_date = i2d(20140401)
>>> DurationUnits.months.add_duration(start_date, 3)
datetime.date(2014, 7, 1)
>>> DurationUnits.years.add_duration(start_date, 1)
datetime.date(2015, 4, 1)

Display colors ¶

class lino.modlib.system.DisplayColors¶: A list of colors to be specified for displaying.

This is a subset of the 140 colors supported by all modern browsers

>>> rt.show(system.DisplayColors)
======= ============ ============ ============
 value   name         text         Font color
------- ------------ ------------ ------------
   white        White        black
   gray         Gray         black
   black        Black        white
   gainsboro    Gainsboro    black
   ghostwhite   GhostWhite   black
   cornsilk     Cornsilk     black
   red          Red          white
   orange       Orange       white
   yellow       Yellow       black
   green        Green        white
   blue         Blue         white
   magenta      Magenta      white
   violet       Violet       white
   silver       Silver       black
   maroon       Maroon       white
   peru         Peru         white
   pink         Pink         black
   olive        Olive        white
   aqua         Aqua         white
   navy         Navy         white
   aquamarine   Aquamarine   black
   darkgreen    DarkGreen    white
   palegreen    PaleGreen    black
   chartreuse   Chartreuse   black
   lime         Lime         black
   teal         Teal         white
   fuchsia      Fuchsia      white
   cyan         Cyan         black
   purple       Purple       white
======= ============ ============ ============

Here is how these colors are rendered in your browser:

White Gray Black Gainsboro GhostWhite Cornsilk Red Orange Yellow Green Blue Magenta Violet Silver Maroon Peru Pink Olive Aqua Navy Aquamarine DarkGreen PaleGreen Chartreuse Lime Teal Fuchsia Cyan Purple

Time zones ¶

Every Lino site can define its own list of time zones. Time zones are used by lino.modlib.users.User.time_zone and lino_xl.lib.working.Session.time_zone. These fields are dummy fields when USE_TZ is False.

By default, the USE_TZ is False and the TimeZones list contains only one item:

>>> settings.USE_TZ
False

>>> rt.show('system.TimeZones')
======= ========= ======
 value   name      text
------- --------- ------
 01      default   UTC
======= ========= ======

To activate time zones, you must:

set USE_TZ to True
populate in the TimeZones list.

You usually populate in the TimeZones list in your local workflows_module. For example:

# don't forget to import the default workflows:
from lino_noi.lib.noi.workflows import *

from lino.modlib.about import TimeZones
TimeZones.clear()
add = TimeZones.add_item
add('01', settings.TIME_ZONE or 'UTC', 'default')
add('02', "Europe/Tallinn")
add('03', "Europe/Brussels")
add('04', "Africa/Tunis")

See noi2 : Noi with publisher and without accounting for an example of a site with activated time zones.

class lino.modlib.system.TimeZones¶

The list of time zones available on this site.

This choicelist always contains at least one choice named default.

You can redefine this choicelist in your local workflows_module.

default¶: The default time zone on this server, corresponding to TIME_ZONE. Unlike TIME_ZONE (which is a string), default is a Choice object whose text is the same as the string and which has an attribute tzinfo, which contains the time zone info object.

Date formats ¶

class lino.modlib.system.DateFormats¶

A list of date formats.

Used by lino.modlib.users.User.date_format.

This is currently used only by the lino_xl.lib.google plugin. Date formatting is configured site-wide in lino.core.site.Site.date_format_strftime & Co.

>>> rt.show('system.DateFormats')
======= ========= ==========
 value   name      text
------- --------- ----------
 010     default   dd.mm.y
 020               dd.mm.yy
 030               dd/mm/y
 040               dd/mm/yy
======= ========= ==========

Miscellaneous ¶

class lino.modlib.system.BleachChecker¶: A data checker used to find unbleached html content.

class lino.modlib.system.Genders¶

Defines the possible choices for the gender of a person (“male”, “female” and “nonbinary”).

>>> rt.show('system.Genders')
======= =========== ===========
 value   name        text
------- ----------- -----------
 M       male        Male
 F       female      Female
 N       nonbinary   Nonbinary
======= =========== ===========

This choicelist is used for deciding the salutation (Mr/Mrs) and for its mf() method.

See The Human mixin.

class lino.modlib.system.YesNo¶

A choicelist with two values “Yes” and “No”.

Used e.g. to define parameter panel fields for BooleanFields:

foo = dd.YesNo.field(_("Foo"), blank=True)

class lino.modlib.system.ObservedEvent¶

Base class for choices of “observed event”-style choicelists.

add_filter(self, qs, pv)¶: Add a filter to the given Django queryset. The given obj must be either a datetime.date object or must have two attributes start_date and end_date. The easiest way is to have it an instance of DateRange or DateRangeValue.

class lino.modlib.system.PeriodEvents¶: The list of things you can observe on a lino.mixins.periods.DateRange.

system : Site-wide settings¶

`system` : Site-wide settings¶