Pular para o conteúdo

Criando uma tela de aplicativo com o UI

A maioria dos projetos WordPress acaba precisando de uma tela mais parecida com um aplicativo do que com uma página: uma lista de registros, um botão que abre um formulário e um aviso quando o salvamento é concluído. A solução habitual é um framework JavaScript, um conjunto de controladores REST e uma biblioteca de componentes, todos mantidos junto ao tema.

Blockstudio já inclui cada um desses elementos. db.php oferece armazenamento, validação e endpoints CRUD para blocos. rpc.php adiciona ações personalizadas no servidor. Os componentes incluídos UI fornecem a caixa de diálogo, os campos do formulário, os botões, os selos e as notificações toast. Um armazenamento Interactivity API conecta tudo. Este guia cria uma tela completa em uma única pasta de bloco:

  • Uma tabela de projetos, renderizada no servidor e mantida sincronizada no cliente.
  • Uma caixa de diálogo Novo projeto com um formulário que valida os dados de acordo com o esquema.
  • Botões Arquivar e Restaurar que chamam uma função RPC com atualização otimista e reversão.
  • Botões Excluir que usam diretamente os dados API.
  • Uma notificação toast após a criação bem-sucedida e outra quando uma alteração não é salva.

Antes de começar

Os componentes incluídos são opcionais. Ative-os em blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

A tela fica em um único bloco:

Código
acme/
└── blockstudio/
    └── projects/
        ├── block.json
        ├── db.php
        ├── rpc.php
        ├── index.php
        ├── script.inline.js
        └── style.inline.css

Etapa 1: O modelo de dados

PHP
<?php
return [
    'storage'    => 'sqlite',
    'capability' => [
        'create' => 'edit_posts',
        'read'   => 'edit_posts',
        'update' => 'edit_posts',
        'delete' => 'edit_posts',
    ],
    'fields'     => [
        'name'   => [
            'type'      => 'string',
            'required'  => true,
            'minLength' => 2,
            'maxLength' => 80,
        ],
        'owner'  => [
            'type'     => 'string',
            'format'   => 'email',
            'required' => true,
        ],
        'status' => [
            'type'     => 'string',
            'enum'     => ['active', 'archived'],
            'required' => true,
        ],
    ],
];

Toda operação exige a capacidade edit_posts; por isso, os endpoints respondem 401 a solicitações de usuários desconectados, e somente editores ou usuários com nível superior podem alterar dados. O armazenamento SQLite mantém os registros em projects/db/default.sqlite, junto ao código.

status é required, em vez de conter um default. Com SQLite e armazenamento em tabela, o esquema não preenche um valor ausente na criação; portanto, um registro criado sem status é armazenado com esse campo vazio. Tornar o campo obrigatório e enviá-lo pelo formulário mantém todas as linhas válidas.

Adicione alguns registros pela linha de comando:

Shell
wp bs db create acme/projects --name="Website relaunch" --owner=ana@example.com --status=active
wp bs db create acme/projects --name="Q3 report" --owner=ben@example.com --status=archived
wp bs db list acme/projects
Código
Success: Record created (ID: 1).
Success: Record created (ID: 2).
id	name	owner	status	created_at	updated_at
2	Q3 report	ben@example.com	archived	...
1	Website relaunch	ana@example.com	active	...

A lista é exibida da mais recente para a mais antiga, que é a ordem usada pela tabela.

Etapa 2: Uma ação no servidor

Do ponto de vista do usuário, arquivar não é uma simples edição de campo; por isso, a ação recebe uma função própria:

PHP
<?php
use Blockstudio\Db;

return [
    'set_status' => [
        'callback'   => function (array $params) {
            $id     = (int) ($params['id'] ?? 0);
            $status = (string) ($params['status'] ?? '');
            $db     = Db::get('acme/projects');

            if (!$db->get_record($id)) {
                return new \WP_Error('not_found', 'Project not found.', ['status' => 404]);
            }

            return $db->update($id, ['status' => $status]);
        },
        'capability' => 'edit_posts',
    ],
];

Db::update() valida os dados de acordo com o esquema, então o enum em db.php ainda protege o valor. Chamar a função com um status desconhecido retorna o mesmo formato de erro dos dados API:

JSON
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}

A função também pode ser chamada pela linha de comando:

Shell
wp bs rpc call acme/projects set_status --id=2 --status=active
Código
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

Etapa 3: A definição do bloco

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/projects",
  "title": "Projects",
  "category": "widgets",
  "icon": "list-view",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

supports.interactivity faz com que WordPress processe no servidor as diretivas do modelo, o que renderiza as linhas da tabela antes de qualquer execução de JavaScript.

