Twill

https://github.com/area17/twill
Admin
Twill is an open source Laravel package that helps developers rapidly create a custom, beautiful,...
Tokens:374,628
Snippets:2,680
Trust Score:9.3
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and build front-end dependencies

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

Installs npm dependencies and compiles assets with Vite. Required because the example uses Tailwind CSS for styling.

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

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

### Install Twill Basic Page Builder Starter Kit

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

Runs the Twill installer with the 'basic-page-builder' option to set up a starter kit that includes a page module, blade frontend, example blocks, navigation module, and frontpage setting. This command will migrate your database.

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

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

### Install Node and PHP dependencies

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

Run these commands to install the required dependencies before working with the docs.

```bash
npm i
composer install
```

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

### Standard Twill Installation

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

Runs the standard Twill installer, which creates a routes file, migrates the database, publishes configuration and assets, and prompts for a superadmin user. This command will migrate your database.

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

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

### Compile and serve docs site

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

Starts the docs server and compiles the site. Then visit http://localhost:8000/docs.

```bash
npm run docs
```

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

### Install Twill portfolio example

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

Quickly test the BelongsToMany with pivot data setup in a new project by installing the portfolio example.

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

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

### Install dependencies for Twill API docs

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

Run these commands in the docs-api directory to install Composer dependencies for the Doctum-based documentation generator.

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

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

### Create Laravel project with Composer

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

Initializes a new Laravel project named laravel-twill and changes into its directory. Requires Composer and a local development environment or PHP's built-in server.

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

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

### Serve Twill API documentation locally

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

Starts a local server to view the generated documentation. After running, visit http://localhost:8000/2.x/index.html in your browser.

```bash
composer run serve
```

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

### Basic setupController with enableShowImage

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

Example of a module controller's setUpController method enabling the show image feature. The controller extends ModuleController and sets the module name to 'projects'.

```php
<?php

namespace App\Http\Controllers\Twill;

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

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

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

Install the vue-numeric package required by the custom form field example.

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

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

### Require Twill package via Composer

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

Adds the area17/twill package version ^3.2 to the Laravel project. Run from the project root after creating the Laravel application.

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

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

### Install Twill via Composer

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

Adds the Twill package to your Laravel application. This command will migrate your database, so ensure your .env file has database credentials and run it where the database is accessible (e.g., using sail or Vagrant).

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

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

### Build docs with testbench

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

Generates the static docs site.

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

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

### Run php artisan storage:link

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

Run this command after twill:install to create the symbolic link for the storage directory.

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

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

### Install a capsule from GitHub

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

Run this command to install an existing capsule hosted on GitHub, such as the Twill redirections capsule. The command will prompt for the repository and options if not provided.

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

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

### setupController

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

The main method used in a module controller to set all the options you would like to enable/disable. It is called during controller setup and allows customization of the module's behavior.

```APIDOC
## setupController

### Description
The main method used in a module controller to set all the options you would like to enable/disable. It is called during controller setup and allows customization of the module's behavior.

### Method
setupController

### Signature
`protected function setUpController(): void`

### Usage Example
```php
protected function setUpController(): void
{
    $this->enableShowImage();
}
```

### Notes
- This method is called automatically during controller initialization.
- Use this method to call any of the enable/disable/setter methods listed below.
```

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

### Serve docs with testbench

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

Alternative command to serve the docs using testbench.

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

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

### Install Laravel Localization via Composer

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 mcamara/laravel-localization package using Composer.

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

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

### Set ADMIN_APP_URL for subdomain

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

Use the ADMIN_APP_URL environment variable to serve Twill from a subdomain, e.g., http://admin.domain.test.

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

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

### enableShowImage

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

Shows the thumbnail of the content in the list.

```APIDOC
## enableShowImage

### Description
Shows the thumbnail of the content in the list.

### Method
enableShowImage

### Signature
`$this->enableShowImage()`

