Skip to content

Commit 55101f3

Browse files
bryannielsenbryannielsen
committed
Document multiple modifiers and fluid field groups
1 parent 6a00393 commit 55101f3

File tree

9 files changed

+237
-19
lines changed

9 files changed

+237
-19
lines changed

‎docs/getting-started.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ php artisan coilpack
1919

2020
## Choosing a Laravel Version
2121

22-
We recommend using the latest version of Laravel whenever possible. If you are limited to a certain version of PHP we have a table below showing which version of Laravel may be right for you.
22+
We recommend using the latest version of Laravel whenever possible. The only reason you should not use the latest version is if you are limited to a certain version of PHP. The table below shows which versions of Laravel are supported on different versions of PHP.
2323

2424
| PHP | Laravel |
2525
| ------- | ------- |
@@ -34,6 +34,14 @@ To use Coilpack You will need a development environment with PHP >= 7.4.0 and Co
3434

3535
### Create A Laravel Project
3636

37+
This create project command will setup a new Laravel project at the highest version supported by your environment.
38+
39+
```sh
40+
composer create-project --prefer-dist laravel/laravel project-name
41+
```
42+
43+
Alternatively you can specify a major version of Laravel:
44+
3745
```sh
3846
composer create-project --prefer-dist laravel/laravel:^8.0 project-name
3947
```

‎docs/graphql/index.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,11 @@ The GraphQL integration's behavior can be configured in the `config/coilpack.php
3636
*/
3737
'is_default_schema' => true,
3838

39+
/*
40+
* Flag to indicate preference for using GraphQL Union Types
41+
*/
42+
'prefer_union_types' => false,
43+
3944
/**
4045
* Settings to control how requests to the GraphQL API should be authenticated
4146
*/

