Craft CMS

https://github.com/craftcms/cms
Admin
Craft CMS is a flexible and user-friendly content management system for creating custom digital...
Tokens:15,380
Snippets:144
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run VuePress development server

Source: https://github.com/craftcms/cms/blob/5.x/CONTRIBUTING.md

Install dependencies and start the local development server to preview documentation changes.

```bash
# Install npm dependencies
npm install

# Build + run the VuePress dev server
npm run docs:dev
```

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

### Start test generator with npx craft-playwright

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-playwright/README.md

Initializes the environment and launches the Playwright codegen tool for a specific URL.

```bash
npx craft-playwright boot
```

```bash
npx playwright codegen playwright.ddev.site/admin
```

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

### Run all tests with npx craft-playwright test

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-playwright/README.md

Boots the docker environment, installs Craft CMS, executes all tests, and shuts down the environment.

```bash
npx craft-playwright test
```

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

### Install via Composer CLI

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Run this command in your terminal to install the extension using composer.

```bash
php composer.phar require --prefer-dist yii2tech/ar-softdelete
```

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

### Manage docker environment with npx craft-playwright

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-playwright/README.md

Commands to manually boot the environment, run tests, and shut down the environment.

```bash
npx craft-playwright boot
```

```bash
npx playwright test
```

```bash
npx playwright test elements/inituielements
```

```bash
npx craft-playwright down
```

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

### Install craftcms-sass via npm

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-sass/README.md

Install the library as a development dependency using npm.

```bash
npm install craftcms-sass --save-dev
```

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

### Install via composer.json

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Add this line to the require section of your composer.json file.

```json
"yii2tech/ar-softdelete": "*"
```

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

### reload() method example

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The reload() method is used to refresh the table data. This example demonstrates triggering a reload every 15 seconds using setInterval.

```js
const adminTable = new Craft.VueAdminTable({
    // ...
});

// Reload table every 15 seconds
setInterval(function() {
    adminTable.reload();
}, 15000);
```

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

### Define and initialize action buttons for Craft.VueAdminTable

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

This example demonstrates how to define an array of menu and single action buttons and pass them to the Craft.VueAdminTable constructor.

```js
var actions = [
    {
      	// Menu button example
        label: Craft.t('app', 'Set Status'),
        actions: [
            {
                label: Craft.t('app', 'Enabled'),
                action: 'controller/update-status',
                param: 'status',
                value: 'enabled',
                status: 'enabled'
            },
            {
                label: Craft.t('app', 'Disabled'),
                action: 'controller/update-status',
                param: 'status',
                value: 'disabled',
                status: 'disabled'
            },
            {
                label: Craft.t('app', 'Refresh'),
                action: 'controller/refresh',
                param: 'refresh',
                value: 'all',
                allowMultiple: false,
              	separator: true
            }
        ]
    },
  	{
        label: Craft.t('app', 'Delete'),
        action: 'controller/delete',
    }
];

new Craft.VueAdminTable({
  ...,
  actions: actions,
  ...
});
```

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

### Configure Special Columns for Handle, Menu, and Detail

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

This example shows the configuration for handle, menu, and detail columns within a VueAdminTable instance.

