# The `app` object — complete frontend reference
`@simpleworkjs/frontend` attaches a single global, `window.app`, assembled from
the files under `lib/`. Each file adds one namespace and is safe to load in any
order (every file starts with `window.app = window.app || {}`). This document
covers the entire public surface.
## Contents
- [Loading and dependencies](#loading-and-dependencies)
- [Lifecycle: `app.ready` / `app.isReady`](#lifecycle)
- [`app.api`](#appapi) — REST wrapper
- [`app.model`](#appmodel) — schema-aware model client
- [`app.pubsub`](#apppubsub) — in-browser event bus
- [`app.socket`](#appsocket) — Socket.IO client
- [`app.sync`](#appsync) — server events → local refresh events
- [`app.render`](#apprender) — schema-driven Bootstrap UI (collection cards, forms)
- [`app.modal`](#appmodal) — reusable Bootstrap modal
- [`app.messages`](#appmessages) — action messages, confirms, toasts
- [`app.util`](#apputil) — helpers
- [`app.custom`](#appcustom) — per-page initializer registry
- [`$.fn.validate`](#fnvalidate) — attribute-driven form validation
- [Event topics](#event-topics)
- [`data-sw-*` attributes](#data-sw-attributes)
- [Schema and field shape](#schema-and-field-shape)
---
## Loading and dependencies
The scripts are served by `@simpleworkjs/backend` at `/lib/js/`. Load them after
their third-party dependencies:
```html
```
| Dependency | Required by | Notes |
|------------|-------------|-------|
| **jQuery** | all modules | The whole library is an IIFE over `jQuery`. |
| **Socket.IO client** | `app.socket` | If `io` is undefined, `app.socket` stays `null` and live sync is disabled — everything else still works. |
| **jq-repeat + Mustache** | `app.render` tables/cards | `app.render` emits `jq-repeat` templates using `{{field}}` placeholders and drives them through `$.scope[name]`. |
| **Bootstrap 5 JS** | `app.messages.toast` | Uses `new bootstrap.Toast(...)`. |
| **Font Awesome** | `app.messages` | Confirm/close buttons use `fa-solid` icons (cosmetic). |
## Lifecycle
`app.ready(callback)` runs `callback` once the DOM is ready and the socket has
been wired up. If that has already happened it runs immediately.
```js
app.ready(function () {
// DOM ready, app.socket connected (if Socket.IO is present)
});
```
- `app.isReady` — `boolean`, `true` after the ready phase has run.
- `app.onReady` — internal queue of pending callbacks (do not use directly).
`app.model` and `app.sync` register their own `app.ready` hooks: on ready,
`app.model.init()` loads all schemas and `app.sync.init()` starts bridging
server events. To run code after **schemas** are loaded, use
[`app.model.ready`](#appmodel), which is a distinct, later signal.
Ordering of readiness signals:
```
DOM ready ──▶ app.ready callbacks ──▶ app.model.init() ──▶ app.model.ready callbacks
(socket wired) (schemas fetched)
```
---
## `app.api`
Thin promise-returning wrapper over `$.ajax`; every method returns a jqXHR
(thenable / `.done()` / `.fail()`). All responses are parsed as JSON. Paths are
passed through verbatim (e.g. `/api/Task`).
| Method | Signature | HTTP |
|--------|-----------|------|
| `get` | `app.api.get(path, data?)` | `GET` (`data` → query string) |
| `options` | `app.api.options(path)` | `OPTIONS` (schema) |
| `post` | `app.api.post(path, data)` | `POST` (JSON body) |
| `put` | `app.api.put(path, data)` | `PUT` (JSON body) |
| `del` | `app.api.del(path)` | `DELETE` |
```js
app.api.get('/api/Task', {done: false});
app.api.post('/api/Task', {title: 'Buy milk'});
app.api.put('/api/Task/' + id, {done: true});
app.api.del('/api/Task/' + id);
```
> The delete method is **`del`**, not `delete` (`delete` is a reserved word).
---
## `app.model`
A schema-aware client layered on `app.api`. On startup it reads the API root
(`GET /api/`), then fetches every model's `OPTIONS` schema and caches it.
### Properties
| Property | Type | Description |
|----------|------|-------------|
| `schemas` | `object` | `{[modelName]: schemaResponse}` — cached `OPTIONS` responses. |
| `cache` | `object` | `{[modelName]: {}}` — per-model record cache (reserved for future use). |
| `isReady` | `boolean` | `true` once all schemas have loaded. |
| `lastEvent` | `object` | `{[modelName]: ms}` — timestamp of the last WebSocket event per model (shown in the Debug panel). |
| `readyCallbacks` | `array` | Internal queue for `ready()`. |
### Methods
| Method | Returns | Description |
|--------|---------|-------------|
| `ready(cb)` | — | Run `cb` once schemas are loaded (immediately if already ready). |
| `init()` | jQuery promise | Load the API root + all schemas. Called automatically on `app.ready`. |
| `schema(name)` | schema \| `undefined` | The cached `OPTIONS` response for a model. |
| `list(name, params?)` | promise → `{results, page, pageSize, total, pageCount}` | List a page; `params` (e.g. `{page, pageSize, where}`) become query args. |
| `get(name, pk)` | promise → `{data: {...}}` | Fetch one record. |
| `create(name, data)` | promise → `{data: {...}}` | Create. |
| `update(name, pk, data)` | promise → `{data: {...}}` | Update. |
| `remove(name, pk)` | promise → `{data: {...}}` | Delete. |
| `relatedList(name, pk, association)` | promise → `{results: [...]}` | `GET /api/:name/:pk/:association` for a `hasMany`. |
```js
app.model.ready(function () {
const schema = app.model.schema('Task'); // see "Schema and field shape"
app.model.list('Task', {done: false}).done(function (resp) {
console.log(resp.results);
});
});
```
---
## `app.pubsub`
A synchronous in-browser event bus. **Topic patterns are matched as regular
expressions** (`new RegExp(pattern).test(topic)`), so anchor them (`^…$`) when
you need an exact match.
| Member | Description |
|--------|-------------|
| `subscribe(pattern, listener)` | Returns `{remove()}`. `listener(data, topic)` is called for every published topic matching `pattern` as a regex. |
| `publish(topic, data)` | Invoke every listener whose pattern matches `topic`. A throwing listener is caught and logged; it does not stop the others. |
| `listeners` | Internal `{[pattern]: listener[]}` map. |
```js
const sub = app.pubsub.subscribe('^model:Task:(create|update)$', function (data, topic) {
console.log(topic, data);
});
sub.remove();
```
---
## `app.socket`
The Socket.IO client instance (`io()`), or `null` when Socket.IO is not loaded.
It is created during the `app.ready` phase and bridges the server's
`model:event` channel onto `app.pubsub`:
```js
// internal wiring (app.js):
app.socket.on('model:event', function (data) {
app.pubsub.publish('model:' + data.model + ':' + data.action, data);
app.pubsub.publish('model:any', data);
});
```
You can use `app.socket` directly for custom events, but for model changes
prefer `app.sync` / `app.pubsub`.
---
## `app.sync`
Bridges *incoming* server model events into *local* refresh events that the
renderers consume. On `app.ready`, `app.sync.init()` subscribes to `model:any`;
for each change it re-fetches the record and republishes:
- `model:local::refresh` → `{model, pk, data}` when the record still exists.
- `model:local::remove` → `{model, pk}` when the fetch 404s (deleted).
| Method | Description |
|--------|-------------|
| `onAny(listener)` | Subscribe to every model event (`model:any`). Returns `{remove()}`. |
| `on(modelName, action, listener)` | Subscribe to `model::` (e.g. `on('Task', 'update', fn)`). Returns `{remove()}`. |
| `init()` | Start the bridge. Called automatically. |
```js
app.sync.on('Task', 'create', function (data) { /* {model, action, pk, data} */ });
app.sync.onAny(function (data) { /* any model changed */ });
```
---
## `app.render`
Generates Bootstrap UI from a model's schema and binds it to live `jq-repeat`
scopes so it updates as `app.sync` reports changes. All interpolated values are
HTML-escaped.
| Method | Description |
|--------|-------------|
| `build(selector)` | For each matched element, read its `data-sw-*` attributes and render the requested mode. **Default mode is `collection`.** |
| `collection($el, name, schema)` | **The default view.** One card per collection (below). |
| `table($el, name, schema)` | Render a Bootstrap table with View/Edit/Delete actions. |
| `cards($el, name, schema)` | Render a responsive card grid. |
| `form($el, name, schema, pk?, options?)` | Render a create form, or an edit form when `pk` is given. `options` = `{modal, onSuccess}` (below). |
| `_reload(name, scopeName)` | Internal: re-fetch a model's list and `replace()` the bound jq-repeat scope. |
| `_teardown($el)` | Internal: remove the pubsub subscriptions a previous `build()` attached to `$el` (idempotent re-builds). |
### The `collection` view
The default. Renders one Bootstrap card per collection:
- **Header** — the collection title, plus **Debug**, **Permissions**, and **New**
action buttons.
- **Body** — a paginated jq-repeat list of rows, each with **View**, **Edit**
(modal), and **Delete** (confirm) actions.
- **Footer** — "Showing X–Y of N" and Prev/Next. Page size comes from
`schema.display.pageSize` (default 20). The list re-fetches the current page on
every live change.
- **Debug** button → a modal with the model's endpoints, permissions, field
schema, and the last WebSocket update time (`app.model.lastEvent`).
- **Permissions** button → a read-only modal listing the required token(s) per
action (from OPTIONS `permissions`) with a legend. (Editing arrives when
permissions become DB-backed and runtime-configurable.)
Typical usage is fully declarative — mark up an element and call `build()`:
```html
```
```js
app.model.ready(function () {
app.render.build('[data-sw-model]');
});
```
Behavior notes:
- **Table** hides private fields and relationship (`references`) columns, adds
View/Edit/Delete actions, and wires the Delete button through
`app.messages.confirm` + `app.model.remove` + a toast.
- **Cards** use the model's `display.titleField` as the card title.
- **Form** renders one input per settable field (private-but-`writeOnly` fields
like `password` are included), chooses the control from the field's `htmlType`
(`checkbox`, `textarea`, otherwise a typed ``), and for `hasOne` fields
renders a `