Merge remote-tracking branch 'origin/2.x' into laravel-9-support

area17 · Feb 22, 2022 · 3f49796 · 3f49796
2 parents aa220f4 + be0de68
commit 3f49796
Show file tree

Hide file tree

Showing 25 changed files with 362 additions and 183 deletions.
diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/src/.vuepress/public/_media/screenshot-sidebar.png b/docs/src/.vuepress/public/_media/screenshot-sidebar.png
diff --git a/docs/src/.vuepress/sidebar.js b/docs/src/.vuepress/sidebar.js
@@ -155,6 +155,10 @@ module.exports = [
             "title": "Multi Select Inline",
             "path": "/form-fields/multi-select-inline.html",
           },
+          {
+            "title": "Tags",
+            "path": "/form-fields/tags.html",
+          },
           {
             "title": "Checkbox",
             "path": "/form-fields/checkbox.html",
@@ -190,6 +194,10 @@ module.exports = [
           {
             "title": "Conditional Fields",
             "path": "/form-fields/conditional-fields.html",
+          },
+          {
+            "title": "Field grouping",
+            "path": "/form-fields/field-grouping.html",
           }
         ],
         "collapsable": true

diff --git a/docs/src/block-editor/adding-repeater-fields-to-a-block.md b/docs/src/block-editor/adding-repeater-fields-to-a-block.md
@@ -16,12 +16,12 @@ Inside a block, repeaters can be used too.
 ```
 You can add other fields before or after your repeater, or even multiple repeaters to the same block.
 
-- Create an *item* block, the one that will be reapeated inside the *container* block
+- Create an *item* block, the one that will be repeated inside the *container* block
 
 filename: ```views/admin/repeaters/accordion_item.blade.php```
 ```php
   @twillRepeaterTitle('Accordion item')
-  @twillRepeaterMax('10')
+  @twillRepeaterMax('10') // Optional
 
   @formField('input', [
       'name' => 'header',

diff --git a/docs/src/block-editor/creating-a-block-editor.md b/docs/src/block-editor/creating-a-block-editor.md
@@ -43,7 +43,8 @@ Available annotations:
   - Provide an icon with `@twillPropIcon` or `@twillBlockIcon` or `@twillRepeaterIcon`
   - Provide a group with `@twillPropGroup` or `@twillBlockGroup` or `@twillRepeaterGroup` (defaults to `app`)
   - Provide a repeater trigger label with `@twillPropTrigger` or `@twillRepeaterTrigger`
-  - Provide a repeater max items with `@twillPropMax` or `@twillRepeaterMax`
+  - Provide a repeater max items with `@twillPropMax` or `@twillRepeaterMax`, `@twillRepeaterMax` can also be defined from
+the formField. See [Repeater form field](/form-fields/repeater.html)
   - Define a block or repeater as compiled with `@twillPropCompiled` or `@twillBlockCompiled` or `@twillRepeaterCompiled`
   - Define a block or repeater component with `@twillPropComponent` or `@twillBlockComponent` or `@twillRepeaterComponent`
 

diff --git a/docs/src/block-editor/previewing-blocks.md b/docs/src/block-editor/previewing-blocks.md
@@ -10,17 +10,17 @@ You can enable the content editor individual block previews by providing a `reso
 
 ```php
 <!doctype html>
-<html>
-    <head>
-        <title>#madewithtwill website</title>
-        <link rel="stylesheet" href="/css/app.css">
-    </head>
-    <body>
-        <div>
-            @yield('content')
-        </div>
-        <script src="/js/app.js"></script>
-    </body>
+<html lang="en">
+<head>
+    <title>#madewithtwill website</title>
+    <link rel="stylesheet" href="{{mix('css/app.css')}}">
+</head>
+<body>
+<div>
+    @yield('content')
+</div>
+<script src="{{mix('js/app.js')}}"></script>
+</body>
 </html>
 ```
 

diff --git a/docs/src/crud-modules/form-requests.md b/docs/src/crud-modules/form-requests.md
@@ -48,3 +48,27 @@ $this->messagesForTranslatedFields([
 ```
 
 Once you defined the rules in this file, the UI will show the corresponding validation error state or message next to the corresponding form field.
+
+## Validating repeater fields
+
+To validate repeater fields added to your model you can reuse the same `rulesForCreate` and `rulesForUpdate` methods.
+
+If your repeater is named `accordion_item` and you want to add validation to the `headline` field you can use:
+
+```php
+public function rulesForCreate()
+{
+    return ['repeaters.accordion_item.*.header' => 'required'];
+}
+```
+
+Alternatively if your field is translatable you can use the helpers as defined above:
+
+```php
+public function rulesForUpdate()
+{
+    return $this->rulesForTranslatedFields([], [
+        'repeaters.accordion_item.*.header' => 'required'
+    ]);
+}
+```
diff --git a/docs/src/form-fields/field-grouping.md b/docs/src/form-fields/field-grouping.md
@@ -0,0 +1,130 @@
+---
+pageClass: twill-doc
+---
+
+# Field grouping
+
+Twill supports grouping fields in the database using a json column.
+
+Examples:
+
+- An address section existing out of a street, city and postal code field
+- An external link with Label, url and target
+- ...
+
+Each set of grouped fields requires a column in the database. The grouped fields can be translatable or not.
+
+## Migration and Model setup
+
+The migration for adding a grouped field can look like this (using external link as example):
+
+### Translatable
+
+```php
+## Add a migration
+Schema::table('blog_translations', function (Blueprint $table) {
+    $table->json('external_link')->nullable();
+});
+
+## Update your models fillable
+class Blog extends Model {
+    public $translatedAttributes = [
+        ...
+        'external_link'
+    ];
+
+    protected $fillable = [
+        ...
+        'external_link'
+    ];
+}
+
+## Update your Translation model and add the cast
+public $casts = [
+    'external_link' => 'array',
+];
+```
+
+### Non translatable
+
+```php
+## Add a migration
+Schema::table('blogs', function (Blueprint $table) {
+    $table->json('external_link')->nullable();
+});
+
+## Update your models fillable
+class Blog extends Model {
+    protected $fillable = [
+        ...
+        'external_link'
+    ];
+}
+```
+
+## Field setup
+
+To store the fields you want into the json we have to update the repository:
+
+```php
+protected $fieldsGroups = [
+    'external_link' => [
+        'link_target',
+        'link_url',
+        'link_label',
+    ],
+];
+
+# The below can be setup optionally, documented below.
+public $fieldsGroupsFormFieldNamesAutoPrefix = false;
+public $fieldsGroupsFormFieldNameSeparator = '_';
+```
+
+Finally in our model form we can add the fields:
+
+```php
+@formField('input', [
+    'name' => 'link_target',
+    'label' => 'Link target',
+    'translated' => true
+])
+@formField('input', [
+    'name' => 'link_url',
+    'label' => 'Link url',
+    'translated' => true
+])
+@formField('input', [
+    'name' => 'link_label',
+    'label' => 'Link label',
+    'translated' => true
+])
+```
+
+### Using the field name separator
+
+In the repository file you can setup the following parameters:
+
+```php
+public $fieldsGroupsFormFieldNamesAutoPrefix = true;
+public $fieldsGroupsFormFieldNameSeparator = '.'; // Default is _
+```
+
+This will automatically group/ungroup these fields based on the separator:
+
+```php
+@formField('input', [
+    'name' => 'external_link.link_target',
+    'label' => 'Link target',
+    'translated' => true
+])
+@formField('input', [
+    'name' => 'external_link.link_url',
+    'label' => 'Link url',
+    'translated' => true
+])
+@formField('input', [
+    'name' => 'external_link.link_label',
+    'label' => 'Link label',
+    'translated' => true
+])
+```
diff --git a/docs/src/form-fields/index.md b/docs/src/form-fields/index.md
@@ -14,9 +14,12 @@ Your module `form` view should look something like this (`resources/views/admin/
 @stop
 ```
 
-The idea of the `contentFields` section is to contain your most important fields and, if applicable, the block editor as the last field.
+The idea of the `contentFields` section is to contain your most important fields and, if applicable, the block editor as
+the last field.
 
-If you have other fields, like attributes, relationships, extra images, file attachments or repeaters, you'll want to add a `fieldsets` section after the `contentFields` section and use the `@formFieldset` directive to create new ones like in the following example:
+If you have other fields, like attributes, relationships, extra images, file attachments or repeaters, you'll want to
+add a `fieldsets` section after the `contentFields` section and use the `@formFieldset` directive to create new ones
+like in the following example:
 
 ```php
 @extends('twill::layouts.form', [
@@ -31,13 +34,68 @@ If you have other fields, like attributes, relationships, extra images, file att
 @stop
 
 @section('fieldsets')
-    @formFieldset(['id' => 'attributes', 'title' => 'Attributes'])
+    @formFieldset(['id' => 'attributes', 'title' => 'Attributes', 'open' => false])
         @formField('...', [...])
         ...
     @endformFieldset
 @stop
 ```
 
+You can use the following arguments when defining a `formFieldset`
+
+| Option      | Description                                                                  | Type/values    | Default value |
+|:------------|:-----------------------------------------------------------------------------|:---------------|:--------------|
+| id          | The id of the fieldset, this should match the value in `additionalFieldsets` | string         |               |
+| title       | The title of the fieldset                                                    | string         |               |
+| open        | If the fieldset should be open by default                                    | boolean        | false         |
+
+
 The additional fieldsets array passed to the form layout will display a sticky navigation of your fieldset on scroll.
-You can also rename the content section by passing a `contentFieldsetLabel` property to the layout, or disable it entirely using
+You can also rename the content section by passing a `contentFieldsetLabel` property to the layout, or disable it
+entirely using
 `'disableContentFieldset' => true`.
+
+## Sidebar
+
+You can add content to the sidebar below the publication information by using the `sideFieldset` and `sideFieldsets`
+sections.
+
+This can be useful for small metadata, options or seo fields.
+
+If you use the `sideFieldset` it will automatically be embedded into a collapsible fieldset called options
+
+```php
+@section('sideFieldset')
+    @formField('input', [
+        'name' => 'description',
+        'label' => 'Description',
+        'translated' => true,
+        'maxlength' => 100
+    ])
+@endsection
+```
+
+alternatively, or if you need more control, you can use the `sideFieldsets` section:
+
+```php
+@section('sideFieldsets')
+    <a17-fieldset title="SEO" id="seo">
+        @formField('input', [
+            'name' => 'description',
+            'label' => 'Description',
+            'translated' => true,
+            'maxlength' => 100
+        ])
+        @formField('input', [
+            'name' => 'meta',
+            'label' => 'Meta',
+            'translated' => true,
+            'maxlength' => 100
+        ])
+    </a17-fieldset>
+@endsection
+```
+
+Both combined produces the result as shown in the screenshot below:
+
+![screenshot](/docs/_media/screenshot-sidebar.png)
diff --git a/docs/src/form-fields/repeater.md b/docs/src/form-fields/repeater.md
@@ -10,11 +10,12 @@ pageClass: twill-doc
 @formField('repeater', ['type' => 'video'])
 ```
 
-| Option       | Description                                   | Type    | Default value  |
-| :----------- | :-------------------------------------------- | :-------| :------------- |
-| type         | Type of repeater items                        | string  |                |
-| name         | Name of the field                             | string  | same as `type` |
-| buttonAsLink | Displays the `Add` button as a centered link  | boolean | false          |
+| Option       | Description                                  | Type    | Default value    |
+|:-------------|:---------------------------------------------|:--------|:-----------------|
+| type         | Type of repeater items                       | string  |                  |
+| name         | Name of the field                            | string  | same as `type`   |
+| max          | Maximum amount that can be created           | number  | null (unlimited) |
+| buttonAsLink | Displays the `Add` button as a centered link | boolean | false            |
 
 <br/>