Configuring Perspective Inline Frame Hubs and Shared Docks

Session Scope in an Inline Frame Hub

The target layout is an App_Hub project that shows an app list, like a phone home screen, with one entry per topic: MES, TR, Part, Report. Selecting an app loads that project in an Inline Frame. The hub keeps the app list on screen, so the operator can switch apps without losing the way back. Two problems follow from that design: the host and the embedded project cannot see each other's data, and it is not obvious when the inner sessions end.

A Perspective session is the gateway-side object created when a browser loads a project URL. It holds session properties, authentication state, and every open page for that one project. A session belongs to exactly one project. When the Inline Frame in App_Hub loads the MES project URL, the browser opens a second, independent session in the MES project. The gateway treats it like a new browser tab. Projects do not share sessions, and no setting merges them.

This has three consequences:

• Session custom properties, the logged-in user, and in-session messages in the hub are invisible to the framed project, and the reverse also holds.
• Each framed project authenticates on its own. The user sees one login, not two, only if both projects use the same Identity Provider and that IdP supports single sign-on.
• Each app switch that changes the iframe URL leaves the previous inner session behind. That session stays on the gateway until its timeout expires.

Check 1: open the hub in one browser tab, select an app, then open the gateway's status page for active Perspective sessions. Expect two sessions for that tab: one under App_Hub and one under the framed project. Switch apps twice. Expect the older inner sessions to stay listed until they time out.

Session Lifetime and Timeout

A session stays alive while the browser keeps its connection to the gateway. If the page closes, the tab is killed, or the network drops, the gateway does not remove the session right away. It keeps the session for the configured timeout so a reconnecting client can resume it. When the timeout expires, the gateway closes the session and discards its state. Session properties, unsaved view state, and anything the session was polling all go with it.

The timeout is set per project in the Perspective project properties in the Designer. The gateway applies no global value that overrides it, so read the current setting in each project rather than assuming a default. In an iframe hub, the effective memory load is:

Live sessions ≈ open hub tabs × (1 + app switches still within the timeout window)

That is a planning estimate, not a formula from the gateway. It shows why a short timeout matters more in an iframe design than in a single-project design.

Check 2: note the timeout in each project's properties. Close a hub tab and watch the session list. Expect both the hub session and the inner session to disappear once the configured timeout has passed, not before.

Architecture Decision: Iframe Hub, Single Project, or Inherited Dock

The reason for splitting is valid: one project with many views across MES, part management, and reports becomes hard to maintain. Nested sessions are the wrong fix. Wiring data between separate sessions creates a messaging layer that has to be versioned, tested, and debugged across project boundaries. That becomes a nightmare to maintain. The hub also exists mainly to provide navigation, and Perspective already offers that through docked views.

Decision path:

1. If the topics share users, tags, and session context, such as the logged-in operator or a selected line or work order, build one project with pages. This is the default answer.
2. If the topics must stay as separate projects for deployment, ownership, or licensing, use an inheritable parent that provides the navigation dock.
3. Keep the Inline Frame hub only when a framed app cannot be rebuilt as a page or child project. Accept the messaging and session costs described below.

Check 3: list the data that must cross between apps. If the list is non-empty and the apps will be used in the same browser tab, option 1 is the only one where that data moves without custom plumbing.

Single Project: Pages and a Shared Docked View

A page here means a URL path in the project's Page Configuration mapped to a primary view. A docked view is a view pinned to the top, left, right, or bottom edge of the page, outside the primary view. When a docked view is defined in the shared settings of the Page Configuration, it appears on every page unless a page's own configuration overrides it.

