Statamic CMS

https://github.com/statamic/cms
Admin
Statamic CMS is a flat-first, Laravel and Git powered content management system designed for...
Tokens:21,157
Snippets:355
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Importing UI components from @statamic/cms/ui

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/Overview.mdx

Demonstrates optional namespace imports from `@statamic/cms/ui` to enable IDE autocomplete and linking. The example shows a Vue `<script setup>` block and its template using the imported components.

```vue
<script setup>
import { Card, Heading, Button } from '@statamic/cms/ui';
</script>

<template>
    <Card>
        <Heading text="A lovely card" />
        <Button @click="doSomething" text="Click me" />
    </Card>
</template>
```

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

### Custom PublishContainer layout with script setup

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/PublishContainer.mdx

This script setup defines the component's props and reactive state for the custom publish layout. It imports necessary components from '@statamic/cms/ui' and initializes meta and values refs from props.

```javascript
<script setup>
import { ref } from 'vue';
import { PublishContainer, PublishComponents, PublishTabs, Button } from '@statamic/cms/ui';

const props = defineProps({
    permalink: String,
    blueprint: Object,
    initialMeta: Object,
    initialValues: Object,
});

const meta = ref(props.initialMeta);
const values = ref(props.initialValues);
</script>
```

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

### Antlers noparse example

Source: https://github.com/statamic/cms/blob/6.x/tests/__fixtures__/content/1996-11-18-dance.md

An Antlers template example showing how to prevent parsing of expressions using the noparse tag.

```antlers
{{ noparse }}
  Welcome to {{ fast_food_chain }},
  home of the {{ fast_food_chain_specialty_item }},
  can I take your order?
{{ /noparse }}
```

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

### Generate translation files for a new language

Source: https://github.com/statamic/cms/wiki/Translating-the-Control-Panel

Specify the language code as an argument to generate a new translation file. For example, 'fr' for French.

```bash
php translator generate fr
```

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

### PHP isNumberwang method

Source: https://github.com/statamic/cms/blob/6.x/tests/__fixtures__/content/1996-11-18-dance.md

A PHP method that checks if a value is in a list of numbers. Used as an example of a custom method.

```php
/**
     * Is it or is it not numberwang?
     *
     * @param $value
     * @return bool
     */
    public function isNumberwang($value)
    {
        return in_array($value, [1, 22, 7, 9, 1002, 2.3, 15, 109876567, 31]);
    }
```

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

### Import and use useArchitecturalBackground composable

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/EmptyState.mdx

Recommended for use alongside the empty state components. Call the composable to apply the architectural background styling.

```js
import { useArchitecturalBackground } from '@statamic/cms/inertia';

useArchitecturalBackground();
```

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

### Using UI components with kebab-case syntax

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/Overview.mdx

Shows the basic syntax for using Statamic UI components with the `ui-` prefix. This works in both Blade and Vue templates.

```html
<ui-card>
    <ui-heading text="A lovely card" />
    <ui-button @click="doSomething" text="Click me" />
</ui-card>
```

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

### Generate translation files for existing languages

Source: https://github.com/statamic/cms/wiki/Translating-the-Control-Panel

Run this command to generate translation files for all existing languages. It will populate them with empty strings.

```bash
php translator generate
```

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

### PHP development commands

Source: https://github.com/statamic/cms/blob/6.x/CLAUDE.md

Commands for running PHPUnit tests, using Laravel Pint for code style, and running a specific test file.

```bash
# Run PHPUnit tests
./vendor/bin/phpunit
# OR use the batch file on Windows
phpunit.bat

# Code style/linting (Laravel Pint)
./vendor/bin/pint

# Run specific test
./vendor/bin/phpunit tests/path/to/TestFile.php
```

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

### Action controller, routes, and actionUrl prop

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/Listing.mdx

Action controller extending Statamic's ActionController with a `$key` matching the action's `visibleTo` method and `getSelectedItems` looking up items by ID. Two routes point to `run` and `bulkActions`; the first route's URL is passed to the `actionUrl` prop.

