根据数据表生成表单

机器翻译

本页由英文原文机器翻译而来，尚未经过母语审校，欢迎在 GitHub 上提出修改。内容如有出入，以英文原文为准。

任务： 为一张数据表做一个表单，而不必把每个字段和每条规则再写一遍。

yaml

# Recipe: the table's schema gives the action its rules and the form its fields.
paths:
  components: ./components
  migrations: ./migrations

datasources:
  db:
    driver: sqlite
    database: ./data/library.db

数据表结构已经说明了一本书需要什么：

sql

CREATE TABLE authors (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL
);

CREATE TABLE books (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title VARCHAR(120) NOT NULL,
    author_id INTEGER NOT NULL REFERENCES authors(id),
    genre TEXT NOT NULL CHECK (genre IN ('novel', 'poetry', 'essay')),
    pages INTEGER,
    lent BOOLEAN NOT NULL DEFAULT 0
);

INSERT INTO authors (name) VALUES ('Clarice Lispector'), ('Machado de Assis');

<q:action table="books" datasource="db"> 读取它，按数据表的顺序，为除主键外的每一列生成一个 q:param：

列	变成
`title VARCHAR(120) NOT NULL`	必填，最多 120 个字符
`author_id ... REFERENCES authors(id)`	一个必须对应已有作者的整数
`genre ... CHECK (genre IN (...))`	三者之一
`pages INTEGER`（可以为 NULL）	一个整数；留空时以 `None` 到达动作
`lent BOOLEAN`	一个复选框

没有自己字段的 ui:form 为每个参数画一个字段，标签取自名字（author_id 变成 "Author"）。作者字段是一个作者名字的列表。查询的 pages 参数上的 null="true" 把留空的值保存为 NULL。

xml

<q:component name="Books">
  <!-- No q:param: each column but the key becomes one, with the rules the
       schema gives it (UI-10). NOT NULL is required, VARCHAR(120) a
       maxlength, the CHECK a list, the REFERENCES a row that must exist. -->
  <q:action name="add" method="POST" table="books" datasource="db">
    <q:query name="added" datasource="db">
      INSERT INTO books (title, author_id, genre, pages, lent)
      VALUES (:title, :author_id, :genre, :pages, :lent)
      <q:param name="title" value="{title}" type="string" />
      <q:param name="author_id" value="{author_id}" type="integer" />
      <q:param name="genre" value="{genre}" type="string" />
      <q:param name="pages" value="{pages}" type="integer" null="true" />
      <q:param name="lent" value="{lent}" type="boolean" />
    </q:query>
    <q:redirect url="/" flash="Added: {title}" />
  </q:action>

  <q:query name="books" datasource="db">
    SELECT b.title, a.name AS author, b.genre FROM books b JOIN authors a ON a.id = b.author_id
    ORDER BY b.id
  </q:query>

  <ui:window title="Library">
    <q:if condition="flash">
      <ui:alert variant="{flashType == 'error' and 'danger' or 'success'}">{flash}</ui:alert>
    </q:if>
    <!-- A form with no fields draws one per param: a list of authors for
         author_id, a list for genre, a box for lent, and the button. -->
    <ui:form on-submit="add" submit="Add book" />
    <ui:table source="{books}" />
  </ui:window>
</q:component>

xml

<q:test name="the form draws a field per column, labelled from its name" page="/">
  <test:visit />
  <test:expect text="Title" />
  <test:expect text="Author" />
  <test:expect text="Machado de Assis" />
  <test:expect text="Add book" />
</q:test>

<q:test name="a book is added" page="/">
  <test:submit action="add" title="Dom Casmurro" author_id="2" genre="novel" pages="256" />
  <test:expect redirect="/" flash="Added: Dom Casmurro" />
  <test:expect table="books" count="1" where="title = 'Dom Casmurro' AND pages = 256 AND lent = 0" />
</q:test>

<q:test name="the rules come from the schema" page="/">
  <test:submit action="add" title="" author_id="9" genre="comic" pages="many" />
  <test:expect error="title" message="Required" />
  <test:expect error="author_id" message="Must name an existing row of authors (no id = 9)" />
  <test:expect error="genre" message="Must be one of: novel, poetry, essay" />
  <test:expect error="pages" message="Must be an integer, got 'many'" />
  <test:expect table="books" count="0" />
</q:test>

<q:test name="a blank optional column is stored as NULL" page="/">
  <test:submit action="add" title="A hora da estrela" author_id="1" genre="novel" pages="" />
  <test:expect table="books" count="1" where="pages IS NULL" />
</q:test>

text

tests/books.test.q
  PASS  the form draws a field per column, labelled from its name
  PASS  a book is added
  PASS  the rules come from the schema
  PASS  a blank optional column is stored as NULL
4 passed, 0 failed

写在动作里的 q:param 优先于数据表结构中的，columns="a,b" 只保留这些列。参见 UI-10。

根据数据表生成表单 ​

根据数据表生成表单