Etapa 4: O modelo

PHP
<?php
$can_edit = current_user_can('edit_posts');
$projects = $can_edit ? \Blockstudio\Db::get('acme/projects')->list() : [];

wp_interactivity_state('acme/projects', [
    'projects'    => array_values($projects),
    'hasProjects' => !empty($projects),
    'notice'      => '',
    'isArchived'  => function () {
        $context = wp_interactivity_get_context();

        return 'archived' === ($context['project']['status'] ?? '');
    },
]);
?>
<div
    useBlockProps
    class="projects"
    data-wp-interactive="acme/projects"
    data-wp-on-document--formsuccess="actions.created"
>
<?php if (!$can_edit) : ?>
    <p>Sign in with an editor account to manage projects.</p>
<?php else : ?>
    <div class="projects__bar">
        <bs:bsui-text content="Projects" variant="title" tag="h2" />
        <bs:bsui-dialog>
            <bs:bsui-dialog-trigger trigger_label="New project" />
            <bs:bsui-dialog-backdrop />
            <bs:bsui-dialog-popup>
                <bs:bsui-dialog-header>
                    <bs:bsui-dialog-title content="New project" />
                    <bs:bsui-dialog-description content="Projects start out active." />
                </bs:bsui-dialog-header>
                <bs:bsui-dialog-content>
                    <bs:bsui-form block="acme/projects">
                        <bs:bsui-field name="name">
                            <bs:bsui-field-label text="Name" />
                            <bs:bsui-input name="name" placeholder="Spring campaign" required="true" />
                            <bs:bsui-field-error />
                        </bs:bsui-field>
                        <bs:bsui-field name="owner">
                            <bs:bsui-field-label text="Owner email" />
                            <bs:bsui-input name="owner" type="email" placeholder="owner@example.com" required="true" />
                            <bs:bsui-field-error />
                        </bs:bsui-field>
                        <input type="hidden" name="status" value="active" />
                        <bs:bsui-space size="2" />
                        <bs:bsui-button label="Create project" />
                    </bs:bsui-form>
                </bs:bsui-dialog-content>
                <bs:bsui-dialog-footer>
                    <bs:bsui-dialog-close label="Cancel" />
                </bs:bsui-dialog-footer>
            </bs:bsui-dialog-popup>
        </bs:bsui-dialog>
    </div>

    <table class="projects__table">
        <thead>
            <tr>
                <th scope="col">Name</th>
                <th scope="col">Owner</th>
                <th scope="col">Status</th>
                <th scope="col">Actions</th>
            </tr>
        </thead>
        <tbody>
            <template data-wp-each--project="state.projects" data-wp-each-key="context.project.id">
                <tr>
                    <td data-wp-text="context.project.name"></td>
                    <td data-wp-text="context.project.owner"></td>
                    <td>
                        <span data-wp-bind--hidden="state.isArchived"><bs:bsui-badge label="Active" variant="success" /></span>
                        <span data-wp-bind--hidden="!state.isArchived"><bs:bsui-badge label="Archived" variant="secondary" /></span>
                    </td>
                    <td class="projects__actions">
                        <span data-wp-on--click="actions.toggleArchived">
                            <span data-wp-bind--hidden="state.isArchived"><bs:bsui-button label="Archive" variant="outline" size="sm" /></span>
                            <span data-wp-bind--hidden="!state.isArchived"><bs:bsui-button label="Restore" variant="outline" size="sm" /></span>
                        </span>
                        <span data-wp-on--click="actions.remove"><bs:bsui-button label="Delete" variant="ghost" size="sm" /></span>
                    </td>
                </tr>
            </template>
        </tbody>
    </table>

    <p class="projects__empty" data-wp-bind--hidden="state.hasProjects">No projects yet.</p>

    <div class="projects__toasts">
        <bs:bsui-toast-provider>
            <div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isCreatedNotice" data-wp-on--click="actions.dismissNotice">
                <bs:bsui-toast message="Project created." />
            </div>
            <div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isFailedNotice" data-wp-on--click="actions.dismissNotice">
                <bs:bsui-toast message="That change was not saved." />
            </div>
        </bs:bsui-toast-provider>
    </div>
<?php endif; ?>
</div>

Vale analisar mais de perto quatro partes deste modelo.

O estado do servidor prepara a renderização inicial. wp_interactivity_state() fornece os registros ao processador de diretivas do servidor e ao armazenamento do cliente. O modelo data-wp-each se expande em linhas reais no servidor, uma tr por registro. isArchived é um fechamento: WordPress o avalia para cada linha durante o processamento no servidor, e wp_interactivity_get_context() retorna o contexto dessa linha; assim, as linhas arquivadas mostram o selo e o botão corretos antes da hidratação. No navegador, o getter do armazenamento com o mesmo nome assume o controle. hasProjects é um valor simples pelo mesmo motivo: sem ele, o servidor não saberia se deve ocultar o parágrafo de estado vazio.

