번들된 UI으로 앱 화면 만들기
대부분의 WordPress 프로젝트에는 언젠가 페이지라기보다 애플리케이션에 가까운 화면이 필요합니다. 레코드 목록, 양식을 여는 버튼, 저장 완료를 알리는 피드백 같은 요소가 있는 화면입니다. 일반적으로 테마와 함께 유지 관리하는 JavaScript 프레임워크, REST 컨트롤러 모음, 구성 요소 라이브러리를 사용합니다.
Blockstudio에는 이 모든 요소가 이미 포함되어 있습니다. db.php은 블록 저장소, 검증, CRUD 엔드포인트를 제공합니다. rpc.php은 사용자 정의 서버 작업을 추가합니다. 번들된 UI 구성 요소는 대화상자, 양식 필드, 버튼, 배지, 토스트를 제공합니다. Interactivity API 스토어가 이 요소들을 연결합니다. 이 가이드에서는 블록 폴더 하나에서 처음부터 끝까지 화면 하나를 만듭니다.
- 서버에서 렌더링되고 클라이언트와 동기화되는 프로젝트 표.
- 스키마에 따라 검증하는 양식이 있는 새 프로젝트 대화상자.
- 낙관적 업데이트와 롤백을 적용해 RPC 함수를 호출하는 보관 및 복원 버튼.
- 데이터 API를 직접 사용하는 삭제 버튼.
- 생성 성공 후 토스트가 표시되고 변경 사항을 저장하지 못하면 또 다른 토스트가 표시됩니다.
시작하기 전에
번들된 구성 요소는 선택 기능입니다. blockstudio.json에서 활성화하세요.
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
화면은 블록 하나에 있습니다.
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
1단계: 데이터 모델
<?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,
],
],
];
모든 작업에는 edit_posts 기능이 필요하므로 로그아웃한 요청에는 엔드포인트가 401을 반환하고 편집자 이상만 데이터를 변경할 수 있습니다. SQLite 저장소는 코드 옆의 projects/db/default.sqlite에 레코드를 보관합니다.
status은 required이며 default를 포함하지 않습니다. SQLite과 테이블 저장소를 사용하면 생성 시 누락된 값을 스키마가 채우지 않으므로 status 없이 생성된 레코드는 해당 값이 빈 상태로 저장됩니다. 필드를 필수로 지정하고 양식에서 값을 보내면 모든 행이 유효하게 유지됩니다.
명령줄에서 레코드를 몇 개 추가해 보세요.
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
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 ...
목록은 최신 항목이 먼저 나오며, 표에서도 같은 순서를 사용합니다.
2단계: 서버 작업
사용자 관점에서 보관은 단순한 필드 수정이 아니므로 이름이 있는 함수를 사용합니다.
<?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()은 스키마에 따라 검증하므로 db.php의 enum이 여전히 값을 보호합니다. 알 수 없는 상태로 함수를 호출하면 데이터 API와 같은 형태의 오류를 반환합니다.
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
명령줄에서도 함수를 호출할 수 있습니다.
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
3단계: 블록 정의
{
"$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은 WordPress이 템플릿 지시문을 서버에서 처리하게 합니다. 덕분에 JavaScript가 실행되기 전에 표 행이 렌더링됩니다.
4단계: 템플릿
<?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>
이 템플릿에서 자세히 살펴볼 부분은 네 가지입니다.
서버 상태가 첫 화면을 채웁니다. wp_interactivity_state()은 레코드를 서버 측 지시문 처리기와 클라이언트 스토어 모두에 전달합니다. data-wp-each 템플릿은 서버에서 실제 행으로 확장되며 레코드마다 tr 하나가 생성됩니다. isArchived은 클로저입니다. 서버 처리 중 WordPress가 각 행마다 이를 평가하고, wp_interactivity_get_context()가 해당 행의 컨텍스트를 반환하므로 하이드레이션 전에 보관된 행에 올바른 배지와 버튼이 표시됩니다. 브라우저에서는 같은 이름의 스토어 getter가 그 역할을 이어받습니다. hasProjects도 같은 이유로 단순한 값입니다. 이 값이 없으면 서버는 빈 상태 문단을 숨길지 알 수 없습니다.
대화상자와 양식은 시스템 구성 요소입니다. trigger_label은 트리거 안의 bsui/button로 전달됩니다. 자세한 내용은 UI 조합을 참조하세요. bsui/form와 block="acme/projects"은 필드를 FormData로 직렬화해 해당 블록의 생성 엔드포인트로 보냅니다. 각 bsui/field에는 입력 이름이 지정되어 있어 스키마에서 반환된 필드별 오류가 올바른 컨트롤 아래에 표시됩니다. 빈 양식을 제출하면 Name 아래에 “최소 2자 이상이어야 합니다.”, Owner email 아래에 “올바른 이메일 주소를 입력하세요.”, 양식 하단에 “검증에 실패했습니다.”가 표시됩니다. 숨겨진 status 입력도 양식 데이터와 함께 전송되므로 새 프로젝트가 필수 필드를 충족합니다.
표는 직접 작성한 마크업입니다. bsui/table는 템플릿에서 직접 작성한 행에 적합합니다. 헤더 셀은 기존 tr 요소를 옮겨 정렬하므로, 행을 관리하는 권한을 두고 data-wp-each와 충돌할 수 있습니다. Blockstudio 7.7 이전에는 해당 파트가 div를 table, thead, tbody, tr 안에 직접 넣기도 했으며, 브라우저는 이를 테이블 밖으로 이동합니다. 스토어에서 가져온 행의 경우 table 요소를 직접 작성하고 시스템 컴포넌트는 셀 안에 두세요. 행 템플릿의 배지와 버튼은 일반 bsui/badge 및 bsui/button 태그입니다. 각 버튼은 클릭 지시문이 있는 span 안에 있으므로, 버튼은 시스템 버튼으로 유지되고 동작은 스토어에 속합니다.
토스트는 표시만 담당합니다. bsui/toast-provider은 공손한 라이브 영역을 렌더링하고 bsui/toast은 닫기 버튼이 있는 상태 메시지를 렌더링합니다. 제공자는 화면에서 위치를 지정하지 않으며 닫기 버튼은 마크업에서 렌더링한 토스트를 숨기지 않습니다. 따라서 화면에서 두 가지를 모두 처리합니다. position: fixed가 있는 래퍼로 영역을 배치하고 각 토스트는 div 안에 둡니다. 해당 hidden 바인딩과 클릭 핸들러는 화면의 스토어에 속합니다. 닫기 버튼 클릭 이벤트는 해당 div까지 버블링됩니다.
5단계: 스토어
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');
}
},
},
});
양식 이벤트 처리. 저장에 성공하면 bsui/form은 버블링되고 취소할 수 있으며 생성된 레코드를 event.detail에 담는 formsuccess 이벤트를 디스패치합니다. 저장에 실패하면 오류 본문과 함께 formerror을 디스패치합니다. 리스너는 화면의 루트 요소가 아니라 문서(data-wp-on-document--formsuccess)에 둡니다. 열린 대화상자 팝업은 document.body로 이동해 이벤트가 더 이상 블록을 따라 버블링되지 않기 때문입니다. owner 검사는 같은 페이지의 다른 양식에서 발생한 이벤트를 건너뜁니다.
event.preventDefault()을 호출하면 성공 메시지가 양식 필드를 대체하지 않지만 양식은 계속 초기화됩니다. 그런 다음 작업이 레코드를 맨 앞에 추가하고 bsui/dialog 스토어의 close 작업으로 대화상자를 닫은 뒤 토스트를 표시합니다. close은 맨 위에 열린 대화상자를 닫고 트리거에 포커스를 돌려보내므로 생성 후 키보드 포커스는 새 프로젝트로 돌아옵니다.
오류 발생 시 롤백. bs.mutate()은 낙관적 변경을 즉시 적용하고 fn의 프로미스가 거부되면 이전 값을 복원합니다. bs.fn()와 bs.db()은 HTTP 오류가 발생해도 거부되지 않습니다. RPC 함수의 WP_Error, 검증 실패, 레코드 누락은 모두 오류 본문과 함께 해결됩니다. ok() 헬퍼는 code가 있는 결과를 거부로 바꿉니다. 그러면 행이 이전 상태로 돌아가고 실패 토스트가 나타납니다. 이 헬퍼가 없으면 실패한 업데이트가 오류 본문을 행에 병합하고 실패한 삭제는 행을 제거된 상태로 남깁니다.
블록 이름 지정. Blockstudio은 인라인 스크립트를 <script type="module">로 출력하고 모듈 스크립트에는 document.currentScript가 없으므로 bs.fn()은 어떤 블록이 호출하는지 감지할 수 없습니다. 스토어에서 BLOCK를 사용하는 것처럼 블록 이름을 세 번째 인수로 전달하세요.
6단계: 페이지에 화면 배치
파일 기반 페이지에는 태그로 블록을 배치합니다.
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
파서는 태그를 네이티브 블록으로 변환합니다.
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
wp bs pages sync을 실행해 페이지를 만드세요. postStatus: "private"은 익명 방문자가 로그인 안내만 보게 되므로 페이지에서 제외합니다.
런타임에서 화면 작동 방식
편집자로 페이지를 열면 다음과 같습니다.
- 두 행이 모두 렌더링된 표가 표시됩니다. 보관된 행에는 보관됨 배지와 복원 버튼이 나타납니다.
- 새 프로젝트를 누르면 대화상자가 열립니다. 팝업과 배경이
document.body로 이동하고 Name 필드에 포커스가 놓입니다. Escape 또는 취소를 누르면 대화상자가 닫힙니다. - 유효한 값을 제출하면
/wp-json/blockstudio/v1/db/acme-projects/default로POST하나가 전송됩니다. 대화상자가 닫히고 새 행이 맨 위에 표시되며 모서리에 "프로젝트가 생성되었습니다."가 4초간 나타납니다. - 보관을 누르면 배지가 즉시 바뀌고
/wp-json/blockstudio/v1/fn/acme/projects/set_status를 통해set_status이 전송됩니다. 그 사이 레코드가 다른 곳에서 삭제되었다면 함수가404오류를 반환하고 행은 활성 상태로 돌아오며 "변경 사항을 저장하지 못했습니다."가 표시됩니다. - 삭제를 누르면 행이 즉시 제거됩니다. 마지막 행을 삭제하면 "아직 프로젝트가 없습니다."가 표시됩니다.
스타일 지정
화면 자체의 CSS는 라이브러리 토큰을 읽으므로 표의 모양이 주변 구성 요소와 일치하고 --bs-ui-* 속성의 테마 재정의를 따릅니다.
.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;
}
40의 z-index는 토스트 영역을 대화상자 배경 아래에 배치하고, 대화상자 배경의 값은 50입니다. 화면 전체의 테마를 바꾸려면 스타일 지정에 설명된 대로 토큰을 재정의하세요. 구성 요소와 표 모두 이를 따릅니다.