```javascript
var data = [
  {
    id: 1,
    title: 'My First Item',
    status: true,
    url: '/my-first-item',
    handle: 'myFirstItem',
    menu: {
      showItems: false,
      menuBtnTitle: Craft.t('site', 'Edit Settings'),
      label: Craft.t('site', 'Edit Settings'),
      url: '/settings/1',
      items: null
    },
    detail: {
      handle: '<span data-icon="info"></span>',
      content: '<p>Extra information to show under the main row</p>'
    }
  },
  {
    id: 2,
    title: 'My Second Item',
    status: false,
    url: '/my-second-item',
    handle: 'mySecondItem',
    detail: {
      title: Craft.t('site', 'Further Information'),
      content: { list: 'of', things: ['to', 'show'] },
      showAsList: true    
    },
    menu: {
      showItems: true,
      showCount: true,
      menuBtnTitle: Craft.t('site', 'Edit Sub Options'),
      label: Craft.t('site', 'Edit Sub Options'),
      url: '/settings/subOptions',
      items: [
        {
          label: 'First Item of Second',
          url: '/my-second-item/first-item'
        },
        {
          label: 'Second Item of Second',
          url: '/my-second-item/second-item'
        }
      ]
    }
  }
];

var columns = [
  { name: '__slot:title', title: Craft.t('app', 'Title') },
  { name: '__slot:handle', title: Craft.t('app', 'Handle') },
  { name: '__slot:menu', title: Craft.t('site', 'Sub Options') },
  { name: '__slot:detail', title: '' }
];

new Craft.VueAdminTable({
  columns: columns,
  tableData: data
});
```

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

### DDL for Customer and Purchase tables

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Example DDL structure for relational tables using foreign keys with ON DELETE RESTRICT constraints.

```sql
CREATE TABLE `Customer`
(
   `id` integer NOT NULL AUTO_INCREMENT,
   `name` varchar(64) NOT NULL,
   `address` varchar(64) NOT NULL,
   `phone` varchar(20) NOT NULL,
    PRIMARY KEY (`id`)
) ENGINE InnoDB;

CREATE TABLE `Purchase`
(
   `id` integer NOT NULL AUTO_INCREMENT,
   `customerId` integer NOT NULL,
   `itemId` integer NOT NULL,
   `amount` integer NOT NULL,
    PRIMARY KEY (`id`)
    FOREIGN KEY (`customerId`) REFERENCES `Customer` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE,
    FOREIGN KEY (`itemId`) REFERENCES `Item` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE,
) ENGINE InnoDB;
```

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

### Initialize VueAdminTable with Title Column

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

This example demonstrates how to use the __slot:title column type to render items with status, title, and URL attributes.

```javascript
var data = [
  {
    title: 'My First Item',
    status: true,
    url: '/my-first-item',
  },
  {
    title: 'My Second Item',
    status: false,
    url: '/my-second-item',
  }
];

var columns = [
  { name: '__slot:title', title: Craft.t('app', 'Title') },
];

new Craft.VueAdminTable({
  columns: columns,
  tableData: data
});
```

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

### Run specific tests with npx craft-playwright test

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-playwright/README.md

Executes only the specified test suite, such as elementindex/sorting, while managing the docker lifecycle.

```bash
npx craft-playwright test elementindex/sorting
```

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

### Query entries error response

Source: https://github.com/craftcms/cms/blob/5.x/tests/gql/data/gql.txt

Example of an error response when querying entries.

```graphql
{entries (sectionId: 1000) {title slug}}
```

```json
{"errors":[{"message":"Cannot query field \"entries\" on type \"Query\"
```

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

### Handle ElementEditor input in Playwright

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-playwright/README.md

Use pressSequentially with a delay instead of fill to avoid flakiness caused by custom keyboard handling.

```javascript
.pressSequentially('text', { delay: 100 })
```

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

### checkboxStatus callback example

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Use the checkboxStatus callback to determine the status of a checkbox based on a boolean value in each row. This is also the appropriate location for additional logic, such as calling other data.

```js
new Craft.VueAdminTable({
    // ... 
    checkboxStatus: function(row) {
        return row.isCheckboxEnabled
    }
    // ...
});
```

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

### Initialize Craft.VueAdminTable

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Initialize the table using JavaScript with the required options.

```js
new Craft.VueAdminTable({...options...});
```

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

### Implement beforeDelete hook

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The beforeDelete hook provides control over the deletion process by returning a Promise. The promise should resolve with a boolean to determine if the process continues, using the provided id parameter.

```js
new Craft.VueAdminTable({
    // ...
    beforeDelete: id => {
        return new Promise(function (resolve) {
            setTimeout(() => {
                resolve(id > 99);
            }, 1500);
        });
    },
    // ...
});
```

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

