Edit this page on Github

Spress >= 2.0

Data sources can load data from certain locations like filesystem or database. Every data source must extends AbstractDataSource. Data loaded from data sources are called items. There is three type of them: content, layout and include. Items must implements ItemInterface.

Items

Items are the basic building blocks and consist of content and metadata attributes. Each item has an identifier and a set of attributes (metadatas). Attributes consist of key-value array. FilesystemDataSource implementation is able to load attributes located at the Front matter or in a separeted metadata file which are stored in YAML format.

How to create an item?

use Yosymfony\Spress\Core\DataSource\Item;

$item = new Item('Test of content', 'myPage.md', ['title' => 'My page']);

Item is an implementation of ItemInterface. First argument is the content, second is the identifier and last one are the attributes.

To get and set attributes uses getAttributes and setAttributes methods:

use Yosymfony\Spress\Core\DataSource\Item;

$item = new Item('Test of content', 'myPage.md', ['title' => 'My page']);

$attributes = $item->getAttributes();
$attributes['parmalink'] = '/my-page'

$item->setAttributes($attributes);

Setting the paths

Item's paths are organized around snapshots that define a path at a specific point of compilation a site. An item without relative path snapshot will be compiled but not stored by the data writer.

Predefined snapshots:

  • relative: defines the relative route of the item in the site. This is an important snapshot because it will be used as the basis for generating the permalink.
  • permalink: generated automatically by permalink generator. Constains the relative URL.
  • source: in case of binary content, contains the real path to the item. This improve the performance because the file will be copied instead of dumping the content from memory.
  • last: the most recent path snapshot.
use Yosymfony\Spress\Core\DataSource\Item;

$item = new Item('Test of content', 'about.md', []);
$item->setPath('help/about.md', 'relative');
$item->getPath('relative');

First argument of setPath method is the path and the second argument is the snapshot's name. getPath method recovers the path of associated to a snapshot. If you call to getPath method without arguments you will get the last snapshot.

Predefined snapshots are defined as constants:

  • ItemInterface::SNAPSHOT_PATH_RELATIVE
  • ItemInterface::SNAPSHOT_PATH_PERMALINK
  • ItemInterface::SNAPSHOT_PATH_LAST
  • ItemInterface::SNAPSHOT_PATH_SOURCE

Binary content

If the extension of the item is included in the site configuration’s text_extension attribute, it is considered to be textual. Otherwise it will be considered as binary. More details about text_extension value.

use Yosymfony\Spress\Core\DataSource\Item;

$item = new Item('', 'assets/img/header.png', [], true);
$item->setPath('assets/img/header.png', 'relative');
$item->setPath('assets/img/header.png', 'source');  

The last one argument of the constructor indicates that content is binary. At the prior example, the items has defined relative and source snapshots. This mean that FilesystemDataWriter will copied from source path to relative path at ./build folder.

Binary items without relative path snapshot

use Yosymfony\Spress\Core\DataSource\Item;

$binaryContent = $assetsManager->getImage('logo');

$item = new Item($binaryContent, 'assets/img/header.png', [], true);
$item->setPath('assets/img/header.png', 'relative');

In this case, FilesystemDataWriter will dump the content from memory to the file at the moment of storing the item.

Type of items

There is three type of item:

  • content: (default) regular content like post or pages.
  • layout: indicates how to organize the content.
  • include: reusable content.

The Item's constructor accept a fifth argument for the type:

use Yosymfony\Spress\Core\DataSource\Item;

$layoutItem = new Item('{{ page.content }}', 'page.html', [], false, ItemInterface::TYPE_LAYOUT);

Item types are defined as constants:

  • ItemInterface::TYPE_ITEM
  • ItemInterface::TYPE_LAYOUT
  • ItemInterface::TYPE_INCLUDE

Content snapshots

A snapshot is the compiled content at a specific point during the compilation process. Following, a list of predefined content snapshots, mostly of they are generated automatically:

  • raw: the content right before actual compilation is started.
  • after_convert: the content right after converter was applied.
  • after_render_blocks: the content right after rederizer was applied without layouts.
  • after_render_page: the content right after rederizer was applied with layouts.
  • last: the most recent compiled content.

Predefined snapshots are defined as constants:

  • ItemInterface::SNAPSHOT_RAW
  • ItemInterface::SNAPSHOT_LAST
  • ItemInterface::SNAPSHOT_AFTER_CONVERT
  • ItemInterface::SNAPSHOT_AFTER_RENDER_BLOCKS
  • ItemInterface::SNAPSHOT_AFTER_RENDER_PAGE

Usually, binary items don't have content snapshots.

The below example show you how to get the content:

use Yosymfony\Spress\Core\DataSource\Item;

$item = new Item('The content', 'index.html');

$a = $item->getContent();
$b = $item->getContent('last');
$c = $item->getContent('raw');

$item->setContent('New content', 'custom-snapshot');

In this case, $a = $b = $c. When you create a new item initial content is available at raw and last snapshots. By default getContent method returns the last snapshot.

To set content uses setContent method. The first argument is the content and the last one is the snapshot name.

Relationships

Spress >= 2.1

The relationships between items are useful for setting a set of related items, such as set of related posts to a post or simply previous and next items in a sorted collection.

use Yosymfony\Spress\Core\DataSource\Item;

$item = new Item('Test of content', 'myPage.md');

$relationships = $item->getRelationshipCollection();
$relationships->add('related', $itemPage1);
$relationships->add('related', $itemPage2);

// items of 'related' relationship:
$items = $relationships->get('related');

The getRelationshipCollection method returns a RelationshipCollection object.

Spress adds prior and next relationships to each item belonging to a sorted collection referring to the previous item and next item in the collection.

Predefined data sources

FilesystemDataSource

Spress comes with FilesystemDataSource to load your site. Data sources are defined at data_source option at site configuration file:

data_sources:
  filesystem:
    class: 'Yosymfony\Spress\Core\DataSource\Filesystem\FilesystemDataSource'
    arguments:
      source_root: '%site_dir%/src'
      include: '%include%'
      exclude: '%exclude%'
      text_extensions: '%text_extensions%'
      attribute_syntax: '%attribute_syntax%'

This is the default configuration and is not necessary to modify your config.yml file at your site.

MemoryDataSource

MemoryDataSource is useful for generating dynamic content. At the below example the permalink of the item will be /welcome and its path /welcome/index.html at the compiled site:

class TestPlugin implements PluginInterface
{
    public function getMetas()
    {
        return [
            'name' => 'Test plugin',
        ];
    }

    public function initialize(EventSubscriber $subscriber)
    {
        $subscriber->addEventListener('spress.start', 'onStart');
    }

    public function onStart(EnvironmentEvent $event)
    {
        $dsm = $event->getDataSourceManager();

        $item = new Item('# Welcome!', 'welcome.md');
        $item->setPath('welcome.md', Item::SNAPSHOT_PATH_RELATIVE);

        $memoryDataSource = new MemoryDataSource();
        $memoryDataSource->addItem($item);

        $dsm->setDataSource('memory-plugin', $memoryDataSource);
    }
}

To adds a new layout type item or include type item uses addLayout and addInclude methods:

$include = new Item('<div>{{ page.content }}<div>');

$memoryDataSource = new MemoryDataSource();
$memoryDataSource->addInclude($item);