### Install Basic Page Builder Example

Source: https://github.com/area17/twill/blob/3.x/examples/basic-page-builder/README.md

Installs the basic-page-builder example into your Laravel project using the Twill installer command.

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

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

### Setup Controller Example

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/5_controllers.md

Demonstrates how to set up a module controller by enabling specific features like showing images.

```php
<?php

namespace App\Http\Controllers\Twill;

class ProjectController extends ModuleController
{
    protected $moduleName = 'projects';
    
    public function setUpController(): void
    {
        $this->enableShowImage();
    }
}
```

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

### Install Twill Starter Kit

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Use this command to install the basic page builder starter kit for Twill. This command will migrate your database.

```bash
composer require area17/twill:"^3.4"
```

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

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

### Install Dependencies

Source: https://github.com/area17/twill/blob/3.x/docs-api/README.md

Run this command in the 'docs-api' directory to install project dependencies using Composer.

```bash
cd docs-api
composer install
```

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

### Install Twill with Preset

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/16_artisan-commands/index.md

Installs Twill with core migrations and creates a superadmin user. Run only once.

```bash
php artisan twill:install {preset?} {--fromBuild}
```

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

### Create New Laravel Project

Source: https://github.com/area17/twill/blob/3.x/examples/basic-page-builder/README.md

Installs a new Laravel project using Composer. This is the first step before installing Twill and the example.

```bash
composer create-project laravel/laravel laravel-twill
cd laravel-twill
```

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

### Install Node and Composer Dependencies

Source: https://github.com/area17/twill/blob/3.x/docs/readme.md

Install project dependencies using npm and composer.

```bash
npm i
composer install
```

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

### Install Frontend Dependencies and Build

Source: https://github.com/area17/twill/blob/3.x/examples/basic-page-builder/README.md

Installs frontend dependencies using npm and compiles assets using Vite. This is necessary for Tailwind CSS to work.

```bash
npm install
npm run build
```

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

### Serve API Documentation Locally

Source: https://github.com/area17/twill/blob/3.x/docs-api/README.md

Use this Composer script to start a local web server for viewing the generated API documentation.

```bash
composer run serve
```

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

### Start Local Development Server for Twill

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/5_block-editor/12_development-workflow.md

Starts a local server that watches for frontend changes. Requires `'dev_mode' => true` in `config/twill.php`.

```bash
php artisan twill:dev
```

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

### Example: Implementing Multiple Table Filters

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/6_table-builder.md

This example demonstrates how to configure various filters including BelongsToFilter, FieldSelectFilter, BooleanFilter, and a custom BasicFilter with specific apply logic.

```php
public function filters(): TableFilters
{
    return TableFilters::make([
        BelongsToFilter::make()->field('partner'),
        FieldSelectFilter::make()->field('year'),
        BooleanFilter::make()->field('published')->label('Published'),
        BasicFilter::make()
            ->queryString('verified')
            ->options(collect(['yes' => 'Verified', 'no' => 'Not verified']))
            ->apply(function (Builder $builder, string $value) {
                if ($value === 'yes') {
                    $builder->where('is_verified', true);
                } elseif ($value === 'no') {
                    $builder->where('is_verified', false);
                }
            }),
    ]);
}
```

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

### Configure Homestead Hosts

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Example configuration for the /etc/hosts file when using Laravel Homestead and serving Twill from a subdomain.

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

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

### Install an Existing Twill Capsule

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/4_capsules.md

Use this command to install a Twill capsule from GitHub. The `--copy` flag places the capsule in your `app/Twill/Capsules` folder, while `--require` uses Composer. Specify a `--branch` if a release is not yet available.

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

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

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

### Azure Media Library Endpoint Setup

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/3_configuration.md

Configure the Azure endpoint for the media library by providing environment variables for the account key, account name, and container name.

```bash
MEDIA_LIBRARY_ENDPOINT_TYPE=azure

AZURE_ACCOUNT_KEY=AZURE_ACCOUNT_KEY
AZURE_ACCOUNT_NAME=AZURE_ACCOUNT_NAME
AZURE_CONTAINER=AZURE_CONTAINER
```

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

### Install Twill with Composer

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/3_installing-twill.md

Use Composer to require the Twill package and its dependencies.

```bash
composer require area17/twill:"^3.6"
```

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

### Custom Admin Subdomain Example

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Specify a custom subdomain for the admin console using the ADMIN_APP_URL variable.

```bash
ADMIN_APP_URL=http://manage.domain.test
```

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

### Basic Twill Project Controller Setup

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/11_repeater.md

