Websites
/
lektor-website
mirror of https://github.com/lektor/lektor-website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added docs on system fields

This commit is contained in:
Armin Ronacher 2015-12-25 22:53:37 +01:00
parent 079158a2f1
commit d3d90fe0d8
16 changed files with 255 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
content/docs/api/db/record/getitem/contents.lr Normal file
View File

@ -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']
```

11
content/docs/api/db/system-fields/alt/contents.lr Normal file
View File

@ -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.

14
content/docs/api/db/system-fields/attachment-type/contents.lr Normal file
View File

@ -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.

13
content/docs/api/db/system-fields/contents.lr Normal file
View File

@ -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).

20
content/docs/api/db/system-fields/discoverable/contents.lr Normal file
View File

@ -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.

20
content/docs/api/db/system-fields/gid/contents.lr Normal file
View File

@ -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>
```

20
content/docs/api/db/system-fields/hidden/contents.lr Normal file
View File

@ -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.

32
content/docs/api/db/system-fields/id/contents.lr Normal file
View File

@ -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>
```

23
content/docs/api/db/system-fields/model/contents.lr Normal file
View File

@ -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>
```

22
content/docs/api/db/system-fields/path/contents.lr Normal file
View File

@ -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 }} -->
```

13
content/docs/api/db/system-fields/slug/contents.lr Normal file
View File

@ -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/).

20
content/docs/api/db/system-fields/source-alt/contents.lr Normal file
View File

@ -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 }} -->
```

13
content/docs/api/db/system-fields/template/contents.lr Normal file
View File

@ -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.

6
content/docs/content/contents.lr
View File

@ -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 Some fields are plain text, others can be markdown syntax and more. These
fields become available for rendering in the template automatically. 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 dash. This means `----` will render as `---` and `-----` will render as
`----` etc. `----` 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/).

12
models/doc-page.ini
View File

@ -28,16 +28,12 @@ default = yes
checkbox_label = Show comment box checkbox_label = Show comment box
width = 1/4 width = 1/4
[fields.body]
label = Body
type = markdown
[fields.type] [fields.type]
label = Technical Type label = Technical Type
type = select type = select
description = Of what general type this doc page is. If not set, it's a normal doc page. 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 choices = class, function, method, property, operator, filter, cmdlet, event, type, sysfield
choice_labels = Class, Function, Method, Property, Operator, Filter, Commandlet, Event, Field Type choice_labels = Class, Function, Method, Property, Operator, Filter, Commandlet, Event, Field Type, System Field
width = 1/2 width = 1/2
[fields.module] [fields.module]
@ -61,3 +57,7 @@ description = An optional template variable if it exists there as such.
[fields.version_added] [fields.version_added]
label = Added in version label = Added in version
type = string type = string
[fields.body]
label = Body
type = markdown

2
templates/macros/docs.html
View File

@ -11,7 +11,7 @@
<i class="glyphicon glyphicon-console"></i> <i class="glyphicon glyphicon-console"></i>
{%- elif page.type == 'event' -%} {%- elif page.type == 'event' -%}
<i class="glyphicon glyphicon-flash"></i> <i class="glyphicon glyphicon-flash"></i>
{%- elif page.type == 'type' -%} {%- elif page.type == 'type' or page.type == 'sysfield' -%}
<i class="glyphicon glyphicon-pencil"></i> <i class="glyphicon glyphicon-pencil"></i>
{%- else -%} {%- else -%}
<i class="glyphicon glyphicon-list-alt"></i> <i class="glyphicon glyphicon-list-alt"></i>