### Usage Example
```php
$this->enableShowImage();
```
```

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

### enableReorder

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

Allows to reorder the items, if this was setup on the model.

```APIDOC
## enableReorder

### Description
Allows to reorder the items, if this was setup on the model.

### Method
enableReorder

### Signature
`$this->enableReorder()`

### Usage Example
```php
$this->enableReorder();
```
```

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

### Build docs fresh with testbench

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

Rebuilds the docs from scratch, useful after layout or structure changes.

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

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

### Subdomain navigation configuration example

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

Example navigation array exposing your CMS on `admin.subdomain1.app-url.test` and `admin.subdomain2.app-url.test` urls with corresponding links.

```php
<?php

return [
    'subdomain1' => [
        'module1' => [...],
        ...
    ],
    'subdomain2' => [
        'module2' => [...]
        ...
    ]
];
```

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

### Install PHP_CodeSniffer globally via Composer

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

Install PHP_CodeSniffer globally using Composer for PHP contextual linting in VS Code with the phpcs extension.

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

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

### Define buckets configuration in config/twill.php

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

Defines a 'homepage' bucket page with two buckets: 'home_primary_feature' (max 1 item) and 'home_secondary_features' (max 10 items). Each bucket accepts 'guides' module with a 'published' scope. Add more modules to 'bucketables' to allow mixing modules in a single bucket.

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

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

### Add subdomain to /etc/hosts for Homestead

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

For Homestead users, add the subdomain to /etc/hosts to point to the app's public directory. Replace with your own IP and domain.

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

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

### Build Twill API documentation

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

Generates the static website for browsing the Twill API using Doctum.

```bash
composer run build
```

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

### enableBulkFeature

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

Enables the 'Feature' bulk operation.

```APIDOC
## enableBulkFeature

### Description
Enables the 'Feature' bulk operation.

### Method
enableBulkFeature

### Signature
`$this->enableBulkFeature()`

### Usage Example
```php
$this->enableBulkFeature();
```
```

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

### setSearchQuery

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

For finer control over the search.

```APIDOC
## setSearchQuery

### Description
For finer control over the search.

### Method
setSearchQuery

### Parameters
- **callback** (Closure) - Required - A closure that receives a Builder and a search string.

### Usage Example
```php
$this->setSearchQuery(fn (Builder $q, string $search) => $q->orWhereHas('profile', fn (Builder $q) => $q->where('first_name', 'like', "$search%")->orWhere('last_name', 'like', "$search%")));
```
```

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

### Install and copy the redirections capsule

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

Full command to install the redirections capsule and copy it into your project. The --copy flag makes a copy into app/Twill/Capsules, and --branch=main is used because no release exists yet for this capsule.

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

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

### php artisan twill:install

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

Generates and runs core migrations for a starter Twill installation. Optionally installs a preset and can be run from a build. After migrations, it automatically runs the twill:superadmin command to create a superadmin user.

```APIDOC
## [CLI] php artisan twill:install

### Description
Generates and runs core migrations for a starter Twill installation. Optionally installs a preset and can be run from a build. After migrations, it automatically runs the twill:superadmin command to create a superadmin user.

### Method
CLI

### Endpoint
php artisan twill:install

### Parameters
#### Arguments
- **preset** (string) - Optional - The preset to install

#### Options
- **--fromBuild** - Optional - Run from a build

### Response
No response body; runs migrations and then the twill:superadmin command.
```

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

### eagerLoadListingRelations

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

Relations to eager load for the index view.

```APIDOC
## eagerLoadListingRelations

### Description
Relations to eager load for the index view.

### Method
eagerLoadListingRelations

### Parameters
- **relations** (array) - Required - An array of relation names to eager load.

### Usage Example
```php
$this->eagerLoadListingRelations(['comments', 'author']);
```
```

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

### enableDuplicate

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

Enables the 'Duplicate' option from the content lists.

```APIDOC
## enableDuplicate

### Description
Enables the 'Duplicate' option from the content lists.

### Method
enableDuplicate