Sets up the module name for a Twill controller. This is a foundational step for managing a specific module within the Twill admin panel.

```php
<?php

namespace App\Http\Controllers\Twill;

use A17\Twill\Http\Controllers\Admin\ModuleController as BaseModuleController;
use A17\Twill\Models\Contracts\TwillModelContract;
use A17\Twill\Services\Forms\Fields\BlockEditor;
use A17\Twill\Services\Forms\Fields\Input;
use A17\Twill\Services\Forms\Fields\Repeater;
use A17\Twill\Services\Forms\Form;
use A17\Twill\Services\Forms\InlineRepeater;
use App\Models\Partner;

class ProjectController extends BaseModuleController
{
    protected function setUpController(): void
    {
        $this->setModuleName('projects');
    }

    public function getForm(TwillModelContract $model): Form
    {
        return Form::make([
            Input::make()
                ->translatable()
                ->name('description'),
            // [tl! focus:start]
            // Inline repeater that can select existing entries.
            InlineRepeater::make()
                ->label('Partners')
                ->name('project_partner')
                ->triggerText('Add partner') // Can be omitted as it generates this.
                ->selectTriggerText('Select partner') // Can be omitted as it generates this.
                ->allowBrowser()
                ->relation(Partner::class)
                ->fields([
                    Input::make()
                        ->name('title')
                        ->translatable(),
                    Input::make()
                        ->name('role')
                        ->translatable()
                        ->required(),
                ]),
            Repeater::make()->type('comment'), // Regular repeater using a view.
            // Regular repeater for creating items without a managed model.
            InlineRepeater::make()
                ->name('links')
                ->fields([
                    Input::make()
                        ->name('title'),
                    Input::make()
                        ->name('url')
                ]),
            // [tl! focus:end]
            BlockEditor::make()
        ]);
    }
}
```

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

### Local Media Library Endpoint Setup

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/3_configuration.md

Configure the local media library endpoint using environment variables for the endpoint type and local path. Ensure PHP and web server settings accommodate the file size limit.

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

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

### Define Buckets Configuration

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/9_buckets/1_index.md

Configure your buckets, including their names, associated modules, and maximum items. This example defines a 'homepage' bucket with primary and secondary featured content zones.

```php
'buckets' => [
    'homepage' => [
        'name' => 'Home',
        'buckets' => [
            'home_primary_feature' => [
                'name' => 'Home primary feature',
                'bucketables' => [
                    [
                        'module' => 'guides',
                        'name' => 'Guides',
                        'scopes' => ['published' => true],
                    ],
                ],
                'max_items' => 1,
            ],
            'home_secondary_features' => [
                'name' => 'Home secondary features',
                'bucketables' => [
                    [
                        'module' => 'guides',
                        'name' => 'Guides',
                        'scopes' => ['published' => true],
                    ],
                ],
                'max_items' => 10,
            ],
        ],
    ],
],
```

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

### S3 Media Library Endpoint Setup

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/3_configuration.md

Set up the S3 endpoint for the media library using environment variables for credentials, bucket name, and optionally region. For S3-compliant storage like Minio, specify the endpoint URL.

```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
```

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

### Example Fieldset with Fields

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/7_form-builder.md

Demonstrates adding a fieldset named 'Opengraph' containing specific input fields for OG Title, OG Description, and OG Image.

```php
$form->addFieldset(
    Fieldset::make()->title('Opengraph')->id('opengraph')->fields([
        Input::make()->name('og_title')->label('OG Title'),
        Input::make()->name('og_description')->label('OG Description'),
        Files::make()->name('og_image')->label('OG Image')
    ])
);
```

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

### Run Twill Installation Artisan Command

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/3_installing-twill.md

Execute the Twill artisan command to prepare the database, publish configuration files and assets, and prompt for super admin creation.

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

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

### Standard Twill Installation

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Add the Twill package to your Laravel application using Composer. This command will also migrate your database.

```bash
composer require area17/twill:"^3.4"
```

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

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

### Configure Local Package Installation

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/14_packages/1_creating-a-package.md

After generating a package, add this configuration to your project's `composer.json` to enable local development. This allows Composer to find and manage your package directly from its source directory.

```bash
Your package has been generated!

You can now add it to your project's composer json repositories to work on it:

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

Then you can require it: composer require area17/twill-extension

By default the package has no functionality, you can add a first capsule using (Replace YourModel with the model you want to use):

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

Enjoy!
```

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

### Database Migration for Select Field

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/05_select.md

This migration example shows how to add a string column for a select field. No migration is needed when using the field within a block editor.

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

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

