Craft CMS Documentation

Craft CMS is a flexible, self-hosted CMS designed for custom digital experiences. Key features include:

• Content Modeling: A clean-slate approach with no assumptions about your content structure.
• Templating: A fast and flexible system based on Twig.
• Headless Capabilities: An auto-generated GraphQL API for building headless applications.
• Ecommerce: A powerful platform for bespoke ecommerce experiences via Craft Commerce.
• Extensibility: A built-in Plugin Store and a robust extension framework for advanced customization.
• Control Panel: An intuitive interface for content creation and administration.

All craft-playwright commands must be run from the root of your CMS repository. These commands manage a Docker-based environment (using DDEV) that boots up, installs Craft CMS, and executes tests.

• Run all tests and shut down: Boots the environment, runs all tests, and shuts down Docker.
• Run specific test files: Boots the environment, runs only the specified test path, and shuts down Docker.
• Interactive UI mode: Add the --ui flag to run tests in the Playwright interactive UI.
• Debug mode: Add the --debug flag to run tests in interactive UI mode with a debugger for line-by-line stepping.

If you want to keep the testing environment running instead of shutting it down after every test run, use the following workflow:

1. Boot the environment: npx craft-playwright boot (sets up Docker and installs Craft CMS).
2. Run tests: Use standard Playwright commands, such as npx playwright test or npx playwright test <path>.
3. Shut down: When finished, run npx craft-playwright down to stop the environment.

To start the Playwright test generator (codegen) within the testing environment:

1. Boot the environment using npx craft-playwright boot.
2. Run the codegen command targeting the local DDEV site: npx playwright codegen playwright.ddev.site/admin.

The Craft.VueAdminTable component supports two data modes:

1. Data Mode: Pass an array of objects directly to the tableData option. Note that Column Sorting and Pagination are not available in this mode.

2. API Mode: Use the tableDataEndpoint option to fetch data from a controller. The controller must return a JSON response with a specific structure containing pagination and data keys.

return $this->asJson([
    'pagination' => [
      'total' => (int)$total,
      'per_page' => (int)$limit,
      'current_page' => (int)$page,
      'last_page' => (int)$lastPage,
      'next_page_url' => $nextPageUrl,
      'prev_page_url' => $prevPageUrl,
      'from' => (int)$from,
      'to' => (int)$to,
    ],
    'data' => $rows
]);

To access the same mixins and variables used by the core Craft CMS Control Panel templates, import _mixins.sass into your Sass files using the @import directive. Note that the exact path to the mixins file will depend on your project's directory structure relative to node_modules.

@import "../node_modules/craftcms-sass/mixins";

To set up the Playwright testing environment, ensure you have docker, node, and nvm installed on your host machine. Follow these steps within your CMS repository directory (e.g., packages/cms):

1. Pull the relevant branch.
2. Navigate to your CMS repository location.
3. Run nvm use to switch to the correct Node version.
4. Run npm ci to install dependencies.
5. Run npx playwright install to install Playwright browsers.
6. Navigate into the tests-playwright directory and copy .env.example to .env, adjusting values as necessary.

Transactions

softDelete() can be wrapped in a manual database transaction. Additionally, if your model uses yii\db\ActiveRecord::transactions() to define automatic transaction scenarios, softDelete() will participate in those transactions as it responds to both OP_UPDATE and OP_DELETE operations.

Warning: safeDelete() uses its own internal transaction logic and may conflict with automatic transactions defined via ActiveRecord::transactions(). Avoid using safeDelete() in scenarios managed by that method.

Optimistic Locking

softDelete() supports optimistic locking. If your model implements optimisticLock(), calling softDelete() will throw a yii\db\StaleObjectException if the version attribute has changed since the record was loaded.

You can apply the notDeleted() scope as a default to all find() calls by calling it within the find() method override. To bypass this default scope and retrieve all records (including deleted ones), use onCondition([]) for relational databases or where([]) for NoSQL databases.

<?php

class Item extends ActiveRecord
{
    public static function find()
    {
        $query = parent::find();
        $query->attachBehavior('softDelete', SoftDeleteQueryBehavior::className());
        return $query->notDeleted();
    }
}

// Returns only not "deleted" records
$notDeletedItems = Item::find()->all();

// Returns all records (including deleted)
$allItems = Item::find()->onCondition([])->all();

To render a Vue Admin Table, provide a mounting point in your HTML. The table requires a specific element with an ID to serve as the mount target.

<div id="example-admin-table"></div>