pgkiln 0.85.0 → 0.86.0

package/db/migrations/155_mail_available.sql

@@ -0,0 +1,23 @@
+-- 155: meta.mail_available() (sprint 166)
+--
+-- A Send E-Mail process (and meta.send_mail) raises an error when the application has
+-- no mail service, which rolls back the whole submit; until now application code had
+-- no way to ask first (meta.mail_caller is internal). meta.mail_available() answers
+-- whether the current application may send e-mail: it is called from application code
+-- (meta.app_id() set), it has an enabled mail service, and that service has a From
+-- address (the application's own or the service's default). Use it as a process's
+-- condition: condition_type sql, condition_expr meta.mail_available(). It says nothing
+-- about other applications and never raises. Found by the App Gallery's Sample Processes.
+
+create function meta.mail_available() returns boolean
+language sql stable security definer set search_path = meta, pg_catalog as $$
+  select meta.app_id() is not null and exists (
+    select 1
+      from meta.mail_service s
+      left join meta.app_mail_service x on x.app_id = meta.app_id() and x.service_id = s.id
+     where s.id = meta.mail_service_for_app(meta.app_id()) and s.enabled
+       and coalesce(x.from_address, nullif(s.settings->>'default_from', '')) is not null)
+$$;
+revoke all on function meta.mail_available() from public;
+grant execute on function meta.mail_available() to public;
+comment on function meta.mail_available() is 'Whether the current application may send e-mail: an enabled mail service with a From address (155)';

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

@@ -104,7 +104,7 @@ 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 |
+| `collapsible` | A standard card whose body can be collapsed by clicking the header; its header buttons stay visible while it is collapsed |
 | `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) |

package/docs/guide/06-processing.md

@@ -113,7 +113,7 @@ Plus: every **required** editable item must have a value.
 | Property | Meaning |
 |---|---|
 | `item_name` | The message is shown next to this item (otherwise at the top of the page) |
-| `message` | The error message |
+| `message` | The error message; (sprint 166) `&ITEM.` substitutions are filled in with the submitted values (`The name &P3_NAME. is taken.`) |
 | `when_button` | Only validate for this request. A `DELETE` request runs only the validations with `when_button` `DELETE` (e.g. "approved requests can't be deleted"), not the item checks |
 | `condition_type`, `condition_expr`, `condition_value` | Only validate when the [server-side condition](#server-side-conditions) holds, e.g. `request_in` `SAVE,CREATE` (sprint 154) |
 | `authz` | Only validate for users the authorization scheme lets through (sprint 155) |
@@ -154,7 +154,7 @@ two combine well; see error handling below.
 | `parent_process` | The name of a `chain` process on the page: this process then runs only inside that chain |
 | `region_id` | The form or grid region, for `form_dml` / `grid_dml` |
 | `config` | Settings of a `data_load`, `invoke_api`, `download`, `chain`, `workflow`, `send_push` or `plugin` process (JSON) |
-| `success_message` | Shown after the redirect; messages of several processes are joined |
+| `success_message` | Shown after the redirect; messages of several processes are joined. (sprint 166) `&ITEM.` substitutions are filled in with the values after the process (`Order &P3_ID. created.`) |
 | `authz` | Skipped when the user isn't authorized |
 | `seq` | Order |
 
@@ -398,6 +398,10 @@ or with an [e-mail template](#e-mail-templates):
 {"to": "&P5_EMAIL.", "template": "ORDER_SHIPPED", "placeholders": {"NAME": "&P5_NAME.", "ORDER_ID": "&P5_ID."}}
 ```
 
+Without a mail service the process raises an error and the submit is rolled back. When the mail is
+optional, give the process the condition `sql` `meta.mail_available()` (sprint 166): it runs only when
+the application has an enabled mail service with a From address.
+
 `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`,
