Added docs on system fields
This commit is contained in:
Armin Ronacher
parent
079158a2f1
commit
d3d90fe0d8
|
|
@ -0,0 +1,22 @@
|
|||
title: []
|
||||
---
|
||||
summary: Looks up a field from the type.
|
||||
---
|
||||
type: operator
|
||||
---
|
||||
body:
|
||||
|
||||
The “get-item” operator is used to look up a field from a record. Within
|
||||
templates attribute access automatically falls back to this operator which
|
||||
is why you can typically access `foo.bar` instead of `foo['bar']` unless a
|
||||
conflict with a record property exists.
|
||||
|
||||
All available fields can be accessed this way (model defined fields as well
|
||||
as system fields which are prefixed by an underscore).
|
||||
|
||||
## Example
|
||||
|
||||
```python
|
||||
for child in this.children:
|
||||
print 'ID: %s' % child['_id']
|
||||
```
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
title: _alt
|
||||
---
|
||||
summary: The alt for this record.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This field points to the [Alternative :ref](../../../../content/alts/) of
|
||||
the page. This should be considered as an internal field that is exposed
|
||||
through the [alt :ref](../../obj/alt/) source object property instead.
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
title: _attachment_type
|
||||
---
|
||||
summary: An indication of the attachment type.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This indicates the type of the attachment. Currently only a small set of
|
||||
attachments is detected. The most useful attachment type is `image` which
|
||||
identifies images. The attachments are detected by the file extension.
|
||||
|
||||
!!!! This feature in many ways does not entirely work as you would expect
|
||||
and should be taken is something that will improve in future versions.
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
title: System Fields
|
||||
---
|
||||
summary: The complete list of system fields in Lektor
|
||||
---
|
||||
body:
|
||||
|
||||
All records have a few system fields available in addition to the fields
|
||||
defined by the data model. These fields are always there and control internal
|
||||
behavior in Lektor. They are prefixed by an underscore to separate them
|
||||
from the fields a model defines.
|
||||
|
||||
Many system fields are hidden from the admin panel but some can be changed
|
||||
there (`_template`, `_hidden`, and a few others).
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
title: _discoverable
|
||||
---
|
||||
summary: Controls if this page is picked up by collection queries by default.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
version_added: 2.0
|
||||
---
|
||||
body:
|
||||
|
||||
By default any non hidden page is returned from `.children` on iteration. This
|
||||
field can be set to `no` to hide a page from such default queries. This
|
||||
implicitly hides a page for most template operations but Lektor will still
|
||||
build it. This for instance is very useful for draft blog posts. If a post is
|
||||
set to not being discoverable it will be hidden from the blog index without
|
||||
further custom template code, but someone who knows the URL can still find it.
|
||||
|
||||
This is also particularly useful to hide special pages such as `sitemap.xml`
|
||||
which would otherwise cause problems because generic code might not expect
|
||||
it.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
title: _gid
|
||||
---
|
||||
summary: A globally unique ID of the page.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
The `_gid` is the MD5 hashed version of the page's [`_path`](../path/). This
|
||||
is useful in situations where a stable ID is needed that follows a certain
|
||||
format. For instance it can come in useful when a ID is needed for a DOM
|
||||
element.
|
||||
|
||||
## Example
|
||||
|
||||
```html+jinja
|
||||
<body class="page-{{ this._gid }}">
|
||||
...
|
||||
</body>
|
||||
```
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
title: _hidden
|
||||
---
|
||||
summary: Controls if the page should be built or not.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This field controls if Lektor should process the page into a build artifact.
|
||||
By default each page is built into a build artifact (HTML page) and each
|
||||
attachment is processed. This can be prevented by setting `_hidden` to `yes`.
|
||||
|
||||
This also automatically applies to all children of a page unless they
|
||||
forcefully override this setting.
|
||||
|
||||
This is useful for more advanced setups like [Single Page Applications
|
||||
:ref](../../../../guides/single-page/).
|
||||
|
||||
Hidden pages are automatically also removed from the `.children` property
|
||||
of records but stay available for querying via the pad.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
title: _id
|
||||
---
|
||||
summary: The local identifier of a record.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
Each record has an `_id`. This ID is basically a form of the filename.
|
||||
Depending on if you are looking at an attachment or a page the rules are
|
||||
slightly different.
|
||||
|
||||
For pages the ID is the name of the folder. So if you have a page called
|
||||
`docs/overview/contents.lr` then `_id` is `overview`. If you have however
|
||||
an attachment named `docs/overview/screenshot.jpg` the `_id` will be the
|
||||
filename of the attachment: `screenshot.jpg`.
|
||||
|
||||
Note that IDs are not globally unique! There is also the `_path` which is
|
||||
the entire path if the record.
|
||||
|
||||
The `_id` is automatically set and cannot be overridden.
|
||||
|
||||
## Example
|
||||
|
||||
```html+jinja
|
||||
<ul class="nav">
|
||||
{% for item in site.query('/projects') %}
|
||||
<li{% if item._id == this._id %} class="active"{%
|
||||
endif %}>{{ item.name }}</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
```
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
title: _model
|
||||
---
|
||||
summary: The model the record uses for its fields.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This field selects the model that should be used for non-system fields. In
|
||||
many situations the model is picked automatically but for equally many
|
||||
situations it needs to be selected manually.
|
||||
|
||||
This field is most useful for filtering when operating on mixed collections.
|
||||
|
||||
## Example
|
||||
|
||||
```html+jinja
|
||||
<ul class="projects">
|
||||
{% for child in this.children.filter(F._model == 'project') %}
|
||||
<li>{{ child.name }}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
```
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
title: _path
|
||||
---
|
||||
summary: The full path of the record.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
The `_path` is the more complete version of the [`_id`](../id/). It contains
|
||||
the entire path of records that are the parents of a record. So if you have a
|
||||
record named `docs/api/db/contents.lr` the `_id` would be `db` but the `_path`
|
||||
would be `docs/api/db`.
|
||||
|
||||
The path can be used to uniquely identify a page but for that purpose the
|
||||
[`_gid`](../gid/) can also be used which is a hashed hexadecimal version of
|
||||
the page.
|
||||
|
||||
## Example
|
||||
|
||||
```html+jinja
|
||||
<!-- generated from {{ this._path }} -->
|
||||
```
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
title: _slug
|
||||
---
|
||||
summary: The URL slug of the record.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This field defines the URL slug of the record. If not set it defaults to
|
||||
either the `_id` or an expansion of what the parent defines for all children.
|
||||
|
||||
For more information about this refer to [URLs and Slugs
|
||||
:ref](../../../../content/urls/).
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
title: _source_alt
|
||||
---
|
||||
summary: The alt from the source of the record.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This field points to the true source [Alternative
|
||||
:ref](../../../../content/alts/) of the page. This primarily exists internally
|
||||
to support the builder. In particular the difference to the `_alt` field is
|
||||
that this one will indicate if an alt falls back to a different alternative.
|
||||
At present pages can only fall back to the `_primary` alternative which will
|
||||
be reflected by this field.
|
||||
|
||||
## Example
|
||||
|
||||
```html+jinja
|
||||
<!-- generated from language {{ this._source_alt }} -->
|
||||
```
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
title: _template
|
||||
---
|
||||
signature:
|
||||
---
|
||||
summary: Selects the template for the page.
|
||||
---
|
||||
type: sysfield
|
||||
---
|
||||
body:
|
||||
|
||||
This field sets the template that Lektor uses for rendering. It defaults to
|
||||
model name + `.html`. If the `_model` is `page` the name of the template
|
||||
will be `page.html`. In some situations it makes sense to override this.
|
||||
|
|
@ -85,6 +85,10 @@ the key. The format of each field is specific to how the model is configured.
|
|||
Some fields are plain text, others can be markdown syntax and more. These
|
||||
fields become available for rendering in the template automatically.
|
||||
|
||||
**Tip:** If you want to use `---` itself in the document text, just add another
|
||||
!!! If you want to use `---` itself in the document text, just add another
|
||||
dash. This means `----` will render as `---` and `-----` will render as
|
||||
`----` etc.
|
||||
|
||||
Fields prefixed with an underscore are so-called system fields. They are
|
||||
provided by Lektor and customize behavior within Lektor. For a list of
|
||||
available fields see [System Fields :ref](../api/db/system-fields/).
|
||||
|
|
|
|||
|
|
@ -28,16 +28,12 @@ default = yes
|
|||
checkbox_label = Show comment box
|
||||
width = 1/4
|
||||
|
||||
[fields.body]
|
||||
label = Body
|
||||
type = markdown
|
||||
|
||||
[fields.type]
|
||||
label = Technical Type
|
||||
type = select
|
||||
description = Of what general type this doc page is. If not set, it's a normal doc page.
|
||||
choices = class, function, method, property, operator, filter, cmdlet, event, type
|
||||
choice_labels = Class, Function, Method, Property, Operator, Filter, Commandlet, Event, Field Type
|
||||
choices = class, function, method, property, operator, filter, cmdlet, event, type, sysfield
|
||||
choice_labels = Class, Function, Method, Property, Operator, Filter, Commandlet, Event, Field Type, System Field
|
||||
width = 1/2
|
||||
|
||||
[fields.module]
|
||||
|
|
@ -61,3 +57,7 @@ description = An optional template variable if it exists there as such.
|
|||
[fields.version_added]
|
||||
label = Added in version
|
||||
type = string
|
||||
|
||||
[fields.body]
|
||||
label = Body
|
||||
type = markdown
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
<i class="glyphicon glyphicon-console"></i>
|
||||
{%- elif page.type == 'event' -%}
|
||||
<i class="glyphicon glyphicon-flash"></i>
|
||||
{%- elif page.type == 'type' -%}
|
||||
{%- elif page.type == 'type' or page.type == 'sysfield' -%}
|
||||
<i class="glyphicon glyphicon-pencil"></i>
|
||||
{%- else -%}
|
||||
<i class="glyphicon glyphicon-list-alt"></i>
|
||||
|
|
|
|||
Loading…
Reference in New Issue