‎docs/graphql/queries/channel-entries.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,14 +56,22 @@ Here is an example of using the `resize` modifier available on File fieldtypes
5656
}
5757
```
5858

59-
And here is an example of using the `length` modifier available on most fieldtypes.
59+
Here is an example of using the `length` modifier which is available on most fieldtypes. This example also demonstrates how to chain modifiers together to get the `length` of the page_content after it has gone through a `limit` modifier.
6060

6161
```graphql
6262
{
6363
exp_channel_entries {
6464
entry_id
6565
title
6666
page_content(length:true)
67+
excerpt_length:page_content(
68+
limit: {characters: 10, end_char: "..."},
69+
length: true
70+
)
6771
}
6872
}
69-
```
73+
```
74+
75+
:::info
76+
While the [GraphQL specification treats arguments as unordered](http://spec.graphql.org/draft/#sec-Language.Arguments.Arguments-Are-Unordered) Coilpack does extra work to ensure the order of modifiers is maintained.
77+
:::

‎docs/index.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@ No, it's important to remember that Coilpack serves the purpose of connecting Ex
3131

3232
## Known Issues
3333

34-
- There is a known conflict when using Spatie Ray and the ExpressionEngine core Add-on Structure
3534
- Using Laravel Telescope will register a wildcard event listener that conflicts with how we translate ExpressionEngine extensions into Laravel Events. For now we recommend setting `TELESCOPE_EVENT_WATCHER=false` in your .env file otherwise your site may not render properly.
3635
- Coilpack works well out of the box when using Laravel Valet and with Apache webservers, but we have noticed some issues in certain Nginx installs. We recommend using a configuration similar to the one below with Nginx:
3736

‎docs/templates/fieldtypes.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,7 @@ Certain parameters or modifiers may behave differently in Coilpack or may not be
1818
1919
{# Modifier with parameters #}
2020
{{ entry.field_name.modifier_name({parameter_name: "value"}) }}
21+
22+
{# Chaining Modifiers #}
23+
{{ entry.field_name.modifier_name({parameter_name: "value"}).another_modifier() }}
2124
```

‎docs/templates/fieldtypes/file.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,14 @@ File fields utilize the built-in file browser to store uploaded files and images
6767
{{ entry.file.manipulation('manipulation_name') }}
6868
```
6969

70+
## Chaining Modifiers
71+
72+
ExpressionEngine 7.3 introduced the ability to chain modifiers. This can be a very valuable tool when working with files if you want to manipulate a modified file even further.
73+
74+
```twig
75+
{{ entry.file.manipulation('manipulation_name').crop({width: 100, height: 100}) }}
76+
```
77+
7078
:::info
7179
See the ExpressionEngine Documentation for more information on the [File fieldtype](https://docs.expressionengine.com/latest/fieldtypes/file.html)
7280
:::

‎docs/templates/fieldtypes/fluid.md

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs/templates/fieldtypes/fluid.mdx

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
4+
5+
# Fluid
6+
7+
A Fluid field is a collection of fields. A Fluid field can contain any native fieldtype except another Fluid field. The fields assigned to the Fluid field can then be used multiple times in the same entry when creating/editing the entry. The author also has control over the order of the fields.
8+
9+
## Template Usage
10+
11+
When iterating over the rows of a Fluid field in a template you will have access to the value but also extra data which can be used to control the display of these fields and field groups.
12+
13+
<Tabs>
14+
<TabItem value="twig" label="Twig">
15+
16+
```twig
17+
{% for row in entry.fluid %}
18+
Value: {{ row }}
19+
20+
Field Type: {{ row._field_type }} or {{ row.field.field_type }}
21+
Field Name: {{ row._field_name }} or {{ row.field.field_name }}
22+
Group Name: {{ row._field_name }} or {{ row.group.short_name }}
23+
24+
Field (when row is a field): {{ row.field }}
25+
Group (when row is a field group): {{ row.group }}
26+
27+
Condition for fields - {% if row.field %} ... {% endif %}
28+
Condition for field groups - {% if row.group %} ... {% endif %}
29+
30+
{% endfor %}
31+
```
32+
33+
</TabItem>
34+
<TabItem value="blade" label="Blade">
35+
36+
```php
37+
@foreach($entry->fluid as $row)
38+
Value: {{ $row }}
39+
40+
Field Type: {{ $row->_field_type }} or {{ $row->field.field_type }}
41+
Field Name: {{ $row->_field_name }} or {{ $row->field.field_name }}
42+
Group Name: {{ $row->_field_name }} or {{ $row->group.short_name }}
43+
44+
Field (when row is a field): {{ $row->field }}
45+
Group (when row is a field group): {{ $row->group }}
46+
47+
Condition for fields - @if($row->field) ... @endif
48+
Condition for field groups - @if($row->group) ... @endif
49+
50+
@endforeach
51+
```
52+
53+
</TabItem>
54+
</Tabs>
55+
56+
57+
58+
## Field Groups
59+
60+
ExpressionEngine 7.3 introduced the ability to use field groups within a Fluid field to further improve the content authoring experience. Coilpack makes the Field Group's `short_name` available as the `_field_name` attribute and sets the `_field_type` attribute to a value of `field_group`. We recommend using these attributes to conditionally handle the display of your fields and field groups.
61+
62+
<Tabs>
63+
<TabItem value="twig" label="Twig">
64+
65+
```twig
66+
{% for row in entry.fluid %}
67+
{% if row._field_name == 'my_group' %}
68+
{% for group_row in row.fields %}
69+
{% if group_row._field_name == 'my_text' %}
70+
<div class="my-text">{{ group_row | raw }}</div>
71+
{% elseif group_row._field_name == 'my_image' %}
72+
<div class="my-image"><img src="{{ group_row }}"/></div>
73+
{% elseif group_row._field_name == 'my_grid' %}
74+
<table>
75+
<tr>
76+
<th>Column 1</th>
77+
<th>Column 2</th>
78+
</tr>
79+
{% for grid_row in group_row %}
80+
<tr>
81+
<td>{{ grid_row.column_1 }}</td>
82+
<td>{{ grid_row.column_2 }}</td>
83+
</tr>
84+
{% endfor %}
85+
</table>
86+
{% endif %}
87+
{% endfor %}
88+
{% endif %}
89+
{% endfor %}
90+
```
91+
92+
</TabItem>
93+
<TabItem value="blade" label="Blade">
94+
95+
```php
96+
@foreach($entry->fluid as $row)
97+
@if($row->_field_name == 'my_group')
98+
@foreach($row->fields as $group_row)
99+
@if($group_row->_field_name == 'my_text')
100+
<div class="my-text">{!! $group_row !!}</div>
101+
@elseif($group_row->_field_name == 'my_image')
102+
<div class="my-image"><img src="{{ $group_row }}"/></div>
103+
@elseif($group_row->_field_name == 'my_grid')
104+
<table>
105+
<tr>
106+
<th>Column 1</th>
107+
<th>Column 2</th>
108+
</tr>
109+
@foreach($group_row as $grid_row)
110+
<tr>
111+
<td>{{ $grid_row->column_1 }}</td>
112+
<td>{{ $grid_row->column_2 }}</td>
113+
</tr>
114+
@endforeach
115+
</table>
116+
@endif
117+
@endforeach
118+
@endif
119+
@endfor
120+
```
121+
122+
</TabItem>
123+
</Tabs>
124+
125+
126+
## GraphQL
127+
128+
When using GraphQL you can slightly alter the way you interact with a Fluid field by changing the value of the `graphql.prefer_union_types` in `config/coilpack.php`. There are pros and cons for each approach so this is purely a matter of developer preference.
129+
130+
The default behavior does not utilize Union Types. This lends itself to a simpler request structure but will have extra response data with null values.
131+
132+
```graphql
133+
exp_channel_entries {
134+
data {
135+
title
136+
fluid_field {
137+
_field_name
138+
_field_type
139+
my_group {
140+
_field_name
141+
_field_type
142+
my_text
143+
my_image
144+
my_grid {
145+
column_1
146+
column_2
147+
}
148+
}
149+
}
150+
}
151+
}
152+
```
153+
154+
Whereas using [Union Types](https://graphql.org/learn/schema/#union-types) can make the request a little more complex but will have a simpler and more succinct response.
155+
156+
```graphql
157+
exp_channel_entries {
158+
data {
159+
title
160+
fluid_field {
161+
... on fluid__my_group {
162+
name
163+
fields {
164+
__typename
165+
... on fluid__my_text {
166+
mytext:content
167+
}
168+
... on fluid__my_image {
169+
myimage:content {
170+
url
171+
filename
172+
width
173+
file_name
174+
}
175+
}
176+
... on fluid__my_grid {
177+
mygrid:content {
178+
column_1
179+
column_2
180+
}
181+
}
182+
}
183+
}
184+
}
185+
}
186+
}
187+
```
188+
189+
:::info
190+
See the ExpressionEngine Documentation for more information on the [Fluid fieldtype](https://docs.expressionengine.com/latest/fieldtypes/fluid.html)
191+
:::

‎docs/upgrade-guide.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Upgrade Guide
2+
3+
You can upgrade to the latest version of Coilpack by running `composer update` at the root level of your Laravel project. Upgrades that require extra attention or interaction will be documented on this page.
4+
5+
## Review the Changelog
6+
7+
It's always a good idea to be aware of what is changing in each release. You can see a list of all changes in our [current changelog](https://github.com/ExpressionEngine/Coilpack/blob/1.x/CHANGELOG.md).
8+
9+
## Configuration Changes
10+
11+
Between versions the Coilpack configuration file may change. We recommend comparing the most [recent changes](https://github.com/ExpressionEngine/Coilpack/blob/1.x/config/coilpack.php) with your own `config/coilpack.php` file.

0 commit comments

Comments
 (0)