App Templates & App Editor

Part of the IP4CMS portal. ← All module guides

What it's for — App Templates & the App Editor are where you design the member/resident-facing PWA apps (and the equivalent customer and supplier apps). You control the home-screen tiles people tap, the navigation (bottom tabs and hamburger menu), and which banners appear — without writing code or rebuilding the app. Each public-facing domain is backed by an app template: a reusable blueprint of tiles, navigation and banners. Templates are often shared — a central/core app template (such as the standard DCApp member app) is assigned to many tenant domains, so each tenant edits its own copy while inherited items stay in sync with the core. At runtime the published app identifies itself by sending its template's id in the x-app-template-id header, and the portal serves back exactly the tiles, navigation and branding you configured here.

Where to find it — Left navigation: Settings → App Editor. Route: /app/settings/app-editor. The list shows every editable app (one row per domain that has an app template assigned). Click a row, or Edit, to open the full-screen App Editor for that app at /app/settings/app-editor/{domainConfigId}. The same editor is reachable from Settings → Domains when you open a domain's app configuration.

Before you start

• Licence modules. The App Editor itself requires public_portals:app_editor. If it's not enabled, the page shows "The App Configuration module is not enabled for this tenant." The parent public_portals module enables the public-portal/app concept. Which app types you can build depends on the per-audience modules:
• public_portals:member — Member Portal apps (residents).
• public_portals:customer — Customer Portal apps.
• public_portals:supplier — Supplier Portal apps.
• A domain must already exist. An app only appears in the App Editor list if a domain (Settings → Domains) has an app template assigned to it (app_template_id) and a matching domain config record. Domains without a template are skipped. Create/assign the domain first.
• Permissions. You need the App Editor / domain-config management permission for your role. Editing of inherited (core) items may be further restricted by the template's group permissions — see Permissions & access.
• Branding (logo, colours, app name) is set once in Settings → General → Branding and flows into every app for the tenant — see How the data connects.

Key tasks

Open an app and read its overview

1. Go to Settings → App Editor. The grid lists each app with its Domain, Assigned App (the template name), Domain Type (Member / Customer / Supplier / Partner), Status and Last Accessed. Primary domains sort to the top.
2. Click the row to open the full-screen editor. It has five tabs: Overview, Configuration, Tiles, Navigation, Banners.
3. The Overview tab is read-only and shows what this app is wired to: Domain, App Type, Platform Scope, template Status, Configured Items (tile / banner counts), the Assigned Template Id, the Tenant Version, and the template Description. Use it to confirm you're editing the right app before changing anything.

Inherited-template note: if this domain is editing an assigned core template, the Overview explains that core (inherited) tiles and banners can only be overridden, reordered, or hidden here — you can't delete them. Items you add yourself are fully editable.

Configure the app tiles (the home screen)

The Tiles tab is a drag-and-drop Tiles Configurator with three buckets:

• Available Tiles — created but not yet placed.
• Main Tiles — the home page. The app uses a fixed 4-column grid; each tile sets a column span (how many of the 4 columns it occupies).
• More categories — named groups that appear under the app's "More" area; create a category, then drop tiles into it.

To add or edit a tile:

1. On the Tiles tab click Add Tile (or the edit icon on an existing tile). Inherited core tiles can be edited within the limits the template allows.
2. Set the tile fields:

• Display name / heading — the label shown on the tile.
• Open method — what happens on tap: modules (jump to a built-in app module — pick the module from the module options, e.g. Documents, Support, Payments), eform (open a chosen e-form / flow), app (deep-link to another app via Android/iOS URI + app id), or browser (open a URL). When you pick a module, the name/icon can autofill from that module.
• Visual type — icon (a module/glyph icon) or thumbnail (upload your own image). Use Upload to attach tile artwork; a preview is shown.
• Location — home, more, or unassigned (this mirrors which bucket it sits in).
• Column span / width — how many of the 4 grid columns it takes on the home page.
• Status — active or disabled (disabled tiles are hidden in the live app without being deleted).
• Optional action config (e.g. contact-group targeting for a support/contact tile).

1. Arrange by dragging tiles between Available, Main and More categories, or use the Up / Down buttons to reorder within a bucket. The layout you set (which tile is where, in what order) is what the live app renders.
2. Duplicate a tile to clone its settings as a starting point; Delete removes tiles you created (inherited core tiles can be hidden, not deleted).

Configure navigation (bottom tabs & hamburger)

The Navigation tab controls the app's chrome — the persistent bottom tab bar and the hamburger (side) menu. It's organised into three buckets:

• Available — navigation items not currently placed.
• Bottom tabs — the bar along the bottom of the app. There's a bottom-tab limit (enforced by the editor) because only a few fit on a phone screen.
• Hamburger menu — the slide-out menu for everything else.

1. Add a navigation item by choosing a module from the navigation module options. Each item has a label, an icon, and a target route/module.
2. Drag items between Available, Bottom tabs and Hamburger to set placement; reorder within a bucket to set the order shown.
3. Set each item's status (active / disabled) or hide inherited items you don't want, without deleting them.
4. Save. The arrangement maps directly to the live app's tab bar and menu.

App branding (logo, colours, name)

Branding is not set per-template inside the App Editor — it's tenant-wide. Set it once in Settings → General → Branding: upload your large logo, small logo and favicon, and set the primary colour (colour picker or hex). The platform/app name is read-only there (set at provisioning). Those values are picked up automatically by every published app for the tenant, alongside the tiles/navigation you design here. See the Settings guide for the branding fields.