### Database Migration for Datepicker Field

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/07_datepicker.md

Example database migrations for storing date picker data. Use `date` for dates only or `dateTime` for dates and times.

```php
Schema::table('posts', function (Blueprint $table) {
    ...
    $table->date('event_date')->nullable();
    ...
});
// OR
Schema::table('posts', function (Blueprint $table) {
    ...
    $table->dateTime('event_date')->nullable();
    ...
});
```

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

### Configure Image Block Crops

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/6_creating-a-block.md

Add crop configurations for media fields used in blocks to `config/twill.php`. This example defines 'desktop' and 'mobile' crops for the 'highlight' media field.

```php
<?php

return [
    'block_editor' => [
        'use_twill_blocks' => [],
        'crops' => [ 
            'highlight' => [
                'desktop' => [
                    [
                        'name' => 'desktop',
                        'ratio' => 16 / 9,
                    ],
                ],
                'mobile' => [
                    [
                        'name' => 'mobile',
                        'ratio' => 1,
                    ],
                ],
            ],
        ],
    ],
];
```

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

### Configure Capsule in twill.php

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/4_capsules.md

Add your installed capsule to the `capsules.list` array in `config/twill.php` to enable it. The `name` should match the capsule's display name, and `enabled` should be set to `true`.

```php
<?php

return [
    'capsules' => [
        'list' => [
            [
                'name' => 'Redirections',
                'enabled' => true,
            ],
        ],
    ],
    ...
];
```

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

### Override afterDuplicate for Custom Duplication

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/11_repositories.md

Override the `afterDuplicate` method to add custom logic for duplicating related content. Ensure you call `parent::afterDuplicate` to preserve default duplication behavior. This example sets the publish start date for the new entry to tomorrow.

```php
use A17\Twill\Models\Contracts\TwillModelContract;

class BlogRepository extends ModuleRepository
{
    public function afterDuplicate(TwillModelContract $old, TwillModelContract $new): void
    {
        parent::afterDuplicate($old, $new);

        $new->publish_start_date = Carbon::tomorrow();
        $new->save();
    }
}
```

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

### Serve Docs with Testbench

Source: https://github.com/area17/twill/blob/3.x/docs/readme.md

Serve the documentation using the Testbench command.

```bash
./vendor/bin/testbench twill:staticdocs:serve
```

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

### Define Media Crop Configurations for Repeaters

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/11_repeater.md

If your JSON repeater contains media form fields, define the `mediasParams` in `config/twill.php` under `repeaters.crops` or `block_editor.crops`. This example shows the configuration structure.

```php
'repeaters' => [
  'crops' => [
     ‘your-media-field-name’ => [
       …
     ]
  ],
]
```

```php
'block_editor' => [
  'crops' => [
     ‘your-media-field-name’ => [
       …
     ]
  ],
]
```

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

### Build Docs with Testbench

Source: https://github.com/area17/twill/blob/3.x/docs/readme.md

Build the documentation using the Testbench command.

```bash
./vendor/bin/testbench twill:staticdocs:generate
```

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

### Install vue-numeric Dependency

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/4_creating_custom_components_form_fields_and_blocks.md

Installs the vue-numeric package using npm, which is used for creating custom number form fields.

```bash
npm install vue-numeric --save
```

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

### Install PHP_CodeSniffer Globally

Source: https://github.com/area17/twill/blob/3.x/CONTRIBUTING.md

Install PHP_CodeSniffer globally using Composer. This is required for the PHPCS VS Code extension for contextual linting.

```bash
composer global require "squizlabs/php_codesniffer=*"
```

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

### Build API Documentation

Source: https://github.com/area17/twill/blob/3.x/docs-api/README.md

Execute this Composer script to generate the static API documentation website.

```bash
composer run build
```

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

### Navigate to Project Directory

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/2_installing-laravel.md

Change into the newly created Laravel project directory.

```bash
cd laravel-twill
```

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

### Define a complex Twill block with multiple fields

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/5_block-editor/02_creating-a-block-editor.md

This example demonstrates a media block with fields for images, video, caption, transition effects, background color, and timing. It utilizes various Twill custom components like `x-twill::medias`, `x-twill:files`, `x-twill::input`, `x-twill::select`, and `x-twill::color`.

