Understand the scope and execution boundary of Page Script, behavior Definition, animation expressions, and interaction scripts, then use the complete send/read/type/limit workflow for Open Link, openPage, and page popups.
Start with the five script locations
HQ VISU Designer has no global script document that automatically spans every page. Where code is placed determines who can reference it, when it runs, and whether asynchronous work or device writes are allowed.
- Page Script: belongs to the current page. Top-level var, let, const, class, and function declarations are available to animations and expressions on that page.
- hqVisuDesignerPageReady(ctx): runs once after the page runtime is ready and suits component initialization; constants and helpers needed by the first animation evaluation still belong at Page Script top level.
- Definition / Setup Script: prepares variables and intermediate results for one behavior only; it is not a page-global area.
- Condition / Active / Enabled / Value / Text / Fill / Border / Visibility / Source Value: synchronous expression slots that must immediately return one result.
- Click / Hover / Press-Release Script: full event-driven script bodies. WriteTag is allowed only for a genuine Click, Press, or Release; Hover cannot write device data.
Recommended animation-script split
Put Tag prefixes, engineering ranges, conversion helpers, and formatters shared by several animations in Page Script. Put one behavior's reads and intermediate calculations in Definition. Keep the output field as the final expression. This preserves reuse while making each behavior's final result easy to inspect.
// Current Page Script: shared on this page
const pumpTagPrefix = "PLC_LINE01.PUMP01";
function percent(value, min, max) {
return Math.max(0, Math.min(100, (value - min) * 100 / (max - min)));
}
// Scale Definition: this behavior only
var level = ReadTagDouble(pumpTagPrefix + ".LEVEL", 0);
var levelPercent = percent(level, 0, 10);
// Scale Source Value: final result only
levelPercent
Synchronous, asynchronous, and write boundaries
Do not put fetch, Promise, setTimeout, or setInterval directly in an expression slot because animation evaluation needs an immediate result. Prepare asynchronous data in an async function in Page Script, hqVisuDesignerPageReady, Click Script, or Hover Script, then expose a page variable or host data source for the animation to read. await is valid only inside an async function; top-level await and import/export module syntax are unsupported. Device writes require a genuine user click, press, or release and remain subject to host permission, confirmation, reason, and audit controls.
Navigation parameters: supported content
Open Link supports Jump Parameters for Presentation Page, File / URL, and Website; System Screen and Script Action do not expose the section directly. Scripted navigation passes the second hqVisuDesigner.openPage argument. Values may be strings, numbers, booleans, or null, but the destination reads strings and reads null as an empty string.
- parameters must be an array whose entries have { key, value }.
- The array preserves order and repeated keys. A plain object is not the formal openPage parameter shape.
- frameTarget supports frame, fullscreen, and _blank; openInNewWindow: true is equivalent to _blank.
- Use openPage within one package. Use openScreen(screenCode) across packages, but generic Jump Parameters are not guaranteed across a screen-package boundary.
- Website / File URL parameters become URL query values and are read according to the destination system's query rules.
hqVisuDesigner.openPage("device_details", {
frameTarget: "frame",
parameters: [
{ key: "PLC", value: "PLC_LINE01" },
{ key: "Device", value: "PUMP_01" },
{ key: "Mode", value: 1 },
{ key: "Enabled", value: true }
]
});
Destination reads and type conversion
Read parameters in the destination Page Script and validate before use. GetPageParameter returns the first matching value; GetPageParameterValues returns every value for a repeated key; GetPageParameters returns every { key, value } in original order. All three also have hqVisuDesigner namespace forms. Every read value is a string, so explicitly convert numbers and booleans and constrain allowed characters before building a Tag name.
var plc = GetPageParameter("PLC", "");
var device = GetPageParameter("Device", "");
var modeText = GetPageParameter("Mode", "0");
var enabledText = GetPageParameter("Enabled", "false");
if (!/^[A-Za-z0-9_-]{1,64}$/.test(plc) ||
!/^[A-Za-z0-9_-]{1,64}$/.test(device)) {
throw new Error("Invalid page parameter");
}
var mode = Number.parseInt(modeText, 10);
var enabled = enabledText === "true";
var statusTag = plc + "." + device + ".STATUS";
Popup parameters and close results
Open Page as Popup uses an object: static mode accepts a JSON object and dynamic mode evaluates an expression that returns an object. A top-level array is invalid and an object cannot represent repeated keys. The popup destination still reads values through GetPageParameter*. Close Current Popup's Result expression is a reverse result channel from the popup to its opener and may return a boolean, number, string, or object; it is separate from the query parameters used to open the popup.
Count, length, and security limits
The Runtime keeps at most 64 navigation parameters. A key is limited to 256 characters and a value to 2048 characters; invalid entries are ignored. Parameters enter the URL query and must not carry passwords, tokens, authorization proof, sensitive personal data, or large JSON payloads. Cookie, localStorage, and sessionStorage depend on origin, iframe, and host loading details and are not a formal cross-page parameter protocol. Page parameters cannot expand host-granted Tag, page, or user permissions.
Separate four value mechanisms and troubleshoot in order
Template variables, Runtime Variables, PLC Tags, and page parameters solve different problems. Template variables are substituted on an instance and before export; Runtime Variables link state on the current page; PLC Tags belong to the host data layer; page parameters carry context only when a destination is opened. If a read is empty, check whether the target type supports parameters, key spelling and case, whether parameters is an array, count/length limits, whether the host took over navigation, whether the destination URL contains the query, and whether a cross-package relative path was used by mistake.