### Query global sets by handle

Source: https://github.com/craftcms/cms/blob/5.x/tests/gql/data/gql.txt

Fetches the name and plain text field for a specific global set.

```graphql
{globalSets (handle: "aDifferentGlobalSet") {name ... on aDifferentGlobalSet_GlobalSet { plainTextField}}}
```

```json
{"data":{"globalSets":[{"name":"A different global set","plainTextField":"No more information to give."}]}}
```

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

### Craft.VueAdminTable Constructor

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Initializes a new VueAdminTable instance. This component supports both data mode (using tableData) and api mode (using tableDataEndpoint).

```APIDOC
## Craft.VueAdminTable

### Description
Initializes the VueAdminTable component. It accepts configuration properties such as search settings, data sources, and callbacks like checkboxStatus.

### Parameters
- **searchClear** (String) - Optional - Title of the button that clears search value.
- **searchParams** (Array) - Optional - The attributes to search through (only used in data mode).
- **searchPlaceholder** (String) - Optional - Search placeholder text.
- **tableData** (Array) - Optional - Array of objects used to populate the table data for data mode.
- **tableDataEndpoint** (String) - Optional - Endpoint for api mode to retrieve table data, pagination and table metadata.
- **checkboxStatus** (Function) - Optional - Callback to determine the status of a checkbox for a given row.
```

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

### Using safeDelete() for conditional deletion

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Demonstrates how safeDelete() attempts a regular delete and falls back to soft delete if a foreign key constraint violation occurs.

```php
<?php

// if there is a foreign key reference :
$customer = Customer::findOne(15);
var_dump(count($customer->purchases)); // outputs; "1"
$customer->safeDelete(); // performs "soft" delete!
var_dump($customer->isDeleted) // outputs: "true"

// if there is NO foreign key reference :
$customer = Customer::findOne(53);
var_dump(count($customer->purchases)); // outputs; "0"
$customer->safeDelete(); // performs actual delete!
$customer = Customer::findOne(53);
var_dump($customer); // outputs: "null"
```

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

### Configure SSO Provider in components

Source: https://github.com/craftcms/cms/blob/5.x/src/auth/sso/README.md

Configures an OIDC provider within the components array. Uses environment variables for sensitive client credentials.

```php
'components' => [
    'sso' => [
        'providers' => [
            'test' => [
                'type' => \craft\auth\oidc\Google::class,
                'settings' => [
                    'clientId' => App::env('GOOGLE_OAUTH_CLIENT_ID'),
                    'clientSecret' => App::env('GOOGLE_OAUTH_CLIENT_SECRET'),
                ]
            ],
//                'saml' => [
//                    'type' => 'modules\auth\providers\Saml',
//                ],
            // etc.
        ],
    ],
]
```

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

### Craft.VueAdminTable

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The VueAdminTable constructor initializes a data-driven table component. It accepts configuration options including column definitions and the data source to be rendered.

```APIDOC
## Craft.VueAdminTable

### Description
Initializes a new VueAdminTable instance to render data in a structured table format. It supports special column slots and custom rendering callbacks.

### Constructor
new Craft.VueAdminTable(options)

### Parameters
- **columns** (array) - Required - An array of column definition objects. Special columns can be enabled using the `__slot:` prefix (e.g., `__slot:title`, `__slot:handle`, `__slot:menu`, `__slot:detail`).
- **tableData** (array) - Required - An array of objects containing the data to be displayed in the table rows.

### Column Definition Options
- **name** (string) - Required - The key in the data object or the slot identifier.
- **title** (string) - Optional - The display title for the column header.
- **callback** (function) - Optional - A function that receives the cell value and returns custom HTML for rendering the cell content.
```

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

### Craft.VueAdminTable

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Initializes a Vue-based admin table in the Craft control panel. This constructor accepts an options object to configure table behavior, toolbar buttons, and selection settings.

