WinCC Unified V21: Open Pop-up Windows from Faceplates via Tag Prefix

Overview

The faceplate concept in Siemens WinCC Unified lets engineers author a single reusable HMI symbol (motor, valve, PID loop) and instantiate it dozens of times on a process screen, with each instance bound to a different data source through the Tag Prefix property. The natural next step in a standardized HMI library is drill-down: clicking the symbol opens a detailed pop-up window that shows status, diagnostics, and command buttons specific to that instance.

This reference covers how to:

1. Author a faceplate with a structure-typed data interface.
2. Configure the Tag Prefix so an instance on a screen resolves to the correct PLC tags.
3. Trigger a pop-up at runtime using the UI.OpenFaceplateInPopup() JavaScript method.
4. Chain pop-ups (a popup opens another popup) without losing the data binding.
5. Animate faceplate elements from structure members.

Tested against WinCC Unified V21 (TIA Portal V21 engineering). The method and behavior are similar from V18 onward, but the documented parameter set for UI.OpenFaceplateInPopup() is current for V20/V21 help.

Prerequisites

Faceplate Fundamentals

A faceplate is a reusable screen object stored in the HMI project library. Each instance on a process screen receives its own data context through the Tag Prefix property. Because the prefix is a plain string, the same faceplate can read from any data source: a DB element, a tag array slice, or an arbitrary path of HMI tags.

Structure-Typed Interface on the PLC

Define a PLC data block (for example DB_Motor) with members the faceplate will display and control:

TYPE "UDT_Motor"
VERSION : 0.1
   STRUCT
      StartCommand   : Bool;
      StopCommand    : Bool;
      Running        : Bool;
      Fault          : Bool;
      Current        : Real;       // A
      Speed          : Real;       // rpm
      SetpointSpeed  : Real;       // rpm
      OperatingMode  : Int;        // 0=Manual, 1=Auto
   END_STRUCT;
END_TYPE;

Create an array of this UDT in the PLC (Array[1..20] of "UDT_Motor") and map the array to HMI tags. Each element of the array becomes a candidate Tag Prefix for a faceplate instance.

Tag Prefix Property

In the faceplate instance properties (Properties pane → Interface), set the Tag Prefix:

The prefix is a string that WinCC Unified prepends to every tag reference inside the faceplate. The HMI tag database must contain the full path; otherwise the faceplate shows ### placeholders or quality code "Bad Configuration".

UI.OpenFaceplateInPopup() Method

The runtime object model exposes UI.OpenFaceplateInPopup() to launch a faceplate in a floating window at runtime. The official reference is the UI.OpenFaceplateInPopup() (RT Unified) – TIA Portal V21 Help page.

Signature

UI.OpenFaceplateInPopup(
    faceplateType : String,        // Name of the faceplate type in the library
    tagPrefix     : String,        // Tag prefix for the instance
    popupOptions  : Object         // Optional: position, size, title, modality
);

Parameters

popupOptions Object

Return Value

UI.OpenFaceplateInPopup() returns a handle object that lets you close the popup programmatically:

{
    handle: Number,     // Unique handle for the popup
    close(): Void       // Method to close the popup programmatically
}

Store the handle if you plan to dismiss the popup on a condition (e.g., a fault clears) without relying on the user clicking the X.

Configuring the Faceplate for Popup Use

1. In the HMI project library, open your faceplate (e.g., fpMotor).
2. In the Faceplate Interface editor, add a property of type String named TagPrefix. Mark it as the runtime reference.
3. Bind the faceplate's internal tag references to Interface.TagPrefix + ".Running", Interface.TagPrefix + ".Current", etc., using dynamic addressing.
4. Expose any commands (Start, Stop, Reset) as faceplate events.
5. Add a script event on the faceplate body OnClick that calls UI.OpenFaceplateInPopup("fpMotorDetail", TagPrefix, ...).

Inside a faceplate script, the symbol TagPrefix refers to the current instance prefix automatically. It is a runtime-resolved context variable; you do not need to pass it from the screen.

JavaScript: Opening the Popup

The following script is placed in a faceplate event (e.g., "Mouse click" on the body rectangle):

// Open a detailed faceplate popup for the current instance
export function Faceplate_OnMouseDown(item, x, y, modifiers, trigger) {
    const options = {
        x: 200,
        y: 150,
        width: 480,
        height: 320,
        title: "Motor Detail - " + TagPrefix,
        modal: false,
        closeOnTouchOutside: true
    };
    UI.OpenFaceplateInPopup("fpMotorDetail", TagPrefix, options);
}

For a screen-level button that operates on a selected instance, pass the prefix explicitly:

// Bound to a screen button; the prefix comes from a screen tag
export function Btn_OpenDetail_OnClick(item) {
    const prefix = Tags("SelectedMotorPrefix").Read();
    if (!prefix) {
        HMIRuntime.Trace("No motor selected");
        return;
    }
    UI.OpenFaceplateInPopup("fpMotorDetail", prefix, {
        title: "Motor Detail",
        width: 480,
        height: 320
    });
}

Verifying the Tag Prefix Resolution

