Twill CMS

https://twillcms.com/docs/
Admin
Twill is an open source Laravel package that helps developers rapidly create a custom CMS that is...
Tokens:88,006
Snippets:1,056
Trust Score:8.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Twill Starter Kit

Source: https://twillcms.com/docs/getting-started/installation.html

Run the starter kit installation command to set up a basic page builder. Ensure database credentials are configured in .env before running.

```bash
php artisan twill:install basic-page-builder
```

--------------------------------

### Run Twill Artisan Installation

Source: https://twillcms.com/docs/1.x

Execute the installation command to migrate the database and publish necessary files.

```bash
php artisan twill:install
```

--------------------------------

### Start Webpack HMR Server

Source: https://twillcms.com/docs/1.x

Command to start the development server for Twill admin console UI assets.

```bash
npm run twill-dev

```

--------------------------------

### Configure Module Controller

Source: https://twillcms.com/docs/modules/controllers.html

Example of overriding the setUpController method to enable specific module features.

```php
<?php

namespace App\Http\Controllers\Twill;

class ProjectController extends ModuleController
{
    protected $moduleName = 'projects';

    public function setUpController(): void
    {
        $this->enableShowImage();
    }
}
```

--------------------------------

### Install a Twill capsule via CLI

Source: https://twillcms.com/docs/modules/capsules.html

Use the artisan command to install a capsule. The --copy flag copies files locally, while --require uses composer.

```bash
php artisan twill:capsule:install
```

```bash
php artisan twill:capsule:install area17/twill-capsule-redirections --copy --branch=main
```

--------------------------------

### Registering Blocks Directory

Source: https://twillcms.com/docs/api/3.x/A17/Twill/TwillPackageServiceProvider.html

Example of how to make block views publishable for end-user overrides when registering a blocks directory.

```php
  $this->publishes([
       __DIR__ . '/../resources/views' => resource_path('views/vendor/PACKAGE-NAME'),
  ]);
```

--------------------------------

### Retrieve default quick filters

Source: https://twillcms.com/docs/modules/table-builder.html

Call getDefaultQuickFilters to start with the standard set of filters before adding custom ones.

```php
1public function quickFilters(): QuickFilters
2{
3    return $this->getDefaultQuickFilters();
4}
```

--------------------------------

### Input Field Implementation Methods

Source: https://twillcms.com/docs/form-fields/input.html

Examples of defining input fields using the fluent builder, Blade components, and Blade directives.

```php
1Input::make()
2    ->name('subtitle')
3    ->label(twillTrans('Subtitle'))
4    ->maxLength(100)
5    ->required()
6    ->note(twillTrans('Field note'))
7    ->translatable()
8    ->placeholder(twillTrans('Placeholder'))
```

```blade
 1<x-twill::input
 2    name="subtitle"
 3    label="Subtitle"
 4    :maxlength="100"
 5    :required="true"
 6    note="Hint message goes here"
 7    placeholder="Placeholder goes here"
 8/>
 9 
10<x-twill::input
11    name="subtitle_translated"
12    label="Subtitle Translated"
13    :maxlength="100"
14    :required="true"
15    type="textarea"
16    :rows="3"
17    :translated="true"
18    direction="ltr"
19/>
```

```blade
 1@formField('input', [
 2    'name' => 'subtitle',
 3    'label' => 'Subtitle',
 4    'maxlength' => 100,
 5    'required' => true,
 6    'note' => 'Hint message goes here',
 7    'placeholder' => 'Placeholder goes here',
 8])
 9 
10@formField('input', [
11    'translated' => true,
12    'name' => 'subtitle_translated',
13    'label' => 'Subtitle (translated)',
14    'maxlength' => 250,
15    'required' => true,
16    'note' => 'Hint message goes here',
17    'placeholder' => 'Placeholder goes here',
18    'type' => 'textarea',
19    'rows' => 3,
20    'direction' => 'ltr'
21])
```

--------------------------------

### Example Block Class Structure

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Helpers/BlockRenderer.html

Visual representation of a nested block class hierarchy.

```text
TwoColumnsBlock
 ->children: [
     TextBlock: [
         ActionBlock
     ]
     ImageBlock: [
     ]
 ]
```

--------------------------------

### Database Migration for Unpacked Select

Source: https://twillcms.com/docs/form-fields/select.html

Example migration for storing values from an unpacked select field.

```php
1Schema::table('posts', function (Blueprint $table) {
2    ...
3    $table->string('discipline')->nullable();
4    ...
5});
```

--------------------------------

### Configure input form fields

Source: https://twillcms.com/docs/1.x

Examples of standard and translated input fields, including textarea configuration.

```blade
@formField('input', [
    'name' => 'subtitle',
    'label' => 'Subtitle',
    'maxlength' => 100,
    'required' => true,
    'note' => 'Hint message goes here',
    'placeholder' => 'Placeholder goes here',
])

@formField('input', [
    'translated' => true,
    'name' => 'subtitle_translated',
    'label' => 'Subtitle (translated)',
    'maxlength' => 250,
    'required' => true,
    'note' => 'Hint message goes here',
    'placeholder' => 'Placeholder goes here',
    'type' => 'textarea',
    'rows' => 3
])
```

--------------------------------

### Common Repeater Configuration Errors

Source: https://twillcms.com/docs/1.x

Examples of incorrect configurations that will prevent repeaters from functioning.

```php
        'repeaters' => [
            ...
            'accordion' => [
                'title' => 'Accordion',
                'trigger' => 'Add accordion',
                'component' => 'a17-block-accordion',
                'max' => 10,
            ],
            ...
        ]
```