### Signature
`$this->enableDuplicate()`

### Usage Example
```php
$this->enableDuplicate();
```
```

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

### Imgix Image Rendering Environment Variables

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

Use these environment variables to offload responsive image rendering to Imgix, assuming a source is configured on top of the S3 bucket storing Twill uploads. Additional optional variables: IMGIX_USE_SIGNED_URLS, IMGIX_SIGN_KEY.

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

```

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

### setSearchColumns

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

Set the columns to search in.

```APIDOC
## setSearchColumns

### Description
Set the columns to search in.

### Method
setSearchColumns

### Parameters
- **columns** (array) - Required - An array of column names to search in.

### Usage Example
```php
$this->setSearchColumns(['title', 'year']);
```
```

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

### getLocalizedPermalinkBase method

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

Define a localized permalink base for multilingual setups, returning an array of language keys to permalink bases.

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

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

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

Optional step to initialize a Git repository in the laravel-twill directory, stage all files, and create an initial commit.

```bash
git init
```

```bash
git add .
```

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

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

### enableFeature

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

Allow to feature the content. This requires a 'featured' fillable boolean on the model.

```APIDOC
## enableFeature

### Description
Allow to feature the content. This requires a 'featured' fillable boolean on the model.

### Method
enableFeature

### Signature
`$this->enableFeature()`

### Usage Example
```php
$this->enableFeature();
```
```

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

### setBreadcrumbs

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

Breadcrumbs to display.

```APIDOC
## setBreadcrumbs

### Description
Breadcrumbs to display.

### Method
setBreadcrumbs

### Parameters
- **breadcrumbs** (Breadcrumbs) - Required - The breadcrumbs object.

### Usage Example
```php
$this->setBreadcrumbs($breadcrumbs);
```
```

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

### Add crop roles globally in config/twill.php

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

Adds a crop role available to all modules by defining it under 'default_crops' in the `config/twill.php` file. The example defines a 'page_cover' role with a single 'default' crop.

```php
<?php

return [
    'default_crops' => [
        'page_cover' => [
            'default' => [
                [
                    'name' => 'default',
                    'ratio' => 16 / 9,
                ]
            ]
        ]
    ]
];
```

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

### Force npm install with twill:build --install

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

Use this flag to force npm install for Twill's own dependencies. It only affects Twill's dependencies; run npm install directly in your project for your own dependencies.

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

```

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

### enableSkipCreateModal

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

Disables the create modal and directly forwards you to the full edit page.

```APIDOC
## enableSkipCreateModal

### Description
Disables the create modal and directly forwards you to the full edit page.

### Method
enableSkipCreateModal

### Signature
`$this->enableSkipCreateModal()`

### Usage Example
```php
$this->enableSkipCreateModal();
```
```

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

### eagerLoadFormRelations

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

Relations to eager load for the form view.

```APIDOC
## eagerLoadFormRelations

### Description
Relations to eager load for the form view.

### Method
eagerLoadFormRelations

### Parameters
- **relations** (array) - Required - An array of relation names to eager load.

### Usage Example
```php
$this->eagerLoadFormRelations(['comments', 'author']);
```
```

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

### disableBulkRestore

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

Removes the 'Trash' quick filter.

```APIDOC
## disableBulkRestore

### Description
Removes the 'Trash' quick filter.

### Method
disableBulkRestore

### Signature
`$this->disableBulkRestore()`

### Usage Example
```php
$this->disableBulkRestore();
```
```

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

### setModuleName

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

Set the name of the module you are working with.

```APIDOC
## setModuleName

### Description
Set the name of the module you are working with.

### Method
setModuleName

### Parameters
- **moduleName** (string) - Required - The name of the module.

### Usage Example
```php
$this->setModuleName('projects');
```
```

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

### disableBulkEdit

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

Disables bulk operations.

```APIDOC
## disableBulkEdit

### Description
Disables bulk operations.

### Method
disableBulkEdit

### Signature
`$this->disableBulkEdit()`

