Data Modelling

What makes Lektor so powerful is the ability to model your data and to then use this data to generate the final results. Getting this part right will make it easier later to generate beautiful looking HTML.

Models

Models are the blueprints for your pages. They define which fields exist and what goes into them. Models are stored in the models folder in your project and are basic UTF-8 encoded INI files. Models can have any name but if no model has been explicitly selected, a default model will be selected. For most situations this will be the model with the name page. Detailed information can be found under Default Model Selection.

Here is an example of a very basic model (models/page.ini):

[model]
name = Page
label = {{ this.title }}

[fields.title]
label = Title
type = string
size = large

[fields.body]
label = Body
type = markdown

In this particular case, we have a model with the id page (as defined by the filename) and a name Page which will appear like that in the UI. Pages that use this model will use the template expression {{ this.title }} to be displayed in the UI. In this case, it uses the title of the page.

There are two fields defined: a title and a body. The former is just an unformatted string which is shown larger in the UI (size = large) and the latter uses markdown for rendering. This will give it a text area in the admin panel.

Fields

Fields for models are ordered in the UI in the order they appear in the model. Most options in the field are specific to the type that is selected, but some are the same for all of them.

Fields not only define the behavior of the data (for instance strings and integers are sorted differently) but also how it's shown in the UI and what can be done with it in general.

The following options are used for all types:

  • label: the label for the field. This is shown in the UI in larger letters
  • description: an optional string that provides some description for the field that is shown in the UI to give a bit more explanation.
  • addon_label: an optional string that is supported by all types that are rendered as an input field. This string is shown as an UI label on the right side of the input field to give it more context. For instance, it can be used to clarify units of a field (pixel, percent etc.).
  • width: defines the width of the input in the admin as a fraction. For instance 1/4 sets it to a quarter of the width, 1/2 to a half etc.
  • size can be set to normal, small or large to affect the size a field is rendered in the admin UI.
  • type: defines the type of the field. Depending on the type more options can become available.

There are many different field types that are available and they are documented extensively in the types documentation.

Model Options

Models have the following options that can customize the model itself:

  • name: the name of the model itself. Usually a more capitalized form of the filename which is the ID of the model.
  • label: a template expression that should be used for pages that use this model. Typically this expression refers to the title but not always. For instance blog posts might also want to refer to the date.
  • hidden: a boolean value that indicates if the model should be hidden from the UI or not. If set to yes then new pages cannot select this model. This is very useful for models that are implied through configuration.
  • protected: if a model is set to protected then all of its instances cannot be deleted once created.
  • inherits: if you want to inherit all fields and model option settings from another model then this can be set to the name of another model.

In addition to that, there are some configuration sections in the model file that can customize more behavior.

Comments