Values Blade Wrapper #5201

jasonvarga · 2022-02-04T15:03:29Z

Overview

This PR introduces a new Values class that will make working with Blade a lot nicer.

This class will wrap an array/collection and make accessing data available as if it were an Eloquent model.

The class will be returned by the top level page variable as well as tags, and you will interact with it without needing to ever really think about it.

Basically, no more $value = $value instanceof Value ? $value->value() : $value. Just $value.

Closes #1446

What it's fixing

In a Blade template, all of the entry's "augmented" values are exposed to you as variables.

e.g. If your entry's blueprint has an entries field named related_posts, it would be a Value instance with a raw value of a list of IDs. You'd be able to get the entries by calling ->values(). We do this to make the augmentation happen lazily, for performance.

In Antlers, it's automatic. In Blade, you have manually call ->values() which is annoying. And since those Value objects are mixed in with regular non-Value objects, you only have to do it sometimes, which is even more annoying.

Echoes / Automatic casting

If you were just echoing a value, you could do that without worrying.

{{ $title }}

This would output the augmented value because Value knows how to cast to a string.

Conditions / Manual casting

But for situations where it wouldn't automatically cast, you would need to know if you're working with a Value object, and manually call ->value() on it.

If you were doing a conditional check on a field from your blueprint, you'd need to get the underlying value.

@if ($toggle_field)

This would always be true, even if the value was false, because if (Value instance) evaluates to true.

You'd need to do this:

@if ($toggle_field->value())

But if it's not a Value instance, you wouldn't have to call ->value()....

@if ($published)

If you added ->value() it would say something like Call to a member function value() on bool.

Again, it's silly to have to figure out whether you are or aren't working with a Value each time, and call an extra ->value() method on it.

Act like a model

Now, the top level page variable, as well as any globals will be instances of this new Values class.

Instead of using the top level fields, you can get them through the $page variable.

{{-- old way --}}
{{ $title }}

{{-- new way --}}
{{ $page->title }}

{{-- these also work --}}
{{ $page['foo'] }}
@if ($page->foo)
@if ($page['foo'])
@foreach ($page->foo)
@foreach ($page['foo'])

If any of those are Value objects, it'll grab the augmented version.

If for some reason you need the "raw" value (spoiler: you probably never do) you can call $entry->raw('foo').

Note that other global-ish variables are still available at the top level:

{{ $environment }} {{ $logged_in }} {{ $site_name }} etc

The new Statamic::tag() helper will be returning instances of these new Values classes too, allowing you to do the same thing within loops:

@foreach (Statamic::tag('collection:blog') as $entry)
  {{ $entry->foo }}
  {{-- or $entry['foo'], @if($entry->foo), etc --}}
@endforeach

Queries

Similar to Eloquent relationships, you may chain query methods by using a method, but calling a property will resolve the query and give you a collection.

For example, let's say you have a related_posts field, which is an entries field.

{{-- $post->related_posts would be a Collection instance --}}
@foreach ($post->related_posts as $relatedPost) ... @endforeach

{{-- $post->related_posts() would be a query builder. chain clauses, then call get(). --}}
@foreach ($post->related_posts()->limit(3)->orderBy('title')->get() as $relatedPost) ... @endforeach

String/JSON casting

If you try to echo a field that you expect to be an array or collection, it will convert it to JSON.

{{ $post->entries_field }}

[
  {"id":1,"title":"First",...},
  {"id":2,"title":"Second",...}, 
  ...
]

Same goes for the @json or @js directives.

Previously it would only handle when they're not wrapped in a Value object. The first test was coverage for the existing thing, the second test is coverage for the fix.

Use mocks for test so it's less reliant on a real tag, and the return values can be more easily tested for augmentation etc

…cess etc

isarphilipp · 2022-02-08T20:00:12Z

…I am running out of emojis trying to express the excitement about this PR 🤩

This reverts commit 680dfb1.

# Conflicts: # src/Fieldtypes/Entries.php