### Usage Example
```php
$this->disableBulkEdit();
```
```

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

### disableCreate

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

Removes the 'Create' button on the listing page.

```APIDOC
## disableCreate

### Description
Removes the 'Create' button on the listing page.

### Method
disableCreate

### Signature
`$this->disableCreate()`

### Usage Example
```php
$this->disableCreate();
```
```

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

### setTitleColumnKey

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

Sets the field to use as title, defaults to 'title'.

```APIDOC
## setTitleColumnKey

### Description
Sets the field to use as title, defaults to 'title'.

### Method
setTitleColumnKey

### Parameters
- **key** (string) - Required - The column key to use as title.

### Usage Example
```php
$this->setTitleColumnKey('title');
```
```

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

### Blade medias component examples

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

Use the <x-twill::medias> component in Blade templates. The first example shows basic usage with a note and field-note; the second adds a max attribute.

```blade
<x-twill::medias 
    name="cover" 
    label="Cover image"
    note="Also used in listings"
    field-note="Minimum image width: 1500px"
/>
```

```blade
<x-twill::medias 
    name="cover" 
    label="Cover image"
    note="Also used in listings"
    :max="5"
    field-note="Minimum image width: 1500px"
/>
```

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

### Extend Twill AuthServiceProvider with role constants and permission gates

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

Use class constants to group common roles and extend Twill's AuthServiceProvider to leverage its authorize() and userHasRole() utility methods, reducing duplication when defining permissions. The boot() method defines Gate permissions for the 'pages' and 'posts' modules, using the constants ALL_ROLES and ALL_EDITORS for role checks. This example is from the 'Cleanup AuthServiceProvider' section of the Twill guide on adding custom roles and permissions.

```php
use A17\Twill\AuthServiceProvider as TwillAuthServiceProvider;

class AuthServiceProvider extends TwillAuthServiceProvider
{
    const ALL_ROLES = [UserRole::VIEWONLY, UserRole::AUTHOR, UserRole::PUBLISHER, UserRole::ADMIN];
    const ALL_EDITORS = [UserRole::AUTHOR, UserRole::PUBLISHER, UserRole::ADMIN];

    public function boot()
    {
        // `pages` module permissions
        Gate::define('list-pages', function ($user) {
            return $this->authorize($user, function ($user) {
                return $this->userHasRole($user, [UserRole::VIEWONLY, UserRole::PUBLISHER, UserRole::ADMIN]);
            });
        });
        Gate::define('edit-pages', function ($user) {
            return $this->authorize($user, function ($user) {
                return $this->userHasRole($user, [UserRole::PUBLISHER, UserRole::ADMIN]);
            });
        });

        // `posts` module permissions
        Gate::define('list-posts', function ($user) {
            return $this->authorize($user, function ($user) {
                return $this->userHasRole($user, self::ALL_ROLES);
            });
        });
        Gate::define('edit-posts', function ($user) {
            return $this->authorize($user, function ($user) {
                return $this->userHasRole($user, self::ALL_EDITORS);
            });
        });
    }
}
```

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

### Translatable grouped field migration and model setup

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

Adds a JSON column 'external_link' to the blog_translations table, updates the Blog model's $translatedAttributes and $fillable, and adds an array cast on the Translation model.

```php
## Add a migration
Schema::table('blog_translations', function (Blueprint $table) {
    $table->json('external_link')->nullable();
});

## Update your models fillable
class Blog extends Model {
    public $translatedAttributes = [
        ...
        'external_link'
    ];

    protected $fillable = [
        ...
        'external_link'
    ];
}

## Update your Translation model and add the cast
public $casts = [
    'external_link' => 'array',
];
```

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

### enableEditInModal

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

Enables the function that content is edited in the create modal.

```APIDOC
## enableEditInModal

### Description
Enables the function that content is edited in the create modal.

### Method
enableEditInModal

### Signature
`$this->enableEditInModal()`

