excerpts: Database excerpts

The lino_xl.lib.excerpts adds the notion of database excerpts.

Read also printing : Basic printing functionality.

A tested document

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.max.settings.doctests')
>>> from lino.api.shell import *
>>> from lino.api.doctest import *

What is a database excerpt?

A database excerpt is a database object which represents the fact that a given user has requested a printable document at a given moment. Lino keeps all these requests in a global database table defined by the Excerpt model.

Users can see a printed a history of their database excerpts.

Usage

  • add lino_xl.lib.excerpts to your lino.core.Site.get_installed_apps().

  • Add the virtual field printed

Lino does not automatically add an action per model to make the excerpt history visible from a model. If you want this, add yourself your preferred variant.

This can be either using a ShowSlaveTable button in the toolbar:

show_excerpts = dd.ShowSlaveTable('excerpts.ExcerptsByOwner')
show_excerpts = dd.ShowSlaveTable('excerpts.ExcerptsByProject')

Or by adding excerpts.ExcerptsByOwner or excerpts.ExcerptsByProject (or both, or your own subclass of one of them) to the detail_layout.

In addition to the main template, excerpt types can specify a body template. Before rendering the main template, Lino When the main template is being rendered, it has a context variable body which

As a SiteAdmin user (and when lino.modlib.davlink is installed) you can easily modify the main template which has been used to print a given excerpt using the Edit Template button in the detail window of that Excerpt object.

If you want to configure which document to use as main template, then you must use the Configuration menu:

  • Configuration ‣ Excerpt types

Lino has a main template named excerpts/Default.odt which is

Excerpts

A database excerpt is a database object which represents the fact that a given user has requested a printable document at a given moment. Lino keeps all these requests in a global database table defined by the Excerpt model.

Users can see a history of these database excerpts using the following menu commands:

  • Office ‣ My excerpts

  • Explorer ‣ All excerpts

class lino_xl.lib.excerpts.Excerpt

A printable document that describes some aspect of the current situation.

excerpt_type

The type of this excerpt (ForeignKey to ExcerptType).

owner

The object being printed by this excerpt. See Controllable.owner.

company

The optional company of the recipient of this excerpt. See ContactRelated.company.

contact_person

The optional contact person of the recipient of this excerpt. See ContactRelated.contact_person.

recipient

The recipient of this excerpt. See ContactRelated.recipient

language

The language used for printing this excerpt.

date
time
get_address_html()

See lino_xl.lib.contacts.mixins.ContactRelated.get_address_html().

Return the address of the recipient of this excerpt.

class lino_xl.lib.excerpts.ExcerptDetail
class lino_xl.lib.excerpts.Excerpts

Base class for all tables on Excerpt.

class lino_xl.lib.excerpts.AllExcerpts
class lino_xl.lib.excerpts.MyExcerpts
class lino_xl.lib.excerpts.ExcerptsByType
class lino_xl.lib.excerpts.ExcerptsByOwner

Shows all excerpts whose owner field is this.

class lino_xl.lib.excerpts.ExcerptsByProject

Only used if lino.core.site.Site.project_model is set.

Excerpt types

Lino also has a table of excerpt types where the system administrator can configure which types of database excerpts are available on a site. You can see this list via

  • Configuration ‣ Excerpt types

The detailed structure of this table is documented on the excerpts.ExcerptType model.

When a Lino process starts up, it automatically reads this table and installs a "Print" action on every model of a site for which there is an excerpt type.

class lino_xl.lib.excerpts.ExcerptType

The type of an excerpt. Every excerpt has a mandatory field Excerpt.excerpt_type which points to an ExcerptType instance.

name

The designation of this excerpt type. One field for every language.

content_type

The database model for which this excerpt type is to be used.

build_method

See lino.modlib.printing.mixins.PrintableType.build_method.

template

The main template to be used when printing an excerpt of this type.

body_template

The body template to use when printing an excerpt of this type.

email_template

The template to use when sending this an excerpt of this type by email.