```php
<?php

namespace App\Http\Controllers;

use App\Models\TeamMember;
use Statamic\Http\Controllers\CP\ActionController as Controller;

class TeamMemberActionController extends Controller
{
    protected static $key = 'team-members';

    protected function getSelectedItems($items, $context)
    {
        return $items->map(function ($item) {
            return TeamMember::find($item);
        });
    }
}
```

```php
Route::post('team-members/actions', [TeamMemberActionController::class, 'run']);
Route::post('team-members/actions/list', [TeamMemberActionController::class, 'bulkActions']);
```

```vue
<Listing
    :url="cp_url('team-members/json')"
    :action-url="cp_url('team-members/actions')"
    ...
/>
```

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

### Project structure tree

Source: https://github.com/statamic/cms/blob/6.x/CLAUDE.md

Shows the directory layout of the Statamic CMS core package, highlighting key folders like src/, resources/, tests/, config/, and routes/.

```text
├── src/                  # Core PHP source code (PSR-4: Statamic\)
│   ├── CP/               # Control Panel specific functionality  
│   └── ...               # Many other core modules
├── resources/
│   ├── js/               # Vue.js Control Panel frontend
│   │   ├── bootstrap/
│   │   │   ├── cms/      # Bootstraps the code necessary for the npm package
│   │   │   └── ...
│   │   ├── package/      # The @statamic/cms local npm package to be used by addons
│   │   ├── tests/        # JS test suite (Vitest)
│   │   └── ...
│   ├── css/              # Stylesheets
│   ├── views/            # Blade templates
│   └── lang/             # Translations
├── tests/                # PHPUnit test suite
├── config/               # Configuration files
└── routes/               # Route definitions
```

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

### Review and update existing translations

Source: https://github.com/statamic/cms/wiki/Translating-the-Control-Panel

Interactively review each line in the specified translation file. Shows the key, English phrase, and current translation, allowing you to enter a new translation.

```bash
php translator review fr messages
```

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

### injectPublishContext()

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/PublishContainer.mdx

Documentation for the injectPublishContext() function and the publishContextKey injection key, which expose the PublishContainer context to nested components.

```APIDOC
## injectPublishContext()

### Description
Injects the PublishContainer context into a component nested inside the container. Provides state and methods for managing publish forms.

### Method
injectPublishContext

### Parameters
None

### Returns
An object containing the following keys:

- `asConfig` (boolean) - Returns `true` when it's a config publish form.
- `blueprint` (array) - The blueprint's publish array.
- `components` (array) - Components pushed by addons.
- `desyncField(path)` (function) - Desync a field from its origin value.
- `direction` (string) - Text direction (`ltr` or `rtl`).
- `errors` (object) - Validation errors.
- `extraValues` (object) - Extra values made available to field conditions.
- `hiddenFields` (array) - Array of hidden field handles.
- `isDirty()` (function) - Returns `true` when the publish container's values are dirty.
- `isTrackingOriginValues` (boolean) - Returns `true` when editing a localization.
- `localizedFields` (array) - Array of localized field handles.
- `meta` (object) - Fieldtype meta.
- `name` (string) - The name.
- `originValues` (object) - Values from the origin localization.
- `parentContainer` (object) - The parent component, if nested.
- `previews` (object) - Bard/Replicator set previews.
- `readOnly` (boolean) - Read-only flag.
- `reference` (string) - The reference of the item being edited (e.g., `entry::the-entry-id`).
- `rememberTab` (boolean) - Returns `true` when the active tab should be remembered in the URL hash.
- `revealerFields` (array) - Array of revealer field handles.
- `revealerValues` (object) - Values of revealer fields.
- `setFieldMeta(path, value)` (function) - Update a field's metadata.
- `setFieldPreviewValue(path, value)` (function) - Update a field's Bard/Replicator preview.
- `setFieldValue(path, value)` (function) - Update a field's value.
- `setHiddenField(field)` (function) - Mark field as hidden.
- `setRevealerField(path)` (function) - Mark field as a revealer.
- `setValues(newValues)` (function) - Replace all values.
- `site` (string) - The site handle of the active localization.
- `syncField(path)` (function) - Sync a field with its origin value.
- `unsetRevealerField(path)` (function) - Unmark a field as a revealer.
- `values` (object) - The current form values.
- `visibleValues` (object) - Values for currently visible fields.
- `withoutDirtying()` (function) - Run a callback without marking the form as dirty.
- Any other keys provided by the publish form (e.g., `isWorkingCopy`, `revisionsEnabled`).

### Example (Composition API)
```js
import { injectPublishContext } from '@statamic/cms/ui';
const { values, setFieldValue, etc } = injectPublishContext();