### Usage Example
```php
$this->enableEditInModal();
```
```

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

### disableBulkForceDelete

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

Removes 'restore' from the bulk operations on the 'Trash' content list.

```APIDOC
## disableBulkForceDelete

### Description
Removes 'restore' from the bulk operations on the 'Trash' content list.

### Method
disableBulkForceDelete

### Signature
`$this->disableBulkForceDelete()`

### Usage Example
```php
$this->disableBulkForceDelete();
```
```

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

### Set custom ADMIN_APP_URL subdomain

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 app using ADMIN_APP_URL; it does not have to be 'admin'.

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

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

### eagerLoadFormRelationCounts

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

Relation count to eager load for the form view.

```APIDOC
## eagerLoadFormRelationCounts

### Description
Relation count to eager load for the form view.

### Method
eagerLoadFormRelationCounts

### Parameters
- **relations** (array) - Required - An array of relation names to eager load counts for.

### Usage Example
```php
$this->eagerLoadFormRelationCounts(['comments', 'author']);
```
```

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

### setPermalinkBase

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

The static permalink base to your module. Defaults to setModuleName when empty.

```APIDOC
## setPermalinkBase

### Description
The static permalink base to your module. Defaults to setModuleName when empty.

### Method
setPermalinkBase

### Parameters
- **base** (string) - Required - The permalink base.

### Usage Example
```php
$this->setPermalinkBase('example');
```
```

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

### Inline Repeater with Relations (ProjectController)

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

Full example from the 'portfolio' installable example showing an inline repeater with relation to Partner model, plus regular repeaters. Uses allowBrowser() and relation() to select existing entries. The focus markers highlight the repeater configurations.

```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()
        ]);
    }
}
```

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

### setResultsPerPage

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

Sets the amount of results to show per page, defaults to 20.

```APIDOC
## setResultsPerPage

### Description
Sets the amount of results to show per page, defaults to 20.

### Method
setResultsPerPage

### Parameters
- **perPage** (int) - Required - The number of results per page.

### Usage Example
```php
$this->setResultsPerPage(20);
```
```

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

### Set SESSION_DOMAIN for cross-subdomain cookies

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

Use the SESSION_DOMAIN variable with a leading dot to share cookies between Twill and frontend subdomains, enabling draft access.

```bash
SESSION_DOMAIN=.domain.test
```

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

### BasicFilter example

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

A basic filter with full control over values and queries. Uses queryString 'verified' and an apply callback that filters based on the selected value.

```php
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);
        }
    });
```

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

### disableEdit

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

Disables table interaction and removes edit links.

```APIDOC
## disableEdit

### Description
Disables table interaction and removes edit links.

### Method
disableEdit

### Signature
`$this->disableEdit()`

### Usage Example
```php
$this->disableEdit();
```
```

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

### Set ADMIN_APP_PATH to /cms

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

Use the ADMIN_APP_PATH environment variable to change the default admin console path from /admin to a custom path like /cms.

```bash
ADMIN_APP_PATH=/cms
```

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

### Get default quick filters

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

Returns the default set of quick filters by calling `getDefaultQuickFilters()` inside the `quickFilters` method.

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

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

### Create homepage settings blade file

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

Defines a settings block for selecting the homepage page using a Twill browser component. Place this file at resources/views/twill/settings/homepage/homepage.blade.php.

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

<x-twill::browser
    label="Select the homepage"
    module-name="pages"
    name="page"/>
```

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

### Replace welcome route with frontend.home route

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

Updates routes/web.php to replace the default welcome route with a route to the PageDisplayController's home method, and adds a catch-all route for pages.

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

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

### Add home method to PageDisplayController

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

Adds a home method that retrieves the homepage setting, checks if a published page exists, and returns the page view or aborts with 404. Includes the existing show method for context.

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

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

### Add crop roles in a model with $mediasParams

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

Defines image roles specific to a model by adding a `$mediasParams` property to the model class. The example shows a `Page` model with a 'cover' role and 'default' and 'mobile' crops.