@@ -448,7 +452,7 @@ the process's attributes (`config`), checked when it is saved and again when it
 |---|---|---|---|
 | `close_dialog` | Close Dialog | `{"items": ["P5_ID"]}` | Closes the modal page after the submit (a modal page closes after a submit anyway; this one also hands the items' values to the page below, where items of the same name take them before its [Dialog Closed](07-dynamic-actions.md#dialog-closed) actions run) |
 | `clear_session_state` | Clear Session State | `{"items": ["P3_NAME"], "pages": [3, 4], "all": false}` | Empties the items, every `P<n>_` item of the pages, or all page and application items |
-| `reset_pagination` | Reset Pagination | – | Reports and grids start on their first page after the submit |
+| `reset_pagination` | Reset Pagination | – | An interactive grid saved from a later page starts on its first page again (a report starts on its first page after any submit anyway: its page number is in the URL) |
 | `user_preferences` | User Preferences | `{"action": "set", "preference": "DEFAULT_DEPT", "item": "P1_DEPT"}`, or `"reset"` | Stores (or removes) a [user preference](#user-preferences); nothing for the public user |
 | `server_geocoding` | Server Side Geocoding | `{"address_item": "P3_ADDRESS", "coordinates_item": "P3_LOCATION", "country": "nl"}` | The installation's geocoder (`GEOCODER_URL`); the first place's `lat,lng` goes into the coordinates item |
 | `print_report` | Print Report | `{"document": "EMPLOYEE_SHEET"}` | A [document template](16-files.md#document-templates) or report query, sent as the answer to the submit |

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

@@ -91,7 +91,7 @@ items, in the browser. A tree of departments that filters an employee report, wi
 |---|---|---|
 | `show` / `hide` | browser | Show or hide the affected items/region. **With a condition, the opposite happens when the condition is false**, so one dynamic action gives "show commission only for salesmen". Also applied when the page loads (and already on the server, so there's no flicker) |
 | `enable` / `disable` | browser | Enable or disable the controls, reversed when the condition is false |
-| `set_value` | server | Runs `code` (a SELECT); its first row's columns set the affected items, in order |
+| `set_value` | server | Runs `code` (a SELECT); its first row's columns set the affected items, in order. The affected items must be on the page: a `hidden` item isn't rendered (its value stays on the server, safe from tampering), so set a text or display item, or use a computation |
 | `execute_sql` | server | Runs `code`; returned columns named like items set those items |
 | `refresh_region` | server | Re-renders `affected_region_id` with the current session state (e.g. a report filtered by the changed item) |
 | `refresh_item` | server | Re-renders the affected items (e.g. a list whose LOV depends on another item) |
@@ -119,10 +119,10 @@ items, in the browser. A tree of departments that filters an employee report, wi
 | `wait_popup` | browser | Shows a modal "please wait" popup with `message` (default *Please wait…*) until `remove_wait_popup` or the next page (APEX: Show Wait Popup); [below](#wait-popup) |
 | `remove_wait_popup` | browser | Removes the wait popup (APEX: Remove Wait Popup) |
 | `cancel_event` | browser | Stops the actions after it, and the event's own effect: a button doesn't submit or follow its link, a typed key (`key_down`, `key_press`) stays out of the field, a refresh doesn't happen (APEX: Cancel Event). Sprint 156 |
-| `set_style` | browser | Sets CSS properties on the affected items or region: `{"styles": {"color": "#b42318", "font-weight": "bold"}}` in the attributes (APEX: Set Style). Properties from a fixed list (colours, font, text, border, opacity, visibility, padding, margin, width); values without `url()` or `var()`, checked when saved and again before they reach the page |
+| `set_style` | browser | Sets CSS properties on the affected items (their field: input, select list or text area; (sprint 166) before, the item's wrapper) or region: `{"styles": {"color": "#b42318", "font-weight": "bold"}}` in the attributes (APEX: Set Style). Properties from a fixed list (colours, font, text, border, opacity, visibility, padding, margin, width); values without `url()` or `var()`, checked when saved and again before they reach the page |
 | `collapse_tree` / `expand_tree` | browser | Closes / opens every node of the affected tree region (APEX: Collapse Tree, Expand Tree) |
 | `show_ai_assistant` | browser | Opens the affected AI assistant region (or the inline dialog it sits in) and puts the cursor in its question (APEX: Show AI Assistant) |
-| `trigger_geocoding` | browser | The affected geocoded address item looks its text up, as its *Check address* button does (APEX: Trigger Geocoding) |
+| `trigger_geocoding` | browser | The affected geocoded address item looks its text up, as its *Check address* button does (APEX: Trigger Geocoding); (sprint 166) not when its text is the address just chosen from the list, so a `change` action on the address item itself doesn't reopen it |
 | `open_report_dialog` | browser | Opens a dialog of the affected interactive report: `code` is `filter`, `columns`, `sort`, `highlight`, `compute`, `aggregate`, `chart`, `group`, `pivot`, `break`, `rows` or `saved` (APEX: Invoke Interactive Report Dialog) |
 
 Server-side actions first store `items_to_submit` in session state, run as the application's

package/docs/guide/09-reference.md

@@ -111,6 +111,7 @@ service (an administrator chooses it under Workspace utilities → Mail services
 | `meta.send_mail_template(p_template, p_placeholders jsonb, p_to, p_cc, p_bcc, p_from, p_reply_to)` | The same with an [e-mail template](06-processing.md#e-mail-templates) and its placeholder values (APEX_MAIL.SEND with `p_template_static_id`) |
 | `meta.add_mail_attachment(p_mail_id, p_content bytea, p_filename, p_mime)` | Adds a file to a mail queued **in the same transaction** (APEX_MAIL.ADD_ATTACHMENT); at most 20 files and 20 MB per mail, 10 MB per file |
 | `meta.mail_status(p_mail_id)` | `queued`, `sending`, `sent`, `error` or `cancelled`; NULL for another application's mail |
+| `meta.mail_available()` | (155) Whether the application may send e-mail now: it has an enabled mail service with a From address. Without one, `meta.send_mail` and a Send E-Mail process raise an error (rolling back the submit), so use it as their condition when mail is optional |
 
 The mail is sent by the server **after the transaction commits**. Over the application's limit per
 day `meta.send_mail` raises an error. Application roles can't read the queue; the owner can:

package/docs/guide/12-development.md

@@ -15,6 +15,7 @@ scripts/migrate.ts         migration/seed runner (src/migrate.ts does the work)
 website/                   the website pgkiln.vargar.eu (VitePress): landing page + this guide, synced from docs/ at build time;
                            cd website && npm install && npm run dev; scripts/deploy.sh publishes it (see website/deploy/)
 scripts/screenshots.ts     the README's screenshots in docs/images/ (npm run screenshots, HR example)
+scripts/check-sample.ts    (sprint 166) one App Gallery sample: install, sign in as demo, render every page, report errors (--keep)
 scripts/docker-start.ts    container entry point: checks secrets, migrates (locked), sets role and admin passwords, starts the server
 deploy/                    compose.yaml and .env.example for Docker (Dockerfile at the root; chapter 1)
 bin/pgkiln.js              the `pgkiln` command line (runs src/cli/main.ts with tsx)
@@ -651,6 +652,9 @@ test/
   gallery.test.ts          the App Gallery: every starter and utility created from its review and every sample app installed, with all
                            their pages rendering; sample apps (admins), the search, a failing script leaves nothing
   gallery-samples.ts       the gallery's shipped apps for the tests: SAMPLES (schema and role of each script), BLUEPRINTS, drop/install
+  sample-coverage.test.ts  (sprint 166) every feature in a sample app: each value of the components' catalogues (check constraints
+                           listed in sample-coverage.sql, and meta.condition_ok's condition types) is used by HR or a gallery
+                           sample, or exempted there with a reason
   builder-apex-screens.test.ts sprint 61: sign-in with a workspace, message and banner, utilization, SQL Workshop home, groups, reports
   workspace-isolation.test.ts isolated workspaces (090): logins, RLS on meta, app_id, roles, SQL Workshop, scripts, imports
   ai.test.ts               AI services: Generate text with AI (text, structured outputs, errors, limits, keys), its dynamic action,

package/examples/gallery/README.md

@@ -19,21 +19,38 @@ The builder's **App Gallery** (`/builder/gallery`) lists what `gallery.json` nam
 |---|---|---|
 | `sample-charts.sql` | Sample Charts (`/a/sample-charts`) | the 22 chart types, a page per question, a drill-down to a report |
 | `sample-cards.sql` | Sample Cards | cards with a form, KPI tiles, lists as cards, built-in template components |
-| `sample-calendar.sql` | Sample Calendar | month, week, day and list views, create on click, drag and drop through a function |
-| `sample-grids.sql` | Sample Interactive Grids | an editable grid, select lists, totals, frozen column, row menu, master-detail, views |
-| `sample-dynamic-actions.sql` | Sample Dynamic Actions | show/hide/enable, set value, refresh, messages, wait popup, classes, inline dialog |
+| `sample-calendar.sql` | Sample Calendar | month, week, day and list views, create on click, drag and drop through a function, the calendar's dynamic action events (a chosen day, the view) |
+| `sample-grids.sql` | Sample Interactive Grids | an editable grid, select lists, totals, frozen column, row menu, master-detail, views, a new row's defaults (`grid_row_init`) and a message after saving (`grid_save`) |
+| `sample-dynamic-actions.sql` | Sample Dynamic Actions | show/hide/enable, set value, refresh, messages, wait popup, classes, inline dialog, and every other event (keyboard, mouse, focus, before submit, page unload, resize, scroll, refreshes, a tree, facets) and action (styles, disable, clear, submit, download, print, share, push subscribe, dialogs, trees, report dialogs, the AI assistant) with client-side conditions |
 | `sample-reporting.sql` | Sample Reporting | interactive report, faceted search, smart filters, a classic report with column options |
-| `sample-maps.sql` | Sample Maps | markers and clusters, layers with GeoJSON and a heat map, a map filtering a list by distance, a location item |
-| `sample-approvals.sql` | Sample Approvals | a workflow started by a form, an approval task and the task list, the workflow console (accounts demo and approver) |
+| `sample-maps.sql` | Sample Maps | markers and clusters, layers with GeoJSON and a heat map, a map filtering a list by distance, a location item, the map's events (a clicked marker, the zoom), the current position, geocoding an address and the Display Map item |
+| `sample-approvals.sql` | Sample Approvals | a workflow started by a form, an approval task and the task list, the workflow console and diagram, the notification bell (`send_notification`, `meta.notify`), a navigation menu with badges from SQL and live badges, a `timer` dynamic action (accounts demo and approver) |
+| `sample-validations.sql` | Sample Validations | every validation type and error location, every server-side condition type |
+| `sample-processes.sql` | Sample Processes | every process type, page and application computations, branches, application processes and Ajax callbacks, report queries, shortcuts |
 | `sample-data-loading.sql` | Sample Data Loading | `data_load` processes: by column name and merged, through a data load definition, skipping rows with errors |
 | `sample-files.sql` | Sample Files | a file in the record's columns, several files in a child table, a photo cropped before upload |
-| `ux-patterns.sql` | UX Pattern Catalog | region templates and options, buttons, items and form layouts, content and page patterns |
+| `ux-patterns.sql` | UX Pattern Catalog | region templates and options, buttons and every button position, items (autocomplete, image upload, multiselect, percent graph, URL) and form layouts, content and page patterns, display positions, the minimal and right-side-column page templates, URL and sign-in regions |
 
 Each script creates its own schema (`sample_charts`, …), a role (`app_sample_charts`, …) granted to the runtime, the
 application and one account, **demo** / **demo**. Without the builder:
 `psql "$DATABASE_URL" -1 -f examples/gallery/samples/sample-charts.sql`. To remove one, delete the application in the
 App Builder, then `drop schema sample_charts cascade; drop role app_sample_charts;`.
 
+## Every feature in a sample app
+
+Every catalogued value of the application components (region, item, process, validation and
+computation types, dynamic action events, actions and conditions, server-side condition types,
+button positions, page templates, …) is used by HR or one of these samples: `test/sample-coverage.test.ts`
+fails for a value nobody uses, unless it is exempted there with the reason it can't be shown (an
+authentication scheme that needs an outside service). `test/gallery.test.ts` installs each sample and
+renders every page as its demo account, so what a sample shows also works. A new feature therefore
+comes with a sample that uses it. While you write one:
+
+```bash
+npx tsx scripts/check-sample.ts examples/gallery/samples/sample-processes.sql   # install, render every page, remove
+npx tsx scripts/check-sample.ts examples/gallery/samples/sample-processes.sql --keep   # and leave it installed
+```
+
 A sample script follows the pattern of the HR example: plain SQL that inserts `meta.*` rows, using
 `meta.generate_page()` for wizard-made pages and two temporary helpers (`pg_temp.page_id`, `pg_temp.region_id`).
 Every page starts with a text that says how it is made.

package/examples/gallery/gallery.json

@@ -20,6 +20,10 @@
      "description": "Maps of Dutch museums without PostGIS: markers with popups and clustering, several layers (a route and an area as GeoJSON, a heat map you switch on), a map that filters the list beside it by distance, and a form with a location item. Demo account demo / demo."},
     {"key": "sample-approvals", "title": "Sample Approvals", "alias": "sample-approvals", "icon": "list-checks", "file": "samples/sample-approvals.sql",
      "description": "Purchase requests that start a workflow: approved by itself below 1,000, otherwise an approval task for the role approver, decided under My tasks; the workflow console with its diagram and history. Demo accounts demo / demo (asks) and approver / approver (decides)."},
+    {"key": "sample-validations", "title": "Sample Validations", "alias": "sample-validations", "icon": "shield", "file": "samples/sample-validations.sql",
+     "description": "Every validation type with its error shown next to the field, at the top or both, and every server-side condition type deciding whether a region, item, button or process is there, each page saying which one it shows. Demo account demo / demo."},
+    {"key": "sample-processes", "title": "Sample Processes", "alias": "sample-processes", "icon": "settings", "file": "samples/sample-processes.sql",
+     "description": "What runs when a page is shown and submitted: every process type, page and application computations, branches, application processes and Ajax callbacks, report queries in six formats and shortcuts, each page saying how it is made. Demo account demo / demo."},
     {"key": "sample-data-loading", "title": "Sample Data Loading", "alias": "sample-data-loading", "icon": "file-up", "file": "samples/sample-data-loading.sql",
      "description": "Loading CSV, Excel and JSON files into a table from a page: merged by the key, through a data load definition that maps other headings and a date format, and skipping rows with errors. Example files to download included. Demo account demo / demo."},
     {"key": "sample-files", "title": "Sample Files", "alias": "sample-files", "icon": "files", "file": "samples/sample-files.sql",

package/examples/gallery/samples/sample-approvals.sql

@@ -7,7 +7,18 @@
 --   * from 1,000 it asks for approval: a PURCHASE_APPROVAL task for the
 --     users with the role approver, decided under My tasks; the task's
 --     action records the decision on the request
---   * the console lists the workflows with their diagram and history
+--   * the console lists the workflows with their diagram and history; the
+--     request's form draws its workflow (a workflow_diagram region)
+--   * on the request's form the approver claims or releases the task, and
+--     who asked can ask again after a rejection (the declarative process
+--     types human_task_manage and human_task_create)
+--   * the notification bell: a request of 1,000 or more notifies the
+--     approver (a send_notification process), a decision notifies who asked
+--     (meta.notify in the decision); opening one goes to the request
+--   * the navigation menu is a list whose entries have badges from SQL
+--     (your pending requests, the tasks waiting for you), refreshed every
+--     15 seconds by the live badges; a timer dynamic action refreshes
+--     "Waiting for me"
 --
 -- Two accounts: demo / demo asks, approver / approver decides (nobody
 -- approves their own request).
@@ -50,11 +61,25 @@ create trigger purchase_defaults before insert on sample_approvals.purchase
 -- the decision, from the approval task's action (by the approver) or the workflow's SQL step
 -- (which runs as the user who started the workflow, so it says who decided: 'workflow')
 create function sample_approvals.decide(p_id int, p_outcome text, p_note text, p_by text default null) returns void language plpgsql as $$
+declare
+  p sample_approvals.purchase;
 begin
   update sample_approvals.purchase
      set status = case lower(p_outcome) when 'approved' then 'APPROVED' when 'rejected' then 'REJECTED' else status end,
          decided_by = coalesce(p_by, meta.app_user()), note = nullif(p_note, '')
-   where id = p_id and status = 'PENDING';
+   where id = p_id and status = 'PENDING'
+  returning * into p;
+  -- the bell of who asked: the decision, opening the request (page 3); a notification
+  -- that can't be added (notifications turned off) never stops the decision
+  if p.status in ('APPROVED', 'REJECTED') and p.requested_by is not null and meta.app_id() is not null then
+    begin
+      perform meta.notify(p.requested_by, format('Purchase %s: %s', lower(p.status), p.title),
+                          coalesce(p.note, format('Decided by %s', p.decided_by)),
+                          3, jsonb_build_object('P3_ID', p.id), case p.status when 'APPROVED' then 'check' else 'x' end);
+    exception when others then
+      raise warning 'sample_approvals.decide: no notification: %', sqlerrm;
+    end;
+  end if;
 end
 $$;
 
@@ -73,8 +98,8 @@ grant select, insert, update, delete on sample_approvals.purchase to app_sample_
 grant execute on function sample_approvals.decide(int, text, text, text) to app_sample_approvals;
 
 -- 3. The application ----------------------------------------------------------
-insert into meta.app (alias, name, home_page, authentication, db_role)
-values ('sample-approvals', 'Sample Approvals', 1, 'app_users', 'app_sample_approvals');
+insert into meta.app (alias, name, home_page, authentication, db_role, notifications, live_badges_s, nav_list)
+values ('sample-approvals', 'Sample Approvals', 1, 'app_users', 'app_sample_approvals', true, 15, 'APPROVAL_MENU');
 
 insert into meta.app_user (app_id, username, password_hash, roles)
 select a.id, u.name, meta.hash_password(u.name), u.roles
@@ -116,13 +141,29 @@ insert into meta.process (page_id, seq, name, type, code, when_button)
 select pg_temp.page_id('sample-approvals', 3), 15, 'Start the approval', 'sql',
        $c$select meta.start_workflow('PURCHASE', :P3_ID, jsonb_build_object('TITLE', :P3_TITLE, 'AMOUNT', :P3_AMOUNT))$c$, 'CREATE';
 
-insert into meta.nav_entry (app_id, seq, label, icon, target_page)
-select a.id, n.seq, n.label, n.icon, n.page
-  from meta.app a, (values (10, 'Home', 'home', 1), (20, 'Purchases', 'list', 2), (30, 'My tasks', 'check', 4), (40, 'Workflows', 'route', 5)) as n (seq, label, icon, page)
- where a.alias = 'sample-approvals';
+-- from 1,000 the approver gets a notification on the bell (the declarative process type
+-- send_notification; an application with several approvers would call meta.notify for each)
+insert into meta.process (page_id, seq, name, type, when_button, condition_type, condition_expr, config)
+select pg_temp.page_id('sample-approvals', 3), 16, 'Tell the approver', 'send_notification', 'CREATE',
+       'sql', ':P3_AMOUNT::numeric >= 1000',
+       '{"to": "approver", "title": "Purchase to approve: &P3_TITLE.", "body": "&P3_AMOUNT. from &P3_SUPPLIER., asked by &APP_USER.", "page": 4, "icon": "check"}'::jsonb;
 
 insert into meta.list (app_id, name, type, description)
-select id, 'APPROVAL_TOPICS', 'static', 'The pages of Sample Approvals' from meta.app where alias = 'sample-approvals';
+select id, l.name, 'static', l.description from meta.app, (values
+  ('APPROVAL_TOPICS', 'The pages of Sample Approvals'),
+  ('APPROVAL_MENU', 'The navigation menu, with badges from SQL')) as l (name, description)
+ where alias = 'sample-approvals';
+
+-- the navigation menu (app.nav_list): badges from SQL, refreshed by the live badges
+insert into meta.list_entry (app_id, list_name, seq, label, icon, target_page, badge_query)
+select a.id, 'APPROVAL_MENU', e.seq, e.label, e.icon, e.page, e.badge_query
+  from meta.app a, (values
+  (10, 'Home', 'home', 1, null),
+  (20, 'Purchases', 'list', 2, 'select nullif(count(*), 0) from sample_approvals.purchase where status = ''PENDING'' and requested_by = meta.app_user()'),
+  (30, 'My tasks', 'check', 4, 'select nullif(count(*), 0) from meta.tasks where app_id = meta.app_id() and may_act and state in (''unassigned'', ''assigned'')'),
+  (40, 'Workflows', 'route', 5, null)
+  ) as e (seq, label, icon, page, badge_query)
+ where a.alias = 'sample-approvals';
 
 insert into meta.list_entry (app_id, list_name, seq, label, icon, target_page, description)
 select a.id, 'APPROVAL_TOPICS', e.seq, e.label, e.icon, e.page, e.description
@@ -137,11 +178,11 @@ insert into meta.region (page_id, seq, title, type, columns, template, source, c
 select pg_temp.page_id('sample-approvals', r.page), r.seq, r.title, r.type, 12, r.template, r.source, r.config::jsonb
   from (values
   (1, 10, 'Sample Approvals', 'static', 'hero',
-   '<p>Signed in as <strong>demo</strong>, ask for a purchase under <em>Purchases</em>. Below 1,000 the workflow approves it at once; from 1,000 it creates an approval task for the role <code>approver</code>. Sign in as <strong>approver</strong> / approver and decide under <em>My tasks</em>: the task''s action writes the decision on the request, and the workflow ends.</p>',
+   '<p>Signed in as <strong>demo</strong>, ask for a purchase under <em>Purchases</em>. Below 1,000 the workflow approves it at once; from 1,000 it creates an approval task for the role <code>approver</code>. Sign in as <strong>approver</strong> / approver and decide under <em>My tasks</em>: the task''s action writes the decision on the request, and the workflow ends.</p><p>The bell in the header shows notifications: the approver gets one for each request of 1,000 or more (a <code>send_notification</code> process), and who asked gets the decision (<code>meta.notify</code>). The menu''s badges come from SQL and refresh every 15 seconds without a reload: keep both accounts open in two browsers and watch them change.</p>',
    '{"icon": "check"}'),
   (1, 20, 'Topics', 'list', 'plain', null, '{"list": "APPROVAL_TOPICS", "template": "cards"}'),
   (2, 5, 'About this page', 'static', 'plain',
-   '<p class="lead">The form''s Create button runs the wizard''s row process, then <code>select meta.start_workflow(''PURCHASE'', :P3_ID, …)</code>. A trigger fills in who asked and the status from the session, so the form can''t set them.</p>', '{}'),
+   '<p class="lead">The form''s Create button runs the wizard''s row process, then <code>select meta.start_workflow(''PURCHASE'', :P3_ID, …)</code>. A trigger fills in who asked and the status from the session, so the form can''t set them.</p><p>Open a request: below the form a <code>workflow_diagram</code> region draws its workflow, the steps it went through and where it is now. While its approval task is open, the approver gets <strong>Claim task</strong> (and then <strong>Release task</strong>): processes of type <code>human_task_manage</code>. After a rejection, who asked gets <strong>Ask again</strong>: the request, changed or not, is pending again and a process of type <code>human_task_create</code> creates a new <code>PURCHASE_APPROVAL</code> task, outside the workflow, which has ended.</p>', '{}'),
   (4, 5, 'About this page', 'static', 'plain',
    '<p class="lead">Regions of type <code>tasks</code>: what waits for the signed-in user (as owner, here the role <code>approver</code>), and what they asked for. Approve and Reject run the task definition''s action with <code>:DETAIL_PK</code>, <code>:OUTCOME</code> and <code>:COMMENT</code>.</p>', '{}'),
   (4, 10, 'Waiting for me', 'tasks', 'standard', null, '{"empty": "Nothing waits for you. Sign in as approver to decide on requests of 1,000 or more."}'),
@@ -151,3 +192,53 @@ select pg_temp.page_id('sample-approvals', r.page), r.seq, r.title, r.type, 12,
   (5, 10, 'Workflows I started', 'workflows', 'standard', null, '{"completed": true}'),
   (5, 20, 'All purchase workflows (approvers)', 'workflows', 'collapsible', null, '{"context": "admin", "completed": true}')
   ) as r (page, seq, title, type, template, source, config);
+
+-- a timer dynamic action: "Waiting for me" refreshes every 30 seconds while the page is visible
+insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, action, affected_region_id)
+select pg_temp.page_id('sample-approvals', 4), 10, 'Refresh what waits', 'timer', '30', 'refresh_region', r.id
+  from meta.region r where r.page_id = pg_temp.page_id('sample-approvals', 4) and r.title = 'Waiting for me';
+
+-- page 3, the request's form (also the task's details page): its open approval task and its workflow,
+-- computed when the page is shown
+insert into meta.item (page_id, region_id, seq, name, type)
+select r.page_id, r.id, i.seq, i.name, 'hidden'
+  from meta.region r, (values (200, 'P3_TASK_ID'), (210, 'P3_WORKFLOW_ID')) as i (seq, name)
+ where r.page_id = pg_temp.page_id('sample-approvals', 3) and r.type = 'form';
+
+insert into meta.computation (page_id, seq, item_name, point, type, expression)
+values
+  (pg_temp.page_id('sample-approvals', 3), 10, 'P3_TASK_ID', 'before_header', 'sql_query',
+   $q$select id::text from meta.tasks where app_id = meta.app_id() and definition = 'PURCHASE_APPROVAL' and detail_pk = :P3_ID and state in ('unassigned', 'assigned') order by id desc limit 1$q$),
+  (pg_temp.page_id('sample-approvals', 3), 20, 'P3_WORKFLOW_ID', 'before_header', 'sql_query',
+   $q$select id::text from meta.workflows where app_id = meta.app_id() and name = 'PURCHASE' and detail_pk = :P3_ID order by id desc limit 1$q$);
+
+-- the workflow of the request: a Workflow Diagram region (shown to who started it and its administrators)
+insert into meta.region (page_id, seq, title, type, columns, template, config, condition_type, condition)
+values (pg_temp.page_id('sample-approvals', 3), 20, 'Its workflow', 'workflow_diagram', 12, 'standard',
+        '{"instance_item": "P3_WORKFLOW_ID", "empty": "You can''t see this request''s workflow: only who asked and the approvers can."}',
+        'item_not_null', 'P3_WORKFLOW_ID');
+
+-- the open task: Claim (a potential owner, while nobody has it) and Release (its owner);
+-- after a rejection who asked can Ask again: the request (as changed on the form) pending again, and a new approval task
+insert into meta.button (page_id, region_id, seq, name, label, action, condition_type, condition)
+select r.page_id, r.id, b.seq, b.name, b.label, 'submit', 'exists', b.cond
+  from meta.region r, (values
+  (50, 'CLAIM', 'Claim task', $c$select 1 from meta.tasks where id = nullif(:P3_TASK_ID, '')::bigint and may_claim$c$),
+  (60, 'RELEASE', 'Release task', $c$select 1 from meta.tasks where id = nullif(:P3_TASK_ID, '')::bigint and may_release$c$),
+  (70, 'ASK_AGAIN', 'Ask again', $c$select 1 from sample_approvals.purchase where id = :P3_ID::int and status = 'REJECTED' and requested_by = meta.app_user()$c$)
+  ) as b (seq, name, label, cond)
+ where r.page_id = pg_temp.page_id('sample-approvals', 3) and r.type = 'form';
+
+insert into meta.process (page_id, seq, name, type, code, when_button, config, success_message)
+values
+  (pg_temp.page_id('sample-approvals', 3), 30, 'Claim the task', 'human_task_manage', null, 'CLAIM',
+   '{"action": "claim", "task": "&P3_TASK_ID."}', 'The task is yours: approve or reject it under My tasks.'),
+  (pg_temp.page_id('sample-approvals', 3), 40, 'Release the task', 'human_task_manage', null, 'RELEASE',
+   '{"action": "release", "task": "&P3_TASK_ID.", "comment": "Released from the request''s page"}', 'The task is back with every approver.'),
+  (pg_temp.page_id('sample-approvals', 3), 50, 'Pending again', 'sql',
+   $c$update sample_approvals.purchase
+   set title = :P3_TITLE, supplier = :P3_SUPPLIER, amount = :P3_AMOUNT::numeric, status = 'PENDING', decided_by = null, note = null
+ where id = :P3_ID::int and status = 'REJECTED' and requested_by = meta.app_user()$c$, 'ASK_AGAIN', '{}', null),
+  (pg_temp.page_id('sample-approvals', 3), 51, 'Ask for approval again', 'human_task_create', null, 'ASK_AGAIN',
+   '{"definition": "PURCHASE_APPROVAL", "detail_pk": "&P3_ID.", "parameters": {"TITLE": "&P3_TITLE.", "AMOUNT": "&P3_AMOUNT."}, "id_item": "P3_TASK_ID"}',
+   'Asked again: the approvers have a new task.');

package/examples/gallery/samples/sample-calendar.sql

@@ -3,7 +3,8 @@
 --
 -- The calendar region: month, week, day and list views, all-day and timed
 -- events, events over several days, create on click, drag and drop through
--- a PL/pgSQL function with its own rule, and a calendar filtered by an item.
+-- a PL/pgSQL function with its own rule, a calendar filtered by an item, and
+-- dynamic actions on a day chosen and on another view.
 -- The events are placed around today, so there is always something to see.
 --
 -- Installed by an administrator from the App Gallery, or with
@@ -79,7 +80,7 @@ select id, 'demo', meta.hash_password('demo'), '{}' from meta.app where alias =
 insert into meta.page (app_id, page_no, name, title, parent_page)
 select a.id, p.no, p.name, p.name, p.parent
   from meta.app a, (values
-  (1, 'Sample Calendar', null), (2, 'Month', 1), (4, 'Week planner', 1), (5, 'Agenda', 1), (6, 'By category', 1)
+  (1, 'Sample Calendar', null), (2, 'Month', 1), (4, 'Week planner', 1), (5, 'Agenda', 1), (6, 'By category', 1), (7, 'Calendar events', 1)
   ) as p (no, name, parent)
  where a.alias = 'sample-calendar';
 
@@ -96,7 +97,7 @@ insert into meta.nav_entry (app_id, seq, label, icon, target_page)
 select a.id, n.seq, n.label, n.icon, n.page
   from meta.app a, (values
   (10, 'Home', 'home', 1), (20, 'Month', 'calendar', 2), (30, 'Week planner', 'clock', 4),
-  (40, 'Agenda', 'list', 5), (50, 'By category', 'filter', 6)
+  (40, 'Agenda', 'list', 5), (50, 'By category', 'filter', 6), (60, 'Calendar events', 'bolt', 7)
   ) as n (seq, label, icon, page)
  where a.alias = 'sample-calendar';
 
@@ -109,7 +110,8 @@ select a.id, 'CALENDAR_TOPICS', e.seq, e.label, e.icon, e.page, e.description
   (10, 'Month', 'calendar', 2, 'All four views; click a day to add an event, drag an event to move it.'),
   (20, 'Week planner', 'clock', 4, 'Week and day views from 7:00 to 19:00, opened on the week.'),
   (30, 'Agenda', 'list', 5, 'The list view only: a month of events per day.'),
-  (40, 'By category', 'filter', 6, 'A calendar whose query uses a page item, refreshed when it changes.')
+  (40, 'By category', 'filter', 6, 'A calendar whose query uses a page item, refreshed when it changes.'),
+  (50, 'Calendar events', 'bolt', 7, 'Dynamic actions on the calendar''s own events: a day chosen, another view or period.')
   ) as e (seq, label, icon, page, description)
  where a.alias = 'sample-calendar';
 
@@ -159,7 +161,19 @@ select pg_temp.page_id('sample-calendar', r.page), r.seq, r.title, r.type, r.col
   (6, 10, 'Filter', 'static', 12, 'standard', null, '{}', 'filter'),
   (6, 20, 'Events of the category', 'calendar', 12, 'standard',
    E'select starts as start_date, ends as end_date, title, id\n  from sample_calendar.event\n where :P6_CATEGORY is null or category = :P6_CATEGORY',
-   '{"views": ["month", "list"], "link": {"page": 3, "items": {"P3_ID": "#id#"}}}', 'category-calendar')
+   '{"views": ["month", "list"], "link": {"page": 3, "items": {"P3_ID": "#id#"}}}', 'category-calendar'),
+
+  -- 7 Calendar events
+  (7, 5, 'About this page', 'static', 12, 'plain',
+   '<p class="lead">Dynamic actions can listen to the calendar itself (the trigger is its static id <code>planner</code>). <strong>Date Select</strong> (<code>calendar_date_select</code>) runs when you click an empty day or hour: a <em>Set Value</em> without SQL puts the chosen date into <code>P7_DAY</code> and the report beside it is refreshed with that day''s events. This calendar has no <code>create</code> link, so a click only chooses (with one, a <em>Cancel Event</em> on this event would keep the form closed). <strong>View Change</strong> (<code>calendar_view_change</code>) runs on the page that comes back from another view or period: the view (<code>month</code>, <code>week</code>, <code>day</code> or <code>list</code>) goes into <code>P7_VIEW</code>, and the day view adds a hint.</p>',
+   '{}', null),
+  (7, 10, 'Planner', 'calendar', 8, 'standard',
+   E'select starts as start_date, ends as end_date, title, id\n  from sample_calendar.event',
+   '{"views": ["month", "week", "day", "list"], "link": {"page": 3, "items": {"P3_ID": "#id#"}}}', 'planner'),
+  (7, 20, 'Chosen day', 'static', 4, 'standard', null, '{}', 'chosen'),
+  (7, 30, 'Events of the day', 'classic_report', 4, 'standard',
+   E'select to_char(starts, ''HH24:MI'') as "Time", title as "Event", category as "Category"\n  from sample_calendar.event\n where :P7_DAY is not null\n   and starts::date <= left(:P7_DAY, 10)::date and coalesce(ends, starts)::date >= left(:P7_DAY, 10)::date\n order by starts',
+   '{"empty": "Click a day in the calendar."}', 'day-events')
   ) as r (page, seq, title, type, cols, template, source, config, sid);
 
 insert into meta.item (page_id, region_id, seq, name, label, type, lov, config)
@@ -170,3 +184,24 @@ select pg_temp.page_id('sample-calendar', 6), r.id, 10, 'P6_CATEGORY', 'Category
 insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, action, affected_region_id, items_to_submit)
 select pg_temp.page_id('sample-calendar', 6), 10, 'Refresh the calendar', 'change', 'P6_CATEGORY', 'refresh_region', r.id, 'P6_CATEGORY'
   from meta.region r where r.page_id = pg_temp.page_id('sample-calendar', 6) and r.static_id = 'category-calendar';
+
+-- page 7: dynamic actions on the calendar's own events (trigger: its static id)
+insert into meta.item (page_id, region_id, seq, name, label, type, help, config)
+select pg_temp.page_id('sample-calendar', 7), r.id, i.seq, i.name, i.label, i.type, i.help, '{"warn_unsaved": false}'
+  from meta.region r, (values
+  (10, 'P7_DAY', 'Chosen day', 'text', 'Set by the calendar_date_select dynamic action: YYYY-MM-DD, or YYYY-MM-DDTHH:MM for an hour.'),
+  (20, 'P7_VIEW', 'Calendar view', 'display', 'Set by the calendar_view_change dynamic action.')
+  ) as i (seq, name, label, type, help)
+ where r.page_id = pg_temp.page_id('sample-calendar', 7) and r.static_id = 'chosen';
+
+insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, condition_type, condition_value, action,
+                                 affected_items, affected_region_id, items_to_submit, message)
+select pg_temp.page_id('sample-calendar', 7), d.seq, d.name, d.event, 'planner', d.ctype, d.cvalue, d.action, d.items,
+       (select id from meta.region where page_id = pg_temp.page_id('sample-calendar', 7) and static_id = d.region), d.submit, d.message
+  from (values
+  (10, 'The chosen day into P7_DAY', 'calendar_date_select', null, null, 'set_value', 'P7_DAY', null, null, null),
+  (20, 'Its events', 'calendar_date_select', null, null, 'refresh_region', null, 'day-events', 'P7_DAY', null),
+  (40, 'The view into P7_VIEW', 'calendar_view_change', null, null, 'set_value', 'P7_VIEW', null, null, null),
+  (50, 'A hint for the day view', 'calendar_view_change', 'equals', 'day', 'show_success', null, null, null,
+   'The day view: click an hour to see the events of that day.')
+  ) as d (seq, name, event, ctype, cvalue, action, items, region, submit, message);