Raising Faceplate Events in WinCC Unified V20 Popup Containers

Problem Statement: Faceplate Events in Popup Containers

Engineers consolidating HMI screens around a single Faceplate Container in WinCC Unified V20 routinely hit a hidden constraint: when a faceplate is launched through the Open Faceplate as Popup system function, the container's Events tab is not exposed in the engineering view, so you cannot wire a custom script to the popup instance the way you would on a fixed, screen-resident container. The popup loads its own self-contained faceplate type, executes its internal scripts, and dismisses without giving the calling screen an event hook for post-processing (save, delete, write-back to controller tags).

The symptom shows up as:

• An OK / Save / Delete button works visually but does nothing observable to the caller.
• The Events tab on the popup's container is greyed out or absent in the screen editor.
• Multiple popup invocations cannot be differentiated because no parameter is being passed into the instance.
• Dynamic button behavior must be re-implemented per screen rather than reused.

This guide covers the production-ready pattern: declaring an event on the faceplate's Interface, raising it from inside the faceplate with the Faceplate.RaiseEvent API, and exposing the resulting event on the popup's host surface. Where the host surface still hides the event in popup mode, a tag-triggered bridge pattern provides a deterministic fallback that survives firmware revisions.

Prerequisites and Environment

Confirm the engineering environment matches the supported baseline before starting:

Reference configuration patterns are documented in the Siemens support entry Tips and tricks for configuring faceplates with WinCC Unified. Always cross-check against the TIA Portal V20 online help for Faceplate > Interface and Scripts in faceplates topics.

Faceplate Event Interface Configuration

Events are declared on the faceplate's interface, not on its visualization surface. Open the faceplate type in the project tree, then on the Interface editor create a new entry of type Event. The faceplate is a self-contained type definition; the event becomes part of the public contract that every instance (screen-resident or popup) exposes.

1. In the project tree, expand Faceplates, right-click the faceplate type, and select Open.
2. Switch to the Interface tab in the work area.
3. In the Events section, click the empty row and add a new event. Give it a Pascal-case name such as OnUserAction. Decide whether to add parameters; typical signatures are OnUserAction(actionId : Int, payload : String).
4. Compile the faceplate type so the event propagates to every container that references the type.

RaiseEvent Script Syntax in V20

Inside a faceplate, scripts run against the faceplate's own scope. To raise an interface event from a button's Click event script, call Faceplate.RaiseEvent with the event name and parameter list. The runtime resolves the event against the interface and propagates it to whichever host is currently displaying the instance.

When you press the button on a popup, the event fires into the popup's host. If the host container has the event wired, that wiring runs. If the host is a popup opened via Open Faceplate as Popup, the event wiring path depends on how the popup was opened and which container holds the live instance.

Common action ID conventions to standardize your interface:

Why the Event Tab Is Inaccessible in Popups

In TIA Portal V20, an Open Faceplate as Popup call instantiates the faceplate dynamically. The popup is a runtime container, not a configured engineering object with a static event binding surface. Three structural reasons appear:

• The popup is created by the runtime when OpenFaceplateAsPopup executes; the engineering tree has no static instance to attach an Events tab to.
• WinCC Unified's event wiring is performed at compile time. A runtime-popup cannot compile-time-bind events.
• The popup's host surface belongs to the calling screen but the dynamic instance is addressed through a tag or system-internal handle, not through a named object.

Two practical consequences for the engineer:

1. You cannot click an Events tab on a popup container in the editor because there is no editor instance.
2. You must pre-declare the event on the faceplate type's interface and trigger it via script. The caller listens either through the same OpenFaceplateAsPopup-driven host or through a tag-bridge.

Workaround: Tag-Triggered Script Pattern

When the popup's host container still does not surface the event for direct scripting, use a string-tag or integer-tag bridge. The faceplate writes a sentinel value into an HMI tag when the user clicks OK / Save / Delete; the calling screen subscribes to that tag's OnChange event and runs the appropriate logic. This pattern is field-proven and survives between WinCC Unified revisions because it relies on tag change events rather than on faceplate event propagation semantics.

