chore: update examples and Readme

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
 <p>Custom field date: {{this.date}}</p>
 <ul>
-{%- for child, extras in this.children.items() -%}
-{%- set etxra = (extras|first).tags_in_page %}
-<li>{{etxra|length}} tags on page "{{child.path}}": {{etxra}}</li>
+{%- for child in this.children %}
+<li>page "{{child.path}}" with tags: {{child.tags}}</li>
 {%- endfor %}
 </ul>
 ```
@@ -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') %} 
 <a href="{{ x|url }}">({{ x.group }})</a>
 {%- 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).