Source objects is the common interface for all things that come out of the database. There are two types of source objects:

  • Records which are pages and attachments from the contents/ folder.
  • Assets which are files and directories from the assets/ folder.

Whatever object you have in hands that comes from the database, they will at least provide a minimal useful set of API methods and properties.

Plugins can subclass source objects to come up with their own source objects if needed. In addition to that there is a special source object called the VirtualSourceObject which is more useful for plugin usage.

Virtual Source Objects

Most plugins will not have source objects that actually originate on the file system. This means that their "source" is entirely virtual. Because this is a very common situation there is a base class, the VirtualSourceObject which plugins can subclass. The constructor takes one argument which is the source record the virtual source lives below. Virtual sources are separated from the records they belong to with an at sign (@) in the path. The part after the at sign is called the “virtual path”.

For instance in the below example the canonical path for the object would be the record's path + @source. So if the record was /hello then the path would be /hello@source. The true base record it belongs to can be referenced from the record property.

from lektor.sourceobj import VirtualSourceObject
from lektor.utils import build_url

class Source(VirtualSourceObject):

    def path(self):
        return self.record.path + '@source'

    def source_content(self):
        with open(self.record.source_filename) as f:
            return f.read().decode('utf-8')

    def url_path(self):
        return build_url([self.record.url_path, 'source.txt'])

For more information see add-build-program as well as virtualpathresolver.