More about plugins¶

Accessing plugins¶

Django developers are used to code like this:

from myapp.models import Foo

def print_foo(pk=1):
    print(Foo.objects.get(pk=pk))

In Lino we prefer to use the rt.models dict as follows:

from lino.api import rt

def print_foo(pk=1):
    Foo = rt.models.myapp.Foo
    print(Foo.objects.get(pk=pk))

This approach has the advantage of providing Plugin inheritance. One of the basic reasons for using plugins is that another developer can extend it and use their extension instead of the original plugin. Which means that the plugin developer does not know (and does not want to know) where the model classes are actually defined.

Note that rt.models is populated only after having imported the models. So you cannot use it at the module-level namespace of a models.py module. For example the following variant of above code would not work:

from lino.api import rt
Foo = rt.models.foos.Foo  # error `AttrDict has no item "foos"`
def print_foo(pk=1):
    print(Foo.objects.get(pk=pk))

Plugin descriptors get defined and configured before Django models start to load. Lino creates one Plugin instance for every installed plugin and makes it globally available in dd.plugins.FOO (where FOO is the app_label of the plugin).

The Plugin class is comparable to Django’s AppConfig class, which has been added in version 1.7., but there is at least one important difference: in Lino the Plugin instances for all installed plugins are available (in dd.plugins) before Django starts to load the first models.py. This is possible because Plugins are defined in __init__.py files of your plugins. As a consequence, unlike Django’s AppConfig, you cannot define a Plugin in your models.py file, you must define it in your plugins’s __init__.py.

Configuring plugins¶

Plugins can have attributes for holding configuration settings that are not meant to configured by site users via the web interface.

For example, the countries.country_code setting is defined as follows:

...
class Plugin(ad.Plugin):
    ...
    country_code = 'BE'

The values of plugin attributes can be configured at three levels.

As a core developer you specify a hard-coded default value.

As an application developer you can specify default values in your application by overriding the Site.get_plugin_configs() of your Site class. For example:

class Site(Site):

    def get_plugin_configs(self):
        yield super().get_plugin_configs()
        yield 'countries', 'country_code', 'FR'
        yield 'contacts', 'hide_region', True

As a server administrator you can override these configuration defaults in your project’s settings.py

The `Site.get_plugin_setting()` method¶

Some use cases for testing the Site.get_plugin_setting() method:

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

>>> settings.SITE.get_plugin_setting('foo', 'bar')
Traceback (most recent call last):
...
Exception: Plugin foo is not installed and no default was provided

>>> settings.SITE.get_plugin_setting('contacts', 'bar')
Traceback (most recent call last):
...
AttributeError: 'Plugin' object has no attribute 'bar'

In both cases, you can avoid the traceback by specifying a default value:

>>> print(settings.SITE.get_plugin_setting('foo', 'bar', None))
None

>>> settings.SITE.get_plugin_setting('contacts', 'bar', 'baz')
'baz'

The old style using Site.setup_plugins() still works but is deprecated:

class Site(Site):

    def setup_plugins(self):
        super().setup_plugins()
        self.plugins.countries.configure(country_code='BE')
        self.plugins.contacts.configure(hide_region=True)

Note that Site.setup_plugins() is called after Site.get_plugin_configs(). This can cause unexpected behaviour when you mix both methods.

using one of the following methods:

by overriding the Site class as described above for application developers
by setting the value directly after instantiation of your SITE object.

plugin configuration setting¶: A setting that can easily be set in a settings.py file.

More about plugins¶

Accessing plugins¶

Configuring plugins¶

The Site.get_plugin_setting() method¶

The `Site.get_plugin_setting()` method¶