Twill Laravel Package

Getting Started

• Install via Composer: composer require area17/twill, then run php artisan twill:install to scaffold the admin UI, publish config/migrations, and create a basic Admin user.
• Begin by defining a model (e.g., Page) and its migration, then generate a Twill A17\Twill\Http\Controllers\Admin\SingletonModuleController (for singletons) or CrudController (for collections) via php artisan twill:make:admin Page.
• Configure the admin UI in the generated controller using the setUpManager() method—specify which fields to show in listing, form, and relationships via listProperties, formFields, and editFormPanels.
• For rapid iteration: enable twill.disabled in .env to disable the admin UI during development, or run php artisan twill:clear-cache after config changes.

Implementation Patterns

• Module-based Content Modeling: Group related models (e.g., Project, ProjectGalleryImage, ProjectTeamMember) into cohesive modules using Twill’s built-in relationships (many-to-many, morphMany, belongsTo) declared in the controller via hasMany, belongsToMany, etc. Use twill-img, twill-repeater, and twill-modal for rich UI components.
• Singletons for Global Content: Use SingletonModuleController (e.g., for SiteSettings, Homepage) with A17\Twill\Models\Singleton to manage site-wide data that appears in only one instance.
• Reusable Field Blocks: Define repeatable field groups using twill-repeater and twill-blocks—create custom Vue components for specialized blocks (e.g., a HeroBlock with image, video, and CTA) and register them in config/twill.php under blocks.
• Permissions & Roles: Leverage Laravel’s policies—define them for Twill models and register them in AuthServiceProvider. Use canViewAny, canEdit, etc., on models and in controller logic.
• Frontend Sync: Generate RESTful APIs with Twill’s A17\Twill\Api\Controllers\ApiController for headless frontends, or use Twill’s view() method to render Blade views directly. For hybrid apps, use A17\Twill\Traits\Exportable to generate JSON feeds.

Gotchas and Tips

• Migrations must be published early: php artisan twill:install publishes twill_users and related migrations—but if you’re adding custom fields to Twill’s core models (e.g., twill_users), do not modify vendor files; extend via user model traits (e.g., A17\Twill\Models\User) or use A17\Twill\Models\Singleton extensions.
• Blade syntax pitfalls: Use @twillLayout (not @extends) in admin views, and wrap custom admin views in twill::layouts.app. Avoid direct Blade @push in controller views—use Twill’s @twillScripts and @twillStyles slots instead.
• Cache & Rehydration: Twill caches module configs (fields, relationships). If field changes aren’t reflecting, clear: php artisan twill:clear-cache and php artisan config:clear. Rehydration (e.g., $model->rehydrate()) is needed after bulk updates to relationship collections.
• Extending Controllers Safely: When overriding listProperties or formFields, always call parent::setUpManager() first if extending built-in Twill controllers. Missed calls cause missing fields or broken relations.
• Performance Tip: For large datasets (>1k rows), configure pagination in listProperties ('perPage' => 25) and avoid eager-loading unnecessary relations in getIndexQuery()—only include with() relations actually used in listing columns.