Interaction behaviors | Mingcedar Studio

Set Variable on Click updates a current-page variable when clicked. Use it to store a selection, switch views or update component displays. Declare the variable in Page Script first. Use Write Tag or Write Tag Bit for device writes.

Drag Set Variable on Click onto the target component, configure the fields below and save. Place each example part in Page Script or its labeled behavior field. Leave Setup Script empty.

• Setup Script: preparation area. Read tags, define intermediate variables, do calculations for Value here. May be left empty.
• Variable: the name of the variable to write; the name only, no quotes (e.g. enter pumpStart, not "pumpStart").
• Value: the value to write. It may be a single expression or full JavaScript; if you write multi-line script, you must end it with return.
• Condition: true allows the assignment; false skips it.
• (Optional appearance feedback) show hand cursor when enabled, thicker stroke when enabled, hide when not enabled; visual hints for clickable / not clickable.

// Page Script
var pumpStart = false;

// Set Variable on Click → Variable
pumpStart

// Value
!pumpStart

// Condition
true

Best when a click should remember a value inside the page and make other elements react to it.

• Page state toggle: switch pumpStart between true and false on each click and bind the indicator to that variable.
• In-page view switching: different buttons write viewMode (e.g. 1/2/3), and several layers use visibility behaviors to show or hide based on viewMode.
• Remember a selection: write the currently selected device id into a variable for page text, navigation, or scripts to read.

• Do not confuse it with Write Tag: this writes a runtime variable and never reaches the PLC; use Write Tag / Write Tag Bit for the PLC.
• Do not quote the variable name: Variable takes the bare name (pumpStart); quotes or expressions will fail.
• Multi-line Value must return: a single-line expression needs no return, but multi-line logic without return yields no result.
• To make other elements react: writing only refreshes linked behavior state; other elements must bind to and read the same variable name (the variable space is readable via hqVisuDesigner.globals).
• If a click has no effect, check Condition and the variable name, then confirm the configuration was saved and exported.

Open Diagnosis is an Interactions-category behavior that runs only on the exported, running page when the user clicks the shape. It asks the Mingcedar host to open its device diagnosis popup, so an operator can click a device icon on a screen and bring up that device's diagnosis/status window. The behavior does not draw a window itself; it hands a small payload to the host, and the host opens the diagnosis view using its own popup template. Note: it relies on the host popup protocol, so it only works when the page runs inside the Mingcedar host. Opening the exported file directly in a plain browser will not show the diagnosis popup.

In the behavior editor, besides the shared Setup Script and Condition, you fill in the Popup Target group. These four target fields are JavaScript string expressions (use a literal, or build a value dynamically). The labels shown in the editor map to the payload field names the host receives as follows:

• Setup Script: setup logic. Read tags or define variables here for the fields below to use (e.g. var dev = 'F01';).
• PLC: the target PLC / station name (payload PLC). Default 'PLC'.
• Template (payload ID): the host diagnosis template code, which selects the template to load. Default 'device-default'.
• Status Prefix (payload DiagnosisControl): the status Tag prefix, combined with the PLC and template suffix to form full Tag names. Default '' (empty).
• Title (payload GroupRightIndex): the displayed device name or popup title; it is not used to build the status Tag prefix. Default 'ObjectName'.
• Condition (payload Enabled): the run gate; true runs the behavior, false means a click does nothing. Default true.
• Template instances may use string placeholders such as `'<PLC>'`, `'<DIAGNOSIS_TEMPLATE>'`, `'<STATUS_PREFIX>'`, and `'<TITLE>'`; the instance replaces them during export.

// Setup Script
var deviceId = 'PUMP_01';

// Target fields (string expressions)
PLC:           'PLC_LINE01'
Template(ID):  'device-default'
Status Prefix(DiagnosisControl): 'AREA01.PUMP01'   // status Tag prefix
Title(GroupRightIndex):          deviceId         // title shows PUMP_01
Condition(Enabled):              true

// At runtime this is equivalent to:
hqVisuDesigner.openDiagnosis({
  PLC: 'PLC_LINE01', ID: 'device-default',
  DiagnosisControl: 'AREA01.PUMP01',
  GroupRightIndex: 'PUMP_01'
});

Typical case: on a device-overview or process screen, bind Open Diagnosis to each pump, valve, or motor icon so an operator can click an icon and pop up that device's diagnosis/status window to check live bits, alarms, and parameters without switching to a dedicated diagnosis page. You can also drive the target dynamically from Setup Script, e.g. build the ID and prefix from the currently selected device number so one template serves many devices.

