Drupal Canvas
canvas
A comprehensive site-building and content composition system that enables site builders to theme and build websites through a browser-based visual interface, while empowering content creators to compose pages using components without writing code.
Overview
Drupal Canvas is a sophisticated component-based site-building platform that revolutionizes how websites are built and managed in Drupal. It provides a visual, browser-based interface that eliminates the need for traditional Drupal theming expertise.
The module enables site builders without Drupal experience to easily theme and build their entire website using only their browser, without writing code beyond basic HTML, CSS, and templating markup (e.g., Twig). Content creators can compose content on any part of the page without relying on developers.
Canvas supports multiple component sources including Single Directory Components (SDC), JavaScript/Code Components created directly in the browser, and Block plugins as components. It features a comprehensive versioning system for components, auto-save functionality, a powerful HTTP API for the React-based UI, and advanced features like AI-powered page building and personalization.
The module includes a complete set of configuration entities for managing components, patterns, folders, page regions, content templates, and asset libraries. It provides a dedicated 'Canvas Page' content entity type for building standalone pages entirely within the Canvas interface.
Install
composer require 'drupal/canvas:^1.0'
Features
- Visual, browser-based site building interface with React-based UI
- Support for multiple component sources: Single Directory Components (SDC), JavaScript/Code Components, and Block plugins
- Component versioning system with automatic version tracking and fallback support
- Auto-save functionality for both configuration and content entities
- Comprehensive HTTP API (v0) following OpenAPI specification for UI communication
- Content Templates for defining component-based layouts for content entity bundles
- Page Template/Region system for customizing theme regions with component trees
- Pattern system for creating reusable component tree configurations
- Folder organization for components and patterns
- Global Asset Library for site-wide custom CSS and JavaScript
- Shape matching system that maps JSON Schema definitions to Drupal field types
- PropExpression system for evaluating structured data from content entities
- Canvas Page content entity type for building standalone pages
- Semi-coupled theme engine for consistent preview rendering
- Extension system for adding custom functionality to the Canvas UI
- Integration with CKEditor 5 for rich text editing within components
- Media Library integration for image and media handling in components
Use Cases
Building Landing Pages Without Code
Marketing teams can create landing pages entirely through the Canvas visual interface. Using the Canvas Page content entity type, they can drag and drop components, configure props through auto-generated forms, and preview changes in real-time. No knowledge of Drupal theming, PHP, or Twig is required.
Creating Consistent Content Templates
Site builders can create Content Templates that define the component-based layout for specific content types (e.g., Article, Event, Product). Content editors then fill in the content data while the visual structure remains consistent. Exposed slots allow limited layout flexibility within defined boundaries.
Developing Custom Components in Browser
Developers can create Code Components directly in the Canvas UI using JavaScript and CSS. These components support props defined via JSON Schema and can access Drupal data through canvasData settings. Ideal for creating interactive components without touching the codebase.
Reusing Component Configurations as Patterns
Common component arrangements (like a hero section with specific styling) can be saved as Patterns. These patterns can then be inserted into any page or template, ensuring consistency and reducing repetitive configuration work.
Customizing Theme Regions
Site builders can populate theme regions (like sidebars, headers, footers) with component trees through the Page Region system. This provides a visual alternative to placing blocks and allows for more complex region compositions.
External Application Integration
Using the canvas_oauth submodule, external applications like headless CMS frontends or mobile apps can interact with Canvas through the authenticated HTTP API. This enables decoupled architectures while maintaining Canvas's visual editing capabilities.
Tips
- Use the 'V' key shortcut in the Canvas editor to temporarily hide the UI overlay, making it easier to inspect the rendered preview markup in browser developer tools.
- Install the canvas_dev_mode module during development to access the extensions toolbar and private APIs for debugging.
- For Code Components that need external data, use the dataDependencies configuration to declare URL fetches and drupalSettings requirements.
- When creating SDC components for Canvas, define comprehensive JSON Schema with examples for each required prop to improve the auto-generated form experience.
- Use Patterns to save commonly used component configurations, then insert them into pages for consistent layouts.
- The canvas_vite module significantly speeds up UI development by enabling Hot Module Replacement during Canvas UI development.
Dependencies
Related Projects
Canvas natively discovers and supports all SDC components from enabled modules and themes, exposing them as Canvas components with auto-generated input forms based on their JSON Schema definitions.
Full integration with Drupal's Media Library for handling images and media in component props. The Media Library widget is automatically used for image and media reference prop shapes.
Integration for rich text editing within component props that use HTML string formats. Provides dedicated Canvas text formats for block and inline HTML content.
Optional integration through the canvas_oauth submodule for OAuth2-based API authentication, enabling external applications to interact with Canvas.
Optional integration through the canvas_ai submodule for AI-powered page building capabilities.
Canvas can wrap any Drupal block plugin as a Canvas component through the Block ComponentSource plugin, making existing blocks available in the visual editor.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Components | /admin/appearance/component |
View and manage all available components in the Canvas system. Components can be enabled, disabled, audited, and organized into folders. This page lists components from all sources including SDC, Code Components, and Block plugins. |
| Pages | /admin/content/pages |
Manage Canvas Page content entities. View, edit, and delete pages created using the Canvas visual editor. |
| Drupal Canvas | /canvas |
Main entry point to the Canvas visual editing interface. Opens the React-based UI for composing pages and content using components. |
| Canvas Editor | /canvas/editor/{entity_type}/{entity} |
Visual editor interface for composing content using components. Supports editing Canvas Pages, Content Templates, and other component tree-enabled entities. |
Permissions
| Permission | Description |
|---|---|
|
Manage all component configurations, enable/disable components, and access component audit information. |
|
Create, edit, and delete JavaScript/Code components. This permission is restricted because code components can execute JavaScript. |
|
Create, edit, and delete folders for organizing components and patterns. |
|
Create, edit, and delete reusable pattern configurations. |
|
Configure page regions and manage the page template settings for theme regions. |
|
Create, edit, and delete content templates that define component layouts for content entity bundles. |
|
Create new Canvas Page content entities. |
|
Edit existing Canvas Page content entities. |
|
Delete Canvas Page content entities. |
|
Update entities with auto-saved changes in Drupal Canvas. Requires update access for those entities. |
Hooks
| Hook | Description |
|---|---|
hook_canvas_storable_prop_shape_alter |
Alter the storable prop shape for a component property. This hook allows modules to customize how JSON Schema prop definitions are mapped to Drupal field types, widgets, and settings. |
Troubleshooting
Ensure the front-end UI has been built by running 'npm install && npm run build' in the modules/contrib/canvas/ui directory. Also verify that the canvas_stark theme is installed.
Check that components meet the requirements of their source. For SDC components, ensure they have valid JSON Schema definitions in their component.yml file. Visit /admin/appearance/component/status to see disabled and incompatible components.
Verify the user has the 'publish auto-saves' permission and has update access to the entity being edited. Check browser console for API errors.
Ensure the JavaScript code is valid and the props are correctly defined in the JSON Schema. Check browser console for JavaScript errors.
Canvas requires JSON:API's read-only mode to be disabled. Check the status report for warnings about JSON:API configuration.
Security Notes
- The 'administer code components' permission is marked as restricted because Code Components can execute arbitrary JavaScript. Grant this permission only to trusted users.
- Canvas uses CSRF protection for all mutating API endpoints. External API access requires OAuth2 authentication through the canvas_oauth submodule.
- The canvas_oauth submodule should be used for any external application integration to ensure secure authentication.
- Component tree inputs are validated against defined schemas to prevent injection of invalid data.