{collection}

Reads a folder of Markdown files from _content/ and repeats its content once per file, the front matter as fields.

Database Tag pairs

Syntax 

{collection 'name'} ... {/collection}
{collection 'name', slug=$slug} ... @else@ ... {/collection}
{collection 'name', html} ... {/collection}

Parameters

name
The collection: the directory _content/name/, looked up like a _data file - the page's directory first, then its parents, then _common.

Options

slug
Only the file of that name (without .md). A slug that names no file, or is not a plain file name, gives no rows - the @else@ branch.
html
Bare option: raw HTML in the Markdown bodies is let through. By default it is escaped.

Description

{collection 'blog'} turns the Markdown files of _content/blog/ into rows - a small flat-file CMS. Each .md file is one occurrence: the keys of its front matter (YAML between two --- lines) are its fields, and three more are added: slug (the file name without .md), body (the Markdown written as HTML by the {markdown} renderer) and source (the Markdown text as it was).

The body is HTML, so print it raw with {!body} - {$body} would escape it. Raw HTML written in the Markdown itself is escaped unless the tag has the html option, which is meant for files the site's own authors write.

The rows come in file name order; every handling option works on them - sort='date DESC', first=10, where='$draft ne 1', page= with a {pager}. For the page that shows one post, slug=$slug reads that file alone; a slug that names no file gives no rows, so the @else@ branch can say "not found".

The directory is looked up like a _data file: the page's own directory, then each parent up to the application root, then the _common application. A collection without a name, or one that has no directory, is an error under the strict check. From PHP, padCollection ( 'blog' ) gives the same rows.

Examples

A folder of Markdown as rows

Each file of _content/collectionBooks/ is a row - its front matter as fields, its text as body.

Templateexamples/collection/1-list.pad 
{collection 'collectionBooks', sort='year'}
  <h4>{$title} <small>({$year}, {$author})</small></h4>
  {!body}
{/collection}
Resultopen alone

The Hobbit (1937, J.R.R. Tolkien)

A comfortable hobbit is talked into an adventure - and a dragon.

Solaris (1961, Stanisław Lem)

A station orbits an ocean that may be thinking.

  • a planet
  • a mystery

Dune (1965, Frank Herbert)

A desert planet, a spice everyone wants and a family caught in the middle.

One file by its slug

slug= picks a single file; a slug that names none shows the else branch.

Templateexamples/collection/2-slug.pad 
{collection 'collectionBooks', slug='solaris'}
  <p><strong>{$title}</strong> - file {$slug}.md</p>
  <pre>{$source}</pre>
{/collection}
{collection 'collectionBooks', slug='missing'}
  <p>{$title}</p>
@else@
  <p>There is no book named missing.</p>
{/collection}
Resultopen alone

Solaris - file solaris.md 

A station orbits an ocean that may be thinking.

- a planet
- a mystery

There is no book named missing.

With handling options

where, sort and first work on the rows as on any data.

Templateexamples/collection/3-options.pad 
<ul>
  {collection 'collectionBooks', where='$year lt 1965', sort='title DESC', first=1}
    <li>{$title} - {$year}</li>
  {/collection}
</ul>
Resultopen alone
  • The Hobbit - 1937

See also

  • {markdown} Renders its content, or the value of its parameter, as Markdown and writes the HTML.
  • {data} Turns its content - JSON, XML, YAML, CSV, a list or a range - into a named data set for a later tag to iterate.
  • {array} Runs a SQL query on the application database and repeats its content once per row.
  • {files} Scans a directory and iterates its entries, with path, file, ext, item and dir for each.