A few things to watch for:

• Status Prefix / DiagnosisControl is the status Tag prefix. With PLC set to PLC_LINE01, Status Prefix set to AREA01.PUMP01, and a template suffix of RUN, the full Tag is PLC_LINE01.AREA01.PUMP01.RUN. Title / GroupRightIndex supplies the displayed device name.
• The editor labels (Template / Status Prefix / Title) are not the same words as the payload names (ID / DiagnosisControl / GroupRightIndex); use the mapping above when debugging.
• The four target fields are string expressions: quote literals (e.g. 'PLC1'); only use a bare name for a variable (e.g. dev).
• If Condition / Enabled is false, a click does nothing; check it first when 'clicking opens no popup'.
• The popup is opened by the host, so it only works if the host has the matching diagnosis template (Template / ID) configured; it has no effect outside the Mingcedar host.

Open Link runs when a user clicks its component at runtime. Choose Internal page, External URL, System menu, or Run script under Destination.

Drag Open Link onto the target component, open the editor, and choose Destination. Fill the fields for the selected target type:

• Internal page: enter an exported page file such as Main.html in Page address, or click Select PPT page... to choose from this presentation. Relative addresses resolve from the current exported page and must stay within the asset root.
• External URL: select this destination for a complete external or intranet URL, then fill the fields shown for that mode.
• System menu: select this destination for a host menu and confirm the target configured in the host.
• Run script: use this when the destination depends on runtime state or the click combines actions.
• Open options: choose HMI window or Page only, then set Fullscreen and New tab as needed.
• Parameters (optional): add Key / Value pairs only when the destination needs context.

// Run script: choose a page by state
if (ReadTagBoolean("PLC_LINE01.PUMP01.FAULT", false)) {
  hqVisuDesigner.openPage("alarm_overview");
} else {
  hqVisuDesigner.openPage("production_overview");
}

For Internal page, add Key / Value rows under Parameters when the destination needs context. A scripted openPage call may supply strings, numbers, booleans, or null; the destination reads text values. Repeated keys keep their original order.

• Editor sender: select Internal page and add Key / Value rows.
• Script sender: hqVisuDesigner.openPage(pageCode, { frameTarget, parameters }); parameters must be an array, not a plain object.
• Read the first value: GetPageParameter("PLC", "").
• Read every repeated value: GetPageParameterValues("Area").
• Read every parameter in original order: GetPageParameters().
• The equivalent hqVisuDesigner.getPageParameter / getPageParameterValues / getPageParameters methods are also available.

// Source page: navigate within the package and pass context
hqVisuDesigner.openPage("device_details", {
  frameTarget: "frame",
  parameters: [
    { key: "PLC", value: "PLC_LINE01" },
    { key: "Device", value: "PUMP_01" },
    { key: "Area", value: "AREA01" },
    { key: "Area", value: "AREA02" }
  ]
});

// Destination Page Script
var plc = GetPageParameter("PLC", "");
var device = GetPageParameter("Device", "");
var areas = GetPageParameterValues("Area");

Use it to switch pages or open content, for example:

• A Pump Details button on the overview page: use Internal page to select the exported Pump page.
• For a host menu, choose System menu and verify its target in the host.
• For a help, work-order, or reporting site, choose External URL and enter an address reachable at runtime.
• For a static help page in the same package, enter its exported page address under Internal page.
• For a destination computed from live state, use Run script.

An Internal page relative address must stay inside the current package's asset directory. Use a screen code for another package or System menu for a host menu. Do not use a path such as `../../other-screen/index.html` to navigate between packages.

Open Page as Popup opens another Page Code above the current page, for device details, confirmations and parameter panels. The underlying page remains in place.

Bind it to the opener, configure Popup page, Appearance and Interaction, and select Enabled:

• Popup page: select a page from this presentation or enter an existing exported Page Code, without .html or a folder path.
• Appearance: choose Fit content for the useful content or Full page canvas for the complete canvas.
• Interaction: set Block the page behind, Esc closes the popup, and Clicking outside closes it as needed.
• Enabled: controls this behavior. Review the summary below the choices before saving.

Select a fixed destination in Popup page. For a dynamic destination, parameters, or background options, expand Advanced options:

