Folders

Folders are a way to request several Stories at once such as getting the latest news articles or a team of people. It wraps Storyblok’s API for retrieving multiple stories. The read() method will return a collection of Stories matching the specified criteria.

You can generate Folder classes using the built-in the ls:folder Artisan command. The folder name will be used for the class name and also set the folder’s slug but you can update this as required.


```console
php artisan ls:folder FolderName

To get a folder of Stories you can use the App\Storyblok\Folder Class in your controller specifying the slug of the folder in Storyblok you wish yo read from.

<?php

namespace App\Http\Controllers;

use App\Storyblok\Folder;

class NewsController extends Controller
{
    public function index() {
        $stories = new Folder();
        $stories->slug('news');

        return view('storyblok.pages.news', [
                'stories' => $stories->read()
            ]
        );
    }
}

You can access many of a Folder’s settings fluently by chaining methods. For example, to get the first five serivces by their name field you could do the following:

<?php

namespace App\Http\Controllers;

use App\Storyblok\Folder;

class ServiceController extends Controller
{
    public function index() {
        $folder = new \App\Storyblok\Folder();

        return view('storyblok.pages.news', [
                'stories' => $folder->slug('services')->sort('content.name')->asc()->perPage(5)->read()
            ]
        );
    }
}

Setting the path to request

Call the slug() method with the path to the content you wish to request from Storyblok. The argument’s value maps to the starts_with property of the API call so be sure to check the Storyblok documentation.

Sorting the requested items

By default folders are order by their publish date in descending order - so newest items first.

You can change the sort order with the sort($field, $order) method, it accepts any valid sort as specified in the Storyblok documentation such as sort('content.YOUR_FIELD') or sort('content.YOUR_FIELD', 'asc'). Read their docs for full details.

There are also two helper methods for changing order - asc() and desc().

Further refinement

If you need more control over your request the settings() method accepts an array of parameters allowing you to specify any part of the request.

Pagination

To paginate your folder use the perPage() method being read() specifying the number of items per page.

$stories = new Folder();
$stories->perPage(10)->read();

{warning} If you change the per_page value in the $settings array make sure you match the value in perPage(). perPage() does updatesettings` so it’s recommended to only use the method.

Folder’s don’t know what page they are on, you need to tell them by passing the page number to their settings.

<?php

namespace App\Http\Controllers;

use App\Storyblok\Folders\News;
use Illuminate\Http\Request;

class NewsController extends Controller
{
    public function index(Request $request)
    {
        $news = new News();
        $news->settings([
            'page' => (int)$request->get('page') ?: 1,
        ]);

        return view('pages.news', [
            'stories' => $news->perPage(10)->read(),
        ]);
    }
}

The package uses Laravel’s LengthAwarePaginator see the Laravel docs for customisation options.

To display the standard pagination links in your view do the following:

{!! $stories->paginate()->links() !!}

Custom folders

Rather than calling multiple methods each time you need to request a folder you can create custom Folder class by extending \App\Storyblok\DefaultFolder. Within this class you are free to set any defaults or create methods to fulfill your requirements.

Here is an example that loads Stories from the ‘news’ folder that where published any time before now(), ordering them by a publish_date datetime field.

<?php

namespace App\Storyblok\Folders;

class News extends \App\Storyblok\Folder
{
    protected string $slug = 'news';
    protected string $sortBy = 'content.published_at';
    protected string $sortOrder = 'desc';

    public function __construct()
    {
        $this->settings([
            'filter_query' => [
                'published_at' => [
                    'lt_date' => now()->format('Y-m-d H:i'),
                ]
            ],
            'per_page' => 20
        ]);
    }
}

{warning} Warning, if you specify $settings in the constructor and later call $folder->settings([...]) in your code those from your constructor will be lost. You may be better setting the properties directly in the constructor.

And in your controller you simply need to instantiate your Folder class - no need to call any methods. This is handy if you need to reuse a Folder in several locations. Of course you can still override individual settings by calling the above methods if needed.

<?php

namespace App\Http\Controllers;

use App\Storyblok\Folders\News;

class NewsController extends Controller
{
    public function index() {
        $news = new News();

        return view('storyblok.pages.news', [
                'news' => $news->read()
            ]
        );
    }
}

Including folders within Pages

Here’s a more complete controller that loads the root news page Story and additional Stories from the news folder, passing them to the Page’s view.

<?php

namespace App\Http\Controllers;

use App\Storyblok\Folders\News;
use Riclep\Storyblok\StoryblokFacade as StoryBlok;

class NewsController extends Controller
{
    public function index() {
        $news = new News();

        return Storyblok::bySlug('/news')->read()->render(
            [
                'news' => $news->read()
            ]
        );
    }

    public function show($slug) {
        return Storyblok::bySlug('/news/' . $slug)->read()->render();
    }
}

{info} View Components are another great way load folders into your content blocks.

Getting Started

Advanced Usage