```php
        'repeaters' => [
            ...
            'accordion-item' => [
                'title' => 'Accordion',
                'trigger' => 'Add accordion',
                'component' => 'a17-block-accordion_item',
                'max' => 10,
            ],
            ...
        ]
```

--------------------------------

### Configure Translatable Grouped Fields

Source: https://twillcms.com/docs/form-fields/field-grouping.html

Setup migration, model fillables, and casts for translatable grouped fields.

```php

 1## Add a migration
 2Schema::table('blog_translations', function (Blueprint $table) {
 3    $table->json('external_link')->nullable();
 4});
 5 
 6## Update your models fillable
 7class Blog extends Model {
 8    public $translatedAttributes = [
 9        ...
10        'external_link'
11    ];
12 
13    protected $fillable = [
14        ...
15        'external_link'
16    ];
17}
18 
19## Update your Translation model and add the cast
20public $casts = [
21    'external_link' => 'array',
22];
```

--------------------------------

### Configure Environment Variables

Source: https://twillcms.com/docs/1.x

Set up domain and path variables in the .env file for the admin console.

```text
APP_URL=domain.test
```

```text
# this is an example, use your own IP and domain
192.168.10.10 domain.test
192.168.10.10 admin.domain.test
```

```text
ADMIN_APP_URL=manage.domain.test
```

```text
APP_URL=domain.test
ADMIN_APP_URL=domain.test
ADMIN_APP_PATH=admin
```

```text
SESSION_DOMAIN=.domain.test
```

--------------------------------

### Get Image URL

Source: https://twillcms.com/docs/block-editor/creating-a-block-editor.html

Retrieve an image URL using the image helper.

```blade
1{{ $image('cover', 'default', ['h' => 100) }}
```

--------------------------------

### Boot HasMedias Trait

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Models/Block.html

Initializes the HasMedias trait functionality.

```php
static            void     **bootHasMedias**()
```

--------------------------------

### Run Migrations

Source: https://twillcms.com/docs/form-fields/repeater.html

Execute the database migrations.

```bash
1php artisan migrate
```

--------------------------------

### Get Field Options

Source: https://twillcms.com/docs/api/3.x/A17/Twill/View/Components/Fields/MultiSelect.html

Retrieves the array of options available for selection in the component.

```php
array     getOptions()
```

--------------------------------

### Execute Upgrade Command

Source: https://twillcms.com/docs/getting-started/upgrading.html

Run the provided upgrade script to automate namespace, view, route, and configuration migrations.

```bash
1php ./vendor/area17/twill/upgrade.php
```

--------------------------------

### Configure Imgix Service

Source: https://twillcms.com/docs/getting-started/configuration.html

Set the media library to use the Imgix service and specify the source host.

```text
1MEDIA_LIBRARY_IMAGE_SERVICE="A17\Twill\Services\MediaLibrary\Imgix"
2IMGIX_SOURCE_HOST=source.imgix.net
```

--------------------------------

### Install Twill via Composer

Source: https://twillcms.com/docs/1.x

Use Composer to add the Twill package to your Laravel application.

```bash
composer require area17/twill:"1.2.*"
```

--------------------------------

### Create the controller

Source: https://twillcms.com/docs/custom-cms-pages/index.html

Implement the controller to handle the request and return the custom view.

```php
// file: app/Http/Controllers/Twill/CustomPageController.php
 
namespace App\Http\Controllers\Twill;
 
use A17\Twill\Http\Controllers\Admin\Controller;
 
class CustomPageController extends Controller
{
    public function show()
    {
        return view('twill.customPage');
    }
}
```

--------------------------------

### Get Twill directory path

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Commands/Release.html

Retrieves the path to the Twill directory, optionally appending a sub-path.

```php
string getTwillDir(string $path = '')
```

--------------------------------

### Constructor

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Helpers/BlockRenderer.html

Initializes the BlockRenderer with data.

```php
__construct(array $data)
```

--------------------------------

### Browser::browser

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Services/Listings/Columns/Browser.html

Initializes a new Browser column instance.

```APIDOC
## Browser::browser(string $browser)

### Description
Initializes a new Browser column instance.

### Parameters
- **$browser** (string) - Required - The name of the browser.

### Return Value
- **Browser** - The initialized Browser instance.
```

--------------------------------

### Localize Permalink Base

Source: https://twillcms.com/docs/modules/controllers.html

Use getLocalizedPermalinkBase to define language-specific permalink bases in a multilingual setup.

```php
protected function getLocalizedPermalinkBase()
{
    return [
        'en' => 'page',
        'nl' => 'pagina',
    ];
}
```

--------------------------------

### Configure Non-Translatable Grouped Fields

Source: https://twillcms.com/docs/form-fields/field-grouping.html

Setup migration and model fillables for non-translatable grouped fields.

```php

 1## Add a migration
 2Schema::table('blogs', function (Blueprint $table) {
 3    $table->json('external_link')->nullable();
 4});
 5 
 6## Update your models fillable
 7class Blog extends Model {
 8    protected $fillable = [
 9        ...
10        'external_link'
11    ];
12}
```

--------------------------------

### Authenticate a user in Dusk

Source: https://twillcms.com/docs/testing/index.html

Use the superadmin command to create a user and log in via the browser helper.

```php
1$this->artisan('twill:superadmin user@example.org password');
2 
3$this->browse(function(Browser $browser) {
4    $browser->loginAs(\App\Models\User::firstWhere('email', 'user@example.org'), 'twill_users');
5});
```

--------------------------------

### Configure Local Storage Endpoint

