Statamic 6 Alpha

JS/Vue approach

In addons and custom code, when using Statamic's JS components, importing directly from files located in the vendor directory is not supported as not everything is intended for public usage.

Usable items will be exported for you and available through the pseudo-package:

-import something from '../../vendor/statamic/cms/resources/js/somewhere/something.js'; 
+import something from '@statamic/cms/something'; 

UI Components

When building custom areas of the Control Panel, you should aim to use the UI components as much as possible.

These will allow you to write UIs that match the design of Statamic without needing to worry about styles or Tailwind classes.

For example, need a card? Don't use <div class="bg-white p-4 rounded border shadow-sm">, use the Card component!

Importing

To use a component in your Vue files, you can import them from @statamic/cms/ui.

<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>

Global Components

When using Blade (or if you don't like all the benefits your editor can give you when you import) you can use the global components.

They will be available at the kebab-cased name prefixed with ui-. For example:

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

Listings

You can create a fully fledged listing using the aptly named Listing component with search, filters, column customization, etc.

In most cases, you can use the self-closed component and control the behavior using props.

<script setup>
import { Listing } from '@statamic/cms/ui';
</script>
<template>
    <Listing :items="..." />
</template>

Publish Forms

You can create a form using the publish components.

The required components depends on the complexity of what you're building.

• Very simple forms may not need any Vue or JavaScript at all, and could simply use the PublishForm class directly from your controller.
• If you need JavaScript or Vue, the PublishContainer component can be paired with blueprint data to render an entire form.
• The PublishContainer component can have its contents overridden if you need more control over the layout or behavior of the form.

PublishForm

For very simple forms ...

PublishContainer

The PublishContainer component is the workhorse. For a basic form, you can use it self-closed with some props, and it will render exactly what you need.

<script setup>
import { PublishContainer, Button } from '@statamic/cms/ui';
</script>
<template>
    <Button @click="save" text="Save" />
    <PublishContainer
        v-model="values"
        :blueprint="blueprint"
        :meta="meta"
        :errors="errors"
    />
</template>

Based on the provided blueprint, it will render any tabs, sections, and fields appropriately.

You may customize the layout of the form by providing slot content.

<PublishContainer>
    <Tabs /> etc
</PublishContainer>

Save Pipeline

The save pipeline pairs with a PublishContainer to save your data, render validation errors, fire hooks, etc.

The data from your publish container will be sent through the steps. The only required step is the Request.

You provide the pipeline class with a reference to the publish container, the saving state, and errors, and it will update them for you appropriately.

You may provide additional steps, such as the AfterSaveHooks here.

Once everything is done, the then callback will be run, like a promise.

Any errors can be caught in the catch callback. If the pipeline is intentionally stopped, e will be an instance of PipelineStopped.

<script setup>
import { Pipeline, Request, AfterSaveHooks } from '@statamic/cms/save-pipeline';
import { ref, useTemplateRef } from 'vue';

let saving = ref(false);
let errors = ref({});
let container = useTemplateRef('container');

function save() {
    new Pipeline()
        .provide({ container, errors, saving })
        .through([
            new Request(url, method),
            new AfterSaveHooks(name, payload)
        ])
        .then((response) => {
            //
        })
        .catch((e) => {
            //
        });
}
</script>
<template>
    <template v-if="saving">Saving...</template>
    <Button @click="save" text="Save" />
    <PublishContainer ref="container" :errors="errors" />
</template>

Command Palette

The command palette provides handy access to many places in the Control Panel without having to leave your keyboard. Make friends with the ⌘K shortcut.

Out of the box, a number of items will be already added, for example:

• Everything you can find in the navigation
• Content in your search index
• Contextual items, like buttons and actions on the current page.

You may add items to the command palette in a number of ways.

PHP

In PHP, you can add basic links.

use Statamic\CommandPalette\Category;
use Statamic\Facades\CommandPalette;

CommandPalette::add(
    text: ['Search', 'Ancient', 'Hotbot'], // Array will add separators "Search > Ancient > Hotbot"
    url: 'https://hotbot.com',
    openNewTab: true,
    trackRecent: false,
    icon: 'sexy-robot',
    category: Category::Actions,
);

JavaScript

In JavaScript, you can add links too, but you the main benefit over PHP is that you can define functionality.

import throwConfetti from 'confetti';

Statamic.$commandPalette.add({
    text: ['Silliness', 'Celebrate'],
    icon: 'star',
    action: () => {
        throwConfetti();
    },
});

Vue Component

There's a Vue component that will add a command based on props. The props are exposed back to you through the slot so you don't have to define things twice.

A great example of when to use this would be if you have a button on the page that you want to also be accessible through the command palette.

<script setup>
import { CommandPaletteItem, Button } from '@statamic/cms/ui';
</script>
<template>
    <CommandPaletteItem
        text="Go Somewhere"
        url="/somewhere"
        v-slot="{ text, url }"
    >
        <Button :text="text" :href="url" />
    </CommandPaletteItem>
</template>