Banners

Part of the IP4CMS portal. ← All module guides

What it's for — Banners are the promotional and informational images shown inside your member/resident app — the artwork that appears on the app home screen and other designated banner spots. Use them to highlight announcements, campaigns, events, sponsor messages, or links to a website. Each banner is a piece of artwork placed into a predefined banner location and can optionally be tapped to open an external web page.

Where to find it — Banners are configured as part of your member app, not on their own menu. Go to Settings → Domains, open the domain whose app you want to edit, then open its App Configuration / App Editor and switch to the Banners tab. (Route: settings/domains → app editor for the selected domain config.)

Before you start

• The banners licence module must be enabled for your tenant. If it isn't, the Banners tab is hidden and the app returns a "banners module" not-enabled message.
• A domain and an app configuration must already exist for the domain — banners attach to a specific app configuration, so the app/template must be set up first. (See the Settings and Domains / App Editor guides.)
• You need a portal role with permission to edit the app configuration. Banner editing also depends on the banners group permission resolved for your tenant — if a parent/Core tenant has locked banners, the controls are read-only.
• Banners drop into banner locations that are defined on the app template by Core. You choose a location; you don't invent one. Each location has a fixed number of slots, an image ratio (the shape your artwork should match), and a rotation duration.

Key tasks

Add a banner

1. Open Settings → Domains, select the domain, open its App Configuration, and go to the Banners tab.
2. Click Add Banner (under Banner Items).
3. Set the key fields:

• Location* — choose one of the standard banner locations. Locations already full (all slots used) are not selectable.
• Banner Name* — a label for your reference (max 255 characters).
• Status — active or inactive (Inactive banners are configured but not shown).
• Banner Artwork* — upload the image. Drag-and-drop or browse; max file size 10 MB. Match the location's stated image ratio so it isn't cropped oddly. You can add one image per available slot.
• From Date / To Date (optional) — the active date range. Leave blank for "No start" / "No end". The To date cannot be earlier than the From date.

1. Click Create Banner.

Add a tap link to a banner

1. On a banner's artwork, open the link option and enter an External URL (must start with http:// or https://).
2. Save. This sets the banner's action to open that URL when tapped. Leave the URL empty to keep the action as Ignore (the banner is shown but isn't tappable).

Behind the scenes a banner's action can be ignore or external_url. The app template also supports deep links into app areas (home, settings, shop, wallet, sos), but the tenant banner editor exposes the external-URL option for tap targets.

Edit or remove a banner

1. In the Banner Items table, each row shows the banner, its Location, and its date range.
2. Click Edit to change the name, status, dates, or artwork. Click Delete to remove it.
3. Use the up/down controls to reorder banners — this changes the order they rotate/appear within the app.

Set who a banner group applies to (multi-tenant)

If your tenant has child (sub) tenants:

• Descendant edit policy — on a banner group you can choose Allow editing or Disallow editing for child tenants, and optionally restrict it to a chosen list of sub tenants allowed to override.
• Banner group adding — you can allow or disallow child tenants from adding their own banner groups (the "Adding" policy shown on the banners permission row). If Core has locked this, you'll see "Adding Locked By Core".
• Artwork override tenants — for an inherited (Core) banner, you can pick exactly which direct child tenants are permitted to replace that one banner's artwork with their own ("Sub Tenants Allowed To Override").

Preview

The banner form shows a live artwork preview, and the Banner Items table is your at-a-glance list of what's configured (location, dates, slot usage). The artwork as uploaded is what appears in the member app's home banner.

How the data connects

What you configure on the Banners tab is saved against the selected domain app configuration (not globally), in these tenant-api tables:

• domain_app_banner_location — the placement targets (slots, image ratio, rotation duration_ms). Defined by Core on the app template; you place banners into them.
• domain_app_banner_group — a group bound to one location, holding the name, status, date window, and edit policy.
• domain_app_banner — the individual banner: artwork (image_key / image_url), slot, action_type + action_value (the external URL), sort_order, and any allowed override tenants.
• domain_app_banner_group_permission — the rule deciding which child tenants may edit a Core-owned banner group.

A banner is either Core/inherited (source_type = core, pushed down from the app template) or tenant-owned (source_type = tenant, created by you). Inherited banners can only be changed where Core/your parent has allowed it. When the member/resident PWA loads, it reads the resolved app configuration and renders the banners for each location on the app home screen (via the app's image-banner component), rotating between slots on the location's duration.

Permissions & access

• Licence module: banners. Without it the tab and APIs are unavailable.
• Role/permission: ability to edit the domain app configuration; banner edit/delete/move/reorder are gated by the resolved banners group permission (current_tenant_can_edit).
• Multi-tenant visibility: a parent or Core tenant controls whether a child can edit, add banner groups, or override specific artwork. A sub-tenant cannot configure override-tenant lists or banner-group child permissions for groups it doesn't own.
• Banners are scoped to a single domain app configuration, so they only ever appear in that domain's member app.

Tips & gotchas

• You can't add new banner locations. Locations (and their slot counts) come from the app template, set by Core. If a location is full you'll see "Banner location is full — ask Core to increase the max slots." Free a slot or request more.
• Match the image ratio. Each location states an image_ratio; uploading a mismatched shape leads to cropping/letterboxing in the app.
• Inherited (Core) banners are protected. For a Core banner you cannot change its link/action or remove its artwork unless you're explicitly allowed — the link is locked ("Inherited banner artwork links cannot be changed for this tenant"). Use the per-banner artwork override mechanism to let specific child tenants swap the picture while keeping the placement.
• Scheduling is by date only. From/To dates control when a banner is live; there's no time-of-day window. A banner with no dates is always live (subject to its active status).
• Status vs. dates vs. delete. To hide a banner temporarily, set it inactive or set an end date — deleting removes it permanently.
• Reordering matters. Where a location has multiple slots, the up/down order is the rotation order the member sees.
• Banners live under the app, not their own page. If you can't find them, you're looking for a top-level menu — instead open the domain's App Configuration and use the Banners tab.