```php
<?php

namespace App\Models;

use A17\Twill\Models\Behaviors\HasBlocks;
use A17\Twill\Models\Behaviors\HasTranslation;
use A17\Twill\Models\Behaviors\HasSlug;
use A17\Twill\Models\Behaviors\HasMedias;
use A17\Twill\Models\Behaviors\HasRevisions;
use A17\Twill\Models\Model;

class Page extends Model
{
    use HasBlocks, HasTranslation, HasSlug, HasMedias, HasRevisions;

    protected $fillable = [
        'published',
        'title',
        'description',
    ];

    public $translatedAttributes = [
        'title',
        'description',
    ];

    public $slugAttributes = [
        'title',
    ];

    public $mediasParams = [
        'cover' => [
            'default' => [
                [
                    'name' => 'default',
                    'ratio' => 16 / 9,
                ],
            ],
            'mobile' => [
                [
                    'name' => 'landscape',
                    'ratio' => 16 / 9,
                ],
            ],
        ],
    ];
}
```

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

### Azure Blob Storage Environment Variables

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

Provide these environment variables to store Twill media uploads on Azure Blob Storage. Twill uploads directly from the browser, so the Blob Storage CORS policy must allow requests from your CMS domain. Additional optional variables: AZURE_CONTAINER, AZURE_ENDPOINT_SUFFIX, AZURE_UPLOADER_USE_HTTPS.

```bash
AZURE_ACCOUNT_KEY=
AZURE_ACCOUNT_NAME=

```

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

### Set admin subdomain in .env

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

Add the ADMIN_APP_URL key to your .env file to make Twill available on a subdomain instead of the default /admin path. Replace laravel-twill.test with your domain.

```dotenv
ADMIN_APP_URL=admin.laravel-twill.test
```

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

### Set customPermalink via formData in model controller

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

Override the formData method in your model controller to return a customPermalink value. The example uses a named route 'page.detail' to generate a URL like '/page-route/3' for a page with id 3. This is useful when using Laravel for the front-end to keep permalinks and routes in sync.

```php
# Route definition
Route::get('page-route/{id}', function() {...})->name('page.detail');

# Method implementation
protected function formData($request)
{
    if ($request->route('page')) {
        return [
            'customPermalink' => route('page.detail', ['id' => $request->route('page')]),
        ];
    }
    return [];
}
```

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

### Register multiple settings groups at once

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/8_settings-sections/1_index.md

Registers multiple settings groups in a single call using registerSettingsGroups. The example shows the first group and a placeholder for additional ones.

```php
use A17\Twill\Facades\TwillAppSettings;

public function boot(): void 
{
    TwillAppSettings::registerSettingsGroups(
        SettingsGroup::make()
            ->name('site-settings')
            ->label('Site settings')
            ->availableWhen(fn() => \Auth::user()->can('manage.settings')) // Example access control.
        SettingsGroup::make()
          ...
    );
}
```

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

### Create a new module with blocks enabled

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

Run this artisan command to generate a new module named 'articles' with blocks enabled. The -B flag enables blocks on the module.

```bash
php artisan twill:make:module articles -B
```

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

### S3 Storage Environment Variables

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

Provide these environment variables to store Twill media uploads on S3 or S3-compliant services (AWS, Digital Ocean Spaces, Scaleway Object Storage). Twill uploads directly from the browser, so the bucket's CORS policy must allow requests from your CMS domain. Additional optional variables: S3_ROOT, S3_URL, S3_ENDPOINT, S3_USE_PATH_STYLE_ENDPOINT.

```bash
S3_KEY=
S3_SECRET=
S3_BUCKET=
S3_REGION=

```

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

### TwillRoutes::module() usage examples

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

Shows how to use the TwillRoutes facade to create module routes with optional parameters for excluding or including actions, and disabling resource controller actions.