A caixa de diálogo e o formulário são componentes do sistema. trigger_label é encaminhado para o bsui/button dentro do acionador, conforme descrito em ComposiçãoUI. bsui/form com block="acme/projects" serializa os campos com FormData e os envia ao endpoint de criação desse bloco. Cada bsui/field contém o nome da entrada, fazendo com que os erros de validação do esquema apareçam no controle correto. Ao enviar o formulário vazio, aparecem “São necessários pelo menos 2 caracteres.” sob Nome, “Insira um endereço de e-mail válido.” sob E-mail do responsável e “Falha na validação.” na parte inferior do formulário. A entrada oculta status acompanha os dados do formulário; é assim que os novos projetos atendem ao campo obrigatório.

A tabela usa marcação própria. bsui/table é adequado para linhas definidas no modelo: as células do cabeçalho ordenam movendo os elementos tr existentes, o que entraria em conflito com data-wp-each pelo controle das linhas. Antes da versão 7.7 de Blockstudio, suas partes também inseriam um div diretamente dentro de table, thead, tbody e tr; os navegadores movem esse elemento para fora da tabela. Para linhas provenientes de um armazenamento, escreva você mesmo o elemento table e mantenha os componentes do sistema dentro das células. Os selos e botões no modelo da linha são tags comuns bsui/badge e bsui/button. Cada botão fica em um span que contém a diretiva de clique; assim, o botão continua sendo o botão do sistema, enquanto a ação pertence ao seu armazenamento.

A notificação toast é apenas visual. bsui/toast-provider renderiza uma região dinâmica discreta e bsui/toast renderiza uma mensagem de status com botão para dispensá-la. O provedor não posiciona a própria região na tela, e o botão para dispensar não oculta uma notificação renderizada a partir da marcação. Por isso, a tela faz as duas coisas: um contêiner com position: fixed posiciona a região, e cada notificação fica em um div cuja vinculação hidden e cujo manipulador de clique pertencem ao armazenamento da tela. O clique no botão para dispensar sobe até esse div.

Etapa 5: O armazenamento

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const BLOCK = 'acme/projects';
let noticeTimer;

// bs.fn() and bs.db() resolve with the error body on a failed request.
// Throwing here is what lets bs.mutate() roll the optimistic change back.
const ok = (request) =>
    request.then((result) => {
        if (result?.code) {
            throw result;
        }
        return result;
    });

const notify = (notice) => {
    state.notice = notice;
    clearTimeout(noticeTimer);
    noticeTimer = setTimeout(() => {
        state.notice = '';
    }, 4000);
};

const { state } = store(BLOCK, {
    state: {
        get hasProjects() {
            return state.projects.length > 0;
        },
        get isArchived() {
            return getContext().project.status === 'archived';
        },
        get isCreatedNotice() {
            return state.notice === 'created';
        },
        get isFailedNotice() {
            return state.notice === 'failed';
        },
    },
    actions: {
        created(event) {
            const record = event.detail;
            if (!record?.id || !('owner' in record)) {
                return;
            }

            event.preventDefault();
            state.projects = [record, ...state.projects];
            store('bsui/dialog').actions.close();
            notify('created');
        },
        dismissNotice() {
            state.notice = '';
        },
        *toggleArchived() {
            const project = getContext().project;
            const status = project.status === 'archived' ? 'active' : 'archived';

            try {
                yield bs.mutate({
                    fn: () => ok(bs.fn('set_status', { id: project.id, status }, BLOCK)),
                    state,
                    key: 'projects',
                    action: 'update',
                    id: project.id,
                    optimistic: { status },
                });
            } catch (error) {
                notify('failed');
            }
        },
        *remove() {
            const project = getContext().project;

            try {
                yield bs.mutate({
                    fn: () => ok(bs.db(BLOCK).delete(project.id)),
                    state,
                    key: 'projects',
                    action: 'delete',
                    id: project.id,
                });
            } catch (error) {
                notify('failed');
            }
        },
    },
});

Como reagir ao formulário. Quando o salvamento dá certo, bsui/form dispara um evento formsuccess que se propaga, pode ser cancelado e carrega o registro criado em event.detail. Quando o salvamento falha, dispara formerror com o corpo do erro. O listener fica no documento (data-wp-on-document--formsuccess), em vez de ficar no elemento raiz da tela, porque uma janela de diálogo aberta é movida para document.body; assim, seus eventos deixam de se propagar pelo bloco. A verificação owner ignora eventos de outros formulários na mesma página.