* New Antlers docs (#692) Co-authored-by: Jason Varga <[email protected]> * Update blade doc with new `Statamic::tag()` and `Statamic::modify()` usage. (#702) * Frontend form field conditions (#691) * Document conditional fields in front-end forms. * JS. * Finish documenting custom JS drivers. * Suggest more real-world example gist, as well as a link to our built-in Alpine driver. * Tweak the intro Co-authored-by: Jack McDade <[email protected]> * Link to the new parser docs * Mention alternate closing tags * Refactor JSON encoding for form attributes in JS drivers (#723) * fix mobile header overflow issue. Closes #725 * Document newest PHP delimiter * Show the new new site site in the quick start guide * Delete installed.png * initial 3.3 upgrade guide * Blade variables as per statamic/cms#5201 * fix a few code examples * change per statamic/cms#5302 * Improve docs on getting data out of entries * reword * avoid the slash so the example isn't highlighted as a regex. its just an example. * wip * Rely on the automatic TOC * Update fluent tag docs with param setters (#739) * zero impact 3.3 changes * fetch and pagination example * property access * explain void * form submission data change * live preview * live preview * Remove live preview extending page - it's all covered in the regular one * at symbol can escape braces in strings and params * Laravel 8 * explain date field change * Add date where clauses * laravel upgrade guide * Tweak the L7-L8 upgrade guide * A few more tweaks * fix tpyo * enh? * Improve Blade docs * Remove caveats. * Routes and Controller examples for Blade * A little more detail up front Co-authored-by: Jason Varga <[email protected]> Co-authored-by: Jesse Leite <[email protected]>

jasonvarga and others added 15 commits February 3, 2022 19:12

initial values class

dcce335

Apply fixes from StyleCI

cee48b8

Remove method delegation

035d849

Make public

680dfb1

Handle queries

c192531

Parser can handle Value objects that augment to Query Builders ...

51faec7

Previously it would only handle when they're not wrapped in a Value object. The first test was coverage for the existing thing, the second test is coverage for the fix.

improve test coverage for entries fieldtype augmentation

5368d40

entries fieldtype augments to a query builder

bd9ce8d

GraphQL ResolvesValues trait will handle query builders

a75e717

Antlers will handle nested field notation with query builders

5ea7079

improve fluenttagtest ...

148141c

Use mocks for test so it's less reliant on a real tag, and the return values can be more easily tested for augmentation etc

Return Values instances

c2cabf4

Fluent tag Values conversion

9f6d303

Cache the fetch so the tag is only run once, if you're using array ac…

39eb3ad

…cess etc

Apply fixes from StyleCI

3cb5ac4

Revert "Make public"

03fd106

This reverts commit 680dfb1.

jasonvarga mentioned this pull request Feb 8, 2022

Entries fieldtype augments to a query builder #5238

Merged

jasonvarga added 3 commits February 9, 2022 12:33

Merge branch 'master' into feature/values

dd00866

# Conflicts: # src/Fieldtypes/Entries.php

Merge branch 'master' into feature/values

275b7ff

this silly stuff

1561859

jasonvarga marked this pull request as ready for review February 11, 2022 20:00

jasonvarga added 2 commits February 11, 2022 15:15

ValuesCollection objects can cast to string and json

d789e09

Values is Arrayable

a18a21d

jasonvarga mentioned this pull request Feb 11, 2022

Blade templates have some developer issues #1446

Closed

3 tasks

jasonvarga marked this pull request as draft February 11, 2022 21:42

jasonvarga added 3 commits February 11, 2022 17:18

Values is iterable

a901f8c

The "page" at the top level is a Values instance

cc000c5

Globals are Values instances

d542bed

jasonvarga added a commit to statamic/docs that referenced this pull request Feb 14, 2022

Blade variables as per statamic/cms#5201

0756c6d

jasonvarga marked this pull request as ready for review February 14, 2022 15:48

jasonvarga added 2 commits February 14, 2022 11:47

changelog

1a8c751

remove a method that was originally doing more

ebd82f1

jasonvarga merged commit 837a6a7 into master Feb 14, 2022

jasonvarga deleted the feature/values branch February 14, 2022 19:10

jasonvarga mentioned this pull request Feb 14, 2022

Add toValuesCollection macro #5286

Merged

jasonvarga mentioned this pull request Feb 23, 2022

Roll back Values and related classes #5334

Merged

jasonvarga mentioned this pull request Mar 8, 2022

Add Values wrapper and use it in Grid/Replicator/Bard #5436

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Values Blade Wrapper #5201

Values Blade Wrapper #5201

Uh oh!

jasonvarga commented Feb 4, 2022 •

edited

Loading

Uh oh!

isarphilipp commented Feb 8, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Values Blade Wrapper #5201

Values Blade Wrapper #5201

Uh oh!

Conversation

jasonvarga commented Feb 4, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

What it's fixing

Echoes / Automatic casting

Conditions / Manual casting

Act like a model

Queries

String/JSON casting

Uh oh!

isarphilipp commented Feb 8, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jasonvarga commented Feb 4, 2022 •

edited

Loading