README

This package provides custom directives so you can easily access Statamic data in your Blade templates.

ARCHIVED

Note that with the release of Statamic 3.3, this addon is no longer needed. Please update to 3.3 and use the native Statamic::tag(...) functionality. If you need any changes, please fork.

Requirements

PHP 7.4+
Statamic v3.2

Installation

You can install this package via composer using:

composer require edalzell/blade-directives

The package will automatically register itself.

Usage

Automatic augmentation of Statamic values

If you want values to be augmented automatically in your Blade views, you can replace the

Illuminate\View\ViewServiceProvider::class in the providers of your config/app.php with \Edalzell\Blade\Augmentation\AugmentationViewServiceProvider

This will replace all instances of \Statamic\Fields\Value by their augmented values.

Antlers

If tag(), modify() or any of the below directives aren't achieving the desired outcome, it is possible to try the Antlers directive to render Antlers within Blade.

@antlers($str, $variables = [])

We do this by using the Antlers Facade and its parse method.

\Statamic\Facades\Antlers::parse($str, /* $variables = [] or collect(get_defined_vars())->except('__data', '__path')->toArray() */)

There are some things to note however, for these examples we will describe $str as the content or string that you wish to have Antlers parse into Html, while $variables is the context or data that will be passed to Antlers and is used to map variables and data to Antlers, The context will automatically be added to the Antlers::parse call, however if you define the second parameter $variables then the default context will be ignored and your supplied context will act as an override.

An example of this would be if we passed $str into our view,

view('home', ['str' => "{{ 'foo' }}"]);

This will output foo.
@antlers($str)

But now if we instead remove the single quotes from foo, then we will need to provide the context of what foo is.

view('home', [
    'str' => "{{ foo }}",
    'variables' = ['foo' => 'bar']
]);

This will output the value of foo that we assigned in the context, which would output bar.
@antlers($str, $variables)

It is also possible to use the directive inline. If passing everything inline, then the Antlers content will need to have @ added to its curly braces. quotes will need to be escaped too.

This will output testing.
@antlers('@{{ test }}', ['test' => 'testing'])

You can also use @php blocks to define the content and or context.

@php
    $content = '{{ test | ucfirst }}';
    $context = ['test' => 'testing'];
@endphp

This will output Testing.
@antlers($content, $context)

This directive can be used in a bunch of different ways, let your imagination run wild! All you need to do is provide the content and then any context that it might need, how you get/set or provide those doesn't really matter that much.

The default context can be obtained with the following code collect(get_defined_vars())->except('__data', '__path')->toArray()

Assets

@asset('url/to/asset.jpg')
    URl: {{ $asset['url'] }}
    Permalink: {{ $asset['permalink'] }}
    Alt: {{ $asset['alt'] }}
    ...other fields
@endasset

Breadcrumbs

@breadcrumbs
    $item['url']
@endbreadcrumbs

You can use the same parameters as the nav:breadcrumbs tag.

@breadcrumbs(['include_home' => false, 'reverse' => true])
    $item['url']
@endbreadcrumbs

Collection

Use the same params as the {{ collection }} tag

@collection('pages', ['title:is' => 'My Title', 'author:is' => 'Erin', 'limit' => 3, 'sort' => 'title:desc'])\
    @isset($entry['no_results'])
        <p>There are no results</p>
    @else
        {{ $entry['title'] }}
    @endisset
@endcollection

Collection Pagination

@collection('the_collection', ['limit' => 2, 'paginate' => true])
    @foreach($entry['entries'] as $entry)
        @data($entry)
            Title: {{ $title }}
        @enddata
    @endforeach
@endcollection

Data

Use this when you have Statamic data but it's a Value object. This will return a keyed array with all the fields as string/ints/arrays (recursively).

@data($theValueObject)
    {{ $fieldYouWant }}
@enddata

Entry

Gets all the data in an entry. In the example below the data is a replicator, so you have to walk through the sets.

@entry('the_collection_handle', 'entry-slug')
    @foreach($replicator as $set)
        <p>Type is {{ $set['type'] }}</p>
        @include("partials/{$set['type']}", $set)
    @endforeach
@endentry

Forms

You can pass in the same parameters that {{ form:create }} supports. Any other parameters will be added to the <form> tag as attributes.

To access the errors, use standard Blade errors but pass in the proper error bag, which is form.your-form-handle.

@form('contact_us', ['redirect'=> '/', 'error_redirect' => '', 'allow_request_redirect' => false, 'id' => 'form-id', 'class' => 'foo'])
Email: <input type="text" name="email" />
@error('email', 'form.contact_us')
    <div>{{ $message }}</div>
@enderror
<button>Contact Us</button>
@endform

Form Fields

Loops over the fields for a form.

@formfields('contact_us')
<label>{{ $field['display'] }}</label>
<input type="{{ $field['type'] }}" name="{{ $field['handle'] }}" placeholder="{{ $field['placeholder'] ?? '' }}" />
@endformfields

Glide

Generates the glide image.

@glide('/assets/IMG_1325.jpeg', ['width' => 100])
    <p>URL is {{ $url }}</p>
    <img src="{{ $url }}">
    <p>Width is {{ $width }}</p>
    <p>Hight is {{ $height }}</p>
@endglide

Globals

@globalset('footer')
    {{ $set_variable }}
@endglobalset

@globalset('footer', 'set_variable')

Nav

@nav('footer')
    {{ $item['title'] }}
@endnav

You can use the same parameters as the nav tag.

@nav('collection::pages', ['from' => '/', 'show_unpublished' => true, 'include_home' => true])
    {{ $item['title'] }}
@endnav

Site

@site
    {{ $short_locale }}
@endsite

@site('short_locale')

Taxonomy

Use the same params as the {{ taxonomy }} tag

@taxonomy('tags', ['limit' => 6, 'sort' => 'entries_count:desc'])
    <p>Title is {{ $term['title'] }}</p>
@endtaxonomy

Testing

Run the tests with:

vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email addon-security@silentz.co instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

edalzell / blade-directives

Maintainers

Details