Chamar event.preventDefault() impede que o formulário substitua os campos pela mensagem de sucesso; o próprio formulário ainda é redefinido. Em seguida, a ação adiciona o registro no início da lista, fecha a caixa de diálogo com a ação close do armazenamento bsui/dialog e exibe a notificação toast. close fecha a caixa de diálogo aberta mais acima e devolve o foco ao acionador. Assim, após a criação, o foco do teclado volta para Novo projeto.

Revertendo alterações em caso de erro. bs.mutate() aplica a alteração otimista imediatamente e restaura os valores anteriores quando a promessa de fn é rejeitada. bs.fn() e bs.db() não rejeitam em caso de erros HTTP: um WP_Error da função RPC, uma falha de validação ou um registro inexistente; todos resolvem com o corpo do erro. O auxiliar ok() transforma em rejeição um resultado com code, fazendo a linha voltar ao estado anterior e exibindo a notificação de falha. Sem ele, uma atualização malsucedida mesclaria o corpo do erro à linha, e uma exclusão malsucedida deixaria a linha removida.

Dando nome ao bloco. Blockstudio imprime scripts inline como <script type="module">, e scripts de módulo não têm document.currentScript; por isso, bs.fn() não consegue detectar qual bloco está chamando. Passe o nome do bloco como terceiro argumento, como faz o armazenamento com BLOCK.

Etapa 6: Coloque a tela em uma página

Uma página baseada em arquivos insere o bloco com sua tag:

JSON
{
  "$schema": "https://blockstudio.dev/schema/page",
  "name": "projects",
  "title": "Projects",
  "slug": "projects",
  "postStatus": "private"
}
PHP
<h1>Projects</h1>
<bs:acme-projects />

O analisador transforma a tag em um bloco nativo:

HTML
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->

Execute wp bs pages sync para criar a página. postStatus: "private" mantém a página indisponível para visitantes anônimos, que de qualquer forma só veriam a mensagem de acesso.

O que a tela faz durante a execução

Com a página aberta como editor:

  1. A tabela aparece com as duas linhas renderizadas; a linha arquivada exibe o selo Arquivado e o botão Restaurar.
  2. Novo projeto abre a caixa de diálogo. A janela e o fundo escurecido são movidos para document.body, o foco vai para o campo Nome e Escape ou Cancelar fecha a caixa novamente.
  3. O envio de valores válidos faz uma solicitação POST para /wp-json/blockstudio/v1/db/acme-projects/default. A caixa de diálogo fecha, a nova linha aparece no topo e “Projeto criado.” é exibido no canto por quatro segundos.
  4. Arquivar altera o selo imediatamente e envia set_status por /wp-json/blockstudio/v1/fn/acme/projects/set_status. Se o registro tiver sido excluído em outro lugar nesse meio-tempo, a função retorna o erro 404, a linha volta ao estado Ativo e aparece “A alteração não foi salva.”
  5. Excluir remove a linha imediatamente. Excluir a última linha exibe “Ainda não há projetos.”

Estilo

O CSS da própria tela lê os tokens da biblioteca, então a tabela combina com os componentes ao redor e segue qualquer substituição do tema às propriedades --bs-ui-*:

CSS
.projects__table {
    width: 100%;
    border-collapse: collapse;
    font-size: var(--bs-ui-font-size);
}

.projects__table th,
.projects__table td {
    padding: var(--bs-ui-space-2) var(--bs-ui-space-3);
    border-bottom: 1px solid var(--bs-ui-border);
    text-align: left;
}

/* ... */

.projects__toasts {
    position: fixed;
    right: var(--bs-ui-space-4);
    bottom: var(--bs-ui-space-4);
    z-index: 40;
}

O z-index de 40 mantém a região da notificação toast sob o fundo escurecido da caixa de diálogo, que fica em 50. Para mudar o tema da tela inteira, substitua os tokens conforme descrito em estilização; os componentes e a tabela acompanharão a mudança.

Próximas etapas

  • UIComponentes: o sistema de design, os tokens e o conjunto completo de componentes.
  • UIComposição: famílias de componentes compostos, encaminhamento de acionadores e o modelo de camadas por trás da caixa de diálogo.
  • Banco de dados: modos de armazenamento, controle de acesso, bs.db() e bs.mutate().
  • RPC: controle de acesso, métodos HTTP e chamadas entre blocos.
  • Blocos full stack: os mesmos componentes básicos em um aplicativo de tarefas e em um formulário de inscrição para newsletter.