Banners

Promotional banners shown inside the app are managed on the Banners tab (it appears when the banners capability is enabled for the app). You work with banner locations (named slots with a fixed image ratio, slot count and rotation duration), banner groups within a location, and individual banners (image + an action: deep-link, external URL, or ignore, with optional from/to scheduling dates). Inherited core banners can be overridden with your own artwork where the template permits. Banners are a topic in their own right — see the Banners guide for the full workflow. (If a separate Banners guide isn't present in your docs set yet, the Banners tab in the App Editor is self-contained and follows the same add / arrange / status pattern as tiles.)

Per-audience apps (member vs customer vs supplier vs partner)

There isn't one app — there's one per domain type, and each is edited the same way through this editor:

• Member Portal (resident app) — requires public_portals:member.
• Customer Portal — requires public_portals:customer.
• Supplier Portal — requires public_portals:supplier.

The app's type (set on its domain/template) determines which module and navigation options the editor offers you — e.g. a Supplier app surfaces inventory/orders modules, a Member app surfaces resident features. So to build the resident experience you edit the Member-type app; to build the supplier experience you edit the Supplier-type app, and so on.

How app templates are shared / inherited

• A template is a reusable blueprint. A central core template (e.g. the shared DCApp member template used across resident builds) can be assigned to many tenant domains.
• When a core template is assigned to your domain, you get an editable copy: inherited core tiles/navigation/banners appear with a source = core marker. You can reorder, override or hide them, and add your own (source = tenant) items on top.
• Core (root) admins can set descendant permissions per group (tiles / navigation / banners) — controlling whether sub-tenants may edit each group at all (root_only, subtenants_only, both, or locked). If a group is locked by the core, your editor shows it read-only with a banner explaining why.

Preview & publish

The editor saves changes immediately to the app template (there is no separate "draft vs publish" toggle in the App Editor; the Tenant Version shown on Overview tracks the template revision). Tiles, modules and uploaded images render live previews inside the editor so you can confirm appearance before saving. The published member/resident app fetches the current template at runtime, so a saved change is reflected the next time the app loads its configuration.

How the data connects

What you configure → where it's stored → what it produces:

• The App Editor list is built by joining your tenant's domains (which carry app_template_id, app_template_name, app_type, is_primary) with their domain config records (which carry domain_config_id, domain_type, status, last_accessed_at). A domain only becomes an editable app when both exist and a template is assigned.
• Everything you edit on the tabs is persisted against the assigned app template via the domain-config's app-configuration API (/domain-configs/{domainConfigId}/app-configuration/...): tiles, tile categories, navigation items, banner locations/groups/banners, and the descendant permissions. Inherited items keep a source_type of core; items you add are tenant.
• At runtime the published PWA tells the backend which app it is by sending the x-app-template-id header (the template's id). The portal resolves that to the right tiles, navigation, banners and tenant branding and returns them — that's how one codebase renders different apps for different domains/tenants.
• Relationship to other modules:
• Domains (Settings → Domains) — the source of the domain + template assignment; no app exists in the editor without it.
• Branding (Settings → General) — supplies logo/colour/name to every app for the tenant.
• Banners — managed on the Banners tab; see the Banners guide.
• Tile/navigation targets — each tile or nav item can point at another live module (Documents, Support, Payments, e-forms/Flows, etc.), so the apps you design here are the front door to the rest of the portal's features.

Permissions & access

• Page visibility is gated on public_portals:app_editor; without it the App Editor page is blocked entirely. The per-audience modules (public_portals:member / :customer / :supplier) determine which app types you can build and which module/navigation options appear.
• Editing rights within a shared template are controlled by group permissions. Whoever owns the core/root template decides, per group (tiles, navigation, banners), whether descendant tenants may edit (root_only, subtenants_only, both, locked) and whether they may add new banner groups. If a group is read-only for you, the editor disables its controls and shows an amber notice naming the source.
• Branding is governed by Settings permissions (settings:update:all to edit, settings:read:all to view) — it lives in the Settings module, not the App Editor.

Tips & gotchas

• Shared templates are not copies of your data — they're live inheritance. Editing a core (DCApp-style) template's items that you inherited may be limited to override/hide/reorder. To fully control something, add your own tile/nav/banner rather than fighting an inherited one.
• **An app must have a template and a domain config to appear.** If a domain you expect is missing from the App Editor list, check that it has an app_template_id assigned (Domains) and that its domain config exists — a template with no matching config (or vice versa) is silently skipped.
• Wrong / empty x-app-template-id at runtime means the app can't be resolved to a template, so it gets no tiles/navigation from this config. If a published app shows a blank or default shell, suspect a missing or mismatched template id on the domain.
• Home grid is fixed at 4 columns on mobile. Tile "width" is a column span within those 4 — there's no free-form pixel layout. Plan tile sizes accordingly.
• Bottom tabs are capped. The editor enforces a bottom-tab limit; overflow belongs in the hamburger menu, not the tab bar.
• Disabled ≠ deleted. Setting a tile or nav item to disabled (or hiding an inherited item) removes it from the live app while keeping it for later — safer than deleting, and the only option for inherited core items.
• Branding is per-tenant, app config is per-template/domain. Changing your colour/logo changes every app at once; changing tiles only changes the app you're editing.