How-to: How to display a list of links?

How to display a list of links?

Step 1

Open json file of the pages you want in the list:

source
+--- pages
     +--- my.page.html.json

Add a new tag in the tag list (here custom-list), and a position in the list:

{
    ...
    "title": "My Page",
    ...
    "tags": ["post", "sitemap", "custom-list"],
    "custom.list.position": 10,
    ...
}

Step 2

Open the HTML layout configuration file:

source
+--- layout
     +--- html.json

Add 2 new entries with the block template path:

{
    ...
    "custom.list": "template/block/custom-list.html",
    "custom.list.link": "template/block/custom-list/link.html",
    ...
}

Step 3

Create the new block template files with the HTML content:

source
+--- template
     +--- block
          +--- custom-list.html
          +--- custom-list
               +--- link.html

The custom-list.html template contains a query expression to retrieve all the pages with custom-list tag. We limit to the 100 first pages:

<ul>
    {% custom.list.link ~ SELECT ITEMS 1-100 WHERE "custom-list" in tags ORDER BY custom.list.position asc %}
</ul>

The custom-list/link.html template contains the HTML link element:

<li><a href="{{ url }}{{ $_path }}">{{ $title }}</a></li>

Step 4 (optional)

Update the child data or template with a plugin.

Add a new plugin file named customlist.py in the plugin directory:

plugins
+--- customlist.py

Example 1: Add a class

<!-- template/block/custom-list/link.html -->

<li class="{{ custom.list.item.class }}">
    <a href="{{ url }}{{ $_path }}">{{ $title }}</a>
</li>

# plugins/customlist.py

def child_content_query_result(pages: list, args: dict) -> list:
    if args['key'] != 'custom.list.link':
        return pages
    iterator = 0
    for key, page in pages:
        pages[iterator][1]['custom.list.item.class'] = ''
        if page['_full_path'] == args['path'].lstrip('/'):
            pages[iterator][1]['custom.list.item.class'] = 'active'
        iterator += 1
    return pages

Example 2: Update the template

<!-- template/block/custom-list/current.html -->

<li><span>{{ $title }}</span></li>

# plugins/customlist.py

def child_content_query_result(pages: list, args: dict) -> list:
    if args['key'] != 'custom.list.link':
        return pages
    iterator = 0
    for key, page in pages:
        if page['_full_path'] == args['path'].lstrip('/'):
            pages[iterator][1]['_child_template'] = 'template/block/custom-list/current.html'
        iterator += 1
    return pages

Example 3: Remove an element

# plugins/customlist.py

def child_content_query_result(pages: list, args: dict) -> list:
    if args['key'] != 'custom.list.link':
        return pages
    for key, page in pages:
        if page['_full_path'] == args['path'].lstrip('/'):
            pages.remove((key, page))
    return pages