```APIDOC
## Craft.VueAdminTable

### Description
Initializes a new Vue admin table instance on a specified DOM element.

### Constructor
new Craft.VueAdminTable(options)

### Options
- **actions** (Array) - Optional - Array of action options to create action buttons in the table toolbar.
- **allowMultipleSelections** (Bool) - Optional - Determines whether multiple selections are allowed when using checkboxes.
- **allowMultipleDeletions** (Bool) - Optional - Determines whether multiple deletions are allowed when using checkboxes.
- **beforeDelete** (Function) - Optional - A function returning a promise that resolves to a boolean to determine if the delete process continues.
- **buttons** (Array) - Optional - Array of buttons to be placed in the toolbar.
- **checkboxes** (Bool) - Optional - Whether to show the checkbox column.
- **checkboxStatus** (Function) - Optional - Callback function to determine if the row's checkbox should be disabled.
```

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

### Query entries with matrixFirst block

Source: https://github.com/craftcms/cms/blob/5.x/tests/gql/data/gql.txt

Fetches the slug and the first block of the matrixFirst field for entries in section 1000.

```graphql
{  entries (sectionId: 1000) {  slug  ... on test1_test1_Entry {  matrixFirst (limit: 1){  ... on matrixFirst_aBlock_BlockType {  firstSubfield  }  }  }  }  }
```

```json
{"data":{"entries":[{"slug":"Theories--of--matrix","matrixFirst":[{"firstSubfield":"Some text"}]}]}}
```

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

### Craft.VueAdminTable Configuration

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The Craft.VueAdminTable constructor allows for configuring table behavior, including toolbar buttons and lifecycle hooks like beforeDelete.

```APIDOC
## Craft.VueAdminTable Constructor

### Description
Initializes a new VueAdminTable instance with specific configuration options for buttons and delete hooks.

### Parameters
- **buttons** (array) - Optional - An array of objects defining toolbar buttons. Each object contains: label (string), icon (string, optional), href (string), and enabled (boolean or callback).
- **beforeDelete** (function) - Optional - A hook that receives an id and returns a Promise that resolves to a boolean to determine if the delete process should proceed.
```

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

### Craft.VueAdminTable JS Event Usage

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Demonstrates how to hook into various lifecycle and interaction events when initializing a Craft.VueAdminTable instance. The onQueryParams event allows for modifying the request parameters before they are sent to the data endpoint.

```js
new Craft.VueAdminTable({
  // ...
  onLoaded: function() { console.log('LOADED!'); },
  onData: function(data) { console.log('Data:', data); },
  onQueryParams: function(params) {
    console.log('Query Params:', params);

    params.foo = 'bar';
    return params;
  },
  onCellClicked: function(data, field, event) { console.log('Cell Clicked:', data, field, event); },
  onCellDoubleClicked: function(data, field, event) { console.log('Cell Double Clicked:', data, field, event); },
  onRowClicked: function(data, event) { console.log('Row Clicked:', data, event); },
  onRowDoubleClicked: function(data, event) { console.log('Row Double Clicked:', data, event); },
  // ...
});
```

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

### Create delete link with version parameter

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Generate a delete link that includes the version attribute to support optimistic locking.

```php
<?php
use yii\helpers\Html;

/* @var $model Item */
?>
...
<?= Html::a('delete', ['delete', 'id' => $model->id, 'version' => $model->version], ['data-method' => 'post']) ?>
...
```

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

### Restore records using restore()

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Use the restore() method to revert a record previously marked as deleted via softDelete(). The isDeleted property will be set to false after restoration.

```php
<?php

$id = 17;
$item = Item::findOne($id);
$item->softDelete(); // mark record as "deleted"

$item = Item::findOne($id);
$item->restore(); // restore record
var_dump($item->isDeleted); // outputs "false"
```

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

### Query entries by sectionId

Source: https://github.com/craftcms/cms/blob/5.x/tests/gql/data/gql.txt

Fetches the title and slug for entries in section 1000.

```graphql
{entries (sectionId: 1000) {title slug}}
```