• Use a dynamic Page Code expression: provide a JavaScript expression that returns the Page Code.
• Page parameters (JSON object): pass a static object such as `{"PLC":"PLC_LINE01","Device":"PUMP_01"}`. A top-level array is invalid.
• Build page parameters with an expression: return an object or an ordered array of { key, value } entries; use the array to preserve repeated keys.
• Background behind popup: choose Dim the page behind or Keep the page visible. Dim strength is limited to 0%-85%.
• Allow the same popup to open more than once: permit duplicate instances. It is off by default to avoid accidental duplicates.

// Fixed page + static parameters
Page Code: device_details
Page parameters: {"PLC": "PLC_LINE01", "Device": "PUMP_01", "active": true}

// Dynamic page example
selectedDeviceType === "pump" ? "pump_details" : "valve_details"

The static popup input requires a JSON object and cannot represent repeated keys. Dynamic parameter expressions can return an ordered array of { key, value } entries to preserve repeated keys. For consistent host and local-fallback behavior, use string, number, boolean, or null values. The popup destination still reads them with GetPageParameter, GetPageParameterValues, or GetPageParameters and treats the result as text.

• Static parameters: enter a JSON object.
• Dynamic parameters: Build page parameters with an expression accepts an object or an ordered { key, value } array, but not a Promise or DOM object.
• Destination reads: call GetPageParameter* in the popup page's Page Script.
• Close result: Close Current Popup's Result expression sends a result back to the opener; it is not a page query parameter.
• Parameters provide page context only; they do not bypass host permissions or expand Tag access.

// Popup Page Script
var plc = GetPageParameter("PLC", "");
var device = GetPageParameter("Device", "");
var activeText = GetPageParameter("active", "false");
var active = activeText === "true";

The target must be an exported page in the package. Adding, removing or renaming popup pages, or changing shared assets, requires a full export. Select from the page list to match Page Code to the manifest; do not emulate popups with Open Link.

This closes only the popup containing the bound object, with no Page Code. Place it inside the popup; it does not navigate the main page.

By default, this behavior closes the popup without returning a value. To send a result to the opener, select Return data when this button is clicked (optional) and enter a result expression.

• Cancel / Close usually returns no result.
• OK / Done can return `{ confirmed: true }` or another value the opener expects.
• Enabled controls this behavior.
• For a condition, cursor style, or disabled appearance, expand Advanced options and configure the applicable fields.

// Result expression
({ confirmed: true, motorId: selectedMotorId })

Use only in a popup context. Returned data does not write to a PLC; use Write Tag / Write Tag Bit, subject to host permissions and auditing.

Write Tag submits a value to Mingcedar, which checks permissions, confirmation and write handling. Editor preview does not write devices. Use Write Tag Bit for one bit of an integer.

Bind Write Tag and set Target Tag and Value. Configure Setup Script, Condition and appearance options as needed.

• Target Tag: the tag-name expression to write to. Enter the tag name directly, or use a template placeholder for reuse; the hint reads "Use Bit Index for bit writes."
• Value: the value to write. Use a single expression or JavaScript that returns a value. The initial value is 1.
• Setup Script: optional; prepare shared variables or helper logic for Value to use.
• Condition: controls whether the behavior can run; it defaults to true. A false result prevents this behavior from running.
• Options: Show hand cursor when enabled, Use bold border when enabled, Hide when disabled.

// Setup Script
var nextSetpoint = 1200;

// Target Tag
PLC_LINE01.PUMP01.SPEED_SETPOINT

// Value (submit the setpoint)
nextSetpoint

Use for click-triggered start, stop, setpoint or reset requests. Collect operator values with Input and choose the submission behavior or Click Script.

Submission does not confirm success; check the host result.

• Target Tag holds a tag-name expression, not necessarily a quoted string; just enter the tag name as the editor expects.
• If Value is multi-line script, it must end with return, otherwise nothing is written.
• The write may not take effect immediately: the host may run permission checks, a confirm dialog, an async write, or reject it; host write handlers may return a Promise.
• Do not hand-assemble an integer here just to flip one bit. Use Write Tag Bit for that.

Set makes the bit 1, Reset makes it 0, and Toggle reverses it. The runtime computes an integer from the current value and submits it with the bit index and action. Concurrent changes depend on host and device write handling. Add State Color or Tag Text to display the bit.

The editor has General, Interaction Setup and Options sections:

