Data

Data is structured content that you can use in your pages. These might be values like names, places, product prizes, etc. Data is stored in structured data files which can be loaded into your page.

By default, data files are loaded from the /data directory, data can also be loaded from any URL making data very flexible and powerful. Pages supports loading data from YAML, JSON, INI, PHP, XML and MD (markdown) and files.

This powerful feature allows you to avoid repetition in your pages and templates and to set site-specific options without changing config.php.

Table of contents

• The data() function
• Methods
  • Shuffle
  • Slice
  • Filter
  • Flatten
  • toString
• Advanced
• Notes

The data() function

The data() template function allows you to create a data object, either loaded from a file path, or an URL, or created from an associative array you pass in.

From a path or an URL

The data() template function receives a relative path or an URL to the data file that needs to be loaded.

Examples:

• data('company/team') would load from /data/company/team.json
• data('http://myurl/company/team.json') would load from this URL
• data('http://myurl/company/team') would load from this URL

Data formats are handled transparently by Pages, they are discovered based on the data file extension or in the case of an URL discovered from the content type sent by the server the URL is requested from.

The data method returns a ComPagesDataObject which can be iterated in the template.

From an associative array

It's possible to create a new data object from an associative array of data.

Example:

<? $data = data([
    'foo' => 'bar',
    'dog' => 'bark'
]); ?>

Note: A non-associative array will be interpreted as an array of data locations.

Methods

Shuffle

Data can be shuffled by calling the shuffle() or data('testimonials')->shuffle() methods.

This methods works in the same way as shuffle.

Slice

Data can be sliced by calling the slice($offset, $length = NULL) method or data('testimonials')->slice(0, 3) method.

This method works in the same way as array_slice.

Filter

Data can be filtered by calling the filter($key, $value = NULL) method. If only a key is specified, all items will be returned for which the key exists and is not NULL. If a value is set, the key will be matched against the value.

Example:

$data = data('product')->filter('image')

In this example, all products that have an image will be returned.

This method works in the same way as array_filter.

Flatten

The first level of a multi-dimensional data object can be flattened by calling flatten($key_as_property = null)

If defined the key_as_property parameter will be added to each object being flattened and contain the key of the object in the array if it's a named object.

Example:

foreach($list->flatten('product') as $item) {
    echo $item->product;
}

toString()

You can cast a data object to a JSON string by calling the data([..])->toString() method or <?= data([...]) ?> It will return an RFC4627-compliant JSON string, which may also be embedded into HTML.

Advanced

Folders

Inspired by Jekyll, you can not only load data from a single file but also data from all files in a folder.

Example: data('company/members')

If /data/company/members/ exists, then all the files in the folder will be loaded and the data merged into one large data object. This also works if the data types are different so you can use different data file formats to create one data object.

List

You can only load data from a list of locations, either a file or a folder.

Example: data(['company/members', company/vendors'])

All the files and folders will be loaded and appended into one big data object. This also works if the data types are different so you use different data file formats to create one data object.

Aliases

Inspired by Jekyll Get, you can also alias an URL. We use a by-convention approach. Instead of using a config file, you just put the URL as the first line of the data file, the data in the URL will then be loaded.

Example: In file /data/company/team.json add http://myurl/company/team.json on the first line.

Use with: data('company/team')

This also works when loading from a folder, if a file in the folder contains an URL instead of data, the data will be loaded from that URL and merged.

Ordering

Data can be ordered per folder by adding a .order.[format] file to the folder that specifies the specific ordering of all the data files, both files and folders can be ordered. Type can be any data format: YAML, JSON, INI, PHP, and XML.

Example with YAML:

- file1.md
- fileB.md
- folderA
- folderB

Frontmatter

It's possible to inject data dynamically in the page and layout frontmatter. To do that use the following:

• data://path/to/folder will fetch the complete data array and inject it, while
• data://path/to/folder[property] will inject a specific property.

Notes

• Data objects are cached per request to increase performance. You can change a data object in request scope, changes you make will be persistent for the request cycle.
• If the format of the data file is Markdown (.md) the contents of the file will be available as data('file')->content.

Previous: Examples | Next: URLs and Linking