```json
{"data":{"entries":[{"title":"Theories of matrix","slug":"Theories--of--matrix"}]}}
```

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

### Attaching behavior to a custom query class

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Define a custom query class and attach the SoftDeleteQueryBehavior within its behaviors() method.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;
use yii2tech\ar\softdelete\SoftDeleteQueryBehavior;

class Item extends ActiveRecord
{
    // ...
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                // ...
            ],
        ];
    }

    /**
     * @return ItemQuery|SoftDeleteQueryBehavior
     */
    public static function find()
    {
        return new ItemQuery(get_called_class());
    }
}

class ItemQuery extends \yii\db\ActiveQuery
{
    public function behaviors()
    {
        return [
            'softDelete' => [
                'class' => SoftDeleteQueryBehavior::className(),
            ],
        ];
    }
}
```

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

### Register AdminTableAsset in PHP

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Register the asset bundle within a controller, plugin, or module.

```php
$this->getView()->registerAssetBundle(AdminTableAsset::class);
```

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

### reload()

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Reloads the table data from the configured source.

```APIDOC
## reload()

### Description
Refreshes the table by re-fetching or re-processing the data source.

### Usage Example
```js
const adminTable = new Craft.VueAdminTable({ ... });
adminTable.reload();
```
```

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

### Query entries with matrix field appointments

Source: https://github.com/craftcms/cms/blob/5.x/tests/gql/data/gql.txt

Fetches entries in section 1000 including specific columns from the appointments matrix field.

```graphql
{entries (sectionId: 1000) { title slug ... on test1_test1_Entry { appointments { col1 col3 } } }}
```

```json
{"data":{"entries":[{"title":"Theories of matrix","slug":"Theories--of--matrix","appointments":[{"col1":"A rally","col3":7},{"col1":"A protest","col3":500}]}]}}
```

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

### Define ActiveRecord with SoftDeleteBehavior and optimisticLock

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Configure the SoftDeleteBehavior and specify the version attribute for optimistic locking in the ActiveRecord class.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;

class Item extends ActiveRecord
{
    /**
     * {@inheritdoc}
     */
    public function behaviors()
    {
        return [
            'softDelete' => [
                'class' => SoftDeleteBehavior::className(),
                'softDeleteAttributeValues' => [
                    'isDeleted' => true
                ],
            ],
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function optimisticLock()
    {
        return 'version';
    }
}
```

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

### Implement Column Callback for Custom HTML

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Use the callback option in a column definition to customize cell output, such as injecting custom HTML based on the cell value.

```javascript
var data = [
  {
    myColumn: true
  },
  {
    myColumn: false
  }  
];

var columns = [
  { 
    name: 'myColumn', 
    title: Craft.t('site', 'My Column'),
    callback: function(value) {
      if (value) {
        return '<span data-icon="check" title="'+Craft.t('app', 'Yes')+'"></span>';
      }
      
      return '';
    }
  }
];

new Craft.VueAdminTable({
  columns: columns,
  tableData: data
});
```

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

### Handle soft delete events in ActiveRecord class

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Handle soft delete and restore events by declaring methods like beforeSoftDelete() and beforeRestore() within your ActiveRecord class.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;

class Item extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                // ...
            ],
        ];
    }

    public function beforeSoftDelete()
    {
        $this->deletedAt = time(); // log the deletion date
        return true;
    }

    public function beforeRestore()
    {
        return $this->deletedAt > (time() - 3600); // allow restoration only for the records, being deleted during last hour
    }
}
```

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

### Mounting element for Admin Table

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Define the HTML element where the Vue admin table will be mounted.

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

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

### Attaching SoftDeleteQueryBehavior manually

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Attach the SoftDeleteQueryBehavior to the query instance within the find() method of your ActiveRecord class.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;
use yii2tech\ar\softdelete\SoftDeleteQueryBehavior;

class Item extends ActiveRecord
{
    // ...
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                // ...
            ],
        ];
    }

    /**
     * @return \yii\db\ActiveQuery|SoftDeleteQueryBehavior
     */
    public static function find()
    {
        $query = parent::find();
        $query->attachBehavior('softDelete', SoftDeleteQueryBehavior::className());
        return $query;
    }
}
```

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