Source: https://twillcms.com/docs/1.x

Environment variables to enable local storage and define the upload directory path.

```bash
MEDIA_LIBRARY_ENDPOINT_TYPE=local
MEDIA_LIBRARY_LOCAL_PATH=uploads/
```

--------------------------------

### Define a simple block with Blade

Source: https://twillcms.com/docs/block-editor/creating-a-block-editor.html

A basic example of a quote block using mandatory title and icon annotations.

```blade
 1@twillBlockTitle('Quote')
 2@twillBlockIcon('text')
 3 
 4<x-twill::input
 5    name="quote"
 6    type="textarea"
 7    label="Quote text"
 8    :maxlength="250"
 9    :rows="4"
10/>
```

--------------------------------

### Retrieve Media Parameters

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Models/Block.html

Retrieves the configuration parameters for media.

```php
array     **getMediasParams**()
```

--------------------------------

### Map Data Storage Formats

Source: https://twillcms.com/docs/form-fields/map.html

Examples of the JSON structure stored in the database for default and extended map data.

```json
{
  "latlng": "48.85661400000001|2.3522219",
  "address": "Paris, France"
}
```

```json
{
  "latlng": "51.1808302|-2.256022799999999",
  "address": "Warminster BA12 7LG, United Kingdom",
  "types": [
    "point_of_interest",
    "establishment"
  ],
  "boundingBox": {
    "east": -2.25289275,
    "west": -2.257066149999999,
    "north": 51.18158853029149,
    "south": 51.17889056970849
  }
}
```

--------------------------------

### Configure Imgix Source Host

Source: https://twillcms.com/docs/1.x

Set the Imgix source URL using an environment variable.

```text
IMGIX_SOURCE_HOST=source.imgix.net

```

--------------------------------

### Define File Form Fields

Source: https://twillcms.com/docs/1.x

Examples of using the files form field with different translation and count configurations.

```blade
@formField('files', [
    'name' => 'single_file',
    'label' => 'Single file',
    'note' => 'Add one file (per language)'
])

@formField('files', [
    'name' => 'single_file_no_translate',
    'label' => 'Single file (no translate)',
    'note' => 'Add one file',
    'noTranslate' => true,
])

@formField('files', [
    'name' => 'files',
    'label' => 'Files',
    'noTranslate' => true,
    'max' => 4,
])
```

--------------------------------

### Visit a module entry

Source: https://twillcms.com/docs/testing/index.html

Navigate to an existing module entry page.

```php
1$this->browse(function(Browser $browser) {
2    $browser->visitTwill();
3    $browser->visitModuleEntryWithTitle('Partners', 'Twill');
4});
```

--------------------------------

### Browser field implementation methods

Source: https://twillcms.com/docs/form-fields/browser.html

Examples of defining a browser field using FormBuilder, Blade components, and the formField directive.

```php
1Browser::make()
2    ->modules([Publications::class])
3    ->name('publications')
4    ->max(4);
```

```blade
1<x-twill::browser
2    module-name="publications"
3    name="publications"
4    label="Publications"
5    :max="4"
6/>
```

```php
1@formField('browser', [
2    'moduleName' => 'publications',
3    'name' => 'publications',
4    'label' => 'Publications',
5    'max' => 4,
6])
```

--------------------------------

### Configure Hosts File for Subdomains

Source: https://twillcms.com/docs/getting-started/installation.html

Map subdomains to the local IP address in the hosts file for development environments.

```bash
# this is an example, use your own IP and domain
192.168.10.10 domain.test
192.168.10.10 admin.domain.test
```

--------------------------------

### Define a Repeater Field

Source: https://twillcms.com/docs/form-fields/repeater.html

Basic implementation examples for defining a repeater field using different Twill syntax styles.

```php
1Repeater::make()
    ->type('video')
```

```blade
1<x-twill::repeater
    type="video"
/>
```

```blade
1@formField('repeater', ['type' => 'video'])
```

--------------------------------

### Configure Local Media Library Service

Source: https://twillcms.com/docs/getting-started/configuration.html

Set the media library endpoint and image service to local mode using environment variables.

```text
1MEDIA_LIBRARY_ENDPOINT_TYPE=local
2MEDIA_LIBRARY_IMAGE_SERVICE="A17\Twill\Services\MediaLibrary\Glide"
```

--------------------------------

### Define Bucket Configuration

Source: https://twillcms.com/docs/buckets/index.html

Configure bucket zones, bucketables, and item limits within the buckets array in your configuration file.

```php
 1'buckets' => [
 2    'homepage' => [
 3        'name' => 'Home',
 4        'buckets' => [
 5            'home_primary_feature' => [
 6                'name' => 'Home primary feature',
 7                'bucketables' => [
 8                    [
 9                        'module' => 'guides',
10                        'name' => 'Guides',
11                        'scopes' => ['published' => true],
12                    ],
13                ],
14                'max_items' => 1,
15            ],
16            'home_secondary_features' => [
17                'name' => 'Home secondary features',
18                'bucketables' => [
19                    [
20                        'module' => 'guides',
21                        'name' => 'Guides',
22                        'scopes' => ['published' => true],
23                    ],
24                ],
25                'max_items' => 10,
26            ],
27        ],
28    ],
29],
```

--------------------------------

### Conditional Fields Implementation

Source: https://twillcms.com/docs/form-fields/conditional-fields.html

Example showing how to use formConnectedFields to conditionally display inputs based on a browser field selection.