• Behavior Name: a label for this behavior so you can recognize it later.
• Component Name: the current shape name; read-only, cannot be edited.
• Setup Script: optional. Prepare variables or helper logic here, or leave it empty.
• Target Tag: enter the parent integer tag that holds the bits; do not add a bit subscript here. A plain tag name needs no quotes; use expression form for a variable.
• Bit Index: which bit to change, 0-31. Bit 0 is the least significant (right-most) bit.
• Bit Action: Set (force to 1) / Reset (force to 0) / Toggle (flip 0 and 1); pick one.
• FORCE writes are unavailable. When opening an older project, review the write settings and save the behavior again.
• Condition (Enabled): acts as a gate; runs the action when it evaluates to true, skips this click when false.
• Options: Show hand cursor when enabled, Use bold border when enabled, Hide when disabled.

Target Tag: PLC_LINE01.PUMP01.CTRL_WORD
Bit Index:  3
Bit Action: Toggle
Condition:  ReadTagBoolean("PLC_LINE01.PUMP01.REMOTE", false)

Typical case: one control-word integer packs several command bits.

• Start/Stop button: use Toggle to flip the run bit in the control word, so one button starts and stops it.
• Reset an alarm-acknowledge bit: use Reset to clear a bit, or use Set to raise an enable bit to 1.
• When you need to gate the click, put a check in Condition (e.g. only allow the flip in remote mode).

Check these settings:

• Tag must be the parent integer tag that holds the bits; do not append [bit] to the tag name. The bit is set separately by Bit Index (the [0..31] subscript form is for reads, not bit writes).
• Bits are zero-based. Choose a bit supported by the parent Tag: 0–7 for 8-bit, 0–15 for 16-bit, or 0–31 for 32-bit values. The editor range does not validate the device width. This write path rejects 64-bit integer parents.
• A write is not guaranteed to be immediate: the host may add permission checks, confirmation, reason input, or async processing, so never assume 'clicked means succeeded and synchronous'.
• An empty Condition is treated as true (the action runs).

Click Script is an Interactions behavior for custom click logic. Scripts can access object, objects, event, tag, page, presentation, shape, hqVisuDesigner and globals.

General has editable Behavior Name and read-only Component Name; Trigger is Click. Configure these Interaction Setup fields:

• Click Script: the script body executed on click. It supports multiple lines for conditions, tag reads and writes, component updates, and dialogs. Use return to exit early or return a result.
• Condition: an enable-gate expression, defaulting to true;. Put only a single expression that resolves immediately to true/false here, e.g. ReadTagBoolean(...) or a comparison; when false, that click does not run.
• Tag helpers available: ReadTagBoolean/Integer/Double/String, and during this real click action WriteTagBoolean/Integer/Double/String. Components and navigation use hqVisuDesigner (setComponentFill / setComponentText / setComponentVisible / openPage / openScreen, etc.).
• Async APIs (fetch, setTimeout, setInterval, ...) belong only in a script body like Click Script; never in Condition (a synchronous evaluation slot).
• The script snippet button is context-aware: it offers full script snippets in Click Script and short expression snippets in Condition.

// Click Script
var v = prompt("Enter a value", "0");
if (v === null || v === "") { return; }
var n = parseInt(v, 10);
if (isNaN(n)) { alert("Please enter an integer."); return; }
WriteTagInteger("PLC_LINE01.PUMP01.SETPOINT", n);

// Condition
ReadTagBoolean("PLC_LINE01.PUMP01.ALLOW_OP", false)

Use for multi-step or custom click actions:

• Confirm-then-write: prompt/confirm the operator first, then WriteTagInteger/WriteTagBoolean.
• Drive several components on one click: recolor, relabel, or show/hide multiple components in a single handler (hqVisuDesigner.setComponentFill / setComponentText / setComponentVisible).
• A guarded action button: wire Condition to an allow/logged-in/manual-mode tag so the click simply does nothing when the precondition isn't met.

Configuration requirements:

• Writes remain subject to host permissions, confirmation, reason capture, and asynchronous processing. Calling WriteTag does not confirm that the device accepted the value; verify the result in the runtime platform.
• Condition must return its result synchronously. It does not support fetch() or other asynchronous calls that return a Promise.
• A multi-line Click Script can finish naturally without a final return. Use return in branches that must exit early, such as when the user cancels.
• Don't navigate with relative disk paths: use hqVisuDesigner.openPage("PageName") within the same package, hqVisuDesigner.openScreen("SCREEN_CODE") across packages, and a URL only for real external sites.