```php
@twillBlockTitle('Media')
@twillBlockIcon('image')

<x-twill::medias
    name="image"
    label="Images"
    :max="20"
/>

<x-twill:files
    name="video"
    label="video"
    note="Video will overwrite previously selected images"
    :max="1"
/>

<x-twill::input
    name="caption"
    label="Caption"
    :maxlength="250"
    :translated="true"
/>

@php
    $options = [
        [
            'value' => 'cut',
            'label' => 'Cut'
        ],
        [
            'value' => 'fade',
            'label' => 'Fade In/Out'
        ]
    ];
@endphp

<x-twill::select
    name="effect"
    label="Transition effect"
    placeholder="Select transition effect"
    default="cut"
    :options="$options"
/>

<x-twill::color
    name="bg"
    label="Background color"
    note="Default is light grey (#E6E6E6)"
/>

<x-twill::input
    name="timing"
    label="Timing"
    note="Timing in ms (default is 4000ms)"
/>
```

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

### Install Laravel Localization Package

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/2_building_a_multilingual_site_with_twill_and_laravel_localization.md

Install the Laravel Localization package using Composer. This is the first step to enable localization features in your Laravel project.

```bash
composer require mcamara/laravel-localization
```

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

### Initialize Git Repository

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/2_installing-laravel.md

Initialize a Git repository and commit the initial project files. This is an optional but recommended step for version control.

```bash
git init
```

```bash
git add .
```

```bash
git commit -m "Initial commit"
```

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

### Build Twill Assets with Custom Components

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/4_creating_custom_components_form_fields_and_blocks.md

Use the `twill:build` Artisan command to compile Twill assets along with your custom Vue components. Use the `--install` flag to force NPM dependency installation.

```bash
php artisan twill:build
```

```bash
php artisan twill:build --install
```

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

### Require Twill CMS

Source: https://github.com/area17/twill/blob/3.x/examples/basic-page-builder/README.md

Installs the Twill CMS package into your Laravel project using Composer.

```bash
composer require area17/twill:"^3.2"
```

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

### Compile and Serve Docs Site

Source: https://github.com/area17/twill/blob/3.x/docs/readme.md

Compile and serve the documentation site locally. Access it at http://localhost:8000/docs.

```bash
npm run docs
```

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

### Build Docs Fresh with Testbench

Source: https://github.com/area17/twill/blob/3.x/docs/readme.md

Perform a fresh build of the documentation, useful for layout or structure changes.

```bash
./vendor/bin/testbench twill:staticdocs:generate --fresh
```

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

### Template Label Accessor

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/7_prefill-block-editor-from-template.md

Provides a convenient way to get the display name of the selected template.

```php
public function getTemplateLabelAttribute()
{
    $template = collect(static::AVAILABLE_TEMPLATES)->firstWhere('value', $this->template);

    return $template['label'] ?? '';
}
```

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

### Database Migration for Color Field

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/13_color.md

Example migration schema for adding a color field to a database table.

```php
Schema::table('posts', function (Blueprint $table) {
    ...
    $table->string('main_color', 10)->nullable();
    ...
});
```

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

### Define Front-End Route

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/8_building-a-front-end.md

Adds a GET route to 'routes/web.php' that captures a 'slug' from the URL and directs it to the 'show' method of the PageDisplayController.

```php
<?php

use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| Web Routes
|--------------------------------------------------------------------------
|
| Here is where you can register web routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| contains the "web" middleware group. Now create something great!
|
*/

Route::get('/', function () { 
    return view('welcome');
});
Route::get('{slug}', [\App\Http\Controllers\PageDisplayController::class, 'show'])->name('frontend.page');
```

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

### Configure Imgix Media Service

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/3_configuration.md

Set the Imgix media service and source host. Ensure sensitive credentials like the signature key are managed via environment variables.

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

```bash
IMGIX_USE_SIGNED_URLS=true
IMGIX_SIGN_KEY=
```

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

### Get Image URL in Block Component

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/5_block-editor/02_creating-a-block-editor.md

Use the $image() helper to retrieve image URLs with specified crop and dimensions.

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

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

### Run Migrations

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/6_manage_frontend_user_profiles_from_twill.md

Execute the database migrations to apply the changes to your database schema.

```bash
php artisan migrate
```

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

### Define Available Templates and Constants

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/7_prefill-block-editor-from-template.md

Sets up constants for default template and defines available templates with their associated block selections.

```php
public const DEFAULT_TEMPLATE = 'full_article';

public const AVAILABLE_TEMPLATES = [
    [
        'value' => 'full_article',
        'label' => 'Full Article',
        'block_selection' => ['article-header', 'article-paragraph', 'article-references'],
    ],
    [
        'value' => 'linked_article',
        'label' => 'Linked Article',
        'block_selection' => ['article-header', 'linked-article'],
    ],
    [
        'value' => 'empty',
        'label' => 'Empty',
        'block_selection' => [],
    ],
];
```

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