The tag-bridge approach mirrors the pattern long used on older WinCC Professional and Optix screens and remains the most portable choice when the Unified V20 popup event wiring path is unclear or unsupported on a specific comfort panel firmware.

Step-by-Step Implementation

Step 1: Define the faceplate interface

1. Open the faceplate type in the project tree.
2. On the Interface editor, add the event OnUserAction(actionId : Int, payload : String).
3. Add input properties you need to pass in: e.g. CurrentRecipe : String, Mode : Int.
4. Compile the faceplate type.

Step 2: Wire the RaiseEvent inside the faceplate

1. On the faceplate's OK button, configure the Click event with a script.
2. Paste the RaiseEvent call: Faceplate.RaiseEvent("OnUserAction", 1, "save");
3. Repeat for Save, Delete, Cancel using the action IDs from the table above.

Step 3: Embed the faceplate on the screen

1. Drag the faceplate type from the library into a Faceplate Container on the calling screen.
2. In the container's Properties > Events tab, the OnUserAction event is now listed; wire it to a screen-level script or function.

Step 4: Open as popup from a list screen

1. On the source screen, configure a list row's double-click event to call Open Faceplate as Popup.
2. Choose the faceplate type and pass properties (e.g. CurrentRecipe = Tags("SelectedRecipe").Read()).
3. Because the popup is runtime-dynamic, you cannot bind OnUserAction in the editor here. Use the tag-bridge pattern.

Step 5: Listen on the tag bridge

1. Create an internal HMI tag, e.g. HMI_FaceplateCommand (Int, initial value 0).
2. Inside the popup faceplate, write the action ID into this tag on button click.
3. On the calling screen, add a tag change event on HMI_FaceplateCommand and branch on the value.

Passing Parameters Through the Interface

Self-contained faceplates do not see screen-level tags by name; they only see interface properties. Declare every input the script needs as an interface property, then map the property at the container:

A void parameter (no value set) raises an event with default-initialized arguments. Always pass at least an action ID, even if you do not need a payload, so the caller can branch deterministically.

Verification and Commissioning Tests

Validate the pattern in this order before shipping to the line:

1. Compile the project: errors on the faceplate interface mean an event or property name typo. Fix the names, never the wiring.
2. Run the simulation (WinCC Unified RT): start the PC runtime with the project; open the screen; trigger the popup. Watch the HMI_FaceplateCommand tag in the tag simulator.
3. Trigger every action ID: Save (1), Delete (2), Cancel (3), Apply (4). Each must change the tag and trigger the calling screen's branch.
4. Cycle test: open the popup, perform Save, dismiss, open again, perform Delete. Verify the tag resets to 0 after each action; otherwise, the change event will not re-fire on the next identical value.
5. Parameter test: open the popup with two different recipe names. Confirm CurrentRecipe reflects the value passed at OpenFaceplateAsPopup time, not a leftover.
6. Offline vs online tag scope: the tag-bridge tag must be defined as an HMI internal tag in the project's HMI tags editor and not as a PLC tag, otherwise the write fails silently.
7. Runtime license: confirm the Unified Runtime license count covers the panel or PC instances. A missing license downgrades the runtime to demo mode and disables tag/event scripts.

Troubleshooting Matrix

Best Practices and Field Notes

• Prefer RaiseEvent for screen-resident containers; it is the cleanest pattern and survives TIA version changes within V17-V20.
• Use the tag-bridge for runtime popups opened by OpenFaceplateAsPopup. Tag change events are a stable contract across Unified versions.
• Always reset the bridge tag to 0 in the caller. Without a reset, identical consecutive actions will not retrigger the change event.
• Declare parameters on the interface, not as screen-level reads. Faceplate scripts run in faceplate scope and cannot see screen tags directly.
• Keep the action ID small enum. Larger ID spaces invite typos and waste interface bandwidth.
• Document the interface contract in the faceplate's Description field so other engineers can wire callers without opening the type.
• Test on the target panel, not only the PC simulator. Comfort Panel firmware sometimes lags V20 PC runtime by a point release, and faceplate scripting behavior can differ.

FAQ