Forms and screens

Design data-entry screens as JSON with @xeplr/ui-factory and save their records into real tables with @xeplr/factory.

Two packages work together:

npm i @xeplr/factory @xeplr/ui-factory

An app made by @xeplr/cli already has both wired in.

Screens are JSON, records are not

A screen is a JSON document: controls placed on a canvas with labels, validation, options and styles. Only the design is JSON, stored in the factory_screens table with one row per screen per version, as a draft or published.

Records are never stored as JSON. Every form saves into its own table, one column per field, so ordinary SQL works:

select e."firstName", d."name", e."startDate"
from employees e join departments d on d.id = e."departmentId"
where e."isActive"

Every table also gets id, isActive, mtId1–4 and the audit columns. A table that a dropdown reads needs an id and a name column.

A screen saves itself in the background a moment after each change, once the values are acceptable. There is no submit button.

Publishing changes the table

Publishing is the only way a table is created or changed. There are no migration files. The table is compared with the screen as the table actually is in the database, and changed in the same transaction as the publish, so either both happen or neither does.

Publish a table that others point at first, departments before employees. To preview the SQL without running it:

npx xeplr-factory migration employee-edit.screen.json

The database user needs permission to create and alter tables in the app database.

An entity is a set of files

A request such as “a form for employees” is an entity. Every entity is the same set of files. Create all of them, even the ones that only run the defaults.

npx xeplr-factory screens employee.entity.json -o src/screens/employee

--no-pages leaves out the two .jsx files. --force replaces only the screen JSON. The pages, hooks and model are your code and are always kept.

{
  "entity": "employee",
  "fields": [
    { "label": "First name", "required": true },
    { "label": "Department", "type": "dropdown", "table": "departments", "required": true },
    { "label": "Start date", "type": "date", "required": true }
  ],
  "listColumns": ["firstName", "departmentId", "startDate"]
}

Names are derived once and agree everywhere: ids employee_list and employee_edit, files employee-*.screen.json, components EmployeeList and EditEmployee, table employees. A table dropdown stores the row’s id, so “Department” becomes departmentId.

Which file for which request

CLI

npx xeplr-factory screens <entity.json> -o <dir>   # entity → list + edit screens, pages, server hooks + model
npx xeplr-factory migration <edit.screen.json>     # preview the SQL Publish would run
npx xeplr-factory generate <spec.json> -o <screen.json>   # one screen from a spec
npx xeplr-factory validate <screen.json>           # every problem, with its path
npx xeplr-factory controls                         # controls, props and rules
npx xeplr-factory schema <screen.json>             # the form's @xeplr/schema-handler schema

Front-end hooks

Front-end hooks control what a screen does in the browser: loading, saving, deleting, and extra row buttons. They are a class you extend. Every method is the default. Override the one you need and call super.

import { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'

class TaskHooks extends FactoryHooks {
  async save(values, ctx) {
    const saved = await super.save({ ...values, title: values.title.trim() }, ctx)   // before
    toast('Saved ' + saved.title)                                                   // after
    return saved
  }
  actions(ctx) {
    return [{ label: 'Mark done', onClick: async (record) => { await markDone(record.id); ctx.refresh() } }]
  }
}

• Change the input and call super to run code before the default. Await super and use its result to run code after. Skip super to replace the default.
• Write hooks as methods, not arrow-function properties, because super does not work in arrow functions.
• The same hooks run in the popup that a list opens. ctx.screen says which screen is calling.
• The server keeps only values that are fields of the form. A value added in save that is not a field needs a server save.before that accepts it.

Front-end hooks shape what the person sees and sends. Anything that must hold goes in server hooks.

Server hooks

// employee.hooks.js
module.exports = {
  save: {
    before: async function(ctx) {
      if (ctx.values.endDate < ctx.values.startDate) ctx.reject('Ends before it starts', { field: 'endDate' })
      return Object.assign({}, ctx.values, { employeeCode: ctx.values.employeeCode.toUpperCase() })
    },
    after: async function(ctx) { if (ctx.isNew) await mail.welcome(ctx.result) },
    error: async function(ctx, err) { log.warn('employee not saved', err) }
  },
  get: {
    before: function(ctx) { if (!ctx.user.isManager) ctx.query.where('employees.departmentId', ctx.user.departmentId) }
  },
  delete: {
    before: function(ctx) { if (ctx.previous.isFounder) ctx.reject('Founders cannot be deleted') }
  }
}

await factory.init({ knex: appKnex, hooks: { employee_edit: require('./screens/employee/employee.hooks') } })

Hooks are registered by screen id. A list screen uses the hooks of the screen it edits in, so one file covers the entity. A misspelt operation or hook (beforeSave, onSaved) fails at startup instead of silently never running.

Each operation runs in this order:

1. before(ctx). On save, return an object to replace ctx.values. The screen’s rules then check the result. On get, narrow ctx.query. Anywhere, ctx.reject(message, { field }) stops with a 422 whose message the form shows on that field.
2. The generic work.
3. after(ctx), once it succeeded, with ctx.id and ctx.result set. Return a value to replace the response. If after throws, the operation has still happened.
4. error(ctx, err), when anything above failed. The original error is still the response.

override(ctx) is the whole operation instead. When a screen has one, nothing generic runs for that operation: no rules, no before, no query, no after, no error.

save.before may set columns the form does not show (a fullName worked out from two fields). They must be real columns and not standard ones. Keys that the UI sends which are not fields of the screen are always dropped.

Models

A model shapes values between your code and the table, like getters and setters. Use one file per form, next to its hooks.

var { FactoryModel } = require('@xeplr/factory')

class TaskModel extends FactoryModel {
  static table = 'tasks'
  static fields = {
    tags: {
      set: (value) => (Array.isArray(value) ? value.join(',') : value),   // before it is written
      get: (value) => (value ? value.split(',') : [])                     // after it is read
    }
  }
  static toDb(values) { return super.toDb(values) }     // override for more than one field at a time
  static fromDb(row) { return super.fromDb(row) }
}

await factory.init({ knex, hooks, models: [TaskModel] })     // or factory.registerModel(TaskModel)

Setters run after save.before and before the screen’s rules. Getters run before get.after. Both run on the routes and in factory.table(). A table with no model is left as it is. Models shape data, and hooks decide behaviour.

Your own queries: factory.table()

Form tables are ordinary tables, so knex('tasks') works, but then you have to remember the factory’s rules yourself. factory.table() is knex with those rules applied:

var open = await factory.table('tasks').where({ status: 'todo' })                         // this company's active rows, through the getters
await factory.table('tasks', { user: req.user }).insert({ title: 'Plant seeds' })         // id, company, audit filled in; setters
await factory.table('tasks', { user: req.user }).where({ id }).update({ status: 'done' }) // audit; cannot change the company
await factory.table('tasks').where({ id }).del()                                          // soft: isActive = false

Inside a hook it is ctx.db(). Use plain knex('tasks') only for work that must see every company.

Keys and labels

A form has a key (farming_department) and a label. The key names its screens and its table and never changes once the form is published. The label is the screens’ name and can be renamed at any time. Code only ever uses keys. A new form is created with POST /factory/entities { key, label? }, or from Configure UI → Forms in a generated app.

Server setup and routes

var factory = require('@xeplr/factory')

await factory.init({ knex: appKnex })                                   // the app database, where entity tables live
app.use(factory.router({ access: true, auth: auth.mtMembershipGate }))  // after mtMiddleware()
await factory.publishScreens([require('./screens/task/task-edit.screen.json'), require('./screens/task/task-list.screen.json')])

DB_FACTORY=myapp xeplr-factory-migrate up        # creates factory_screens, once

publishScreens runs at startup. It publishes each screen that has no published version yet, which creates its table, and leaves the rest alone. A restart therefore never overwrites a design someone has since changed. These screens are published for every tenant, and a company’s own later version wins for that company.

What a request can reach. A request names a screen, never a table or a column. Table and column names come only from a published screen and are checked against the table’s real columns before any query. Values go through @xeplr/schema-handler with the screen’s own rules, so the server accepts exactly what the form does.

In the browser, connect the components with createFactoryApi({ fetch: authFetch }). authFetch returns parsed bodies, and createFactoryApi accepts that.

Access

Every factory route is a row in the auth database’s apis catalog. Add node_modules/@xeplr/factory/migrations-auth to XEPLR_AUTH_MIGRATIONS to install them.

With { access: true }, each route answers only a caller whose req.access.apis names it. Anyone else gets 403. A request with no req.access at all is refused too, because it means the router was mounted where no auth gate ran.

Access is checked per route, not yet per screen or table. Whoever may save records may save them on any published screen.

An app made by @xeplr/cli goes further: designing, creating forms and publishing are Super Admin only, whatever else a role has been granted (api/routes/access.js). Relax that there once your app has decided who else should be allowed.

Last updated 16 September 2026