```blade
<x-twill::browser
    module-name="publication"
    name="related_publications"
    label="Related publications"
    :max="4"
/>
 
<x-twill::formConnectedFields
    field-name="publication"
    :is-browser="true"
    :keep-alive="true"
>
    <x-twill::input
        name="related_publications_header"
        label="Related publications header"
    />
    <x-twill::input
        name="related_publications_copy"
        label="Related publications copy"
    />
</x-twill::formConnectedFields>
```

--------------------------------

### Configure Imgix image rendering service

Source: https://twillcms.com/docs/getting-started/installation.html

Environment variables to enable Imgix for responsive image rendering.

```bash
MEDIA_LIBRARY_IMAGE_SERVICE="A17\Twill\Services\MediaLibrary\Imgix"
IMGIX_SOURCE_HOST=source.imgix.net
```

--------------------------------

### Define a complex block with multiple fields

Source: https://twillcms.com/docs/block-editor/creating-a-block-editor.html

A more advanced block example incorporating media, file, select, and color input components.

```blade
 1@twillBlockTitle('Media')
 2@twillBlockIcon('image')
 3 
 4<x-twill::medias
 5    name="image"
 6    label="Images"
 7    :max="20"
 8/>
 9 
10<x-twill:files
11    name="video"
12    label="video"
13    note="Video will overwrite previously selected images"
14    :max="1"
15/>
16 
17<x-twill::input
18    name="caption"
19    label="Caption"
20    :maxlength="250"
21    :translated="true"
22/>
23 
24@php
25    $options = [
26        [
27            'value' => 'cut',
28            'label' => 'Cut'
29        ],
30        [
31            'value' => 'fade',
32            'label' => 'Fade In/Out'
33        ]
34    ];
35@endphp
36 
37<x-twill::select
38    name="effect"
39    label="Transition effect"
40    placeholder="Select transition effect"
41    default="cut"
42    :options="$options"
43/>
44 
45<x-twill::color
46    name="bg"
47    label="Background color"
48    note="Default is light grey (#E6E6E6)"
49/>
50 
51<x-twill::input
52    name="timing"
53    label="Timing"
54    note="Timing in ms (default is 4000ms)"
55/>
```

--------------------------------

### Generate Module and Migration for Dynamic Values

Source: https://twillcms.com/docs/form-fields/multi-select.html

Commands to create the necessary module and pivot table for dynamic relationship-based multi-select.

```bash
php artisan twill:make:module sectors
```

```bash
php artisan make:migration create_post_sector_table
```

--------------------------------

### Create Migration for Metadata Fields

Source: https://twillcms.com/docs/media-library/custom-metadata.html

Add the corresponding columns to the media table, using text for regular fields and json for translatable ones.

```php
 1<?php
 2 
 3use Illuminate\Database\Migrations\Migration;
 4use Illuminate\Database\Schema\Blueprint;
 5use Illuminate\Support\Facades\Schema;
 6 
 7return new class extends Migration
 8{
 9    public function up()
10    {
11        Schema::table(config('twill.medias_table', 'twill_medias'), function (Blueprint $table) {
12            $table->text('source')->nullable();
13            $table->json('attribution')->nullable();
14        });
15    }
16 
17    public function down()
18    {
19        Schema::table(config('twill.medias_table', 'twill_medias'), function (Blueprint $table) {
20            $table->dropColumn('source');
21            $table->dropColumn('attribution');
22        });
23    }
24};
```

--------------------------------

### Configure WYSIWYG form fields

Source: https://twillcms.com/docs/1.x

Examples of WYSIWYG fields using Quill editor, including basic toolbar options and advanced configurations.

```blade
@formField('wysiwyg', [
    'name' => 'case_study',
    'label' => 'Case study text',
    'toolbarOptions' => ['list-ordered', 'list-unordered'],
    'placeholder' => 'Case study text',
    'maxlength' => 200,
    'note' => 'Hint message',
])

@formField('wysiwyg', [
    'name' => 'case_study',
    'label' => 'Case study text',
    'toolbarOptions' => [ [ 'header' => [1, 2, false] ], 'list-ordered', 'list-unordered', [ 'indent' => '-1'], [ 'indent' => '+1' ] ],
    'placeholder' => 'Case study text',
    'maxlength' => 200,
    'editSource' => true,
    'note' => 'Hint message',
])
```

```blade
 @formField('wysiwyg', [
    'name' => 'case_study',
    'label' => 'Case study text',
    'toolbarOptions' => [ 
      ["font" => ["serif", "sans-serif", "monospace"]],
      ['header' => [2, 3, 4, 5, 6, false]],
      'bold',
      'italic',
      'underline',
      'strike',
      ["color" => []],
      ["background" => []],
      ["script" => "super"],
      ["script" => "sub"],
      "blockquote",
      "code-block",
      ['list' => 'ordered'],
      ['list' => 'bullet'],
      ['indent' => '-1'],
      ['indent' => '+1'],
      ["align" => []],
      ["direction" => "rtl"],
      'link',
      'image',
      'video',
      "clean",
    ],
    'placeholder' => 'Case study text',
    'maxlength' => 200,
    'editSource' => true,
    'note' => 'Hint message`',
 ])
```

--------------------------------

### Render blocks in Blade templates

Source: https://twillcms.com/docs/1.x

Use the renderBlocks helper on a model instance to render CMS-created blocks. The first example renders all blocks, while the second disables child block rendering.

```blade
{!! $item->renderBlocks() !!}
```

```blade
{!! $work->renderBlocks(false) !!}
```

--------------------------------

### Configure Permission Levels and Modules

Source: https://twillcms.com/docs/user-management/advanced-permissions.html

Set the desired permission level and define which modules are subject to permission management.

```php
<?php
 