shortcut

Optional pointer to a shortcut field. If this is not empty, then the given shortcut field will manage excerpts of this type.

See also Shortcuts. See also lino_xl.lib.excerpts.choicelists.Shortcuts.

class lino_xl.lib.excerpts.ExcerptTypes

Displays all rows of ExcerptType.

Model mixins

class lino_xl.lib.excerpts.Certifiable

Any model which inherits from this mixin becomes "certifiable".

That is:

  • it has a printed_by field and a corresponding virtual field printed which point to the excerpt that is the "definitive" ("Certifying") printout of this object.

  • It may define a list of "certifiable" fields by providing a get_certifiable_fields() method.

Usage example:

from lino_xl.lib.excerpts.mixins import Certifiable

class MyModel(dd.UserAuthored, Certifiable, dd.Duplicable):
    ...

The lino_xl.lib.excerpts.fixtures.std fixture automatically creates a certifying ExcerptType instance for every model which inherits from Certifiable.

printed

Displays information about when this certifiable has been printed. Clicking on it will display the excerpt pointed to by printed_by.

printed_by

ForeignKey to the Excerpt which certifies this instance.

A Certifiable is considered "certified" when this this is not None.

Note that this field is a nullable ForeignKey with on_delete set to SET_NULL.

on_duplicate(self, ar, master)

After duplicating e.g. a budget which had been printed, we don't want the duplicate point to the same excerpt. lino.mixins.duplicable.Duplicable.on_duplicate().

get_certifiable_fields(cls)

A class method. Expected to return a string with a space-separated list of field names. These files will automaticaly become disabled (readonly) when the document is "certified". The default implementation returns an empty string, which means that no field will become disabled when the row is "certified".

For example:

@classmethod
def get_certifiable_fields(cls):
    return 'date user title'
def get_excerpt_title(self)

A string to be used in templates as the title of the certifying document.

get_excerpt_templates(self, bm)

Return either None or a list of template names to be used when printing an excerpt controlled by this object.

class lino_xl.lib.excerpts.ExcerptTitle

Mixin for models like lino_welfare.modlib.aids.models.AidType and lino_xl.lib.courses.models.Line.

name

The designation of this row as seen by the user e.g. when selecting an instance of this model.

One field for every language.

excerpt_title

The text to print as title in confirmations. One field for every language. If this is empty, then name is used.

Shortcuts

class lino_xl.lib.excerpts.Shortcut
class lino_xl.lib.excerpts.Shortcuts

A choicelists of excerpt shortcut fields. An excerpt shortcut field is a virtual display field with actions for quickly managing, from a given database object, the excerpt for this object of a given type.

These virtual fields are being installed during pre_analyze by set_excerpts_actions().

Templates

excerpts/Default.odt

This template is the default value, used by many excerpt types in their template field. It is designed to be locally overridden by local site administrators in order to match their letter paper.

Fields

class lino_xl.lib.excerpts.BodyTemplateContentField

Actions

class lino_xl.lib.excerpts.CreateExcerpt

Create an excerpt in order to print this data record.

class lino_xl.lib.excerpts.ClearPrinted

Clear any previously generated printable document. Mark this object as not printed. A subsequent call to print will generate a new cache file.

Signal handlers

lino_xl.lib.excerpts.set_excerpts_actions()

A receiver for the lino.core.signals.pre_analyze signal.

Installs (1) print management actions on models for which there is an excerpt type and (2) the excerpt shortcut fields defined in lino_xl.lib.excerpts.choicelists.Shortcuts.

Note that excerpt types for a model with has MTI children, the action will be installed on children as well. For example a lino_avanti.lib.avanti.Client in lino_book.projects.adg can get printed either as a TermsConditions.odt or as a final report.body.html.

lino_xl.lib.excerpts.post_init_excerpt()

This is called for every new Excerpt object and it sets certain default values.

For the default language, note that the owner overrides the recipient. This rule is important e.g. for printing aid confirmations in Lino Welfare.