### Implement Smart Deletion with allowDeleteCallback

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Uses allowDeleteCallback to conditionally perform a hard delete or a soft delete based on record properties. This requires the replaceRegularDelete property to be enabled.

```php
<?php
 
use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;

class User extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                'softDeleteAttributeValues' => [
                    'isDeleted' => true
                ],
                'allowDeleteCallback' => function ($user) {
                    return $user->lastLoginDate === null; // allow delete user, if he has never logged in
                }
            ],
        ];
    }
}

$user = User::find()->where(['lastLoginDate' => null])->limit(1)->one();
$user->softDelete(); // removes the record!!!

$user = User::find()->where(['not' =>['lastLoginDate' => null]])->limit(1)->one();
$user->softDelete(); // marks record as "deleted"
```

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

### Attach SoftDeleteBehavior to ActiveRecord

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Attach the behavior to your model class to enable soft delete functionality.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;

class Item extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                'softDeleteAttributeValues' => [
                    'isDeleted' => true
                ],
            ],
        ];
    }
}
```

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

### Enable replaceRegularDelete option

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Configure the behavior to mutate the native delete() method to perform soft deletion instead of removing the record.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;

class Item extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                'softDeleteAttributeValues' => [
                    'isDeleted' => true
                ],
                'replaceRegularDelete' => true // mutate native `delete()` method
            ],
        ];
    }
}
```

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

### Configuring custom filter conditions

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Manually configure deletedCondition and notDeletedCondition when using non-standard status values.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;
use yii2tech\ar\softdelete\SoftDeleteQueryBehavior;

class Item extends ActiveRecord
{
    // ...
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                'softDeleteAttributeValues' => [
                    'statusId' => 'deleted',
                ],
            ],
        ];
    }

    /**
     * @return \yii\db\ActiveQuery|SoftDeleteQueryBehavior
     */
    public static function find()
    {
        $query = parent::find();
        
        $query->attachBehavior('softDelete', [
            'class' => SoftDeleteQueryBehavior::className(),
            'deletedCondition' => [
                'statusId' => 'deleted',
            ],
            'notDeletedCondition' => [
                'statusId' => 'active',
            ],
        ]);
        
        return $query;
    }
}
```

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

### Using named scopes for filtering

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Use the deleted() and notDeleted() methods provided by the behavior to filter records or join queries.

```php
<?php

// Find all "deleted" records:
$deletedItems = Item::find()->deleted()->all();

// Find all "active" records:
$notDeletedItems = Item::find()->notDeleted()->all();

// find all comments for not "deleted" items:
$comments = Comment::find()
    ->innerJoinWith(['item' => function ($query) {
        $query->notDeleted();
    }])
    ->all();
```

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

### Use softDelete() method

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Use the softDelete() method to mark a record as deleted while keeping the native delete() method available for hard deletes.

```php
<?php

$id = 17;
$item = Item::findOne($id);
$item->softDelete(); // mark record as "deleted"

$item = Item::findOne($id);
var_dump($item->isDeleted); // outputs "true"

$item->delete(); // perform actual deleting of the record
$item = Item::findOne($id);
var_dump($item); // outputs "null"
```

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

### Handle StaleObjectException in controller

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Catch the StaleObjectException in the controller action to resolve conflicts when the version number is outdated.

```php
<?php

use yii\db\StaleObjectException;
use yii\web\Controller;

class ItemController extends Controller
{
    public function delete($id, $version)
    {
        $model = $this->findModel($id);
        $model->version = $version;
        
        try {
            $model->softDelete();
            return $this->redirect(['index']);
        } catch (StaleObjectException $e) {
            // logic to resolve the conflict
        }
    }
    