### Define an Image Block View

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/6_creating-a-block.md

Define the structure for an image block in `resources/views/twill/blocks/image.blade.php`. This example uses a media field named 'highlight'.

```blade
@twillBlockTitle('Image')
@twillBlockIcon('text')
@twillBlockGroup('app')

<x-twill::medias
    name="highlight"
    label="Highlight"
/>
```

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

### Implement Frontpage Display Controller Method

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/10_setup-the-frontpage.md

Implement the 'home' method in PageDisplayController to retrieve and display the selected frontpage, ensuring it is published.

```php
<?php

namespace App\Http\Controllers;

use A17\Twill\Facades\TwillAppSettings;
use App\Repositories\PageRepository;
use Illuminate\Contracts\View\View;

class PageDisplayController extends Controller
{
    public function show(string $slug, PageRepository $pageRepository): View
    {
        $page = $pageRepository->forSlug($slug);

        if (!$page) {
            abort(404);
        }

        return view('site.page', ['item' => $page]);
    }

    public function home(): View
    {
        if (TwillAppSettings::get('homepage.homepage.page')->isNotEmpty()) {
            /** @var \App\Models\Page $frontPage */
            $frontPage = TwillAppSettings::get('homepage.homepage.page')->first();

            if ($frontPage->published) {
                return view('site.page', ['item' => $frontPage]);
            }
        }

        abort(404);
    }
}
```

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

### Get Nested Slug

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/12_nested-modules.md

Retrieve the combined slug for an item, including all its ancestors. This is useful for generating full permalinks for nested content.

```php
// Get the combined slug for an item including all ancestors:
$slug = $item->nestedSlug;

// for a specific locale:
$slug = $item->getNestedSlug($lang);
```

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

### Specify Storage Configuration for Media Library

Source: https://github.com/area17/twill/blob/3.x/UPGRADE.md

If you were using default S3 and Imgix configurations for the media library, you now need to specify them in your .env file.

```env
# Example: Specify storage on S3
# TWILL_MEDIA_LIBRARY_DISK=s3
# TWILL_MEDIA_LIBRARY_IMGPROXY_URL=http://imgproxy:8080
```

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

### Old Twill 2 @formField Directive Syntax

Source: https://github.com/area17/twill/blob/3.x/docs/content/3_blog/2_twill-3-introducing-oop-builders.md

Example of the older Twill 2 syntax using the @formField directive for form fields.

```blade
@extends('twill::layouts.form')

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

    @formField('multi_select', [
        'name' => 'sectors',
        'label' => 'Sectors',
        'min' => 1,
        'max' => 2,
        'options' => [
            [
                'value' => 'arts',
                'label' => 'Arts & Culture'
            ],
            [
                'value' => 'finance',
                'label' => 'Banking & Finance'
            ],
            [
                'value' => 'civic',
                'label' => 'Civic & Public'
            ],
            [
                'value' => 'design',
                'label' => 'Design & Architecture'
            ],
            [
                'value' => 'education',
                'label' => 'Education'
            ]
        ]
    ])

    @formField('block_editor')
@stop

```

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

### Define a Text Block View

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/6_creating-a-block.md

Define the structure and fields for a text block in `resources/views/twill/blocks/text.blade.php`. This example includes a title and a wysiwyg editor, both translatable.

```blade
@twillBlockTitle('Text')
@twillBlockIcon('text')
@twillBlockGroup('app')

<x-twill::input
    name="title"
    label="Title"
    :translated="true"
/>

<x-twill::wysiwyg
    name="text"
    label="Text"
    placeholder="Text"
    :toolbar-options="[
        'bold',
        'italic',
        ['list' => 'bullet'],
        ['list' => 'ordered'],
        [ 'script' => 'super' ],
        [ 'script' => 'sub' ],
        'link',
        'clean'
    ]"
    :translated="true"
/>
```

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

### Run Migrations

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/12_nested-modules.md

Execute the artisan migrate command to apply the database schema changes.

```bash
php artisan migrate
```

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

### PHP Form Builder for Homepage Controller

Source: https://github.com/area17/twill/blob/3.x/docs/content/3_blog/2_twill-3-introducing-oop-builders.md

Example of using the OOP form builder in a PHP controller to define form fields for a singleton module.