```php
<?php

use A17\Twill\Facades\TwillRoutes;

TwillRoutes::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'
TwillRoutes::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'
TwillRoutes::module('yourModulePluralName', [], ['only' => ['index', 'edit', 'store', 'destroy']]);

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

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

### Create a capsule for a Twill package

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

Creates a capsule for the package. Use --singleton for a singleton capsule instead.

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

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

### CustomRender example for Text column

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

Use customRender to control rendering of a column. This example renders a view with the model's title.

```php
Text::make()
  ->field('customField')
  ->customRender(function (Model $model) {
    return view('my.view', ['title' => $model->title])->render();
  });
```

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

### Create PageDisplayController with make:controller

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

Run this artisan command to generate the controller file app/Http/Controllers/PageDisplayController.php.

```shell
php artisan make:controller PageDisplayController
```

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

### Replace routes/web.php with frontend 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

Removes the default welcome route and adds a catch-all GET route for {slug} that maps to PageDisplayController@show, named frontend.page.

```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 () { // [tl! remove:start]
    return view('welcome');
});// [tl! remove:end]
Route::get('{slug}', [\App\Http\Controllers\PageDisplayController::class, 'show'])->name('frontend.page'); // [tl! ++]
```

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

### 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 $image('cover', 'default', ['h' => 100]) to get an image URL with specified crop and parameters.

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

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

### Migration file for articles table

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

The migration file is generated by the artisan command. The 'template' field will be added to the 'up' method.

```php
{
  "file": "./prefill-block-editor-from-template/2021_09_19_131244_create_articles_tables.php",
  "collapseAll": "",
  "focusMethods": ["up"],
  "diffInMethod": {
    "method": "up",
    "start": 7,
    "end": 7
  }
}
```

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

### Blade directive @formField medias examples

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

Use the @formField directive to define medias fields. The first example shows a cover image with note and fieldNote; the second shows a slideshow with max and fieldNote.

```blade
@formField('medias', [
    'name' => 'cover',
    'label' => 'Cover image',
    'note' => 'Also used in listings',
    'fieldNote' => 'Minimum image width: 1500px'
])
```

```blade
@formField('medias', [
    'name' => 'slideshow',
    'label' => 'Slideshow',
    'max' => 5,
    'fieldNote' => 'Minimum image width: 1500px'
])
```

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

### Package generation instructions output

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

Output after generating a package, showing how to add it to composer repositories and require it locally. Also includes a command to add a first capsule.

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

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

### Command output with routes and navigation snippet

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

After running the module generation command, this output shows the snippet added to routes/twill.php and the navigation link to add to the AppServiceProvider boot method. It also reminds to migrate the database after modifying migrations.

```shell
The following snippet has been added to routes/twill.php:
┌──────────────────────────────────┐
│ use A17\Twill\Facades\TwillRoutes│
│ TwillRoutes::module('pages');    │
└──────────────────────────────────┘
To add a navigation entry add the following to your AppServiceProvider BOOT method.
**************************
use A17\Twill\Facades\TwillNavigation;
use A17\Twill\View\Components\Navigation\NavigationLink;

TwillNavigation::addLink(
    NavigationLink::make()->forModule('pages')
);
**************************
Do not forget to migrate your database after modifying the migrations.
```

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

### Non-translatable grouped field migration and model setup

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

Adds a JSON column 'external_link' to the blogs table and updates the Blog model's $fillable. No translation model or cast is needed for non-translatable fields.

```php
## Add a migration
Schema::table('blogs', function (Blueprint $table) {
    $table->json('external_link')->nullable();
});

