diff --git a/examples/README.md b/examples/README.md index 21fc787..742611a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -53,6 +53,9 @@ template = example-config.html split = ' ' enabled = True +[testA.children] +order_by = -title, body + [testA.fields] title = "Tagged: " ~ this.group @@ -86,7 +89,11 @@ The configuration parameter are: You can have multiple listeners, e.g., one for `/blog/` and another for `/projects/`. Just create as many custom attributes as you like, each having its own section. -There are two additional config mappings, `.fields` and `.key_map`. +The `.children` subsection currently has a single config field: `order_by`. +The usual [order-by](https://www.getlektor.com/docs/guides/page-order/) rules apply (comma separated list of keys with `-` for reversed order). +The order-by key can be anything of the page attributes of the children (the same model where you added the grouping key). + +There are two additional config subsections, `.fields` and `.key_map`. Key-value pairs in `.fields` will be added as attributes to your grouping. You can access them in your template (e.g., `{{this.title}}`). All of the `.fields` values are evaluted in a jinja context, so be cautious when using plain strings. @@ -97,13 +104,11 @@ The built-in field attributes are: - `key`: slugified group value, e.g., "a-title" - `slug`: url path after root node, e.g. "config/a-title.html" (can be `None`) - `record`: parent node, e.g., `Page(path="/")` -- `children`: dictionary of `{record: extras}` pairs -- `first_child`: first page -- `first_extra`: first extra +- `children`: the elements of the grouping (`Record` type) - `config`: configuration object (see below) Without any changes, the `key` value will just be `slugify(group)`. -However, the other mapping `.key_map` will replace `group` with whatever replacement value is provided in the `.key_map` and then slugified. +However, the other mapping `.key_map` will replace `group` with whatever replacement value is provided in the `.key_map` and then slugify. You could, for example, add a `C# = c-sharp` mapping, which would otherwise just be slugified to `c`. This is equivalent to `slugify(key_map.get(group))`. @@ -117,6 +122,7 @@ The `config` attribute contains the values that created the group: - `dependencies`: path to config file (if initialized from config) - `fields`: raw values from `TestA.fields` - `key_map`: raw values from `TestA.key_map` +- `order_by`: list of key-strings from `TestA.children.order_by` In your template file you have access to the attributes, config, and children (pages): @@ -155,7 +161,7 @@ def on_groupby_before_build_all(self, groupby, builder, **extra): # Yield groups value = args.field # type: list # since model is 'strings' type for tag in value: - yield tag, {'tags_in_page': value} + yield tag ``` This example is roughly equivalent to the config example above – the parameters of the `groupby.add_watcher` function correspond to the same config parameters. @@ -183,9 +189,8 @@ field = args.record[k.fieldKey].blocks[k.flowIndex].get(k.flowKey) ``` The callback body **can** produce groupings but does not have to. -If you choose to produce an entry, you have to `yield` a string or tuple pair `(group, extra-info)`. +If you choose to produce an entry, you have to `yield` the group name (string). `group` is slugified (see above) and then used to combine & cluster pages. -The `extra-info` (optional) is passed through to your template file. You can yield more than one entry per source. Or ignore pages if you don't yield anything. @@ -194,9 +199,8 @@ The template file can access and display the `extra-info`: ```jinja2

Custom field date: {{this.date}}

``` @@ -279,7 +283,7 @@ This is useful if you do not want to create subpages but rather an index page co This can be done in combination with the next use-case: ```jinja2 -{%- for x in this|vgroups(keys=['TestA', 'TestB'], fields=[], flows=[], recursive=True)|unique|sort %} +{%- for x in this|vgroups(keys=['TestA', 'TestB'], fields=[], flows=[], recursive=True, order_by='group') %} ({{ x.group }}) {%- endfor %} ``` @@ -290,3 +294,7 @@ The keys (`'TestA', 'TestB'`) can be omitted which will return all groups of all The `fields` and `flows` params are also optional. With these you can match groups in `args.key.fieldKey` and `args.key.flowKey`. For example, if you have a “tags” field and an “additional-tags” field and you only want to show one in a preview. + +`order_by` can be either a comma-separated string or a list of keys. +Again, same [order-by](https://www.getlektor.com/docs/guides/page-order/) rules apply as for any other Lektor `Record`. +Only this time, the attributes of the `GroupBy` object are used for sorting (including those you defined in the `.fields` subsection). diff --git a/examples/configs/groupby.ini b/examples/configs/groupby.ini index 5871b1b..eca3f29 100644 --- a/examples/configs/groupby.ini +++ b/examples/configs/groupby.ini @@ -5,6 +5,9 @@ slug = config/{key}.html template = example-config.html split = ' ' +[testA.children] +order_by = -title, body + [testA.fields] title = "Tagged: " ~ this.group diff --git a/examples/packages/simple-example/lektor_simple.py b/examples/packages/simple-example/lektor_simple.py index 3610da8..f047b64 100644 --- a/examples/packages/simple-example/lektor_simple.py +++ b/examples/packages/simple-example/lektor_simple.py @@ -20,7 +20,7 @@ class SimpleGroupByPlugin(Plugin): # Yield groups value = args.field # type: list # since model is 'strings' type for tag in value: - yield tag, {'tags_in_page': value} + yield tag # Everything below is just for documentation purposes page = args.record # extract additional info from source fieldKey, flowIndex, flowKey = args.key # or get field index diff --git a/examples/templates/example-simple.html b/examples/templates/example-simple.html index b9b021f..c52be5b 100644 --- a/examples/templates/example-simple.html +++ b/examples/templates/example-simple.html @@ -2,8 +2,7 @@

This is: {{this}}

Custom field date: {{this.date}}

\ No newline at end of file diff --git a/examples/templates/page.html b/examples/templates/page.html index 065921f..4bc9d0a 100644 --- a/examples/templates/page.html +++ b/examples/templates/page.html @@ -20,7 +20,7 @@ main { margin: 3em; }