```php
<?php 
namespace App\Http\Controllers\Twill;

use A17\Twill\Models\Contracts\TwillModelContract; 
use A17\Twill\Services\Forms\Fields\BlockEditor;
use A17\Twill\Services\Forms\Fields\Input;
use A17\Twill\Services\Forms\Form;
use A17\Twill\Http\Controllers\Admin\SingletonModuleController as BaseModuleController;  

class HomepageController extends BaseModuleController
{
protected $moduleName = 'homepages';

    public function getForm(TwillModelContract $model): Form 
    {
        $form = parent::getForm($model);

        $form->add(
            Input::make()->name('description')->label('Description')->translatable()
        );

        $form->add(
            BlockEditor::make()
        );

        return $form;
    }

}

```

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

### Configure Supported Locales in Laravel Localization

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/2_building_a_multilingual_site_with_twill_and_laravel_localization.md

Define the locales supported by your application in the Laravel Localization configuration file. This example enables English and French.

```php
    'supportedLocales' => [
        'en' => ['name' => 'English', 'script' => 'Latn', 'native' => 'English', 'regional' => 'en_GB'],
        'fr' => ['name' => 'French', 'script' => 'Latn', 'native' => 'fran ais', 'regional' => 'fr_FR'],
        // ... other unused languages can remain commented ...
    ],
```

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

### Configure .env File

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/2_installing-laravel.md

Set the APP_URL in the .env file to match your local development URL. This is crucial for avoiding issues with image cropping.

```dotenv
APP_URL=http://laravel-twill.test
```

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

### Define a basic Twill block with annotations

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/5_block-editor/02_creating-a-block-editor.md

Use `@twillBlockTitle` and `@twillBlockIcon` for mandatory block identification. This example shows a simple text input for a quote.

```blade
@twillBlockTitle('Quote')
@twillBlockIcon('text')

<x-twill::input 
    name="quote"
    type="textarea"
    label="Quote text"
    :maxlength="250"
    :rows="4"
/>
```

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

### Default Map Data Structure

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/14_map.md

Example JSON structure for default data stored in the database for a map field, including latitude, longitude, and address.

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

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

### Run Database Migrations

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/10_user-management/2_advanced-permissions.md

After configuring permissions management, execute the database migrations to apply the necessary schema changes.

```bash
php artisan migrate

```

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

### Set Custom Search Columns in Twill

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/6_table-builder.md

Extend the `setUpController` method to specify which columns should be searchable. This example adds 'title' and 'year' to the default search.

```php
namespace App\Http\Controllers\Twill;

use A17\Twill\Http\Controllers\Admin\ModuleController;

class ProjectController extends BaseModuleController
{
    ...
    
    public function setUpController(): void
    {
        $this->setSearchColumns(['title', 'year']);
    }
}
```

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

### Link Storage Directory

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Set up storage folders mapping to the public directory. This is a standard Laravel command.

```bash
php artisan storage:link
```

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

### Get Featured Items Directly

Source: https://github.com/area17/twill/blob/3.x/UPGRADE.md

Use the getForBucket helper method to retrieve featured items directly, as scopeForBucket is now a true scope in Twill 3.

```php
getForBucket()
```

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

### Visit Twill Admin Panel

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/15_testing/index.md

Use the `visitTwill` macro to navigate to the Twill admin panel within your Dusk tests. This is often a prerequisite for other actions.

```php
$this->browse(function(Browser $browser) {
    $browser->visitTwill();// [tl! focus]
});
```

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

### Get Ancestor Slugs

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/12_nested-modules.md

Accessors to retrieve the combined slugs of an item's ancestors for the current or a specific locale. Useful for constructing nested permalinks.

```php
// Get the combined slug for all ancestors of an item in the current locale:
$slug = $item->ancestorsSlug;

// for a specific locale:
$slug = $item->getAncestorsSlug($lang);
```

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

### Help for Twill Module Artisan Command

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/1_page-builder-with-blade/4_creating-the-page-module.md

View all available options for creating a new Twill module using the `--help` flag.

```shell
php artisan twill:make:module --help
```

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

### Configure Admin Subdomain

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Serve Twill from a subdomain by setting the ADMIN_APP_URL environment variable.

```bash
ADMIN_APP_URL=http://admin.domain.test
```

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

### Add Buckets Page to CMS Navigation

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/9_buckets/1_index.md

Add a link to your buckets page in your CMS navigation configuration. This example adds a 'Homepage' link under a 'Features' section.

```php
return [
   'featured' => [
       'title' => 'Features',
       'route' => 'twill.featured.homepage',
       'primary_navigation' => [
           'homepage' => [
               'title' => 'Homepage',
               'route' => 'twill.featured.homepage',
           ],
       ],
   ],
   ...
];
```

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