return [
  'enabled' => [
    'permissions-management'
  ],
  'permissions' => [
      'level' => \A17\Twill\Enums\PermissionLevel::LEVEL_ROLE,
      'modules' => ['blogs'],
  ],
]
```

--------------------------------

### Configure Module File Parameters

Source: https://twillcms.com/docs/1.x

Define the file roles in the module model.

```php
public $filesParams = ['file_role', ...]; // a list of file roles
```

--------------------------------

### Configure Media Library Settings

Source: https://twillcms.com/docs/getting-started/configuration.html

The default configuration array for the media library, defining disk, endpoint type, and service options.

```php
<?php
 
return [
    'media_library' => [
        'disk' => 'twill_media_library',
        'endpoint_type' => env('MEDIA_LIBRARY_ENDPOINT_TYPE', 'local'),
        'cascade_delete' => env('MEDIA_LIBRARY_CASCADE_DELETE', false),
        'local_path' => env('MEDIA_LIBRARY_LOCAL_PATH', 'uploads'),
        'image_service' => env('MEDIA_LIBRARY_IMAGE_SERVICE', 'A17\Twill\Services\MediaLibrary\Glide'),
        'acl' => env('MEDIA_LIBRARY_ACL', 'private'),
        'filesize_limit' => env('MEDIA_LIBRARY_FILESIZE_LIMIT', 50),
        'allowed_extensions' => ['svg', 'jpg', 'gif', 'png', 'jpeg'],
        'init_alt_text_from_filename' => true,
        'prefix_uuid_with_local_path' => config('twill.file_library.prefix_uuid_with_local_path', false),
        'translated_form_fields' => false,
        'show_file_name' => false,
        'media_caption_use_wysiwyg' => false,
        'media_caption_wysiwyg_options' => [
            'modules' => [
                'toolbar' => [
                    'bold',
                    'italic',
                ],
            ],
        ],
    ],
];
```

--------------------------------

### Configure S3 Storage Endpoint

Source: https://twillcms.com/docs/getting-started/configuration.html

Environment variables for AWS S3 or S3-compliant storage providers like Minio.

```bash
MEDIA_LIBRARY_ENDPOINT_TYPE=s3
S3_KEY=S3_KEY
S3_SECRET=S3_SECRET
S3_BUCKET=bucket-name
```

```bash
S3_KEY=S3_KEY
S3_SECRET=S3_SECRET
S3_BUCKET=bucket-name
S3_ENDPOINT=https://YOUR_S3_DOMAIN
```

--------------------------------

### Configure Media Library in config/twill.php

Source: https://twillcms.com/docs/1.x

Defines the default media library settings, including disk, endpoint type, and allowed file extensions.

```php
<?php

return [
    'media_library' => [
        'disk' => 'libraries',
        'endpoint_type' => env('MEDIA_LIBRARY_ENDPOINT_TYPE', 's3'),
        'cascade_delete' => env('MEDIA_LIBRARY_CASCADE_DELETE', false),
        'local_path' => env('MEDIA_LIBRARY_LOCAL_PATH'),
        'image_service' => env('MEDIA_LIBRARY_IMAGE_SERVICE', 'A17\Twill\Services\MediaLibrary\Imgix'),
        'acl' => env('MEDIA_LIBRARY_ACL', 'private'),
        'filesize_limit' => env('MEDIA_LIBRARY_FILESIZE_LIMIT', 50),
        'allowed_extensions' => ['svg', 'jpg', 'gif', 'png', 'jpeg'],
        'init_alt_text_from_filename' => true,
        'translated_form_fields' => false,
    ],
];
```

--------------------------------

### Enable Imgix Signed URLs

Source: https://twillcms.com/docs/1.x

Enable signed URLs and provide the signature key via environment variables to secure image access.

```text
IMGIX_USE_SIGNED_URLS=true
IMGIX_SIGN_KEY=xxxxxxxxxxxxxxxx

```

--------------------------------

### Use Layout and Partial Utilities

Source: https://twillcms.com/docs/modules/form-builder.html

Organize fields into columns or inject custom Blade partials.

```php
Columns::make()
    ->left([
        Input::make()
            ->name('description')
            ->translatable(),
    ])
    ->right([
        Input::make()
            ->name('subtitle')
            ->translatable(),
    ]),
```

```php
BladePartial::make()->view('twill.fields.field-under-condition')
```

--------------------------------

### Retrieve setting values

Source: https://twillcms.com/docs/1.x

Use the SettingRepository to fetch stored setting values by their key.

```php
<?php

use A17\Twill\Repositories\SettingRepository;
...

app(SettingRepository::class)->byKey('site_title');
app(SettingRepository::class)->byKey('site_title', 'section_name');
```

--------------------------------

### Create a module entry

Source: https://twillcms.com/docs/testing/index.html

Create a new entry for a specific module by title.

```php
1$this->browse(function(Browser $browser) {
2    $browser->visitTwill();
3    $browser->createModuleEntryWithTitle('Partners', 'Twill');
4});
```

--------------------------------

### Define Navigation via OOP Method

Source: https://twillcms.com/docs/getting-started/navigation.html

Register navigation links within the boot method of your AppServiceProvider using the TwillNavigation facade.

```php
 1use A17\Twill\Facades\TwillNavigation;
 2use A17\Twill\View\Components\Navigation\NavigationLink;
 3 
 4public function boot(): void
 5{
 6    TwillNavigation::addLink(
 7        NavigationLink::make()->forModule('pages')
 8    );
 9    TwillNavigation::addLink(
10        NavigationLink::make()->forModule('projects')
11          ->setChildren([
12            NavigationLink::make()->forModule('projects')
13              ->setChildren([
14                NavigationLink::make()->forModule('projectCustomers'),
15              ]),
16            NavigationLink::make()->forModule('clients'),
17            NavigationLink::make()->forModule('industries'),
18            NavigationLink::make()->forModule('studios'),
19          ]),
20    );
21}
```

--------------------------------

### Generate a New Singleton

Source: https://twillcms.com/docs/artisan-commands/index.html

Scaffolds a new singleton module for Twill.

```bash
 1php artisan twill:make:singleton {moduleName}
 2  {--B|hasBlocks}
 3  {--T|hasTranslation}
 4  {--S|hasSlug}
 5  {--M|hasMedias}
 6  {--F|hasFiles}
 7  {--R|hasRevisions}
 8  {--E|generatePreview}
 9  {--bladeForm}