// Refs are provided, so you need to call `.value` to unwrap it.
const somethingFieldValue = values.value.something;
```

### Example (Options API)
```js
import { publishContextKey } from '@statamic/cms/ui';

export default {
  inject: {
    publishContext: { from: publishContextKey }
  },
  methods: {
    getSomething() {
      return this.publishContext.values.something;
    }
  }
}
```
```

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

### Translate using Google Translate

Source: https://github.com/statamic/cms/wiki/Translating-the-Control-Panel

Use Google Translate to fill in translations automatically. Requires an API key passed with the --key option.

```bash
php translator translate fr --key=123
```

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

### YAML articles collection configuration

Source: https://github.com/statamic/cms/blob/6.x/tests/__fixtures__/content/1996-11-18-dance.md

YAML configuration for an articles collection, setting a view model.

```yaml
# content/collections/articles.yaml
title: Articles
inject:
  view_model: App\ViewModels\ArticleStats
```

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

### Inject Publish Context with Options API

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/PublishContainer.mdx

Use publishContextKey with the Options API inject option to access the publish context. The injected object is not a ref, so values can be accessed directly.

```javascript
import { publishContextKey } from '@statamic/cms/ui';

export default {
  inject: {
    publishContext: { from: publishContextKey }
  },
  methods: {
    getSomething() {
      return this.publishContext.values.something;
    }
  }
}
```

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

### Configure view model injection in articles.yaml

Source: https://github.com/statamic/cms/blob/6.x/tests/__fixtures__/fieldtype_tests/bard/expected.txt

Defines a collection with a view model injected via the `inject` key. The view model class is referenced as `App\ViewModels\ArticleStats`.

```yaml
# content/collections/articles.yaml
title: Articles
inject:
  view_model: App\ViewModels\ArticleStats

```

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

### JSON endpoint controller, route, and Listing component

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/Listing.mdx

Controller method that queries TeamMember data, applies search and sorting from request parameters, and returns a paginated resource collection. The route and Vue component show how to wire the JSON endpoint to the Listing component using the `url` prop.

```php
use Illuminate\Http\Request;

public function json(Request $request)
{
    $query = TeamMember::query();

    if ($search = $request->input('search')) {
        $query->where('name', 'like', "%{$search}%");
    }

    $query->orderBy(
        $request->input('sort', 'name'), // column
        $request->input('order', 'asc') // direction
    );

    return TeamMemberResource::collection($query->paginate($request->input('perPage')));
}
```

```php
Route::get('team-members/json', [TeamMemberController::class, 'json']);
```

```vue
<Listing
    :url="cp_url('team-members/json')"
    ...
/>
```

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

### Inject Publish Context with Composition API

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/PublishContainer.mdx

Use injectPublishContext() in a component nested inside the PublishContainer to access state and methods. Refs are provided, so values must be unwrapped with .value.

```javascript
import { injectPublishContext } from '@statamic/cms/ui';
const { values, setFieldValue, etc } = injectPublishContext();

// Refs are provided, so you need to call `.value` to unwrap it.
const somethingFieldValue = values.value.something;
```

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

### Custom PublishContainer layout template

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/PublishContainer.mdx

This template shows a custom layout using PublishContainer with PublishComponents and PublishTabs. It adds a 'Visit URL' button in the actions slot, linking to the permalink prop.

```html
<template>
    <PublishContainer :meta :blueprint v-model="values">
        <PublishComponents />

        <PublishTabs>
            <template #actions>
                <Button
                    :href="permalink"
                    :text="__('Visit URL')"
                    icon="external-link"
                    target="_blank"
                />
            </template>
        </PublishTabs>
    </PublishContainer>
</template>
```

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

