Dynamic List/Menu Extension Draft

[taufik-nurrohman]

This is a dynamic list/menu extension documentation initiation.

File/Folder

Extension name will be list. This extension will create .\lot\list folder automatically to store list data as a YAML file. Those files then can be used by the layout developer to generate configurable navigation bar or link list to be placed in sidebar and footer:

.\
└── lot\
    └── list\
        ├── blog-roll.yaml
        ├── links.yaml
        ├── nav.yaml
        └── …

Data

A list file contains data like this:

---
title: List Title
description: List description.
list:
- title: Item 1
  decription: Optional list item description.
  link: 'https://example.com#foo'
- title: Item 2
  link: 'https://example.com#bar'
- title: Item 3
  link: 'https://example.com#baz'
- title: Item 4
  link: 'https://example.com#baz'
  list:
  - title: Item 4.1
  - title: Item 4.2
  - title: Item 4.3
    link: 'https://example.com#qux'
...

Without a link attribute, list item will be rendered as plain text.

A non-array value in a list item will be treated as the title value:

---
list:
- Item 1
- Item 2
- Item 3
...

List items order will be arranged as-is. A sortable graphical user interface can be developed to help managing those items.

List can also be sourced from a page. That way, items can be generated automatically:

---
title: List Title
description: List description.
list:
- from: '/lot/page/courses.page'
...

The value of from attribute is a private file path relative to the PATH constant value. When parsed, the source value will be resolved into a valid file path and then every data parsed from that path will be populated to the list item automatically as the default value.

Other data stored directly in the list item will override the generated list data. For example, the title and description value below will override the title and description value from the page file:

---
list:
- title: Home
  url: '/'
- from: '/lot/page/courses.page'
  title: Courses
  description: List of the available courses.
...

If from file has page children, those page files will be parsed as well and then the generated data will be populated to the list attribute. This is very useful for making automatic multi-level navigation. To limit the number of sub-menu generated, users can add a chunk attribute. And to limit the depth of automatic sub-menu generation, users can add deep attribute, just like in the built-in site page-ing system:

---
list:
- title: Home
  url: '/'
- from: '/lot/page/courses.page'
  chunk: 10  # maximum sub-menu to show
  deep: 2  # maximum sub-menu nesting
  sort: [+1, title]  # sort sub-menu by `title`
...

List item visibility can be set through the source file itself. Lets say, we have a page children of .\lot\page\courses.page stored as .\lot\page\courses\chemistry.page. By default, this page will be included as a sub-menu for “Courses”. But users can exclude it by adding skip attribute with true value to the “Chemistry” page:

---
title: Chemistry
description: Chemistry online course.
type: Markdown
skip: true
...

If skip attribute is not set, the value will be determined by the current file extension. If its extension is .page, it will be treated as a value false, if its extension is .archive, it will be treated as a value true. Extension .draft will always be ignored.

$data = extend([
    'skip' => 'page' !== pathinfo($path, PATHINFO_EXTENSION)
], $data);

Layout

A base list layout can be added. The HTML markup generation is up to the layout developer, but I encourage you to only generate a heading element (to render the title value), a paragraph (to render the description value) and a list (to render the list data either as ordered list or as unordered list). This extension should only provide the data.

Calling the default list layout can be done like this. Data are provided via array:

<?= self::list([
    'title' => 'Blog Roll',
    'description' => 'My friends blog.',
    'list' => [
        0 => [
            'title' => 'Blog 1',
            'link' => 'https://example.com'
        ],
        1 => [
            'title' => 'Blog 2',
            'link' => 'https://example.com'
        ]
    ]
]); ?>

If the first argument is a string, then it will be treated as a list source ID, which is the list file name:

<nav class="nav">
  <!-- Loads `.\lot\list\nav.yaml` -->
  <?= self::list('nav'); ?>
</nav>

<section class="widget">
  <!-- Loads `.\lot\list\blog-roll.yaml` -->
  <?= self::list('blog-roll'); ?>
</section>

Use the second argument to override the list data:

<section class="widget">
  <?= self::list('blog-roll', [
      'title' => 'Blog List',
      'description' => 'These are my favorite blog.'
  ]); ?>
</section>

The problem is that list is a reserved keyword. I have not been tested it. But in PHP 8, it should be possible to use reserved keywords as PHP methods:

• https://wiki.php.net/rfc/context_sensitive_lexer
• https://www.php.net/ChangeLog-7.php#7.0.0

Panel

A sortable user interface is needed to render the list data in Panel. A dialog window feature may be needed as an editor for the list item.

For better user experience in selecting file path to fill the from attribute, an AJAX powered fuzzy finder interface ^{1 2} may be needed. So yeah, this is a complex feature.

Footnotes

1. https://github.com/loilo/Fuse ↩

2. https://github.com/krisk/fuse ↩