### Generate Low-Quality Image Placeholders (LQIP)

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/16_artisan-commands/index.md

Generates LQIP for media files to improve page load times. Use --all to regenerate for all files.

```bash
php artisan twill:lqip {--all=0}
```

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

### Format Search Results for Custom Endpoint

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/12_global-search/index.md

Example of how to format search results when using a custom search endpoint. The returned collection should match the expected structure.

```php
return $searchResults->map(function ($item) use ($module) {
    try {
        $author = $item->revisions()->latest()->first()->user->name ?? 'Admin';
    } catch (\Exception $e) {
        $author = 'Admin';
    }

    return [
        'id' => $item->id,
        'href' => moduleRoute($moduleName['name'], $moduleName['routePrefix'], 'edit', $item->id),
        'thumbnail' => $item->defaultCmsImage(['w' => 100, 'h' => 100]),
        'published' => $item->published,
        'activity' => 'Last edited',
        'date' => $item->updated_at->toIso8601String(),
        'title' => $item->title,
        'author' => $author,
        'type' => Str::singular($module['name']),
    ];
})->values();
```

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

### Create Pivot Table Migration

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/06_multi-select.md

Generate a migration file for the pivot table that will link posts and sectors.

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

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

### Instantiate TableColumns in PHP

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/6_table-builder.md

Start by instantiating a `TableColumns` object when defining custom table columns in Twill. This is the initial step before adding individual column definitions.

```php
use A17\Twill\Services\Listings\TableColumns;

protected function getIndexTableColumns(): TableColumns
{
    $columns = new TableColumns();
}
```

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

### Configure Imgix for Image Rendering

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/2_installation.md

Use these environment variables to integrate Imgix for offloading responsive image rendering. Assumes a source is configured on top of your Twill uploads bucket.

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

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

### Create Custom Blocks

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/7_prefill-block-editor-from-template.md

Generates the necessary block files for the article module.

```bash
php artisan twill:make:block article-header
php artisan twill:make:block article-paragraph
php artisan twill:make:block article-references
php artisan twill:make:block linked-article
```

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

### Implement ImageServiceInterface Methods

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/7_media-library/02_image-rendering-service.md

When creating a custom image service, you must implement these methods. The `getUrlWithCrop` method can be used if focal point cropping is not supported.

```php
<?php

public function getUrl($id, array $params = []);
public function getUrlWithCrop($id, array $crop_params, array $params = []);
public function getUrlWithFocalCrop($id, array $cropParams, $width, $height, array $params = []);
public function getLQIPUrl($id, array $params = []);
public function getSocialUrl($id, array $params = []);
public function getCmsUrl($id, array $params = []);
public function getRawUrl($id);
public function getDimensions($id);
public function getSocialFallbackUrl();
public function getTransparentFallbackUrl();

```

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

### Register Permissions with Laravel Gates

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/8_adding-custom-roles-and-permissions.md

Define custom permissions for modules using Laravel's Gate system in `app/Providers/AuthServiceProvider.php`. This example shows permissions for the 'posts' module.

```php
use A17\Twill\Models\Enums\UserRole;

class AuthServiceProvider extends ServiceProvider
{
    // ...

    public function boot()
    {
        $this->registerPolicies();

        // The `list-posts` permission is granted to users of all roles
        Gate::define('list-posts', function ($user) {
            if ($user->isSuperAdmin()) {
                return true;
            }

            return in_array($user->role_value, [
                UserRole::VIEWONLY,
                UserRole::AUTHOR,
                UserRole::PUBLISHER,
                UserRole::ADMIN,
            ]);
        });

        // The `edit-posts` permission is granted to users of all roles, except `View Only`
        Gate::define('edit-posts', function ($user) {
            if ($user->isSuperAdmin()) {
                return true;
            }

            return in_array($user->role_value, [
                UserRole::AUTHOR,
                UserRole::PUBLISHER,
                UserRole::ADMIN,
            ]);
        });
    }
}
```

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

### Extended Map Data Structure

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/4_form-fields/14_map.md

Example JSON structure for extended data stored in the database for a map field, including bounding box coordinates and location types.

```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
  }
}
```

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

### Media Library Configuration

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/3_configuration.md

Configure the media library's disk, endpoint type, and other options. Many settings can be controlled via environment variables for flexibility.

```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',
                ],
            ],
        ],
    ],
];
```

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

### Add a Custom Quick Filter in Twill

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/6_table-builder.md

Extend the `quickFilters` method to add a new custom quick filter. This example adds a 'Test only' filter that searches by translation.