10  {--all}
11  {--force}
12  {--factory}
13  {--packageDirectory=}
14  {--packageNamespace=}
15  {--parentModel=}
```

--------------------------------

### Define Module Routes with Macros

Source: https://twillcms.com/docs/1.x

Use the Route::module macro to quickly generate standard module routes and control available actions.

```php
<?php

Route::module('yourModulePluralName');

// You can add an array of only/except action names as a second parameter
// By default, the following routes are created : 'reorder', 'publish', 'browser', 'bucket', 'feature', 'restore', 'bulkFeature', 'bulkPublish', 'bulkDelete', 'bulkRestore'
Route::module('yourModulePluralName', ['except' => ['reorder', 'feature', 'bucket', 'browser']])

// You can add an array of only/except action names for the resource controller as a third parameter
// By default, the following routes are created : 'index', 'store', 'show', 'edit', 'update', 'destroy'
Route::module('yourModulePluralName', [], ['only' => ['index', 'edit', 'store', 'destroy']])

// The last optional parameter disable the resource controller actions on the module
Route::module('yourPluralModuleName', [], [], false)
```

--------------------------------

### Define Imgix Configuration Array

Source: https://twillcms.com/docs/1.x

Full configuration structure for Imgix, including default transformation parameters and environment variable mappings.

```php
<?php

return [
    'imgix' => [
        'default_params' => [
            'fm' => 'jpg',
            'q' => '80',
            'auto' => 'compress,format',
            'fit' => 'min',
        ],
        'lqip_default_params' => [
            'fm' => 'gif',
            'auto' => 'compress',
            'blur' => 100,
            'dpr' => 1,
        ],
        'social_default_params' => [
            'fm' => 'jpg',
            'w' => 900,
            'h' => 470,
            'fit' => 'crop',
            'crop' => 'entropy',
        ],
        'cms_default_params' => [
            'q' => 60,
            'dpr' => 1,
        ],
        'source_host' => env('IMGIX_SOURCE_HOST'),
        'use_https' => env('IMGIX_USE_HTTPS', true),
        'use_signed_urls' => env('IMGIX_USE_SIGNED_URLS', false),
        'sign_key' => env('IMGIX_SIGN_KEY'),
    ],
];

```

--------------------------------

### Wysiwyg::customTheme

Source: https://twillcms.com/docs/api/main/A17/Twill/Services/Forms/Fields/Wysiwyg.html

Sets a custom theme for the syntax highlighter.

```APIDOC
## Wysiwyg::customTheme(string $customTheme)

### Description
Set a custom theme for the syntax highlighter.

### Parameters
- **$customTheme** (string) - Required - The theme name.
```

--------------------------------

### Wysiwyg::syntax

Source: https://twillcms.com/docs/api/main/A17/Twill/Services/Forms/Fields/Wysiwyg.html

Enables syntax highlighting.

```APIDOC
## Wysiwyg::syntax(bool $syntax = true)

### Description
Enables syntax highlight.

### Parameters
- **$syntax** (bool) - Optional - Whether to enable syntax highlighting.
```

--------------------------------

### Configure Admin Console URL and Path

Source: https://twillcms.com/docs/1.x

Define the URL and path for the Twill admin console using environment variables.

```php
<?php

return [
    'admin_app_url' => env('ADMIN_APP_URL', 'admin.' . env('APP_URL')),
    'admin_app_path' => env('ADMIN_APP_PATH', ''),
];
```

--------------------------------

### Implement Preview Data

Source: https://twillcms.com/docs/1.x

Pass additional data to the preview view by implementing the previewData method.

```php
<?php
...
protected function previewData($item)
{
    return [
        'project' => $item,
        'setting_name' => $settingRepository->byKey('setting_name')
    ];
}
```

--------------------------------

### Configure Auto Login Credentials

Source: https://twillcms.com/docs/user-management/index.html

Set the email and password in the .env file to bypass the login form.

```env
TWILL_AUTO_LOGIN_EMAIL=email@email.com
TWILL_AUTO_LOGIN_PASSWORD=passv0rt
```

--------------------------------

### Repository Field Handling

Source: https://twillcms.com/docs/form-fields/browser.html

Implement repository methods to prepare fields before creation and saving, and to retrieve form fields for the browser.

```php

 1// Prepare the fields.
 2public function prepareFieldsBeforeCreate($fields)
 3{
 4    $fields = parent::prepareFieldsBeforeCreate($fields);
 5    $fields['linkable_id'] = Arr::get($fields, 'browsers.linkables.0.id', null);
 6    $fields['linkable_type'] = Arr::get($fields, 'browsers.linkables.0.endpointType', null);
 7 
 8    return $fields;
 9}