Add a temporary trace to confirm the prefix reaches the popup:

export function Faceplate_OnMouseDown(item, x, y, modifiers, trigger) {
    HMIRuntime.Trace("Opening popup for prefix: " + TagPrefix);
    UI.OpenFaceplateInPopup("fpMotorDetail", TagPrefix);
}

Run the project, click the faceplate, and inspect the RT log. The output should match the configured prefix string exactly (e.g., HMI_Tags::Motor[3]). Mismatches here are the most common cause of "popup shows the wrong data".

Tag Prefix Configuration Patterns

Single Tag Prefix per Faceplate

The most common case. The faceplate body has a single TagPrefix interface property; the popup uses the same string. No remapping is required.

Multi-Prefix Faceplates (Mixed Sources)

Some faceplates need to read from one DB and write to another (for example, a tuning popup that writes setpoints to a separate recipe DB). Define two interface properties:

UI.OpenFaceplateInPopup() accepts only one prefix. For the second prefix, stage it in a tag and recover it inside the popup:

export function Faceplate_OnMouseDown(item) {
    Tags("CmdPrefix_" + UID).Write(TagPrefix + "_Cmd"); // pre-stage
    UI.OpenFaceplateInPopup("fpMotorDetail", TagPrefix);
}

Inside the popup, read Tags("CmdPrefix_" + UID).Read() to recover the second prefix. The UID symbol is a per-instance identifier provided by the faceplate runtime.

Dynamic Prefix from Array Index

When a faceplate is generated in a loop (C-script or screen generator tool), construct the prefix at runtime:

export function LoopInstance_OnClick(item) {
    const idx = item.Parent.Index; // index of the loop faceplate instance
    const prefix = `HMI_Tags::Loop[${idx}]`;
    UI.OpenFaceplateInPopup("fpLoopDetail", prefix);
}

Opening Popups from Popups

The runtime allows a popup to launch another popup. The original popup remains open, and the new popup is created on top of it. The two popups can have different faceplate types and different tag prefixes.

// Inside the detail popup, a "Tuning" button launches a second popup
export function Btn_Tuning_OnClick(item) {
    UI.OpenFaceplateInPopup("fpLoopTuning", TagPrefix, {
        title: "Tuning - " + TagPrefix,
        width: 600,
        height: 400,
        modal: true
    });
}

Recommendations for Chained Popups

• Cap the chain at 2 levels. Deeper nesting hurts usability on panels with small screens.
• Use modal: true on the second popup when the user must finish or cancel before returning to the first.
• Always expose a Close button inside the popup; the runtime's X icon may be hidden in full-screen mode.
• If the same faceplate type is opened twice with different prefixes, both popups remain open and operate on independent data contexts.

Animating Faceplate Elements from Structure Tags

Inside the faceplate editor, you have two options for animation: declarative tag binding or script-based logic.

Option A: Direct Tag Binding (Declarative)

In the Properties pane of an element (for example, a circle's "Visibility"), select the dynamic value, choose the faceplate's interface property, and append a member. For a running indicator:

This is the preferred path. It requires no scripting and updates automatically at the configured refresh cycle.

Option B: Script-Based Animation (Procedural)

For complex animations (color ramp, dynamic text, multi-condition logic), use a script on a screen event or in a faceplate "Update" trigger:

// Called cyclically; recompute color based on Current value
export function Current_Indicator_OnUpdate(item) {
    const current = Tags(TagPrefix + ".Current").Read();
    let color = 0xFF00FF00; // green
    if (current > 50) color = 0xFFFFA500; // orange
    if (current > 80) color = 0xFFFF0000; // red
    item.BackColor = color;
}

Verification and Commissioning

After configuring the faceplate and popup:

1. Compile the HMI project in TIA Portal. Watch for warnings about unbound interface properties.
2. Download to the Unified Runtime (panel or PC).
3. Open the project. Navigate to the screen containing the faceplate instances.
4. Click an instance. The popup must appear with the correct title and data.
5. Verify each instance by clicking 2–3 of them. Each must show its own data and respond to commands independently.
6. Check the RT trace log for warnings about missing tags or invalid prefixes.

Acceptance Test Checklist

Troubleshooting

Field-Proven Cautions

• The implicit TagPrefix symbol is only valid inside faceplate scripts. Calling UI.OpenFaceplateInPopup() from a screen-level script requires an explicit prefix string.
• Map the full UDT array once, not each element separately. Per-element mappings defeat the whole purpose of Tag Prefix.
• Never hardcode prefix strings like "Motor[3]". Use a parameter tag or compute the prefix from a screen tag, so the design survives renumbering.
• On Unified Comfort Panels, popup dragging is constrained to the visible screen. Tests in the RT simulator can give false positives that the popup will be reachable on a 7-inch panel.
• The TIA Portal V21 help documents UI.OpenFaceplateInPopup() under the RT Unified JavaScript object model. Earlier V18/V17 builds expose the same method name but with fewer popupOptions keys. Pin your engineering version to match your runtime version.

References Embedded Above

• UI.OpenFaceplateInPopup() (RT Unified) – TIA Portal V21 Help

Frequently Asked Questions