Skip to content

File-based Collections

This article covers advanced usage intended for those who are writing their own Blade views, and is not required as Hyde comes pre-packaged with many templates for you to use.
This feature was added in v0.43.0-beta.

Introduction to Hyde Data Collections

Hyde provides DataCollections, a subset of Laravel Collections giving you a similar developer experience to working with Eloquent Collections, but here, it's all entirely file-based.

You get the have access to all Laravel Collection methods so you are encouraged to read the Laravel Collections documentation for more information.

Currently only a Markdown collection type is added, but more types like YAML are planned.

Enabling the feature

You may need to enable the module by adding the feature to your Hyde configuration file's features array:

Filepath: config/hyde.php
1'features' => [
2 Features::dataCollections(),
3 ],

High-Level Concept Overview

To make collections easy to use and understand, Hyde makes a few assumptions about the structure of your collections. Follow these conventions and creating dynamic static sites will be a breeze.

  1. Collections are stored in the new _data directory.
  2. Each subdirectory in here can be a collection.
  3. Data collections are automatically generated when you use the Facade you will learn about below.
  4. When using one of the facades, you need to specify the collection name, this name is the name of the subdirectory.
  5. Each subdirectory should probably only have the same filetype to prevent developer confusion, but this is not enforced.
  6. Unlike Markdown pages, files starting with underscores are not ignored.
  7. You can customize the base _data directory through a service provider.

Markdown Collections - Hands on Guide

Setting up the file structure

I think the best way to explain DataCollections is through examples. Let's create a Blade page with customer testimonials.

We start by setting up our directory structure. We will create a testimonials subdirectory, which will be the collection name.

In it we will place Markdown files. Each file will be a testimonial. The Markdown will be parsed into a MarkdownDocument object which parses any optional YAML front matter.

Here is the sample Markdown we will use:

Filepath: _data/testimonials/1.md
1---
2author: John Doe
3---
4 
5Lorem ipsum dolor sit amet, consectetur adipiscing elit...

Let's take a look at our directory structure. I just copied the same file a few times. You can name the files anything you want, I kept it simple and just numbered them.

1_data
2└── testimonials
3 ├── 1.md
4 ├── 2.md
5 ├── 3.md
6 ├── 4.md
7 └── 5.md

Using the Facade to Access the Collections

Now for the fun part! We will use the MarkdownCollection facade to access all our files into a convenient object. The class is already aliased to the facade, so you don't need to use any namespaces.

The general syntax to use the facade is as follows:

1MarkdownCollection::get('subdirectory_name')

This will return a Hyde DataCollection object, containing our Markdown files as MarkdownDocument objects. Here is a quick look at the object the facade returns:

^ Hyde\Framework\Modules\DataCollections\DataCollection {#270 ▼ 
  +key: "testimonials"
  #items: array:5 [
    0 => Hyde\Framework\Models\MarkdownDocument {#273 ▼
      +matter: array:1 []
      +body: "Lorem ipsum dolor sit amet, consectetur adipiscing elit...\n"
      +title: ""
      +slug: ""
    
}
    1 => Hyde\Framework\Models\MarkdownDocument {#274 ▶}
    2 => Hyde\Framework\Models\MarkdownDocument {#275 ▶}
    [The rest is truncated to conserve space...]

Implementing it in a Blade view

Let's create a Blade page to display all our testimonials.

1php hyde make:page "Testimonials" --type="blade"
2# or just touch _pages/testimonials.blade.php

And we can use the collection almost like any other Laravel one. As you can see, we are able to get the author from the front matter, and the content from the body.

1@foreach(MarkdownCollection::get('testimonials') as $testimonial)
2<blockquote>
3 <p>{{ $testimonial->body }}</p>
4 <small>{{ $testimonial->matter['author'] }}</small>
5</blockquote>
6@endforeach