10 
11// On save we set the linkable id and type.
12public function prepareFieldsBeforeSave($object, $fields)
13{
14    $fields = parent::prepareFieldsBeforeSave($object, $fields);
15 
16    $id = Arr::get($fields, 'browsers.linkables.0.id', null);
17    $type = Arr::get($fields, 'browsers.linkables.0.endpointType', null);
18 
19    if ($id) {
20        $fields['linkable_id'] = $id;
21    }
22    if ($type) {
23        $fields['linkable_type'] = $type;
24    }
25 
26    return $fields;
27}
28 
29// Set the browser value to our morphed data.
30public function getFormFields($object)
31{
32    $fields = parent::getFormFields($object);
33 
34    $linkable = $object->linkable;
35 
36    if ($linkable) {
37        $fields['browsers']['linkables'] = collect([
38            [
39                'id' => $linkable->id,
40                'name' => $linkable->title,
41                'edit' => moduleRoute($object->linkable->getTable(), 'content', 'edit', $linkable->id),
42                'thumbnail' => $linkable->defaultCmsImage(['w' => 100, 'h' => 100]),
43            ],
44        ])->toArray();
45    }
46 
47    return $fields;
48}

```

--------------------------------

### Configure Frontend Preview Path

Source: https://twillcms.com/docs/1.x

Set a custom path for frontend preview views in the Twill configuration.

```php
return [
    'frontend' => [
        'views_path' => 'site',
    ],
    ...
];
```

--------------------------------

### Generate a new module via Artisan

Source: https://twillcms.com/docs/modules/cli-generator.html

Use this command to scaffold the necessary files for a new module. Options can be appended to include features like blocks, translations, slugs, and media support.

```bash
php artisan twill:make:module moduleName
```

--------------------------------

### Enable User Activity Logging

Source: https://twillcms.com/docs/dashboard/index.html

Enable login and logout tracking by setting the corresponding configuration keys in config/twill.php.

```text

1twill.dashboard.auth_activity_log.login => true
2twill.dashboard.auth_activity_log.logout => true

```

```php

 1<?php
 2 
 3return [
 4    'dashboard' => [
 5        'auth_activity_log' => [
 6            'login' => true,
 7            'logout' => true
 8        ]
 9    ]
10]

```

--------------------------------

### Render Method

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Helpers/BlockRenderer.html

Renders the blocks using optional view mappings and data.

```php
string     render(array $blockViewMappings = [], array $data = [])
```

--------------------------------

### Configure Migration Settings

Source: https://twillcms.com/docs/getting-started/configuration.html

Control migration behavior, including big integer usage and default migration loading.

```php
<?php
 
return [
    'migrations_use_big_integers' => true,
];
```

```php
<?php
 
return [
    'load_default_migrations' => true,
];
```

--------------------------------

### Define Legacy Migration Methods

Source: https://twillcms.com/docs/getting-started/upgrading.html

Reference implementation for twillIncrementsMethod and twillIntegerMethod if custom logic requires these removed functions.

```php
 1if (!function_exists('twillIncrementsMethod')) {
 2    /**
 3     * @return string
 4     */
 5    function twillIncrementsMethod()
 6    {
 7        return config('twill.migrations_use_big_integers')
 8            ? 'bigIncrements'
 9            : 'increments';
10    }
11}
12 
13if (!function_exists('twillIntegerMethod')) {
14    /**
15     * @return string
16     */
17    function twillIntegerMethod()
18    {
19        return config('twill.migrations_use_big_integers')
20            ? 'bigInteger'
21            : 'integer';
22    }
23}
```

--------------------------------

### Link::shouldOpenInNewWindow

Source: https://twillcms.com/docs/api/3.x/A17/Twill/Services/Listings/Columns/Link.html

Configures whether the link should open in a new window.

```APIDOC
## Link::shouldOpenInNewWindow

### Description
Configures whether the link should open in a new window.

### Parameters
- **$shouldOpenInNewWindow** (bool) - Optional - Whether to open in a new window (default: true).
```

--------------------------------

### Configure Module Controller for Nested UI

Source: https://twillcms.com/docs/1.x

Enable nested listing and define transformation logic in the module controller.

```php
protected $indexOptions = [
    'reorder' => true,
];

protected function indexData($request)
{
    return [
        'nested' => true,
        'nestedDepth' => 2, // this controls the allowed depth in UI
    ];
}

protected function transformIndexItems($items)
{
    return $items->toTree();
}

protected function indexItemData($item)
{
    return ($item->children ? [
        'children' => $this->getIndexTableData($item->children),
    ] : []);
}
```

--------------------------------

### Configure Local Media Storage

Source: https://twillcms.com/docs/1.x

Environment variables for using local storage and Glide for image rendering.

```env
MEDIA_LIBRARY_ENDPOINT_TYPE=local
MEDIA_LIBRARY_IMAGE_SERVICE=A17\Twill\Services\MediaLibrary\Glide

```

--------------------------------

### Create a package capsule

Source: https://twillcms.com/docs/packages/creating-a-package.html

Add a new module or singleton capsule to your package using the artisan command.

```bash
php artisan twill:make:capsule YourModel --singleton --packageDirectory=./packages/twill-extension --packageNamespace=TwillExtension\\YourModel
```

```bash
php artisan twill:make:capsule Project --packageDirectory=./packages/twill-extension --packageNamespace=TwillExtension\\Project
```

--------------------------------

### Build Twill Admin Console Assets

Source: https://twillcms.com/docs/1.x

Command to execute the build process for Twill admin assets.

```bash
npm run twill-build