1. Create a folder per topic in the Views tree, one each for MES, TR, Part, and Report. This gives the folder-level separation the split projects were meant to provide.
2. Build one navigation view containing the app list. Use the same icons and labels the hub used.
3. In Page Configuration, add one page per app, such as /mes, /part, and /report. Set each page's primary view to the topic's landing view.
4. In the shared settings of Page Configuration, add the navigation view as a docked view on the edge you want. Set it to show by default, or on demand with a handle if screen space is tight.
5. Wire each app-list entry to a navigate action that targets the page path, not a full URL. Page-path navigation stays inside the current session.
6. For pages that must not show the navigation, such as a full-screen andon display, override the docks in that page's own configuration. Do not delete the shared dock.
7. Move session-wide context, such as the selected line or active order, into session custom properties. Every page can bind to them directly.

Check 4: open the project and move through all app pages. Expect one session in the gateway session list throughout, the navigation dock on every page except the overridden ones, and session properties set on one page to be readable on another.

Inherited Navigation Dock Across Separate Projects

When the topics must stay as separate projects, drop the outer frame project. Put the navigation "frame" into an inheritable parent project instead. Each topic project inherits it and uses it as a dock. The shared navigation lives in one place, and each project keeps its own views, scripts, and page configuration.

1. Create a parent project and mark it inheritable. Build the navigation view there.
2. Set the parent project as the parent of MES, TR, Part, and Report. Confirm the navigation view appears as an inherited resource in each child's Views tree.
3. In each child's Page Configuration, add the inherited navigation view as a shared docked view.
4. Make the app-list entries navigate by full URL to the target project's client URL, because the target is a different project. Parameterize the host so the same view works in development and production.
5. Edit the navigation view only in the parent. Do not override it in a child unless that child really needs a different menu. An override splits the menu and defeats the single edit point.

Moving between projects this way opens a new session in the destination project. That trade-off comes with project isolation. The user can still reach any app from any app, because every project carries the same dock. The browser back button also returns to the previous project.

Check 5: change a label in the parent's navigation view and save. Open two different child projects. Expect the new label in both without editing either child. Navigate from one to the other and expect one active session per project visited, not two per tab.

Cross-Project Data Exchange When Iframes Stay

If an Inline Frame is unavoidable, data between the host session and the framed session must go through the gateway. The tool for this is system.util.sendMessage. It sends a message to clients running under the gateway, or to a named project within the gateway. The receiving side is a message handler defined in the destination project.

1. In the destination project, create a message handler with a fixed name. Define its payload as a dictionary with an explicit schema, and version that schema.
2. In the sending session, call system.util.sendMessage with the destination project name, the handler name, the payload, and the scope. The scope selects gateway-side handlers or client/session-side handlers. Read the valid scope codes and filter arguments from the function's page in the Ignition User Manual.
3. Include an identifier in the payload that ties the message to one user or one hub tab, such as the username or a correlation key the hub passes to the iframe as a URL parameter. Without it, a message addressed to a project reaches every session of that project that the scope covers.
4. For replies, repeat the pattern in the other direction with a handler in the hub project.

The messaging layer is the maintenance cost the other options avoid. Every field added to a payload is a contract between two projects that deploy separately.

Check 6: with two users logged into the hub at once, send a message from user A's framed app. Expect only user A's hub session to react. If both react, the correlation filter in step 3 is missing.

End-to-End Verification

Run these checks against the chosen architecture before release.

1. Check 7, session count: open one browser tab, visit every app, and read the gateway's active session list. Expect one session for the single-project design. For the inherited-dock design, expect one session per project visited. For a retained iframe hub, expect the hub session plus one per app switched to within the timeout window.
2. Check 8, navigation: from each app, reach every other app using only the dock or app list. Expect every target reachable in one click. For a page with overridden docks, expect a deliberate exit path.
3. Check 9, authentication: log out and open a deep-link page URL directly. Expect exactly one login prompt. A second prompt inside a frame means the framed project uses a different Identity Provider, or its IdP is not providing single sign-on.
4. Check 10, shared context: set the session-wide selection, such as line or order, on one page and open another app. Expect the value carried over in the single-project design. In the multi-project designs, expect it only where a message handler delivers it.
5. Check 11, cleanup: close the browser and wait for the longest configured session timeout among the involved projects. Expect the gateway session list to hold no sessions from that browser.

FAQ