```php
use A17\Twill\Services\Listings\Filters\QuickFilters;

public function quickFilters(): QuickFilters;

```

```php
public function quickFilters(): QuickFilters
{
    $filters = $this->getDefaultQuickFilters();
    $filters->add(
        QuickFilter::make()
            ->queryString('test')
            ->label('Test only')
            ->amount(fn() => $this->repository->whereTranslation('title', 'test')->count())
            ->apply(fn(Builder $builder) => $builder->whereTranslation('title', 'test'))
    );

    return $filters;
}
```

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

### Imgix Configuration Array

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/2_getting-started/3_configuration.md

Configure Imgix settings including source host, HTTPS usage, signed URLs, and default transformation parameters for various use cases.

```php
<?php

return [
    'imgix' => [
        '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'),
        'add_params_to_svgs' => false,
        '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,
        ],
    ],
];
```

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

### Validate Repeater Fields (Create)

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/8_form-requests.md

Define validation rules for repeater fields during the creation process. This example shows how to validate the 'headline' field within an 'accordion_item' repeater.

```php
public function rulesForCreate()
{
    return ['repeaters.accordion_item.*.header' => 'required'];
}
```

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

### Enable Video Support for Media Fields

Source: https://github.com/area17/twill/blob/3.x/UPGRADE.md

If you relied on 'withVideo' being true by default in previous versions, explicitly set it to 'true' for your media fields.

```php
'withVideo' => true
```

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

### Create Profiles Module

Source: https://github.com/area17/twill/blob/3.x/docs/content/2_guides/6_manage_frontend_user_profiles_from_twill.md

Use the Twill CLI to generate a new module for managing user profiles.

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

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

### Twill Project Controller Form Setup

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/6_relations/01_belongs-to-many.md

Configures the inline repeater in the Twill Project controller's `getForm` method to manage the BelongsToMany relationship with pivot data.

```php
<?php

namespace App\Http\Controllers\Twill;

use A17\Twill\Services\Forms\InlineRepeater;
use A17\Twill\Services\Forms\Text;
use A17\Twill\Services\Forms\Date;
use A17\Twill\Services\Forms\DateRange;
use A17\Twill\Services\Forms\Time;
use A17\Twill\Services\Forms\TimeRange;
use A17\Twill\Services\Forms\Color;
use A17\Twill\Services\Forms\Image;
use A17\Twill\Services\Forms\Video;
use A17\Twill\Services\Forms\File;
use A17\Twill\Services\Forms\Map;
use A17\Twill\Services\Forms\Block;
use A17\Twill\Services\Forms\Browser;
use A17\Twill\Services\Forms\BelongsTo;
use A17\Twill\Services\Forms\BelongsToMany;
use A17\Twill\Services\Forms\HasMany;
use A17\Twill\Services\Forms\MorphMany;
use A17\Twill\Services\Forms\MorphTo;
use A17\Twill\Services\Forms\HasOne;
use A17\Twill\Services\Forms\MorphOne;
use A17\Twill\Services\Forms\FieldsCollection;

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

    protected function getFormFields(): FieldsCollection
    {
        return new FieldsCollection([
            new Text('title'),
            new Text('description'),
            new Date('publish_date'),
            new DateRange('publish_date_range'),
            new Time('publish_time'),
            new TimeRange('publish_time_range'),
            new Color('highlight_color'),
            new Image('cover'),
            new Video('intro'),
            new File('attachment'),
            new Map('location'),
            new Block('content'),
            new Browser('author'),
            new BelongsTo('category'),
            new BelongsToMany('tags'),
            new HasMany('steps'),
            new MorphMany('media'),
            new MorphTo('attachable'),
            new HasOne('metadata'),
            new MorphOne('related_item'),
            new InlineRepeater(
                'partners',
                [
                    new BelongsTo('partner'),
                    new Text('role'),
                    new Text('position'),
                ]
            )
        ]);
    }
}
```

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

### Generate a New Twill Package

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/14_packages/1_creating-a-package.md

Use this command to create the basic structure for a new Twill package. It will prompt for necessary information and set up a `composer.json` and service provider.

```bash
php artisan twill:make:package
```

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

### Create Main Table Migration

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/3_modules/9_migrations.md

Use this to create the main table for your module, including default fields.

```php
<?php

// main table, holds all non translated fields
Schema::create('table_name_plural', function (Blueprint $table) {
    createDefaultTableFields($table);
    // will add the following instructions to your migration file
    // $table->increments('id');
    // $table->softDeletes();
    // $table->timestamps();
    // $table->boolean('published');
});
```