pgkiln 0.31.0 → 0.36.0

package/docs/guide/04-pages-and-regions.md

@@ -13,6 +13,32 @@ A page has a number (unique in the app), a name, a title, and these behaviours:
 | `requires_auth` | boolean | `false` makes the page public in an app with a login |
 | `authz` | scheme name | Who may open it (403 otherwise) |
 | `protection` | `checksum`, `unrestricted` | Whether URL item values need a checksum |
+| `warn_unsaved` | boolean | Ask before the user leaves the page with unsaved changes, see [below](#warn-on-unsaved-changes) |
+
+### Warn on unsaved changes
+
+With **Warn on unsaved changes** (Page Designer → Page → Appearance; APEX: the page attribute of the
+same name), the browser asks *"You have unsaved changes. Leave this page anyway?"* when the user
+leaves the page while an item has a value other than the one the page was shown with: a link, a
+redirect button (such as *Cancel*), the navigation menu, closing a dialog (its × or Escape),
+reloading or closing the tab. Submitting the page with a button doesn't ask (that saves). After a
+submit that failed (a validation error), the values on the page are not saved yet, so leaving asks
+even without a further change. The check is in the browser (`pgkiln.isChanged()` tells your own
+JavaScript, like APEX's `apex.page.isChanged()`); without JavaScript there is none.
+
+- **Leave an item out** with `{"warn_unsaved": false}` in its attributes (APEX: the item's *Warn on
+  Unsaved Changes: Ignore*), for example a search field.
+- The interactive grid has its own check of unsaved rows, which is always on.
+- A value a dynamic action changes on page load counts as a change.
+- The create page wizards switch it on for the form pages they make; existing pages have it off
+  until you switch it on.
+
+### Minimal pages
+
+Page template **Minimal (no navigation)** (Page Designer → Page → Appearance; APEX: the page
+template of the same name) shows the page without the header, the navigation menu and the
+navigation bar: the title and the regions only, centred. The application's
+[login page](08-security.md#the-login-page) uses it and gets the sign-in page's backdrop.
 
 ### Dialogs and drawers
 
@@ -43,6 +69,18 @@ Region **templates**:
 | `standard` | A card with a header (title and buttons) and a body |
 | `plain` | No frame and no header: content only (good for KPI cards and intro text) |
 | `collapsible` | A standard card whose body can be collapsed by clicking the header |
+| `hero` | A large banner: an icon (`{"icon": "users"}` in the attributes), the title, the text and the buttons (APEX: Hero) |
+| `title_bar` | The title and buttons on one line over the content, without a card (APEX: Title Bar) |
+| `buttons_container` | The buttons only (after any text), without a header (APEX: Buttons Container) |
+| `inline_dialog` | Hidden until opened, then a dialog over the page with a close button; Esc and a click beside it close it too (APEX: Inline Dialog) |
+| `inline_drawer` | The same, as a panel docked to the right edge (APEX: Inline Drawer) |
+| `wizard` | A narrow, centred card for one step of a wizard; a [list](#list-lists) region with template `wizard_progress` above it shows the steps (APEX: Wizard Container) |
+
+An inline dialog or drawer opens with the dynamic action **Open region** (and closes with **Close
+region**), e.g. on the click of a button with action *Defined by dynamic action*, or with a link to
+`#R<id>` (which also works without JavaScript). Items in it are part of the page: a submit sends
+them along. The carousel is a style of the [display selector](#display_selector-region-display-selector)
+region (`{"style": "carousel"}`). The HR example's page 44 (*Region templates*) shows them all.
 
 Every region also has `seq` (order), `condition` (a SQL boolean expression; the region renders
 only when true) and `authz` (an authorization scheme).
@@ -97,7 +135,7 @@ database only checks the shape (at most 12 names of lower case letters, digits a
 | Type | Purpose |
 |---|---|
 | [`report`](#report-interactive-report) | Read-only table from a SELECT, with search, filters, sorting, control break, aggregates, highlights, computed columns, group by, pivot and chart views, row selection, saved reports, paging and CSV/Excel/PDF download |
-| [`grid`](#grid-interactive-grid) | Editable table on one database table, with aggregates, frozen, movable and resizable columns, saved grid reports, a row actions menu, master-detail and copy/paste of cells |
+| [`grid`](#grid-interactive-grid) | Editable table on one database table, with aggregates, frozen, movable and resizable columns, saved grid reports, a row actions menu, master-detail, copy/paste of cells, and single row, group by and chart views |
 | [`form`](#form) | Fields for one row of a table, with automatic fetch and save |
 | [`chart`](#chart) | Bar, column, stacked, line, area, combo, scatter, bubble, donut, pie, gauge, funnel, radar, Gantt, pyramid or polar chart from a SELECT, with drill-down links |
 | [`cards`](#cards) | Cards or KPI tiles from a SELECT |
@@ -113,6 +151,9 @@ database only checks the shape (at most 12 names of lower case letters, digits a
 | [`template_component`](#template-components) | Each row (or all rows) of a SELECT through a template component: badges, contact cards, timelines, your own |
 | [`tasks`](06-processing.md#approvals-and-the-task-list) | Task list: approvals and actions for the signed-in user |
 | [`workflows`](06-processing.md#workflows) | Workflow console: the workflows the user started or administers |
+| [`search`](#search-search-region) | One search field over several sources (search configurations), results grouped per source |
+| [`url`](#url-url-region) | Another site's page (or a page of this server) in a sandboxed frame |
+| `login` | The sign-in form of the application's own login page (no attributes): identity providers, user name and password, *Keep me signed in*, *Forgot password?*; see [chapter 8](08-security.md#the-login-page) |
 | [`static`](#static-and-dynamic-content) | Fixed HTML with `&ITEM.` substitutions |
 | [`dynamic`](#static-and-dynamic-content) | HTML produced by a SELECT |
 
@@ -333,6 +374,7 @@ Attributes:
 | `master` | | Makes it (or a report, chart, cards …) a **detail**: `{"item": "P27_DEPTNO", "column": "deptno"}` (below) |
 | `actions` | `true` | `false` hides the Actions menu (columns, aggregates, saved reports) |
 | `saved_reports`, `public_reports` | `true`, none | As for reports |
+| `views` | all | The views users may switch to besides the grid: `["row", "group", "chart"]`; `[]` for the grid only |
 
 Cell editors follow the column type: number, date, date-time, checkbox (boolean), select list
 (with `lov`) or text.
@@ -377,6 +419,23 @@ user can only select a row the server showed them; the item is not taken from th
 submit otherwise. A detail **grid** with `master.column` fills that column with the selected value
 on its new rows (and never lets users edit it); saving new rows without a selection is refused.
 
+**Views** (APEX: Single Row View, Group By, Chart). Besides the rows, a grid has three views
+(`r<id>_v=row|group|chart` in the URL, kept in saved grid reports); `views` limits them:
+
+- **Single row view**: one row at a time as a form, opened from **Actions → Single row view** or
+  a row's ⋮ menu. *First*, *Previous*, *Next* and *Last* move through the rows of the search in
+  the grid's order (`r<id>_row=N`, the position from 1); **Add row** opens an empty form
+  (`r<id>_row=new`). It edits the same fields as the grid and is saved by the same `grid_dml`
+  process, with the same checks (signed keys, required columns, lists of values); the user is
+  warned before leaving with unsaved changes. Give the query an `order by` (or sort the grid)
+  so that positions stay the same after a save, as for paging.
+- **Group by** and **Chart**: set up in the Actions menu as for an
+  [interactive report](#report-interactive-report), over every row of the search. Once
+  set up, a switcher above the grid moves between *Grid* and these views.
+
+The developer's `hidden` columns can't be grouped, charted or shown in the single row view.
+After **Save** the grid comes back as it was: its search, page, sort and view.
+
 **Copy and paste.** Click a cell and Shift+click another to select a range; Ctrl+C copies it
 as tab-separated text (which spreadsheets paste as cells). Ctrl+V pastes such text (from a
 spreadsheet or another grid) from the focused cell on, adding rows when the grid allows inserts;
@@ -411,6 +470,18 @@ that column.
 Typical form buttons (as generated by the wizard): *Cancel* (redirect), *Delete* (condition
 `:P3_ID is not null`), *Apply Changes* (same condition) and *Create* (condition `:P3_ID is null`).
 
+**Lost updates** (APEX: *Prevent Lost Updates* and *Lock Row*). When the form fetches its row, the
+page also gets a checksum of the row's form columns (file columns aside). On *Save* or *Delete*,
+`form_dml` locks the row (`SELECT … FOR UPDATE`), computes the checksum again and refuses the
+change when it differs: *"Someone else changed this record after you opened it. Reload the page to
+see the current values, then make your changes again."* Nothing is written, and the other user's
+change is kept. Columns that are not on the form don't count, and the checksum doesn't depend on
+the user's time zone or date format. The check is on by default; switch it off for one form with
+`{"lost_update": false}` in the region's attributes. The checksum is `meta.row_version(table,
+key_column, key, columns)`, which runs as the application's role (so its grants and row level
+security apply). A process that changes the same row *before* `form_dml` in the same submit makes
+the check fail: change the row after `form_dml`, or switch the check off.
+
 The easiest way to get a form is the **Report and form** wizard, which opens the form as a modal
 dialog from the report, or the **Form** wizard for a form page on its own (see
 [Create pages from a table](03-builder.md#create-pages-from-a-table-wizards)). The Cards, Calendar,
@@ -746,7 +817,8 @@ region display selector. Regions take part through their own attributes:
 
 | Key | Meaning |
 |---|---|
-| `style` | `tabs` (default) or `select` |
+| `style` | `tabs` (default), `select`, or `carousel`: one region at a time with *Previous* and *Next* and a dot per region, without *Show all* (APEX: the Carousel template) |
+| `interval` | A carousel turns to the next region every so many seconds (1 to 120); not while the pointer or the focus is in it, nor for users who prefer reduced motion |
 | `show_all` | `false` hides the *Show all* tab (default: shown) |
 | `remember` | `false`: don't remember the chosen tab for the browser session (default: remembered per page) |
 
@@ -946,7 +1018,7 @@ Attributes (the region's **Settings** in the page designer):
 | Key | Meaning |
 |---|---|
 | `list` | The list's name (upper case) |
-| `template` | `links` (default: nested links), `badges` (a row of tiles with the badge as the value), `cards` (a card per entry with its description) or `tabs` (the top-level entries as tabs) |
+| `template` | `links` (default: nested links), `badges` (a row of tiles with the badge as the value), `cards` (a card per entry with its description), `tabs` (the top-level entries as tabs) or `wizard_progress` (numbered steps: the entry of the current page is the current step, the ones before it are done and link back; APEX: Wizard Progress) |
 
 The HR example's page 31 (Shortcuts) shows a static list with each template (with a badge from an
 item, child entries, a manager-only entry and one of an excluded build option) and a department
@@ -1264,6 +1336,88 @@ first rows and a *Show all* button), `char-counter` (item: a maximum length with
 an event in `pgkiln_plugins.event_log`). HR example part 47 installs them and uses all four on page
 40 (*Plug-ins*).
 
+### `search` (search region)
+
+One search field over several sources, with the results grouped per source (APEX 22.2: the Search
+region and search configurations). Each source is a **search configuration** (Shared Components →
+Search configurations):
+
+| Property | Meaning |
+|---|---|
+| Name | The static ID the region names, e.g. `CUSTOMERS` |
+| Label | The heading of its results (translated like the page's texts) |
+| Sequence | The order of the groups |
+| Source type, source | `table`: a table or view (`sales.customers`) · `sql`: a SELECT, `:ITEM` binds allowed · `list`: the entries of a [list](#list-lists) the user may see (their label and description are searched, they link where the entry links) |
+| Searchable columns | The columns the search text is looked for in. Empty: the title, subtitle and description columns |
+| Title, subtitle, description, badge column | What each result shows. The title is required (table, sql), and results are ordered by it |
+| Icon | An [icon name](09-reference.md#icons), or `#COLUMN#` for a column that holds icon names |
+| Link | Where a result goes: `{"page": 3, "items": {"P3_ID": "#ID#"}}` (`#COLUMN#` is the row's value; the link gets a checksum, a modal page opens as a dialog) |
+| Maximum results | Per configuration, 1–100 (default 10); "Showing the first *n* rows." when there are more |
+
+**How it searches.** Each word of the search text must be found (case-insensitively, anywhere in
+the value) in one of the searchable columns, so `clerk mil` finds MILLER the clerk. `%` and `_` are
+plain characters. The text is a query parameter, never SQL; the queries run as the application's
+role (its grants and row level security apply), each on its own, so a configuration that fails
+shows its error and the others still answer. The found words are marked in the results.
+
+```sql
+-- a configuration on a query: employees with their department
+select e.empno, initcap(e.ename) as name, initcap(e.job) as job, d.dname as department
+  from hr.emp e left join hr.dept d on d.deptno = e.deptno
+```
+
+with searchable columns `name, job, department`, title `name`, subtitle `job`, badge `department`
+and link `{"page": 3, "items": {"P3_EMPNO": "#EMPNO#"}}`.
+
+**The region**: attributes
+
+| Key | Meaning |
+|---|---|
+| `configs` | The configurations it searches, e.g. `["CUSTOMERS", "ORDERS"]`; empty or left out: all of the application's |
+| `item` | Search with this page item's value (`"P1_SEARCH"`) instead of a field of the region's own; refresh the region from a dynamic action, or let the item submit the page |
+| `placeholder` | The field's placeholder |
+| `min_length` | Search only from this many characters (default 1) |
+| `empty` | The text when nothing is found (default "Nothing found.") |
+
+The region's own field is a GET form (`?s<region id>=text`, so a search can be bookmarked) and works
+without JavaScript; with JavaScript it searches while the user types and replaces only the results.
+The Advisor plans every configuration with the columns it names and reports names a region uses
+that don't exist. Search configurations are exported with the application. The HR example's page 42
+searches employees, departments and the shortcuts list.
+
+### `url` (URL region)
+
+Shows another site's page in the region, in a sandboxed `<iframe>` (APEX: URL region).
+
+**Source**: the URL. Its scheme and host are written out, so an item can never choose which site is
+shown; `&ITEM.` substitutions are allowed after the host and are URL-encoded:
+
+```text
+https://reports.example.com/dashboard?customer=&P3_CUSTOMER_ID.&lang=&APP_LANGUAGE.
+```
+
+- `https://` only (`http://` for `localhost` during development), no user name or password in the
+  URL. A path that starts with `/` shows a page of this server, such as another pgkiln application
+  (`/a/portal/1`).
+- The page's Content-Security-Policy gets `frame-src` for exactly the origins of its visible URL
+  regions; other pages frame nothing. The Advisor reports a URL that isn't allowed.
+- The other site decides whether it may be framed: many sites forbid it (`X-Frame-Options` or
+  `frame-ancestors`), and the browser then shows an empty frame. Under the frame, *Open in a new tab*
+  opens the page itself.
+- The region's title is the frame's accessible name.
+
+Attributes:
+
+| Key | Meaning |
+|---|---|
+| `height` | The frame's height in pixels, 100–4000 (default 480); the width is the region's |
+| `sandbox` | The frame's sandbox flags, from `allow-scripts`, `allow-forms`, `allow-popups`, `allow-same-origin`, `allow-downloads`, `allow-modals` and `allow-popups-to-escape-sandbox`. Default: the first four (most sites need them to work). `false`: no sandbox. Navigating the whole window (`allow-top-navigation`) is never allowed |
+| `fullscreen` | `true`: the framed page may go full screen (videos, maps) |
+
+```json
+{"height": 640, "sandbox": ["allow-scripts", "allow-same-origin"], "fullscreen": true}
+```
+
 ### `static` and `dynamic` content
 
 - **`static`**: `source` is HTML written by the developer, with `&ITEM.` substitutions

package/docs/guide/05-items.md

@@ -33,6 +33,8 @@ page, optionally inside a region. Name them `P<page>_<NAME>` (uppercase letters,
 | `combobox` | free text with suggestions from the list of values; several values become tags | **colon-separated** values, e.g. `SQL:Sales` |
 | `daterange` | two date pickers, *From* and *To* | `from:to`, e.g. `2026-01-01:2026-06-30` |
 | `qrcode` | display only: the value as a QR code (SVG drawn on the server) | whatever was set |
+| `image` | display only: a picture from a URL in the value, or a BLOB from a query ([Display image](#display-image-and-geocoded-address)) | a URL, or nothing |
+| `address` | a text field with *Check address*: the installation's geocoder offers matching addresses ([Geocoded address](#display-image-and-geocoded-address)) | the address as text |
 | `plugin` | an [item plug-in](04-pages-and-regions.md#plug-ins-with-their-own-code): a text field its JavaScript enhances; `config`: `{"plugin": "char_counter", "attributes": {"MAX": "140"}}` | text |
 
 Use multi-value items in SQL with `string_to_array`:
@@ -70,6 +72,7 @@ Attributes (`config`):
 | Key | Meaning |
 |---|---|
 | `submit_on_change` | `true`: submit the page when the value changes (typical for report filters) |
+| `warn_unsaved` | `false`: a change of this item doesn't count for the page's [warn on unsaved changes](04-pages-and-regions.md#warn-on-unsaved-changes) |
 | `null_label` | Text of the empty option in select lists (default `- Select -`); `false` removes the empty option |
 | `cascade_parents` | Comma-separated items this list depends on, see [cascading lists](#cascading-lists-of-values) |
 | `wide` | `true`: take the full width of the form |
@@ -129,6 +132,50 @@ the Markdown is shown as text, and the result passes through the same allow-list
 
 The HR example's page 20 *Reviews* (`examples/hr/hr_20_items.sql`) uses all of them.
 
+## Display image and geocoded address
+
+**Display image** (`image`, APEX: *Display Image*) shows a picture and can't be submitted. Two
+sources:
+
+- **A URL in the item's value** (a computation, a process or a form fetch sets it): an `https://`
+  URL, a path on this server (`/a/hr/static/logo.png`) or a `data:image/png;base64,…` URL. Other
+  schemes (`http:`, `javascript:`, URLs with a user name) show nothing. The page's
+  Content-Security-Policy allows pictures from exactly the `https` origins its image items show
+  when it is rendered.
+- **A BLOB from a query**: `{"sql": "select photo, photo_mime from hr.emp where empno = :P43_EMPNO::int"}`.
+  The first column of the first row is the picture (`bytea`), the second its MIME type (else it is
+  recognised from the bytes: PNG, JPEG, GIF, WebP). The browser loads it from
+  `/a/<alias>/<page>/image/<item>`, which runs the query as the application's role with the
+  session's item values, after the page's authorization and the item's own; it is never cached,
+  sandboxed and at most 20 MB.
+
+`config`: `{"alt": "Photo of &P43_ENAME.", "width": 160, "height": 160}` (the alternative text,
+`&ITEM.` substitutions allowed; it defaults to the label).
+
+**Geocoded address** (`address`, APEX: *Geocoded Address*) is a text field with a *Check address*
+button. The server asks the installation's geocoder for the typed text and shows up to five
+matching addresses; the one chosen replaces the text, and with
+`{"coordinates_item": "P43_LOCATION"}` its position goes into that item as `latitude,longitude`
+(the format of a `location` item, so a map region can show it). `{"country": "nl"}` (or `"nl,be"`)
+limits the search to those countries. The answers come in the user's language.
+
+The geocoder is set per installation with **`GEOCODER_URL`**, any API that speaks Nominatim's
+search (`?q=…&format=jsonv2`): your own [Nominatim](https://nominatim.org), LocationIQ
+(`https://eu1.locationiq.com/v1/search` with `GEOCODER_KEY`) or, within its usage policy (an
+absolute maximum of one request per second, no heavy use), `https://nominatim.openstreetmap.org/search`.
+Each session may ask once a second. Without `GEOCODER_URL` an address item is a plain text item.
+
+The HR example's page 43 *Data and settings* (`examples/hr/hr_53_data_settings.sql`) has both.
+
+## Keeping values per user
+
+`{"persist": "user"}` on any item (APEX: *Maintain session state: Per User*) keeps its value for
+the signed-in user across sessions: when a page shows the item and the session has no value for it
+yet, the user's last value comes back; a submit of the page (also a plain submit, e.g. *submit on
+change*) saves the value the user could change, in the same transaction as the page's processes.
+The value is a [user preference](06-processing.md#user-preferences) named like the item. Public
+pages and applications without sign-in keep nothing.
+
 ## Lists of values
 
 A list of values (LOV) provides the options of select lists, radio groups, checkbox groups,

package/docs/guide/06-processing.md

@@ -167,6 +167,36 @@ end if;
 All changes of the submit are rolled back, and the page is shown again with the entered
 values so the user can correct them.
 
+**Error handling function** (Settings → *Errors and sessions*; APEX: Error Handling Function). A
+function of your own rewrites every error message users see: those raised in PL/pgSQL, the friendly
+constraint messages and the "reference" messages of unexpected errors.
+
+```sql
+create function sales.error_message(e jsonb) returns jsonb language plpgsql as $$
+begin
+  if e->>'constraint' = 'order_customer_fk' then
+    return jsonb_build_object('message', 'Choose an existing customer.');
+  end if;
+  if (e->>'internal')::boolean then
+    return jsonb_build_object('message', 'Something went wrong. Quote ' || (e->>'reference') || ' to the help desk.');
+  end if;
+  return null;   -- keep the message
+end $$;
+```
+
+It gets `message` (what pgkiln would show), `original_message`, `code` (SQLSTATE), `constraint`,
+`table`, `column`, `detail`, `hint`, `component` (where it happened, e.g. `process "Save order"`),
+`page`, `user`, `internal` (true for an unexpected error) and `reference` (its activity log id), and
+returns `{"message": "…"}` or null. It runs as the application's role, in a transaction of its own,
+with a 2-second limit; when it fails or returns null the message stays as it was. Debug mode shows
+the real error and doesn't call it.
+
+### Ajax callbacks
+
+A process with point **ajax** runs when JavaScript calls it by name, `pgkiln.server.process('NAME')`
+(APEX: On Demand processes, `apex.server.process`), and answers JSON; see
+[chapter 7](07-dynamic-actions.md#ajax-callbacks).
+
 ### Debug messages
 
 Like APEX's debug, pgkiln can record what each request of an application did and how long every
@@ -182,6 +212,10 @@ application's settings):
 | 6 trace | Also each region, process, application process and computation with its duration, and the session (page, user, language, time zone) |
 | 9 everything | Also the posted item values, computed values, skipped processes, hidden regions and other SQL notices |
 
+A developer can also switch debug on for **their own session** only, from the
+[developer toolbar](03-builder.md#developer-toolbar) on the running application: the application
+stays out of debug for everyone else.
+
 Each recorded request lists its entries with the time since the start of the request and, for
 timed steps, their duration. Add your own from any application SQL (processes, region sources,
 conditions, your PL/pgSQL functions), as with `apex_debug.message`:
@@ -240,6 +274,27 @@ a MIME type that doesn't look like one becomes `application/octet-stream`; the r
 sniffed (`nosniff`), is sandboxed by its Content-Security-Policy and isn't cached. At most 1000
 files and 100 MB per download.
 
+#### Data export
+
+With `{"export": "<format>"}` the query returns **rows**, and the download is those rows as one
+file (APEX: `APEX_DATA_EXPORT`): `csv`, `json`, `xml`, `html`, `xlsx` (Excel) or `pdf`.
+
+```json
+{"export": "xlsx", "file_name": "employees-&P43_DEPTNO.", "title": "Employees"}
+```
+
+| Key | Meaning |
+|---|---|
+| `export` | The format |
+| `file_name` | The name without extension, `&ITEM.` substitutions allowed (default: the process name) |
+| `title` | The title of an HTML or PDF file |
+| `layout` | A [report layout](16-files.md#report-layouts) for the PDF (paper, margins, logo) |
+| `separator` | CSV: one character instead of `,` |
+
+Column names are the headings (`hire_date` → *Hire Date*, translated like report headings in Excel
+and PDF). Excel keeps numbers and dates as numbers and dates; Excel and PDF hold at most 100,000
+rows. From SQL, `meta.data_export` makes the same CSV, JSON, XML and HTML ([below](#data-export-from-sql)).
+
 ### Execution chains
 
 A `chain` process runs its **children**: the processes of the page whose `parent_process` is the
@@ -295,6 +350,30 @@ looks up the employee (a `sql` child) and then starts the ONBOARDING workflow (a
 *Stop onboarding* terminates it; *Year-end check* is a background chain whose jobs the region
 "My background jobs" lists from `meta.process_jobs`.
 
+### Send e-mail
+
+A `send_email` process (APEX: *Send E-Mail*) queues a mail through the application's [mail
+service](#sending-e-mail), without SQL:
+
+```json
+{"to": "&P5_EMAIL.", "cc": "&P5_MANAGER_EMAIL.", "subject": "Order &P5_ID. shipped",
+ "body": "Dear &P5_NAME., your order is on its way.",
+ "body_html": "<p>Dear &P5_NAME.,</p><p>your order is on its way.</p>",
+ "attachments": "select content, filename, mime from sales.invoice where order_id = :P5_ID"}
+```
+
+or with an [e-mail template](#e-mail-templates):
+
+```json
+{"to": "&P5_EMAIL.", "template": "ORDER_SHIPPED", "placeholders": {"NAME": "&P5_NAME.", "ORDER_ID": "&P5_ID."}}
+```
+
+`to`, `cc`, `bcc` (several addresses separated by commas), `from`, `reply_to`, `subject` and `body`
+take `&ITEM.` substitutions as they are; in `body_html` the item values are HTML-escaped.
+`attachments` is a SELECT (binds allowed) with the columns `content` (bytea), `filename` and `mime`,
+one attachment per row. The mail is queued in the page's transaction: when a later process fails,
+nothing is sent. It can run in a background chain too.
+
 ### Send push notification
 
 A `send_push` process (APEX: *Send Push Notification*) sends a [push
@@ -514,6 +593,61 @@ select (select empno from hr.emp where lower(username) = lower(:APP_USER)) as ai
 
 `&AI_ENAME.` then greets the user on the dashboard.
 
+## Application settings
+
+**Shared Components → Application settings** (APEX: *Application Settings*, `APEX_APP_SETTING`)
+are named values an administrator changes after deployment: a support address, a limit, a switch.
+Each has a name (`SUPPORT_EMAIL`), a value, a description, optionally a list of **valid values**,
+and *Value required*. Application code reads and changes them:
+
+```sql
+select meta.get_app_setting('SUPPORT_EMAIL');
+select meta.set_app_setting('LEAVE_APPROVAL', 'hr');   -- one of its valid values
+```
+
+Both work for the current application only, called as its own database role (application code),
+and raise an error for an unknown name, a value outside the valid values or an empty required one.
+Settings are exported with the application, values included. An import over an installed
+application (CLI, MCP, a working copy merge) keeps the **installed** value of every setting marked
+*Keep the installed value on upgrade* (the default); with the mark off, the file's value wins. When
+the application's build status is *Run only*, its existing settings can still be edited.
+
+## User preferences
+
+Values kept per user and application across sessions (APEX: `APEX_UTIL.GET_PREFERENCE`,
+`SET_PREFERENCE`, `REMOVE_PREFERENCE`):
+
+```sql
+select meta.set_preference('report.rows', '50');        -- the signed-in user
+select meta.get_preference('report.rows');              -- null when there is none
+select meta.remove_preference('report.rows');
+select meta.get_preference('report.rows', 'blake');     -- another user of the application
+```
+
+Names are letters, digits, `_`, `.` and `-` (at most 100); values at most 32,000 bytes; at most 500
+preferences per user. Setting one needs a signed-in user. Items with `{"persist": "user"}` keep their
+values this way ([Keeping values per user](05-items.md#keeping-values-per-user)). Preferences are data of
+the installation: not exported, kept by an import over the application, deleted with it.
+
+## Data export from SQL
+
+`meta.data_export(query, format, options)` (APEX: `APEX_DATA_EXPORT.EXPORT`) returns a query's
+rows as a file (`bytea`): `csv`, `json` (an array of objects), `xml` (`query_to_xml`) or `html` (a
+table). It runs with the **caller's** privileges, so grants and row level security apply as to the
+query itself. Attach the file to a mail, store it, or send it with a download process:
+
+```sql
+select meta.add_mail_attachment(
+         meta.send_mail('boss@example.com', 'Staff', 'Attached.'),
+         meta.data_export('select empno, ename, sal from hr.emp order by ename', 'csv', '{"separator": ";"}'),
+         'staff.csv', 'text/csv');
+```
+
+Options: `separator` (CSV, one character), `header` (`false`: no heading line), `bom` (`false`: no
+UTF-8 byte order mark, which Excel needs to read UTF-8), `title` (HTML). CSV fields are quoted when
+needed, and text that a spreadsheet would run as a formula (`=`, `+`, `-`, `@`) gets a leading
+apostrophe, as in report downloads. Excel and PDF come from the [download process](#data-export).
+
 ## Automations
 
 **Shared Components → Automations** run SQL or PL/pgSQL on a schedule, like APEX automations:
@@ -604,6 +738,79 @@ creates or replaces the single action (the column itself stays empty).
 
 If you prefer the database to schedule work, [pg_cron](15-extensions.md) still works next to this.
 
+## Sending e-mail
+
+Like APEX's `APEX_MAIL`, applications send e-mail from SQL, from a *Send e-mail* process and from
+e-mail templates. Where APEX sends only through an SMTP server with a user name and password,
+pgkiln sends through any of these **mail services** (Workspace utilities → [Mail
+services](03-builder.md#mail-services), administrators):
+
+| Provider | How pgkiln hands mail over | Credentials |
+|---|---|---|
+| SMTP | Any SMTP server or relay, STARTTLS or TLS | User name and password, or **OAuth2** (SASL XOAUTH2 with a token from the client credentials grant: Microsoft Entra for Exchange Online, or another identity provider's token URL) |
+| Microsoft 365 (Graph) | Microsoft Graph `sendMail` as the From mailbox | An Entra application (tenant, client ID, client secret) with the application permission **Mail.Send**; restrict it to the sending mailboxes with an application access policy |
+| Amazon SES | SES API v2, the raw MIME message, Signature Version 4 | Region, access key ID and secret access key (an IAM user allowed `ses:SendEmail`) |
+| Resend, Postmark, SendGrid, Mailgun | Their HTTP APIs | An API key (Postmark: a server token; Mailgun: also the sending domain and region) |
+| Log only | Nothing is sent: the server's log shows each mail | – (development and demos) |
+
+Microsoft retires basic authentication (a password) for SMTP in Exchange Online: use SMTP with OAuth2
+or the Graph provider. Secrets are stored encrypted with `PGKILN_SECRET_KEY`, are write-only in the
+builder, never exported and never readable by applications. Each service lists the **From
+addresses** it may send as (an address, or `@example.com` for a whole domain); an administrator
+chooses each application's service, its From address and an optional **limit per day**.
+
+**How mail is sent.** `meta.send_mail` and the others only *queue* the mail, in the caller's
+transaction: a transaction that rolls back sends nothing. After the commit, the server sends it at
+once (`NOTIFY`), or on the scheduler's next pass. A failure that may pass (a network problem, HTTP
+429 or 5xx, an SMTP 4xx answer) is tried again after 1, 4, 16 and 64 minutes; the fifth failure, or a
+refusal (an unknown recipient, a sender the provider doesn't accept), marks the mail *error*.
+Applications → Activity → **Mail** shows each mail with its outcome, and sends a failed one again or
+cancels a queued one. Mail is kept 30 days.
+
+### From SQL
+
+```sql
+-- APEX_MAIL.SEND
+select meta.send_mail(
+  p_to        => 'jane@example.com, john@example.com',
+  p_subject   => 'Your leave was approved',
+  p_body      => 'Enjoy your holiday!',                   -- plain text
+  p_body_html => '<p>Enjoy your <b>holiday</b>!</p>',     -- HTML (optional)
+  p_cc        => null, p_bcc => null, p_reply_to => 'hr@example.com',
+  p_from      => null);                                   -- null: the application's From address
+
+-- APEX_MAIL.ADD_ATTACHMENT, in the same transaction
+with m as (select meta.send_mail('jane@example.com', 'Invoice 42', 'Attached.') as id)
+select meta.add_mail_attachment(m.id, i.pdf, 'invoice-42.pdf', 'application/pdf')
+  from m, sales.invoice i where i.id = 42;
+```
+
+See [chapter 9](09-reference.md#e-mail-from-sql) for every function and its limits. The functions
+work for the **current application** only when the caller runs as that application's database role
+(pages, processes, automations, workflows and background chains do); the SQL Workshop is not an
+application.
+
+### E-mail templates
+
+Shared Components → **E-mail templates** (APEX: Email Templates): a name, a subject, an HTML body
+and a plain text body with `#PLACEHOLDERS#`. In the HTML body `#NAME#` is the value HTML-escaped and
+`#NAME!RAW#` the value as it is (trusted HTML only); in the subject and the plain text the value is
+as it is. Names are case-insensitive; a placeholder without a value stays as written.
+
+```sql
+select meta.send_mail_template('LEAVE_DECIDED',
+         jsonb_build_object('NAME', 'Jane', 'STATUS', 'approved', 'START', '1 Aug 2026'),
+         'jane@example.com');
+```
+
+Templates are exported with the application; mail services, the application's service and the
+mail log belong to the installation and are not.
+
+**HR example.** The template `LEAVE_DECIDED` tells an employee that a leave request was approved or
+rejected: a trigger on `hr.leave_request` queues it when the status changes. The example's mail
+service `DEVELOPMENT_LOG` is of provider *log only*, so nothing leaves the server until an
+administrator gives HR a real service.
+
 ## Approvals and the task list
 
 Approvals (APEX: Task Definitions, the Approvals component and the Unified Task List) let an
@@ -676,8 +883,9 @@ open tasks so they don't linger: `select meta.close_tasks('EXPENSE_APPROVAL', :P
 | `meta.task_events` | View: the history and comments of those tasks |
 
 The task tables themselves are closed to the application's role: rights are checked by these
-functions and views, for every call. pgkiln sends no e-mail; put a task list on the home page, or
-use an automation to remind owners of overdue tasks.
+functions and views, for every call. To tell owners by e-mail, call
+[`meta.send_mail`](#sending-e-mail) from the task definition's SQL or from an automation that
+reminds owners of overdue tasks; or put a task list on the home page.
 
 **Example:** in the HR sample application, a leave request creates a `LEAVE_APPROVAL` task for the
 employee's manager; *My tasks* (page 14) approves or rejects it through `hr.decide_leave`, the same

package/docs/guide/07-dynamic-actions.md

@@ -10,8 +10,8 @@ your own from a static application file.
 
 | Property | Meaning |
 |---|---|
-| `event` | `change` (an item's value changed), `click` (a button was clicked), `load` (the page loaded) or `dialog_closed` (a modal dialog opened from the page was submitted and closed) |
-| `trigger_element` | For `change`: one or more item names, comma separated. For `click`: a button name. For `dialog_closed`: the dialog page numbers, comma separated (empty: any dialog) |
+| `event` | When it runs, see [Events](#events) |
+| `trigger_element` | What it listens to: item names (`change`, `focus`, `blur`, `key_release`), a button name (`click`), region ids or static ids (`after_refresh`, `selection_change`), dialog page numbers (`dialog_closed`; empty: any dialog) or event names (`custom`), comma separated. Empty for `load` and `before_submit` |
 | `condition_type`, `condition_value` | Optional client-side condition on the (first) trigger item's value (for `dialog_closed`: on the dialog's page number): `equals`, `not_equals`, `in_list` (comma-separated values), `is_null`, `is_not_null` |
 | `action` | What to do, see below |
 | `affected_items`, `affected_region_id` | What it acts on |
@@ -23,6 +23,31 @@ your own from a static application file.
 | `authz` | Only for authorized users |
 | `build_option` | Only while the [build option](06-processing.md#build-options) is included |
 
+## Events
+
+| Event | Runs when | Trigger |
+|---|---|---|
+| `change` | An item's value changed | Item names |
+| `click` | A button was clicked | A button name |
+| `load` | The page has loaded | – |
+| `dialog_closed` | A modal dialog opened from the page was submitted and closed ([below](#dialog-closed)) | Dialog page numbers (empty: any) |
+| `focus` / `blur` | An item gets / loses the focus (APEX: Get Focus, Lose Focus) | Item names |
+| `key_release` | A key is released in an item | Item names |
+| `after_refresh` | A region was refreshed (`refresh_region`), loaded lazily or shown for another master row | Region ids or static ids |
+| `selection_change` | Rows are selected in a report with [row selection](04-pages-and-regions.md#row-selection), or another master row in a grid; the condition sees the selected values, colon separated | Region ids or static ids |
+| `before_submit` | The page is about to be submitted; a declined `confirm` keeps the page | – |
+| `custom` | JavaScript raised the event: `pgkiln.trigger('ORDER_SAVED', value)` (APEX: custom events, `apex.event.trigger`) | Event names (case-insensitive) |
+
+**The actions of one event and trigger run one after the other, in sequence order** (APEX: the true
+actions of a dynamic action), each waiting for the one before (a server action for its answer). A
+`confirm` that is declined stops the actions after it, and for `before_submit` the submit too:
+
+| Sequence | Event | Action | Message / items |
+|---|---|---|---|
+| 10 | `click` on `DELETE_ALL` | `confirm` | *Delete every selected row?* |
+| 20 | `click` on `DELETE_ALL` | `execute_sql` | `delete from sales.order_line where id = any(string_to_array(:P5_SELECTED, ':')::int[])` |
+| 30 | `click` on `DELETE_ALL` | `refresh_region` | the order lines |
+
 ## Actions
 
 | Action | Runs in | Effect |
@@ -45,11 +70,44 @@ your own from a static application file.
 | `plugin` | browser | Runs the [dynamic action plug-in](04-pages-and-regions.md#plug-ins-with-their-own-code) named in `code`, with `config` `{"attributes": {…}}` (`&ITEM.` filled in); the function gets the same context as *Execute JavaScript* plus `attributes` |
 | `execute_javascript` | browser | Calls the function named in `code`, which a [static application file](03-builder.md#static-application-files) registered; see [below](#execute-javascript) |
 | `push_subscribe` | browser | Turns on [push notifications](17-mobile.md#push-notifications) on the user's device: the browser asks for permission, then the device is registered. Use it with `click` (browsers ask only after one). `message` is shown when it worked, the browser's reason when not. The app needs push notifications on |
+| `confirm` | browser | Asks `message`; **No stops the actions after it** (and the submit, for `before_submit`) |
+| `close_dialog` | browser | In a modal page: closes it; the page below refreshes, or runs its `dialog_closed` actions (APEX: Close Dialog) |
+| `cancel_dialog` | browser | In a modal page: closes it without refreshing the page below |
+| `clear` | browser | Empties the affected items |
+| `open_region` / `close_region` | browser | Opens or closes a *collapsible* region; another region is shown or hidden |
+| `download` | server | Downloads the file of the [download process](06-processing.md#download) named in `code` (a process of the page, with its authorization and condition), after sending `items_to_submit`; the page stays as it is |
+| `print` | browser | The browser's print dialog |
+| `current_position` | browser | The device's position as `latitude,longitude` (5 decimals) into the first affected item |
+| `share` | browser | The device's share sheet with the page's title, `message` and address; where there is none, the address is copied |
 
 Server-side actions first store `items_to_submit` in session state, run as the application's
 database role like everything else, and check the page's and the dynamic action's authorization.
 The SQL itself never reaches the browser.
 
+## Ajax callbacks
+
+A page process with point **ajax** (APEX: an On Demand process) runs only when JavaScript calls it by
+name, and answers JSON; an application process with point *ajax* can be called from every page (a
+page's own process of that name wins). Only processes of type `sql` answer.
+
+```js
+// in a static application file
+const r = await pgkiln.server.process('ORDER_TOTAL', { items: ['P5_ORDER_ID'], x01: 'EUR' });
+r.data.total;   // the first row of the process's last statement
+r.rows;         // its rows (at most 1000)
+r.items;        // the page and application items it set (also set on the page)
+```
+
+```sql
+-- the process ORDER_TOTAL (point ajax): :X01 … :X10 are the x01 … x10 sent
+select sum(qty * price) as total, :X01 as currency from sales.order_line where order_id = :P5_ORDER_ID::int
+```
+
+`items` is a list of item names (their current values are sent) or `{"P5_ID": "7"}`; only items the
+user may change are set, as on a submit. The process runs as the application's role with its
+authorization, condition and build option; errors come back as `{ "error": "…" }` (the promise
+rejects). The request carries the page's CSRF token and needs page access.
+
 ## Execute JavaScript
 
 APEX's *Execute JavaScript Code* runs code typed into the action. pgkiln's Content-Security-Policy