### Shrug method returning emoticon

Source: https://github.com/statamic/cms/blob/6.x/tests/__fixtures__/fieldtype_tests/code/expected.txt

A PHP method that returns the shrug emoticon. Use when you need a playful fallback or placeholder response. The method accepts a parameter but ignores it.

```php
/**
     * Because sometimes you just gotta /shrug.
     *
     * @param $value
     * @return string
     */
    public function shrug($value)
    {
        return '¯\_(ツ)_/¯';
    }
```

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

### Filtering with Scope::filters and Listing filters prop

Source: https://github.com/statamic/cms/blob/6.x/resources/js/stories/docs/Listing.mdx

Controller passes `Scope::filters('team-members', ...)` to the page as `filters`. The Vue component defines a `filters` prop and passes it to the Listing component's `filters` prop.

```php
return Interia::render('team-members/Index', [
    'filters' => Scope::filters('team-members', [
        'company' => 'Statamic',
    ]),
    // ...
]);
```

```js
<script setup>
defineProps({
    filters: Object,
    // ...
});
</script>
```

```html
<template>
    <Listing
        :url="cp_url('team-members/json')"
        :filters="filters"
        ...
    />
</template>
```

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

### Bard field Antlers template

Source: https://github.com/statamic/cms/blob/6.x/tests/__fixtures__/fieldtype_tests/replicator/expected.txt

This is the Antlers template code for rendering a Bard field with various sub-fields. It includes conditionals, loops, and field variable outputs. Use this as a reference for templating Bard fields in Statamic.

```html
{{# Bard - bard #}}
{{ bard }}

    
    {{ if type == 'new_set' }}
    
        {{# Array Dynamic - array #}}
        {{ foreach:array_dynamic }}
        
            {{ key }} - {{ value }}
        {{ /foreach:array_dynamic }}
        {{# Array Keyed - array #}}
        {{ array_keyed }}
        
            {{# Label1 #}}
            {{ key1 }}
            {{# Label2 #}}
            {{ key2 }}
            
        {{ /array_keyed }}
        {{# Button Group - button_group #}}
        {{ button_group }}
        {{# Checkboxes - checkboxes #}}
        {{ checkboxes }}
        {{# Code - code #}}
        {{ code }}
        {{# Color - color #}}
        {{ color }}
        {{# Float - float #}}
        {{ float }}
        {{# Grid - grid #}}
        {{ grid }}
        
            {{# Grid Text 1 - text #}}
            {{ grid_text_1 }}
            {{# Grid Text 2 - text #}}
            {{ grid_text_2 }}
            
        {{ /grid }}
        {{# Stacked Grid - grid #}}
        {{ stacked_grid }}
        
            {{# Stacked Grid Text 1 - text #}}
            {{ stacked_grid_text_1 }}
            {{# Stacked Grid Text 2 - text #}}
            {{ stacked_grid_text_2 }}
            
        {{ /stacked_grid }}
        {{# Hidden Field - hidden #}}
        {{ hidden_field }}
        {{# HTML Field - html #}}
        {{ html_field }}
        {{# Integer Field - integer #}}
        {{ integer_field }}
        {{# Link Field - link #}}
        {{ link_field }}
        {{# Markdown - markdown #}}
        {{ markdown }}
        {{# Radio - radio #}}
        {{ radio }}
        {{# Range Field - range #}}
        {{ range_field }}
        {{# Select Field - select #}}
        {{ select_field }}
        {{# Table - table #}}
        {{ table | table }}
        {{# Textarea - textarea #}}
        {{ textarea }}
        {{# Time - time #}}
        {{ time }}
        {{# Toggle - toggle #}}
        {{ if toggle }} Yes. {{ /if }}
        {{# Video - video #}}
        {{ video }}
        {{# Yaml - yaml #}}
        {{ yaml }}
            {{# Replace with your YAML keys. #}}
        {{ /yaml }}
        
    {{ /if }}
{{ /bard }}

```
Tokens:
Raw