```

--------------------------------

### Configure search columns in ModuleController

Source: https://twillcms.com/docs/modules/table-builder.html

Use setSearchColumns within the setUpController method to define which fields are searchable in the listing.

```php
 1namespace App\Http\Controllers\Twill;
 2
 3use A17\Twill\Http\Controllers\Admin\ModuleController;
 4
 5class ProjectController extends BaseModuleController
 6{
 7    ...
 8
 9    public function setUpController(): void
10    {
11        $this->setSearchColumns(['title', 'year']);
12    }
13}
```

--------------------------------

### Configure browser modules for internal linking

Source: https://twillcms.com/docs/form-fields/wysiwyg.html

Use browserModules to enable internal content selection within the wysiwyg field.

```php
Wysiwyg::make()
    ->name('description')
    ->label('Description')
    ->translatable()
    ->browserModules([Page::class])
```

--------------------------------

### Configure Browser Route Prefixes

Source: https://twillcms.com/docs/1.x

Define route prefixes for browser fields in the configuration.

```php
    'block_editor' => [
        'blocks' => [
            ...
            'product' => [
                'title' => 'Product',
                'icon' => 'text',
                'component' => 'a17-block-products',
            ],
            ...
        ],
        'repeaters' => [
                ...
        ],
        'browser_route_prefixes' => [
            'products' => 'content',
        ],
    ]
```

--------------------------------

### Configure Azure Storage Endpoint

Source: https://twillcms.com/docs/getting-started/configuration.html

Environment variables required to authorize uploads to a Microsoft Azure container.

```bash
MEDIA_LIBRARY_ENDPOINT_TYPE=azure
 
AZURE_ACCOUNT_KEY=AZURE_ACCOUNT_KEY
AZURE_ACCOUNT_NAME=AZURE_ACCOUNT_NAME
AZURE_CONTAINER=AZURE_CONTAINER
```

--------------------------------

### Add Development Scripts

Source: https://twillcms.com/docs/1.x

NPM scripts to enable development mode with hot reloading for Twill.

```json
"scripts": {
  "twill-dev": "mkdir -p vendor/area17/twill/public && npm run twill-copy-blocks && concurrently \"cd vendor/area17/twill && npm ci && npm run hot\" \"npm run twill-watch\" && npm run twill-clean-blocks",
  "twill-watch": "concurrently \"watch 'npm run twill-hot' vendor/area17/twill/public --wait=2 --interval=0.1\" \"npm run twill-watch-blocks\"",
  "twill-hot": "cd vendor/area17/twill && cp -R public/* ${INIT_CWD}/public",
  "twill-watch-blocks": "watch 'npm run twill-copy-blocks' resources/assets/js/blocks --wait=2 --interval=0.1"
}
```

--------------------------------

### Configure local package repository

Source: https://twillcms.com/docs/packages/creating-a-package.html

Add the generated package to your project's composer.json to enable local development.

```json
"repositories": [
    {
        "type": "path",
        "url": "./packages/twill-extension"
    },
],
```

--------------------------------

### Configure block editor settings

Source: https://twillcms.com/docs/1.x

Define block components, paths, and crop configurations in the Twill configuration file.

```php
return [
    'block_editor' => [
        'block_single_layout' => 'site.layouts.block',
        'block_views_path' => 'site.blocks',
        'block_views_mappings' => [],
        'block_preview_render_childs' => true,
        'blocks' => [
            'text' => [
                'title' => 'Body text',
                'icon' => 'text',
                'component' => 'a17-block-wysiwyg',
            ],
            'image' => [
                'title' => 'Image',
                'icon' => 'image',
                'component' => 'a17-block-image',
            ],
        ],
        'crops' => [
            'image' => [
                'desktop' => [
                    [
                        'name' => 'desktop',
                        'ratio' => 16 / 9,
                        'minValues' => [
                            'width' => 100,
                            'height' => 100,
                        ],
                    ],
                ],
                'tablet' => [
                    [
                        'name' => 'tablet',
                        'ratio' => 4 / 3,
                        'minValues' => [
                            'width' => 100,
                            'height' => 100,
                        ],
                    ],
                ],
                'mobile' => [
                    [
                        'name' => 'mobile',
                        'ratio' => 1,
                        'minValues' => [
                            'width' => 100,
                            'height' => 100,
                        ],
                    ],
                ],
            ],
        ],
    ],
    ...
];
```

--------------------------------

### Press save and verify

Source: https://twillcms.com/docs/testing/index.html

Trigger the save action and confirm the operation was successful.

```php
1$this->browse(function(Browser $browser) {
2    $browser->visitTwill();
3    $browser->visitModuleEntryWithTitle('Partners', 'Twill');
4    $browser->pressSaveAndCheckSaved();
5});
```

--------------------------------

### Generate block Vue components

Source: https://twillcms.com/docs/1.x

Run the artisan command to generate necessary Vue components for defined blocks.

```bash
$ php artisan twill:blocks
Starting to scan block views directory...
Block Quote generated successfully
All blocks have been generated!
$
```

--------------------------------

### Configure AWS S3 Media Storage

Source: https://twillcms.com/docs/1.x

Environment variables for using AWS S3 and imgix for media storage and rendering.

```env
S3_KEY=S3_KEY
S3_SECRET=S3_SECRET
S3_BUCKET=bucket-name

IMGIX_SOURCE_HOST=source.imgix.net

```

--------------------------------

### Visit the Twill admin panel

Source: https://twillcms.com/docs/testing/index.html

Navigate to the admin panel using the visitTwill helper.

```php
1$this->browse(function(Browser $browser) {
2    $browser->visitTwill();
3});
```
Tokens:
Raw