Hover Script attaches pointer-enter and pointer-leave scripts to a component for highlighting or temporary hints. It runs when a user moves the pointer in the Mingcedar runtime. Restore any appearance changed on enter in the leave script.

Trigger is Pointer Move. Both script boxes support multi-line code, ReadTag* and async calls such as setTimeout and fetch. Hover actions must not write devices:

• Pointer Enter (mouse over; called Mouse Over in the docs): script that runs when the pointer enters the shape.
• Pointer Leave (mouse out; called Mouse Out in the docs): script that runs when the pointer leaves, used to undo what the enter script changed.
• Context objects available in the script: object, objects, event (mouse context) plus tag, page, presentation, shape, hqVisuDesigner, and globals.
• object is the current shape's DOM element, so you can set its style directly (e.g. object.style.opacity); shape.name is the shape name.
• Note: Hover Script has no Enable/Condition gate (unlike Click Script); both scripts simply run.

// Pointer Enter (mouse over)
object.style.opacity = "0.7";

// Pointer Leave (mouse out)
object.style.opacity = "1";

Use for highlights and hints without a click.

• Device-icon hover highlight: dim the opacity or add a stroke when the pointer is over a pump/valve, restore on leave, to signal it is clickable.
• Temporary info hint: on enter use hqVisuDesigner to show a note or emphasis border on the page, clear it on leave, without interrupting the operator.

Check runtime and restoration behavior:

• Enter changes are not auto-undone: you must write the matching restore logic in Pointer Leave, or the effect stays after the pointer leaves.
• It runs only on real pointer interaction in the exported/host page, not in PowerPoint edit mode, so verify after export.
• Do not call WriteTag* from Hover Script. The runtime grants write capability only to trusted click or Pointer Button press/release actions; keep hover purely visual.

Press/Release Script has a fixed Pointer Button trigger. The runtime accepts a real primary left-pointer interaction: pointerdown runs Pointer Press, while pointerup, pointercancel, or lost pointer capture enters Pointer Release. Unlike Click Script, it distinguishes the held and released phases.

The editor provides two full script boxes, Pointer Press and Pointer Release, with no separate Condition field. The press script enters a temporary state; the release script exits or resets it. Both scripts can use object, objects, event, tag, page, presentation, shape, hqVisuDesigner, and globals.

• Pointer Press: runs on the primary pointer press, for example write a momentary command true, show a pressed state, or begin a temporary action.
• Pointer Release: runs on release, cancellation, or lost capture, for example write false, restore styling, or end the action.
• Each script is syntax-validated separately. An empty phase script does not run.
• Tag writes still depend on host permission, confirmation, reason, and audit processing; a script call is not proof that the device completed the action.

// Pointer Press
WriteTagBoolean("<CommandTag>", true);

// Pointer Release
WriteTagBoolean("<CommandTag>", false);

Use it for actions that remain active until the operator releases the pointer: motor jog, manual valve movement, a temporary acknowledgement, a hold-to-preview state, or pressed-state feedback. Keep one-shot submissions, navigation, and fixed writes in Click Script, Open Link, or Write Tag.

Keep the release script short, idempotent, and safe to repeat. Never configure only the press side and omit the reset path, and never treat this UI behavior as a replacement for PLC interlocks, emergency stops, or a safety circuit. If a host write outcome is uncertain, the runtime may block a later release write; the PLC/control system must enforce the final safe state for critical equipment.

Data quality indicates whether Tag data is valid; process states such as running, stopped and alarmed are separate. In Script Text, select Use quality outline colors under Quality Override and set Good and Bad colors. State Color provides Follow data quality (border / hide), with an option to hide on bad quality.

Condition has a different role in each behavior. Use the table and the corresponding editor to configure it.

For example, enter the expression below in Script Text Condition to evaluate its text only when the specified Tag has good quality. Replace the example name with your project Tag and verify both good and bad quality. Configure the corresponding Quality Override when a persistent quality indication is required.

• Condition must return a Boolean immediately; do not use fetch, promises or timers.
• Condition does not replace Mingcedar write permissions or equipment interlocks.
• Move / Rotate / Scale currently have no separate Post Operations input.

ReadTagQualityGood("PLC_LINE01.PUMP01.SPEED")