    // ...
}
```

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

### Configure buttons in VueAdminTable

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The buttons option accepts an array of objects to define anchor links in the table toolbar. Each object requires a label and href, with an optional icon and an enabled property that accepts a boolean or a callback function.

```js
new Craft.VueAdminTable({
    // ...
    buttons: [
        {
            label: 'Create New Thing',
            icon: 'plus',
            href: '{{ cpUrl("my-plugin/thing/new") }}',
            enabled: () => true,
        }
    ],
});
```

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

### Query entries with formatted date

Source: https://github.com/craftcms/cms/blob/5.x/tests/gql/data/gql.txt

Fetches entries in section 1000 and applies a custom date format to the col2 field in appointments.

```graphql
{  entries (sectionId: 1000) {  slug  ... on test1_test1_Entry {  appointments {  col2 @formatDateTime (format: "---")  }  }  }  }
```

```json
{"data":{"entries":[{"slug":"Theories--of--matrix","appointments":[{"col2":"---"},{"col2":"---"}]}]}}
```

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

### Register AdminTableAsset in Twig

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

Register the asset bundle directly within a template.

```twig
{% do view.registerAssetBundle('craft\web\assets\admintable\AdminTableAsset') -%}
```

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

### Apply SoftDeleteBehavior and Default Scope

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Configures the SoftDeleteBehavior in an ActiveRecord class and overrides the find() method to filter out deleted records by default. The default scope can be reset using onCondition() for relational databases or where() for NoSQL databases.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;
use yii2tech\ar\softdelete\SoftDeleteQueryBehavior;

class Item extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                'softDeleteAttributeValues' => [
                    'isDeleted' => true
                ],
            ],
        ];
    }

    /**
     * @return \yii\db\ActiveQuery|SoftDeleteQueryBehavior
     */
    public static function find()
    {
        $query = parent::find();
        
        $query->attachBehavior('softDelete', SoftDeleteQueryBehavior::className());
        
        return $query->notDeleted();
    }
}

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

$allItems = Item::find()
    ->onCondition([]) // resets "not deleted" scope for relational databases
    ->all(); // returns all records

$allItems = Item::find()
    ->where([]) // resets "not deleted" scope for NOSQL databases
    ->all(); // returns all records
```

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

### Invoke mutated delete() method

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

After enabling replaceRegularDelete, calling delete() will mark the record as deleted.

```php
<?php

$id = 17;
$item = Item::findOne($id);
$item->delete(); // no record removal, mark record as "deleted" instead

$item = Item::findOne($id);
var_dump($item->isDeleted); // outputs "true"
```

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

### Attach event handlers to ActiveRecord

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Attach event handlers to the ActiveRecord object to intercept soft delete operations. Setting $event->isValid to false prevents the soft delete from occurring.

```php
<?php

$item = Item::findOne($id);
$item->on(SoftDeleteBehavior::EVENT_BEFORE_SOFT_DELETE, function($event) {
    $event->isValid = false; // prevent "soft" delete to be performed
});
```

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

### Admin Table Data Endpoint

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The Admin Table component expects a JSON response from the configured tableDataEndpoint to populate rows and handle pagination. The endpoint must return a specific structure containing pagination metadata and the data rows.

```APIDOC
## GET [tableDataEndpoint]

### Description
Retrieves data for the admin table, including pagination information and row data. Sorting parameters are passed to this endpoint via query parameters.

### Method
GET

### Query Parameters
- **sort** (string) - Optional - The sorting criteria in the format `{field}|{direction}` (e.g., `email|asc`).

### Response
#### Success Response (200)
- **pagination** (object) - Pagination metadata including total, per_page, current_page, last_page, next_page_url, prev_page_url, from, and to.
- **data** (array) - An array of associative arrays representing the table rows, where keys map to column handles.

#### Response Example
{
  "pagination": {
    "total": 100,
    "per_page": 20,
    "current_page": 1,
    "last_page": 5,
    "next_page_url": "/api/data?page=2",
    "prev_page_url": null,
    "from": 1,
    "to": 20
  },
  "data": [
    { "id": 1, "email": "test@example.com" }
  ]
}
```

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

