Twill CMS Documentation

Twill is an open source Laravel package designed for rapidly creating custom, flexible content management systems (CMS). It provides a feature-rich admin console with pre-built Vue.js UI components while maintaining full developer control.

Key characteristics include:

• No lock-in: You can create new data models or hook into existing ones.
• Flexible architecture: Can be used within a standard Laravel application or as a headless CMS.
• Modular: You can disable features you do not need to avoid bloat.
• Developer-centric: No need to write or adapt HTML for the admin UI, and it is fully extensible.

In Twill, a Module represents a single content type. A module consists of several key files that work together to bridge your data with the CMS UI:

• Model Class (app/Models): A standard Laravel Eloquent model defining the content type and database connection.
• Module Controller Class (app/Http/Controllers/Twill): Acts as a bridge between your model and the Twill CMS front-end UI.
• Repository Class (app/Repositories): Handles saving, reading, and custom pre/post-save logic for your model.
• Requests Class (app/Http/Requests/Twill): Used for form validation.
• Form Blade File (Optional): Defines how the form appears in the CMS.

Twill leverages Laravel's authentication and authorization. By default, users can log in at /login and reset passwords via the same screen. New users must reset their password before accessing the admin application.

Default Roles

• view only: Can login, view/filter CRUD listings, view/download media/files, and edit their own profile.
• publisher: All 'view only' permissions plus full CRUD, publish, sort, feature, and uploading new media/files.
• admin: All 'publisher' permissions plus full permissions on users.
• super admin: Can impersonate any user at /users/impersonate/{id}. To stop impersonating, visit /users/impersonate/stop.

Twill allows you to configure several high-level CMS features via configuration files:

• User Management: Authentication, authorization, and user management.
• Navigation: A three-level hierarchy with breadcrumbs for content structure.
• Dashboard: Configurable dashboard with quick access links, activity logs, and Google Analytics integration.
• Global Search: Configurable search across the CMS.
• Content Featuring: A 'bucket' UI to manage featured content or localization settings.

Implementing a custom block class allows you to perform the following tasks:

• Customize block validation: Define specific rules for the block's content.
• Modify rendering data: Send additional data properties to the block's Blade rendering file.
• Extend block forms: Send additional data properties to the Twill editor form.

In Twill, a module is the fundamental unit of functionality. It consists of a set of files that define a specific content model and its associated business logic within your application. Modules allow you to configure features for content publishers, such as:

• Translations: Enabling multi-language support for content.
• Media Attachments: Allowing users to attach images and other media to records.
• Complex Data Structures: Defining sophisticated relationships and data types within your content records.

A Twill module is a set of classes and configurations in your Laravel application that enables publishers to manage specific content types. Modules function as feature-rich Laravel resources (CRUD modules) providing operations like Create, Read, Update, Delete, Publish, Feature, Tag, Preview, Restore, Reorder, and Bulk edit.

Modules are implemented using PHP traits in your Eloquent models and Twill repositories, following Laravel's migration and Eloquent conventions. They typically consist of a listing page and a form page or modal.

The Block Editor provides a dynamic, drag-and-drop interface for adding and arranging content blocks (such as images, text, or custom components) within a Twill entry.

To implement a block editor, follow these three high-level steps:

1. Include the block editor form field in your module's form.
2. Create and define the specific block types you want to support.
3. Apply the necessary block traits to your Model and Repository to ensure data is correctly handled.

To begin setting up a project for Twill, install a fresh Laravel project using Composer. This creates the necessary directory structure and downloads required packages.

Run the following command in your terminal:

composer create-project laravel/laravel laravel-twill

After installation, navigate into the project directory:

cd laravel-twill

To run the application locally, you can use Laravel's built-in web server:

php artisan serve