## Update your models fillable
class Blog extends Model {
    protected $fillable = [
        ...
        'external_link'
    ];
}
```

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

### Create Laravel project with composer create-project

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

Run this command in your working directory to create a new Laravel project named 'laravel-twill'. It downloads and extracts all required packages. You can choose a different directory name if desired.

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

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

### Access block input and translated input

Source: https://github.com/area17/twill/blob/3.x/docs/content/1_docs/5_block-editor/05_rendering-blocks.md

Within block Blade views, use the $block variable to retrieve block content. input() gets a regular field value, translatedinput() gets a translated field value. Replace the placeholder names with those specified in the block form.

```php
{{ $block->input('inputNameYouSpecifiedInTheBlockFormField') }}
{{ $block->translatedinput('inputNameYouSpecifiedInATranslatedBlockFormField') }}
```

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

### Generate a capsule

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

Bootstrap a new capsule using the command. It accepts the same arguments as the module CLI generator; if no arguments are passed it will ask during generation, except for --singleton which can be added for a singleton module.

```bash
php artisan twill:make:capsule Comment
```

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

### Register homepage settings group in AppServiceProvider

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

Adds a settings group named 'homepage' with label 'Homepage' using TwillAppSettings::registerSettingsGroup in the boot method. Requires creating the settings folder and blade file to avoid an exception when accessing the settings link.

```php
<?php

namespace App\Providers;

use A17\Twill\Facades\TwillAppSettings;
use A17\Twill\Services\Settings\SettingsGroup;
use Illuminate\Support\ServiceProvider;
use A17\Twill\Facades\TwillNavigation;
use A17\Twill\View\Components\Navigation\NavigationLink;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
    }

    public function boot()
    {
        TwillNavigation::addLink(
            NavigationLink::make()->forModule('pages')
        );
        TwillNavigation::addLink(
            NavigationLink::make()->forModule('menuLinks')->title('Menu')
        );
        TwillAppSettings::registerSettingsGroup(
            SettingsGroup::make()->name('homepage')->label('Homepage')
        );
    }
}
```

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

### Image::make()

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

Renders the first role media in the model by default. Can specify role and crop, and optionally make the image round.

```APIDOC
## Image::make()

### Description
By default renders the first role media in the model. You can specify the `role` and `crop` using their same named methods. If you add `rounded()` the image will be round.

### Method
`Image::make()`

### Parameters
- **role** (string) - Optional - The media role to use.
- **crop** (string) - Optional - The crop to apply.
- **rounded** (bool) - Optional - If true, renders a round image.

### Usage Example
```php
Image::make()->role('cover')->crop('default')->rounded()
```

### Response
Renders the image based on the specified role and crop.
```

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

### Show twill:make:module command options

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

Run this artisan command with the --help flag to display all available options for creating a Twill module. The output lists options such as -B for hasBlocks, -T for hasTranslation, and -S for hasSlug. Only the module name is mandatory; other options are optional.

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

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

Description:
  Create a new Twill Module

Usage:
  twill:make:module [options] [--] <moduleName>

Arguments:
  moduleName

Options:
  -B, --hasBlocks
  -T, --hasTranslation
  -S, --hasSlug
  -M, --hasMedias
  -F, --hasFiles
  -P, --hasPosition
  -R, --hasRevisions
  -N, --hasNesting
      --bladeForm
  -E, --generatePreview
      --parentModel[=PARENTMODEL]
      --all
```

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

### disablePermalink

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

Removes the permalink from the create/edit screens.

```APIDOC
## disablePermalink

### Description
Removes the permalink from the create/edit screens.

### Method
disablePermalink

### Signature
`$this->disablePermalink()`

### Usage Example
```php
$this->disablePermalink();
```
```

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

### Create Twill modules for posts and pages

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

Run these artisan commands to generate the Posts and Pages modules. Then run the migrations with `php artisan migrate`.

```bash
php artisan twill:make:module posts
php artisan twill:make:module pages
```

```bash
php artisan migrate
```

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

### Enable Imgix signed URLs with environment variables

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

Enable signed URLs to restrict image access. Set IMGIX_USE_SIGNED_URLS to true and provide your Imgix signature key via IMGIX_SIGN_KEY. Always use environment variables for credentials, never store them in source control.

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

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

### Generate a Twill package with artisan command

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

Run this command to kickstart a new Twill package. It will create a package with a composer.json and TwillPackageServiceProvider.

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