### Filtering records with filterDeleted

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Use the filterDeleted() method to dynamically apply filtering based on a request parameter.

```php
<?php

// Filter records by "soft" deleted criteria:
$items = Item::find()
    ->filterDeleted(Yii::$app->request->get('filter_deleted'))
    ->all();
```

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

### Craft.VueAdminTable Events

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

The Craft.VueAdminTable component provides various JavaScript and Vue events to hook into table interactions such as selection, data loading, and row/cell clicks.

```APIDOC
## Craft.VueAdminTable Events

### Description
These events allow developers to respond to user interactions and lifecycle changes within the VueAdminTable component.

### JS Events
- **onSelect** (Array of IDs) - Triggered when a checkbox or select all is selected or de-selected.
- **onData** (Array of objects) - Triggered on successful load or page change.
- **onCellClicked** (data, field, event) - Triggered on click of a table cell.
- **onCellDoubleClicked** (data, field, event) - Triggered on double click of a table cell.
- **onRowClicked** (data, event) - Triggered on click of a table row.
- **onRowDoubleClicked** (data, event) - Triggered on double click of a table row.
- **onLoaded** (-) - Triggered when the table has loaded.
- **onLoading** (-) - Triggered when the table is in a loading state.
- **onPagination** (Object) - Triggered when pagination has loaded.
- **onQueryParams** (Object) - Triggered when query parameters are being generated for the table data endpoint. Returns an Object.

### Vue Events
- **onSelect** (Array of IDs) - Triggered when a checkbox or select all is selected or de-selected.
- **data** (Array of objects) - Triggered on successful load or page change.
```

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

### Querying records manually

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Manually filter records by the isDeleted attribute to retrieve either active or deleted items.

```php
<?php

// returns only not "deleted" records
$notDeletedItems = Item::find()
    ->where(['isDeleted' => false])
    ->all();

// returns "deleted" records
$deletedItems = Item::find()
    ->where(['isDeleted' => true])
    ->all();
```

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

### Import mixins in Sass

Source: https://github.com/craftcms/cms/blob/5.x/packages/craftcms-sass/README.md

Import the mixins into your Sass files using the @import directive. The path depends on the location of your node_modules folder relative to the Sass file.

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

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

### Transaction limitation with replaceRegularDelete

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Mutating the delete() method prevents it from functioning with ActiveRecord transactions.

```php
<?php

use yii\db\ActiveRecord;
use yii2tech\ar\softdelete\SoftDeleteBehavior;

class Item extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'softDeleteBehavior' => [
                'class' => SoftDeleteBehavior::className(),
                'replaceRegularDelete' => true // mutate native `delete()` method
            ],
        ];
    }

    public function transactions()
    {
        return [
            'some' => self::OP_DELETE,
        ];
    }
}

$item = Item::findOne($id);
$item->setScenario('some');
$item->delete(); // nothing happens!
```

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

### Enclose softDelete() in a transactional block

Source: https://github.com/craftcms/cms/blob/5.x/lib/ar-softdelete/README.md

Explicitly wrap the softDelete() method call within a database transaction to ensure atomicity with other operations.

```php
<?php

$item = Item::findOne($id);

$transaction = $item->getDb()->beginTransaction();
try {
    $item->softDelete();
    // ...other DB operations...
    $transaction->commit();
} catch (\Exception $e) { // PHP < 7.0
    $transaction->rollBack();
    throw $e;
} catch (\Throwable $e) { // PHP >= 7.0
    $transaction->rollBack();
    throw $e;
}
```

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

### Admin Table Controller Response

Source: https://github.com/craftcms/cms/blob/5.x/src/web/assets/admintable/README.md

This PHP response format is required by the admin table when using API mode. It includes pagination metadata and the data rows as an array of associative arrays.

```php
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
]);
```
Tokens:
Raw