Portal screens and actions

The engine’s reference portal covers the work every partner does. A site can go further without writing Go: it can move and trim its portal, add screens (pages with data the engine reads for the partner’s own organisation) and actions (forms that write a document of the organisation or its custom fields), and restyle every template. Or it can switch the screens off and build its own portal on the member API.

All of this lives in one file per site, config/sites/<site>/portal.yaml, beside templates under the site’s template chain.

A screen and an actionCopy Anchor Link

path: /partners
hide: [events]
screens:
  - key: overview
    path: /organisations/{org}/overview
    template: overview.html
    title: { en-GB: Overview }
    nav: { group: business, order: 10 }
    can: listing.update
    data:
      listings: { documents: { type: listing, states: [draft, published], sort: -updatedAt, limit: 5 } }
      figures: { report: { range: last_month } }
      membership: { membership: {} }
      waiting: { pending: { limit: 5 } }
      nearby: { published: { type: listing, near: $org.listing, within: 2km, sort: distance, limit: 6 } }
actions:
  - key: preferences.update
    label: { en-GB: Update your preferences }
    can: organisation.update
    target:
      organisation: { fields: [custom.preferredContactTime, custom.coachParking] }
    rate_limit: 20/hour/person
    respond: { redirect: { screen: overview } }

{% extends "_layout.html" %}
{% block title %}{{ screen.title }}{% endblock %}
{% block main %}
<h1>{{ screen.title }}</h1>
<ul>
  {% for l in data.listings.items %}<li>{% if l.href %}<a href="{{ l.href|url }}">{{ l.title }}</a>{% else %}{{ l.title }}{% endif %}</li>{% endfor %}
</ul>
{% set f = portal_form('preferences.update') %}
<form {{ f.attrs }}>
  {{ f.hidden }}
  {% for field in f.fields %}{{ field_widget(field, f.errors) }}{% endfor %}
  <p><button class="p-button" type="submit">{{ f.label }}</button></p>
</form>
{% endblock %}

The action writes custom fields declared in config/crm/organisation.yaml (see CRM). The template extends _layout.html, the portal’s layout, which engine-dmo portal scaffold --site main copies into templates/main/portal/ (see Restyling the portal).

Then:

engine-dmo check --fix --project .
engine-dmo portal check --project .

check --fix writes the screen’s scr_ id and the action’s act_ id. engine-dmo dev portal screen add and engine-dmo dev portal action add write the same entries from flags, with --scaffold writing a starting template for a screen.

Per-site portalsCopy Anchor Link

config/sites/<site>/portal.yaml is laid over the install’s config/portal/portal.yaml. Anything it leaves out keeps the install’s value.

The report rules and invitation timings stay install-wide. A link the engine builds to a hidden screen (in the portal, in mail, in the admin) is never made.

ScreensCopy Anchor Link

A screen is a page under the portal path, rendered from a template under the site’s portal template directory, with declared data the engine reads for the person’s active organisation. Templates never query; the data is a closed set of sources, each scoped in the database to the organisation, the person’s role and the site’s network.

A screen keyed as a reference screen (organisation, report, people and so on) replaces that screen’s template and nothing else: it takes only key and template, keeps the reference screen’s path, permission and context, and cannot replace a hidden screen.

Data sourcesCopy Anchor Link

Each entry under data: is <name>: { <source>: { <parameters> } }, and the template reads it as data.<name>. A list source gives { denied, items, count }; when the person’s role lacks a source’s extra permission, denied is true and items is empty.

Every source except published without near reads the active organisation, so the screen’s path needs {org} or {id}; check says so at the line.

The screen template’s contextCopy Anchor Link

t() reads the site’s string catalogue first and then the portal’s own strings; portal check warns about a key in neither.

ActionsCopy Anchor Link

An action is a form the portal posts to {portal path}/actions/<key> (with ?id= for a document it edits, ?org= otherwise). It writes declared fields of one target, and it is refused unless the person’s role grants its permission and the organisation’s tier is one the action allows; both are decided in the database.

Targets:

A document action’s fields are also held to the tier’s member_editable rule: a field no tier the action allows may edit is warned about at load, and a save keeps only what the tier’s rule allows.

A document action from the reference example, which lets silver and gold businesses add offers:

actions:
  - key: offer.create
    label: { en-GB: Add an offer }
    can: listing.update
    tiers: { min: silver }
    target:
      document: { type: offer, create: true }
    fields: [title, summary, validUntil, bookingEmail, heroImage]
    approval: tier
    rate_limit: 20/hour/person
    respond: { redirect: { screen: offers } }

Rendering an action’s formCopy Anchor Link

portal_form('<key>') (or portal_form('<key>', id) for a document it edits) returns the form for the active organisation. It is a template error when the site has no such action or the person may not use it, so a screen never shows a form that would be refused; wrap it in a check of the person’s permission when a screen is open to people who cannot use the action.

The reference organisation screen lists every action the person’s role and tier allow that needs no document (actions in its context).

Restyling the portalCopy Anchor Link

The engine renders its own templates until a file of the same name exists in the site’s portal template directory, templates/<root>/<template_dir>/ along the site’s template chain. Copy the reference portal there to start:

engine-dmo portal scaffold --site main

This writes about forty files (screens, the _layout.html they extend, the claim flow and components/) into the site’s first template root, such as templates/main/portal/. Existing files are left alone unless you pass --force. Always pass --site. Without it the files go to templates/portal/, which is on no site’s template chain unless one of your roots is named portal, so none of them is ever rendered; check then warns that nothing in the folder renders. If that happened, delete templates/portal/ and run the command again with --site. To share one restyled portal between sites, pass --out templates/_shared/portal.

Then edit what you need and delete what you do not: a template you delete falls back to the engine’s.

The portal’s strings are the engine’s own catalogue; a project overrides one by adding the same key to config/strings/<locale>.yaml.

The member APICopy Anchor Link

The member API serves the same data and the same rules as the portal as JSON, for a portal built with another toolchain. It is on when server.api.member.enabled is true (the default) and the site’s portal mode is api or both.

engine-dmo api member routes          # every operation and whether this project serves it
engine-dmo api member openapi         # the OpenAPI 3.1 document
engine-dmo api member form --listing <id> --person <id>   # the form a given member would receive

Declared screens and actions are portal features; the member API does not expose them, and event submission has no API operation yet.

TroubleshootingCopy Anchor Link