From 249d551b034be7a644cfa799d4a214fb5333d9ff Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sat, 26 Dec 2015 14:33:44 +0100 Subject: [PATCH] More docs for system fields --- .../docs/content/system-fields/contents.lr | 61 +++++++++++++++++++ content/docs/models/contents.lr | 5 +- content/docs/models/selection/contents.lr | 23 +++++++ 3 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 content/docs/content/system-fields/contents.lr create mode 100644 content/docs/models/selection/contents.lr diff --git a/content/docs/content/system-fields/contents.lr b/content/docs/content/system-fields/contents.lr new file mode 100644 index 00000000..0b790dd8 --- /dev/null +++ b/content/docs/content/system-fields/contents.lr @@ -0,0 +1,61 @@ +title: System Fields +--- +summary: Brief overview of the system fields in Lektor. +--- +body: + +In addition to the fields that are defined through the [Data Model +:ref](../../models/) there are a lot of fields that come directly from Lektor. +They can be easily recognized because they are prefixed by a leading underscore +(`_`). + +These fields influence how Lektor treats pages and attachment. Here we will +just go over the most important ones but for a full list you can have a look +[at the API Documentation :ref](../../api/db/system-fields/). + +## `_hidden` + +This field is a boolean value and controls if a page is hidden or not. If a +page is hidden all of it's children will automatically also be hidden. A page +that is hidden will not be processed by Lektor's build system. This means such +pages can be discovered through the query API but they are not rendered +themselves. This is useful for situations where you want to have information +stored but not rendered. This is for instance used to [implement Single-Page +websites :ref](../../guides/single-page/). + +*To read more read [the field documentation :ref](../../api/db/system-fields/hidden/).* + +## `_discoverable` + +This fields in many ways is similar to `_hidden` but instead makes a page +be only hidden from queries. In particular this means that it will still be +processed and built, but that it becomes harder for code to reference it. +Pages that are not set to discoverable can only be found through queries if +they are [explicitly included :ref](../../api/db/query/include-undiscoverable/). + +!! This field was added in Lektor 2.0. In earlier versions this feature is +unavailable. + +*To read more read [the field documentation :ref](../../api/db/system-fields/discoverable/).* + +## `_model` + +This key sets the [Data Model :ref](../../models/) that is used for the record. +If not set this defaults to one of different choices depending on configuration +or name. Parent models can pre-define models for children which is the used if +this key is not set. If not set this will be picked up by an algorithm. +See [Default Model Selection :ref](../../models/selection/) for more information. + +*To read more read [the field documentation :ref](../../api/db/system-fields/model/).* + +## `_slug` + +This field can override the default URL slug. For more information about this +feature see [URLs and Slugs :ref](../urls/). + +## `_template` + +This field can be used to override the default template selection which is +just the model name with the `.html` extension. + +*To read more read [the field documentation :ref](../../api/db/system-fields/template/).* diff --git a/content/docs/models/contents.lr b/content/docs/models/contents.lr index 7b93310c..c8bc06be 100644 --- a/content/docs/models/contents.lr +++ b/content/docs/models/contents.lr @@ -15,8 +15,9 @@ easier later to generate beautiful looking HTML. 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, the model with the name `page` will be -used. So having a model with that name is always a good idea. +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 :ref](selection/). Here is an example of a very basic model (`models/page.ini`): diff --git a/content/docs/models/selection/contents.lr b/content/docs/models/selection/contents.lr new file mode 100644 index 00000000..d50d055b --- /dev/null +++ b/content/docs/models/selection/contents.lr @@ -0,0 +1,23 @@ +title: Default Model Selection +--- +summary: Explains how Lektor decides on the model to use. +--- +body: + +When Lektor encounters a content file it needs to decide which data model to +use for figuring out how to handle the fields. In the ideal case the content +file contains `_model` field which will point explicitly to a model. However +if a model was not defined it's picked automatically. + +Lektor will attempt to load a few models and will pick the first that exists. +If no model exists at all then Lektor calls back to the special `none` model +which is empty other than for system fields. + +1. If a model is defined for children by the parent model then it's used. + For more information about this feature see [Children & Pagination + :ref](../children/). +2. The ID of the page is attempted as model name next. +3. If it still does not match anything, it will try the default `page` + model. +4. If that also does not match, it falls back to the special `none` model + which is always empty.