Product: Mingcedar Studio DESIGNER

Script methods | Mingcedar Studio

Choose the script entry point, read typed Tag values, update page objects, and pass data between pages. Start with standard behaviors when they cover the task.

Published 2026-10-25T12:48:42.687198377Z Updated 2026-10-25T12:48:42.687197375Z

<section id="preface" class="docs-block docs-block-intro"> <span class="section-kicker">Manual</span> <h2>Before Use</h2> <p>Choose the script entry point, read typed Tag values, update page objects, and pass data between pages. Start with standard behaviors when they cover the task.</p> </section> <section id="script-placement" class="docs-block"> <span class="section-kicker">Feature</span> <h2>Choose the script entry point</h2> <p>Add runtime logic to the current page with JavaScript. Top-level Page Script variables, constants, classes, and functions are available to every animation and expression on that page. Use ReadTag helpers for Tag values and hqVisuDesigner to drive components and navigation; hqVisuDesignerPageReady runs when the page is ready. Read one bit with the "TAGNAME[bit]" bracket syntax.</p> <div class="docs-detail-list"> <article id="script-placement-item-1" class="docs-detail-row"> <strong>Overview</strong> <p>Scripts add runtime logic to the current page, all in JavaScript. The plugin does not provide a Global Script document shared by the whole PowerPoint file. The Scripts group on the ribbon has one current-page entry point, Page Script; alarm.js is also a protected document for that page. Page Script top-level declarations are available to behaviors on the same page but do not automatically exist on other pages. ReadTag helpers read Tag values, while hqVisuDesigner changes component text, color, visibility, layout, and navigation. WriteTag helpers are allowed during real user click, press or release actions, not in Page Script, Setup Script, or Hover Script. Behavior Setup Script / Condition / Value / Text fields use the same ECMAScript 2022 syntax boundary; expression fields must return one synchronous result.</p> </article><article id="script-placement-item-2" class="docs-detail-row"> <strong>Use Script Workspace from New to Save</strong> <p>Open Scripts → Page Script. Select a document, or click New and enter Folder and Name. Write in Code; clear Enabled to keep a document without exporting it. Save validates and writes all enabled documents on this page.</p> <ul> <li>Scope: confirm that the target page is active.</li><li>New or Ctrl+N: create a script document.</li><li>Folder: optional slash-separated path.</li><li>Name: document name without the .js extension.</li><li>Enabled: a disabled document is retained but not exported or validated on Save.</li><li>Script Library or Ctrl+J: insert a method or template at the caret.</li><li>Save or Ctrl+S: validate and save the complete workspace.</li><li>Help or F1: open script help.</li> </ul> </article><article id="script-placement-item-3" class="docs-detail-row"> <strong>Quick Methods library</strong> <p>Open Quick Methods: filter categories on the left, select a method in the middle, and review its purpose, example and parameters on the right. Search and click Insert to add a snippet. Available methods depend on the installed version.</p> </article><article id="script-placement-item-4" class="docs-detail-row"> <strong>Delete documents and keep protected alarm.js</strong> <p>Select a custom document, click Delete and confirm. Protected alarm.js cannot be deleted; edit its alarm configuration to disable or change page alarm display.</p> <ul> <li>Before deleting, confirm no behavior or other document uses its functions or variables.</li><li>Delete applies only to removable custom documents.</li><li>alarm.js is protected; edit its configuration instead.</li><li>Choose Cancel, not Save, when you want to discard all pending workspace edits.</li> </ul> </article><article id="script-placement-item-5" class="docs-detail-row"> <strong>How to use it: common methods and syntax</strong> <p>Set window.hqVisuDesignerPageReady in Page Script for initialization; it runs once when the page runtime is ready. Common methods follow:</p> <ul> <li>Read tags, ReadTag family: ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString; the second argument is the fallback value used when the tag cannot be read</li><li>Date/time helpers: GetCurrentDate() returns yyyy-MM-dd, GetCurrentDateTime() returns yyyy-MM-dd HH:mm:ss, and FormatDateTime(value, "yyyy/MM/dd HH:mm:ss") formats an existing date/time value; search keywords include time, date, datetime, 时间, 日期</li><li>Read a single bit (key point): append a bracketed bit number to the complete tag name, for example "PLC_LINE01.PUMP01.STATUS[3]", and read it with ReadTagBoolean; the bit number is zero-based, range 0-31, with no spaces inside the brackets</li><li>Tag quality: ReadTagQuality(name, "bad") returns the quality text, ReadTagQualityGood(name) tests whether it is good (quality is only good / bad, not the process value)</li><li>Write tags, WriteTag family: use only in a real user-click script; the host still decides permission, confirmation, reason capture, and the final asynchronous outcome</li><li>Drive components, hqVisuDesigner: setComponentText(nameOrId, value), setComponentFill, setComponentBorder, setComponentVisible, setComponentLayout, findComponent, getComponentData</li><li>Navigation and variables, hqVisuDesigner: openPage("PageName"), openScreen("SCREEN_CODE"), openWebsite(url, openInNewWindow), writeVariable(name, value), and refreshView()</li> </ul> <pre class="docs-code-block"><code>// Page Script: initialize when the page is ready

window.hqVisuDesignerPageReady = function (ctx) {

// Read bit 0 from an integer tag (bracket syntax, no spaces)

const pumpRun = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);

hqVisuDesigner.setComponentText("Title 1", pumpRun ? "RUN" : "STOP");

hqVisuDesigner.setComponentFill("Lamp 1", pumpRun ? "#22C55E" : "#EF4444");

hqVisuDesigner.refreshView();

};</code></pre> </article><article id="script-placement-item-6" class="docs-detail-row"> <strong>Common JS snippets: date/time, status text, and safe defaults</strong> <p>Use these snippets in Page Script, Click Script, or a behavior Setup Script area. Condition / Value / Text slots should contain only the final expression that returns immediately; longer checks and formatting belong in Setup Script or a script body.</p> <ul> <li>Ternary expression: condition ? trueValue : falseValue, useful for converting a boolean to text, color, or a numeric value.</li><li>Safe defaults: the second argument of ReadTagBoolean / ReadTagDouble and similar helpers is the fallback when the tag cannot be read.</li><li>Date/time text: use GetCurrentDate() for the current date, GetCurrentDateTime() for the current date-time, and FormatDateTime(...) for display formatting.</li><li>Multiple conditions: use a ternary for simple cases; use if / else to prepare variables before writing to a component or returning a behavior value.</li> </ul> <pre class="docs-code-block"><code>// date / time

const today = GetCurrentDate(); // yyyy-MM-dd

const nowText = GetCurrentDateTime(); // yyyy-MM-dd HH:mm:ss

const displayTime = FormatDateTime(nowText, "yyyy/MM/dd HH:mm:ss");

// Boolean status to text

const currentValue = ReadTagBoolean("PLC_LINE01.PUMP01.READY", false);

let text = currentValue ? "OK" : "Fault";

// Numeric banding

const speed = ReadTagDouble("PLC_LINE01.MOTOR01.SPEED", 0);

const levelText = speed >= 80 ? "High" : (speed >= 40 ? "Medium" : "Low");

// Quality guard: show communication fault first when quality is bad

if (!ReadTagQualityGood("PLC_LINE01.MOTOR01.SPEED")) {

text = "Communication fault";

}

hqVisuDesigner.setComponentText("StatusText", `${text} / ${displayTime}`);

hqVisuDesigner.setComponentText("LevelText", levelText);</code></pre> </article><article id="script-placement-item-7" class="docs-detail-row"> <strong>Common JS syntax: string concatenation, number formatting, arrays, and objects</strong> <p>Format Tag values with strings, numbers, arrays and objects in Setup Script or Page Script, then return the result to a behavior or write it to a component.</p> <ul> <li>String concatenation: use 'Speed: ' + speed for simple text; use template strings like `Speed: ${speed}` when several values are involved.</li><li>Number formatting: use Number(value).toFixed(1) to control decimal places.</li><li>Arrays: keep status lists, alarm lists, or multiple component names in arrays, then loop through them.</li><li>Objects: keep lookup tables such as state code to text, color, and priority.</li> </ul> <pre class="docs-code-block"><code>// String concatenation and template strings

const speed = ReadTagDouble('PLC_LINE01.MOTOR01.SPEED', 0);

const unit = ' rpm';

const speedText = `Speed: ${Number(speed).toFixed(1)}${unit}`;

const timeText = `Updated: ${GetCurrentDateTime()}`;

// Object map: state code to text and color

const state = ReadTagInteger('PLC_LINE01.MOTOR01.STATE', 0);

const stateMap = {

0: { text: 'Stopped', color: '#94A3B8' },

1: { text: 'Running', color: '#22C55E' },

2: { text: 'Fault', color: '#EF4444' }

};

const stateInfo = stateMap[state] ?? { text: 'Unknown', color: '#F59E0B' };

// Arrays: update several components

const targetNames = ['SpeedText', 'SpeedTextCopy'];

targetNames.forEach((name) => hqVisuDesigner.setComponentText(name, speedText));

hqVisuDesigner.setComponentText('StateText', `${stateInfo.text} / ${timeText}`);

hqVisuDesigner.setComponentFill('StateLamp', stateInfo.color);</code></pre> </article><article id="script-placement-item-8" class="docs-detail-row"> <strong>When to use it</strong> <p>Put shared page functions, constants and Tag prefixes at Page Script top level; put initialization in hqVisuDesignerPageReady. For advanced cross-page reuse, use the host runtime, custom SDK or templates. Use bracket bit reads to drive displays from an integer Tag’s Boolean bit.</p> <ul> <li>Put same-page helpers, constants, and Tag prefixes in the current page's Page Script</li><li>Use hqVisuDesigner.openPage(...) for same-package pages and hqVisuDesigner.openScreen(...) across packages; do not write disk-relative paths like ../../other-screen/index.html</li> </ul> </article><article id="script-placement-item-9" class="docs-detail-row"> <strong>Limitations and troubleshooting</strong> <p>Configuration requirements: (1) Bit-read must use exact "TAGNAME[bit]" syntax with no spaces, and bit numbers are 0-31. Bit writes use the parent integer Tag plus BitIndex; never write TAGNAME[3] as an ordinary Tag. (2) WriteTag is allowed during real user click, press or release actions and is still subject to host permission, confirmation, reason capture, and asynchronous outcome. (3) Async APIs belong only in script-body fields; await must be inside an async function and top-level await is unsupported. (4) import/export are module syntax and are not supported by page documents or animation expressions; advanced modules belong in the custom SDK.</p> </article> </div> <div class="docs-note-grid"> <figure id="script-placement-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/scripts/workspace.png" alt="Mingcedar Studio Script Workspace" loading="lazy" decoding="async"> <figcaption> <strong>Script Workspace</strong> <p>Edit JavaScript documents for the current page; at runtime use ReadTag and hqVisuDesigner to drive the screen.</p> </figcaption> </figure><figure id="script-placement-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/quick-methods.png" alt="Quick Methods library showing categories, methods, code example, and parameter details" loading="lazy" decoding="async"> <figcaption> <strong>Quick Methods library</strong> <p>Browse or search for a method, review its example and parameters, then click Insert. The visible count belongs to this plugin version.</p> </figcaption> </figure> </div> </section><section id="config-methods" class="docs-block"> <span class="section-kicker">Feature</span> <h2>Read page and project configuration</h2> <p>Add runtime logic to the current page with JavaScript. Top-level Page Script variables, constants, classes, and functions are available to every animation and expression on that page. Use ReadTag helpers for Tag values and hqVisuDesigner to drive components and navigation; hqVisuDesignerPageReady runs when the page is ready. Read one bit with the "TAGNAME[bit]" bracket syntax.</p> <div class="docs-detail-list"> <article id="config-methods-item-1" class="docs-detail-row"> <strong>Overview</strong> <p>Scripts add runtime logic to the current page, all in JavaScript. The plugin does not provide a Global Script document shared by the whole PowerPoint file. The Scripts group on the ribbon has one current-page entry point, Page Script; alarm.js is also a protected document for that page. Page Script top-level declarations are available to behaviors on the same page but do not automatically exist on other pages. ReadTag helpers read Tag values, while hqVisuDesigner changes component text, color, visibility, layout, and navigation. WriteTag helpers are allowed during real user click, press or release actions, not in Page Script, Setup Script, or Hover Script. Behavior Setup Script / Condition / Value / Text fields use the same ECMAScript 2022 syntax boundary; expression fields must return one synchronous result.</p> </article><article id="config-methods-item-2" class="docs-detail-row"> <strong>Use Script Workspace from New to Save</strong> <p>Open Scripts → Page Script. Select a document, or click New and enter Folder and Name. Write in Code; clear Enabled to keep a document without exporting it. Save validates and writes all enabled documents on this page.</p> <ul> <li>Scope: confirm that the target page is active.</li><li>New or Ctrl+N: create a script document.</li><li>Folder: optional slash-separated path.</li><li>Name: document name without the .js extension.</li><li>Enabled: a disabled document is retained but not exported or validated on Save.</li><li>Script Library or Ctrl+J: insert a method or template at the caret.</li><li>Save or Ctrl+S: validate and save the complete workspace.</li><li>Help or F1: open script help.</li> </ul> </article><article id="config-methods-item-3" class="docs-detail-row"> <strong>Quick Methods library</strong> <p>Open Quick Methods: filter categories on the left, select a method in the middle, and review its purpose, example and parameters on the right. Search and click Insert to add a snippet. Available methods depend on the installed version.</p> </article><article id="config-methods-item-4" class="docs-detail-row"> <strong>Delete documents and keep protected alarm.js</strong> <p>Select a custom document, click Delete and confirm. Protected alarm.js cannot be deleted; edit its alarm configuration to disable or change page alarm display.</p> <ul> <li>Before deleting, confirm no behavior or other document uses its functions or variables.</li><li>Delete applies only to removable custom documents.</li><li>alarm.js is protected; edit its configuration instead.</li><li>Choose Cancel, not Save, when you want to discard all pending workspace edits.</li> </ul> </article><article id="config-methods-item-5" class="docs-detail-row"> <strong>How to use it: common methods and syntax</strong> <p>Set window.hqVisuDesignerPageReady in Page Script for initialization; it runs once when the page runtime is ready. Common methods follow:</p> <ul> <li>Read tags, ReadTag family: ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString; the second argument is the fallback value used when the tag cannot be read</li><li>Date/time helpers: GetCurrentDate() returns yyyy-MM-dd, GetCurrentDateTime() returns yyyy-MM-dd HH:mm:ss, and FormatDateTime(value, "yyyy/MM/dd HH:mm:ss") formats an existing date/time value; search keywords include time, date, datetime, 时间, 日期</li><li>Read a single bit (key point): append a bracketed bit number to the complete tag name, for example "PLC_LINE01.PUMP01.STATUS[3]", and read it with ReadTagBoolean; the bit number is zero-based, range 0-31, with no spaces inside the brackets</li><li>Tag quality: ReadTagQuality(name, "bad") returns the quality text, ReadTagQualityGood(name) tests whether it is good (quality is only good / bad, not the process value)</li><li>Write tags, WriteTag family: use only in a real user-click script; the host still decides permission, confirmation, reason capture, and the final asynchronous outcome</li><li>Drive components, hqVisuDesigner: setComponentText(nameOrId, value), setComponentFill, setComponentBorder, setComponentVisible, setComponentLayout, findComponent, getComponentData</li><li>Navigation and variables, hqVisuDesigner: openPage("PageName"), openScreen("SCREEN_CODE"), openWebsite(url, openInNewWindow), writeVariable(name, value), and refreshView()</li> </ul> <pre class="docs-code-block"><code>// Page Script: initialize when the page is ready

window.hqVisuDesignerPageReady = function (ctx) {

// Read bit 0 from an integer tag (bracket syntax, no spaces)

const pumpRun = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);

hqVisuDesigner.setComponentText("Title 1", pumpRun ? "RUN" : "STOP");

hqVisuDesigner.setComponentFill("Lamp 1", pumpRun ? "#22C55E" : "#EF4444");

hqVisuDesigner.refreshView();

};</code></pre> </article><article id="config-methods-item-6" class="docs-detail-row"> <strong>Common JS snippets: date/time, status text, and safe defaults</strong> <p>Use these snippets in Page Script, Click Script, or a behavior Setup Script area. Condition / Value / Text slots should contain only the final expression that returns immediately; longer checks and formatting belong in Setup Script or a script body.</p> <ul> <li>Ternary expression: condition ? trueValue : falseValue, useful for converting a boolean to text, color, or a numeric value.</li><li>Safe defaults: the second argument of ReadTagBoolean / ReadTagDouble and similar helpers is the fallback when the tag cannot be read.</li><li>Date/time text: use GetCurrentDate() for the current date, GetCurrentDateTime() for the current date-time, and FormatDateTime(...) for display formatting.</li><li>Multiple conditions: use a ternary for simple cases; use if / else to prepare variables before writing to a component or returning a behavior value.</li> </ul> <pre class="docs-code-block"><code>// date / time

const today = GetCurrentDate(); // yyyy-MM-dd

const nowText = GetCurrentDateTime(); // yyyy-MM-dd HH:mm:ss

const displayTime = FormatDateTime(nowText, "yyyy/MM/dd HH:mm:ss");

// Boolean status to text

const currentValue = ReadTagBoolean("PLC_LINE01.PUMP01.READY", false);

let text = currentValue ? "OK" : "Fault";

// Numeric banding

const speed = ReadTagDouble("PLC_LINE01.MOTOR01.SPEED", 0);

const levelText = speed >= 80 ? "High" : (speed >= 40 ? "Medium" : "Low");

// Quality guard: show communication fault first when quality is bad

if (!ReadTagQualityGood("PLC_LINE01.MOTOR01.SPEED")) {

text = "Communication fault";

}

hqVisuDesigner.setComponentText("StatusText", `${text} / ${displayTime}`);

hqVisuDesigner.setComponentText("LevelText", levelText);</code></pre> </article><article id="config-methods-item-7" class="docs-detail-row"> <strong>Common JS syntax: string concatenation, number formatting, arrays, and objects</strong> <p>Format Tag values with strings, numbers, arrays and objects in Setup Script or Page Script, then return the result to a behavior or write it to a component.</p> <ul> <li>String concatenation: use 'Speed: ' + speed for simple text; use template strings like `Speed: ${speed}` when several values are involved.</li><li>Number formatting: use Number(value).toFixed(1) to control decimal places.</li><li>Arrays: keep status lists, alarm lists, or multiple component names in arrays, then loop through them.</li><li>Objects: keep lookup tables such as state code to text, color, and priority.</li> </ul> <pre class="docs-code-block"><code>// String concatenation and template strings

const speed = ReadTagDouble('PLC_LINE01.MOTOR01.SPEED', 0);

const unit = ' rpm';

const speedText = `Speed: ${Number(speed).toFixed(1)}${unit}`;

const timeText = `Updated: ${GetCurrentDateTime()}`;

// Object map: state code to text and color

const state = ReadTagInteger('PLC_LINE01.MOTOR01.STATE', 0);

const stateMap = {

0: { text: 'Stopped', color: '#94A3B8' },

1: { text: 'Running', color: '#22C55E' },

2: { text: 'Fault', color: '#EF4444' }

};

const stateInfo = stateMap[state] ?? { text: 'Unknown', color: '#F59E0B' };

// Arrays: update several components

const targetNames = ['SpeedText', 'SpeedTextCopy'];

targetNames.forEach((name) => hqVisuDesigner.setComponentText(name, speedText));

hqVisuDesigner.setComponentText('StateText', `${stateInfo.text} / ${timeText}`);

hqVisuDesigner.setComponentFill('StateLamp', stateInfo.color);</code></pre> </article><article id="config-methods-item-8" class="docs-detail-row"> <strong>When to use it</strong> <p>Put shared page functions, constants and Tag prefixes at Page Script top level; put initialization in hqVisuDesignerPageReady. For advanced cross-page reuse, use the host runtime, custom SDK or templates. Use bracket bit reads to drive displays from an integer Tag’s Boolean bit.</p> <ul> <li>Put same-page helpers, constants, and Tag prefixes in the current page's Page Script</li><li>Use hqVisuDesigner.openPage(...) for same-package pages and hqVisuDesigner.openScreen(...) across packages; do not write disk-relative paths like ../../other-screen/index.html</li> </ul> </article><article id="config-methods-item-9" class="docs-detail-row"> <strong>Limitations and troubleshooting</strong> <p>Configuration requirements: (1) Bit-read must use exact "TAGNAME[bit]" syntax with no spaces, and bit numbers are 0-31. Bit writes use the parent integer Tag plus BitIndex; never write TAGNAME[3] as an ordinary Tag. (2) WriteTag is allowed during real user click, press or release actions and is still subject to host permission, confirmation, reason capture, and asynchronous outcome. (3) Async APIs belong only in script-body fields; await must be inside an async function and top-level await is unsupported. (4) import/export are module syntax and are not supported by page documents or animation expressions; advanced modules belong in the custom SDK.</p> </article> </div> <div class="docs-note-grid"> <figure id="config-methods-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/scripts/workspace.png" alt="Mingcedar Studio Script Workspace" loading="lazy" decoding="async"> <figcaption> <strong>Script Workspace</strong> <p>Edit JavaScript documents for the current page; at runtime use ReadTag and hqVisuDesigner to drive the screen.</p> </figcaption> </figure><figure id="config-methods-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/quick-methods.png" alt="Quick Methods library showing categories, methods, code example, and parameter details" loading="lazy" decoding="async"> <figcaption> <strong>Quick Methods library</strong> <p>Browse or search for a method, review its example and parameters, then click Insert. The visible count belongs to this plugin version.</p> </figcaption> </figure> </div> </section><section id="tag-methods" class="docs-block"> <span class="section-kicker">Data binding</span> <h2>Tag names, typed reads, and writes</h2> <p>Identify whether a field expects a Tag name, a variable name, a number, or text. The leading = marks an expression in selected configuration fields. It is not general script syntax and does not grant Tag access.</p> <div class="docs-detail-list"> <article id="tag-methods-item-1" class="docs-detail-row"> <strong>1. Distinguish Tag names, runtime variables, and template parameters</strong> <p>Mingcedar supplies Tag data. Runtime variables hold state on the current page. Template parameters replace placeholders when configuring an instance. A variable containing a Tag name is still a string; a read method retrieves its value. Examples use PLC_LINE01, PUMP01, and TANK01. Replace them with names configured in your project.</p> <ul> <li>Full Tag name: `PLC_LINE01.PUMP01.SPEED`.</li><li>Calculated Tag name: `Line01TotalFlow`, exactly as saved in the host.</li><li>Runtime variables: `selectedSpeedTag` holds a name; `speedValue` holds a number.</li><li>Template placeholders: `<PLC>` and `<PUMP_CODE>`, replaced with instance values.</li> </ul> <pre class="docs-code-block"><code>// Page Script: store the target name

var selectedSpeedTag = "PLC_LINE01.PUMP01.SPEED";

// Behavior Setup Script: read the current value during evaluation

var speedValue = ReadTagDouble(selectedSpeedTag, 0);</code></pre> </article><article id="tag-methods-item-2" class="docs-detail-row"> <strong>2. Target fields in Tag Text and write behaviors</strong> <p>Target tag in Tag Text and Target Tag in Write Tag or Write Tag Bit identify the read or write target. Enter a full fixed name directly, or a variable that holds the name. Use = for object properties or computed names to distinguish them from literal Tag paths. The control performs the read or write; do not call ReadTag or WriteTag inside the target field.</p> <ul> <li>Fixed target: `PLC_LINE01.PUMP01.SPEED`.</li><li>Name variable: `selectedSpeedTag`; define it first and ensure it returns a string.</li><li>Object property: `=bindingConfig.speedTag`.</li><li>Write Tag Bit takes the parent Tag name and a separate Bit Index from 0 to 31.</li> </ul> </article><article id="tag-methods-item-3" class="docs-detail-row"> <strong>3. = expressions in Input and charts</strong> <p>The Input PLC Tag field, chart series Tag fields, Gauge Tag, and JSON Tag treat a fixed entry as a name. To obtain the name from a page variable, enter =selectedSpeedTag. The expression must return a Tag name string, not the current Tag value or a JSON object.</p> <ul> <li>Fixed Input target: `PLC_LINE01.PUMP01.SPEED_SETPOINT`.</li><li>Dynamic Input target: `=selectedSetpointTag`.</li><li>Dynamic chart target: `=selectedSpeedTag`.</li><li>JSON Tag: `PLC_LINE01.REPORT01.CHART_DATA`; use `=selectedJsonTag` for a dynamic name.</li> </ul> </article><article id="tag-methods-item-4" class="docs-detail-row"> <strong>4. Variable-name fields and value fields</strong> <p>In Input Runtime Variable mode, enter the destination name, such as speedSetpointDraft. A dynamic name can use =selectedVariableName, which must return a valid variable-name string. The Variable field in Set Variable on Click identifies the assignment target; Value supplies the content to assign.</p> <ul> <li>Fixed variable name without quotes: `speedSetpointDraft`.</li><li>Dynamic Input variable: define `var selectedVariableName = "speedSetpointDraft";` in Page Script and enter `=selectedVariableName` in the field.</li><li>Value and Condition are expression fields: enter `speedValue` or `speedValue > 1200` directly.</li><li>In JavaScript, use `ReadTagDouble(selectedSpeedTag, 0)`. Do not pass `"=selectedSpeedTag"` as an API name argument.</li> </ul> </article><article id="tag-methods-item-5" class="docs-detail-row"> <strong>5. Literal text and table data</strong> <p>Table Rows and Headers accept arrays, page array variables, or functions returning arrays. Use = to request evaluation explicitly. Quote a literal title when it could be confused with a variable. Table array data and the Tag name required by JSON Chart are different input types.</p> <ul> <li>Headers: `["Equipment", "Status"]`.</li><li>Rows: `[["PUMP01", "Running"], ["PUMP02", "Stopped"]]`.</li><li>Dynamic rows: `pumpRows` or `=buildPumpRows()`, returning an array.</li><li>Literal title: `"Pump station operating record"`.</li> </ul> </article><article id="tag-methods-item-6" class="docs-detail-row"> <strong>6. Combine template parameters and page variables</strong> <p>Set template parameter PLC to PLC_LINE01 and define the equipment code in Page Script. The template replaces <PLC> during authoring. At runtime, the page variable supplies the remaining name. Built-in template expressions use Page Script variables and cannot access another behavior's Setup Script locals. Enter each part below in the location identified by its comment. Lines beginning with = belong in configuration fields, not in a JavaScript script body.</p> <pre class="docs-code-block"><code>// Page Script

var selectedPumpCode = "PUMP01";

// Input or chart Tag field

="<PLC>." + selectedPumpCode + ".SPEED"

// Script Text: Setup Script

var speedTagName = "<PLC>." + selectedPumpCode + ".SPEED";

var speedValue = ReadTagDouble(speedTagName, 0);

// Script Text: Text

speedValue.toFixed(0) + " rpm"</code></pre> </article><article id="tag-methods-item-7" class="docs-detail-row"> <strong>7. Dynamic targets and page access</strong> <p>Variable-selected targets remain subject to export validation and Mingcedar read/write permissions. If export cannot determine a dynamic write target, use HQVISU_DECLARE_TAGS in Page Script to declare the finite candidate names associated with the expression. Those names must exist and be authorized in the host. Declarations do not bypass host permissions. Enter each part below in the location identified by its comment. Lines beginning with = belong in configuration fields, not in a JavaScript script body.</p> <pre class="docs-code-block"><code>var selectedSetpointTag = "PLC_LINE01.PUMP01.SPEED_SETPOINT";

HQVISU_DECLARE_TAGS({

expression: "selectedSetpointTag",

read: ["PLC_LINE01.PUMP01.SPEED_SETPOINT", "PLC_LINE01.PUMP02.SPEED_SETPOINT"],

write: ["PLC_LINE01.PUMP01.SPEED_SETPOINT", "PLC_LINE01.PUMP02.SPEED_SETPOINT"]

});

// Input PLC Tag field

=selectedSetpointTag</code></pre> </article><article id="tag-methods-item-8" class="docs-detail-row"> <strong>8. Evaluation failures and target changes</strong> <p>An explicit expression that fails, returns a non-string, or retains an unresolved placeholder is not reinterpreted as another Tag name. Check variable scope, return type, template values, and name case.</p> <ul> <li>Changing an Input target or binding mode cancels the old unsubmitted draft. Enter a new value for the new target.</li><li>A write already sent is not recalled by a subsequent target change.</li><li>A live chart clears samples from the previous target when its dynamic target changes.</li><li>Runtime variables belong to the current page. Use page parameters to transfer context to another page.</li> </ul> </article><article id="tag-methods-item-9" class="docs-detail-row"> <strong>1. Method and supported fields</strong> <p>Select Calculated Tag / Read in the function picker. Use the method in animation Value, Condition, Script Text, or page scripts. The global method and hqVisuDesigner.ReadCalculatedTag follow the same read rules.</p> <pre class="docs-code-block"><code>ReadCalculatedTag("Line01TotalFlow")

ReadCalculatedTag("Line01TotalFlow", null)

ReadCalculatedTag("Line01Ready", false)

hqVisuDesigner.ReadCalculatedTag("Line01TotalFlow", null)</code></pre> </article><article id="tag-methods-item-10" class="docs-detail-row"> <strong>2. Names and read-only behavior</strong> <p>Use the name saved in the Mingcedar calculated Tag list. Line01TotalFlow requires no PLC or CALC prefix. If the saved name is Line01.TotalFlow, retain the full name. Calculated Tags have no write method and cannot serve as PLC Tag write targets for Input.</p> <ul> <li>Names are at most 128 characters. Use ASCII letters, digits, underscores, and separator dots; each segment starts with a letter or underscore.</li><li>Bit suffixes such as [0] are not supported.</li><li>An ordinary Tag with the same name is not read as a calculated result.</li><li>Renaming an unpublished draft does not change the active published name. Update page references after publishing the new name.</li> </ul> </article><article id="tag-methods-item-11" class="docs-detail-row"> <strong>3. Defaults and data quality</strong> <p>A valid result with good quality returns a number or boolean, preserving 0 and false. Unloaded, unpublished, disabled, poor-quality, unauthorized, or unavailable subscriptions return the supplied default. Omitting the default returns null. A fallback supports display handling and is not a valid calculated result.</p> <ul> <li>Use null and display “--” when data is unavailable to distinguish it from a valid zero.</li><li>Use false when a condition requires a boolean fallback.</li><li>Use `ReadTagQuality("Line01TotalFlow")` to inspect quality. Data quality and process alarms have different meanings.</li> </ul> </article><article id="tag-methods-item-12" class="docs-detail-row"> <strong>4. Combine a template, a name variable, and a result variable</strong> <p>Set template parameter CALCULATED_TAG to Line01TotalFlow. In Setup Script, store the replaced name in calculatedTagName, then read the result. Display Text formats the result. A template parameter used in several fields must satisfy every field's requirements. Use separate parameters, such as CALCULATED_TAG and SETPOINT_TAG, for calculated reads and PLC write targets. Enter Setup Script and Display Text in their respective fields.</p> <pre class="docs-code-block"><code>// Setup Script

var calculatedTagName = "<CALCULATED_TAG>";

var totalFlow = ReadCalculatedTag(calculatedTagName, null);

// Script Text: Text

totalFlow === null ? "--" : totalFlow.toFixed(1) + " m³/h"</code></pre> </article><article id="tag-methods-item-13" class="docs-detail-row"> <strong>5. Runtime verification</strong> <p>Confirm that the host calculated Tag is published, enabled, and has good quality. Then check the page name and permissions. A dynamically supplied name must resolve to a full name string. Reads reuse host latest values and subscriptions without additional PLC polling.</p> </article><article id="tag-methods-item-14" class="docs-detail-row"> <strong>Overview</strong> <p>Scripts add runtime logic to the current page, all in JavaScript. The plugin does not provide a Global Script document shared by the whole PowerPoint file. The Scripts group on the ribbon has one current-page entry point, Page Script; alarm.js is also a protected document for that page. Page Script top-level declarations are available to behaviors on the same page but do not automatically exist on other pages. ReadTag helpers read Tag values, while hqVisuDesigner changes component text, color, visibility, layout, and navigation. WriteTag helpers are allowed during real user click, press or release actions, not in Page Script, Setup Script, or Hover Script. Behavior Setup Script / Condition / Value / Text fields use the same ECMAScript 2022 syntax boundary; expression fields must return one synchronous result.</p> </article><article id="tag-methods-item-15" class="docs-detail-row"> <strong>Use Script Workspace from New to Save</strong> <p>Open Scripts → Page Script. Select a document, or click New and enter Folder and Name. Write in Code; clear Enabled to keep a document without exporting it. Save validates and writes all enabled documents on this page.</p> <ul> <li>Scope: confirm that the target page is active.</li><li>New or Ctrl+N: create a script document.</li><li>Folder: optional slash-separated path.</li><li>Name: document name without the .js extension.</li><li>Enabled: a disabled document is retained but not exported or validated on Save.</li><li>Script Library or Ctrl+J: insert a method or template at the caret.</li><li>Save or Ctrl+S: validate and save the complete workspace.</li><li>Help or F1: open script help.</li> </ul> </article><article id="tag-methods-item-16" class="docs-detail-row"> <strong>Quick Methods library</strong> <p>Open Quick Methods: filter categories on the left, select a method in the middle, and review its purpose, example and parameters on the right. Search and click Insert to add a snippet. Available methods depend on the installed version.</p> </article><article id="tag-methods-item-17" class="docs-detail-row"> <strong>Delete documents and keep protected alarm.js</strong> <p>Select a custom document, click Delete and confirm. Protected alarm.js cannot be deleted; edit its alarm configuration to disable or change page alarm display.</p> <ul> <li>Before deleting, confirm no behavior or other document uses its functions or variables.</li><li>Delete applies only to removable custom documents.</li><li>alarm.js is protected; edit its configuration instead.</li><li>Choose Cancel, not Save, when you want to discard all pending workspace edits.</li> </ul> </article><article id="tag-methods-item-18" class="docs-detail-row"> <strong>How to use it: common methods and syntax</strong> <p>Set window.hqVisuDesignerPageReady in Page Script for initialization; it runs once when the page runtime is ready. Common methods follow:</p> <ul> <li>Read tags, ReadTag family: ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString; the second argument is the fallback value used when the tag cannot be read</li><li>Date/time helpers: GetCurrentDate() returns yyyy-MM-dd, GetCurrentDateTime() returns yyyy-MM-dd HH:mm:ss, and FormatDateTime(value, "yyyy/MM/dd HH:mm:ss") formats an existing date/time value; search keywords include time, date, datetime, 时间, 日期</li><li>Read a single bit (key point): append a bracketed bit number to the complete tag name, for example "PLC_LINE01.PUMP01.STATUS[3]", and read it with ReadTagBoolean; the bit number is zero-based, range 0-31, with no spaces inside the brackets</li><li>Tag quality: ReadTagQuality(name, "bad") returns the quality text, ReadTagQualityGood(name) tests whether it is good (quality is only good / bad, not the process value)</li><li>Write tags, WriteTag family: use only in a real user-click script; the host still decides permission, confirmation, reason capture, and the final asynchronous outcome</li><li>Drive components, hqVisuDesigner: setComponentText(nameOrId, value), setComponentFill, setComponentBorder, setComponentVisible, setComponentLayout, findComponent, getComponentData</li><li>Navigation and variables, hqVisuDesigner: openPage("PageName"), openScreen("SCREEN_CODE"), openWebsite(url, openInNewWindow), writeVariable(name, value), and refreshView()</li> </ul> <pre class="docs-code-block"><code>// Page Script: initialize when the page is ready

window.hqVisuDesignerPageReady = function (ctx) {

// Read bit 0 from an integer tag (bracket syntax, no spaces)

const pumpRun = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);

hqVisuDesigner.setComponentText("Title 1", pumpRun ? "RUN" : "STOP");

hqVisuDesigner.setComponentFill("Lamp 1", pumpRun ? "#22C55E" : "#EF4444");

hqVisuDesigner.refreshView();

};</code></pre> </article><article id="tag-methods-item-19" class="docs-detail-row"> <strong>Common JS snippets: date/time, status text, and safe defaults</strong> <p>Use these snippets in Page Script, Click Script, or a behavior Setup Script area. Condition / Value / Text slots should contain only the final expression that returns immediately; longer checks and formatting belong in Setup Script or a script body.</p> <ul> <li>Ternary expression: condition ? trueValue : falseValue, useful for converting a boolean to text, color, or a numeric value.</li><li>Safe defaults: the second argument of ReadTagBoolean / ReadTagDouble and similar helpers is the fallback when the tag cannot be read.</li><li>Date/time text: use GetCurrentDate() for the current date, GetCurrentDateTime() for the current date-time, and FormatDateTime(...) for display formatting.</li><li>Multiple conditions: use a ternary for simple cases; use if / else to prepare variables before writing to a component or returning a behavior value.</li> </ul> <pre class="docs-code-block"><code>// date / time

const today = GetCurrentDate(); // yyyy-MM-dd

const nowText = GetCurrentDateTime(); // yyyy-MM-dd HH:mm:ss

const displayTime = FormatDateTime(nowText, "yyyy/MM/dd HH:mm:ss");

// Boolean status to text

const currentValue = ReadTagBoolean("PLC_LINE01.PUMP01.READY", false);

let text = currentValue ? "OK" : "Fault";

// Numeric banding

const speed = ReadTagDouble("PLC_LINE01.MOTOR01.SPEED", 0);

const levelText = speed >= 80 ? "High" : (speed >= 40 ? "Medium" : "Low");

// Quality guard: show communication fault first when quality is bad

if (!ReadTagQualityGood("PLC_LINE01.MOTOR01.SPEED")) {

text = "Communication fault";

}

hqVisuDesigner.setComponentText("StatusText", `${text} / ${displayTime}`);

hqVisuDesigner.setComponentText("LevelText", levelText);</code></pre> </article><article id="tag-methods-item-20" class="docs-detail-row"> <strong>Common JS syntax: string concatenation, number formatting, arrays, and objects</strong> <p>Format Tag values with strings, numbers, arrays and objects in Setup Script or Page Script, then return the result to a behavior or write it to a component.</p> <ul> <li>String concatenation: use 'Speed: ' + speed for simple text; use template strings like `Speed: ${speed}` when several values are involved.</li><li>Number formatting: use Number(value).toFixed(1) to control decimal places.</li><li>Arrays: keep status lists, alarm lists, or multiple component names in arrays, then loop through them.</li><li>Objects: keep lookup tables such as state code to text, color, and priority.</li> </ul> <pre class="docs-code-block"><code>// String concatenation and template strings

const speed = ReadTagDouble('PLC_LINE01.MOTOR01.SPEED', 0);

const unit = ' rpm';

const speedText = `Speed: ${Number(speed).toFixed(1)}${unit}`;

const timeText = `Updated: ${GetCurrentDateTime()}`;

// Object map: state code to text and color

const state = ReadTagInteger('PLC_LINE01.MOTOR01.STATE', 0);

const stateMap = {

0: { text: 'Stopped', color: '#94A3B8' },

1: { text: 'Running', color: '#22C55E' },

2: { text: 'Fault', color: '#EF4444' }

};

const stateInfo = stateMap[state] ?? { text: 'Unknown', color: '#F59E0B' };

// Arrays: update several components

const targetNames = ['SpeedText', 'SpeedTextCopy'];

targetNames.forEach((name) => hqVisuDesigner.setComponentText(name, speedText));

hqVisuDesigner.setComponentText('StateText', `${stateInfo.text} / ${timeText}`);

hqVisuDesigner.setComponentFill('StateLamp', stateInfo.color);</code></pre> </article><article id="tag-methods-item-21" class="docs-detail-row"> <strong>When to use it</strong> <p>Put shared page functions, constants and Tag prefixes at Page Script top level; put initialization in hqVisuDesignerPageReady. For advanced cross-page reuse, use the host runtime, custom SDK or templates. Use bracket bit reads to drive displays from an integer Tag’s Boolean bit.</p> <ul> <li>Put same-page helpers, constants, and Tag prefixes in the current page's Page Script</li><li>Use hqVisuDesigner.openPage(...) for same-package pages and hqVisuDesigner.openScreen(...) across packages; do not write disk-relative paths like ../../other-screen/index.html</li> </ul> </article><article id="tag-methods-item-22" class="docs-detail-row"> <strong>Limitations and troubleshooting</strong> <p>Configuration requirements: (1) Bit-read must use exact "TAGNAME[bit]" syntax with no spaces, and bit numbers are 0-31. Bit writes use the parent integer Tag plus BitIndex; never write TAGNAME[3] as an ordinary Tag. (2) WriteTag is allowed during real user click, press or release actions and is still subject to host permission, confirmation, reason capture, and asynchronous outcome. (3) Async APIs belong only in script-body fields; await must be inside an async function and top-level await is unsupported. (4) import/export are module syntax and are not supported by page documents or animation expressions; advanced modules belong in the custom SDK.</p> </article> </div> <div class="docs-note-grid"> <figure id="tag-methods-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/scripts/workspace.png" alt="Mingcedar Studio Script Workspace" loading="lazy" decoding="async"> <figcaption> <strong>Script Workspace</strong> <p>Edit JavaScript documents for the current page; at runtime use ReadTag and hqVisuDesigner to drive the screen.</p> </figcaption> </figure><figure id="tag-methods-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/quick-methods.png" alt="Quick Methods library showing categories, methods, code example, and parameter details" loading="lazy" decoding="async"> <figcaption> <strong>Quick Methods library</strong> <p>Browse or search for a method, review its example and parameters, then click Insert. The visible count belongs to this plugin version.</p> </figcaption> </figure> </div> </section><section id="hqvisudesigner-runtime" class="docs-block"> <span class="section-kicker">Feature</span> <h2>Update page objects through hqVisuDesigner</h2> <p>Add runtime logic to the current page with JavaScript. Top-level Page Script variables, constants, classes, and functions are available to every animation and expression on that page. Use ReadTag helpers for Tag values and hqVisuDesigner to drive components and navigation; hqVisuDesignerPageReady runs when the page is ready. Read one bit with the "TAGNAME[bit]" bracket syntax.</p> <div class="docs-detail-list"> <article id="hqvisudesigner-runtime-item-1" class="docs-detail-row"> <strong>Overview</strong> <p>Scripts add runtime logic to the current page, all in JavaScript. The plugin does not provide a Global Script document shared by the whole PowerPoint file. The Scripts group on the ribbon has one current-page entry point, Page Script; alarm.js is also a protected document for that page. Page Script top-level declarations are available to behaviors on the same page but do not automatically exist on other pages. ReadTag helpers read Tag values, while hqVisuDesigner changes component text, color, visibility, layout, and navigation. WriteTag helpers are allowed during real user click, press or release actions, not in Page Script, Setup Script, or Hover Script. Behavior Setup Script / Condition / Value / Text fields use the same ECMAScript 2022 syntax boundary; expression fields must return one synchronous result.</p> </article><article id="hqvisudesigner-runtime-item-2" class="docs-detail-row"> <strong>Use Script Workspace from New to Save</strong> <p>Open Scripts → Page Script. Select a document, or click New and enter Folder and Name. Write in Code; clear Enabled to keep a document without exporting it. Save validates and writes all enabled documents on this page.</p> <ul> <li>Scope: confirm that the target page is active.</li><li>New or Ctrl+N: create a script document.</li><li>Folder: optional slash-separated path.</li><li>Name: document name without the .js extension.</li><li>Enabled: a disabled document is retained but not exported or validated on Save.</li><li>Script Library or Ctrl+J: insert a method or template at the caret.</li><li>Save or Ctrl+S: validate and save the complete workspace.</li><li>Help or F1: open script help.</li> </ul> </article><article id="hqvisudesigner-runtime-item-3" class="docs-detail-row"> <strong>Quick Methods library</strong> <p>Open Quick Methods: filter categories on the left, select a method in the middle, and review its purpose, example and parameters on the right. Search and click Insert to add a snippet. Available methods depend on the installed version.</p> </article><article id="hqvisudesigner-runtime-item-4" class="docs-detail-row"> <strong>Delete documents and keep protected alarm.js</strong> <p>Select a custom document, click Delete and confirm. Protected alarm.js cannot be deleted; edit its alarm configuration to disable or change page alarm display.</p> <ul> <li>Before deleting, confirm no behavior or other document uses its functions or variables.</li><li>Delete applies only to removable custom documents.</li><li>alarm.js is protected; edit its configuration instead.</li><li>Choose Cancel, not Save, when you want to discard all pending workspace edits.</li> </ul> </article><article id="hqvisudesigner-runtime-item-5" class="docs-detail-row"> <strong>How to use it: common methods and syntax</strong> <p>Set window.hqVisuDesignerPageReady in Page Script for initialization; it runs once when the page runtime is ready. Common methods follow:</p> <ul> <li>Read tags, ReadTag family: ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString; the second argument is the fallback value used when the tag cannot be read</li><li>Date/time helpers: GetCurrentDate() returns yyyy-MM-dd, GetCurrentDateTime() returns yyyy-MM-dd HH:mm:ss, and FormatDateTime(value, "yyyy/MM/dd HH:mm:ss") formats an existing date/time value; search keywords include time, date, datetime, 时间, 日期</li><li>Read a single bit (key point): append a bracketed bit number to the complete tag name, for example "PLC_LINE01.PUMP01.STATUS[3]", and read it with ReadTagBoolean; the bit number is zero-based, range 0-31, with no spaces inside the brackets</li><li>Tag quality: ReadTagQuality(name, "bad") returns the quality text, ReadTagQualityGood(name) tests whether it is good (quality is only good / bad, not the process value)</li><li>Write tags, WriteTag family: use only in a real user-click script; the host still decides permission, confirmation, reason capture, and the final asynchronous outcome</li><li>Drive components, hqVisuDesigner: setComponentText(nameOrId, value), setComponentFill, setComponentBorder, setComponentVisible, setComponentLayout, findComponent, getComponentData</li><li>Navigation and variables, hqVisuDesigner: openPage("PageName"), openScreen("SCREEN_CODE"), openWebsite(url, openInNewWindow), writeVariable(name, value), and refreshView()</li> </ul> <pre class="docs-code-block"><code>// Page Script: initialize when the page is ready

window.hqVisuDesignerPageReady = function (ctx) {

// Read bit 0 from an integer tag (bracket syntax, no spaces)

const pumpRun = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);

hqVisuDesigner.setComponentText("Title 1", pumpRun ? "RUN" : "STOP");

hqVisuDesigner.setComponentFill("Lamp 1", pumpRun ? "#22C55E" : "#EF4444");

hqVisuDesigner.refreshView();

};</code></pre> </article><article id="hqvisudesigner-runtime-item-6" class="docs-detail-row"> <strong>Common JS snippets: date/time, status text, and safe defaults</strong> <p>Use these snippets in Page Script, Click Script, or a behavior Setup Script area. Condition / Value / Text slots should contain only the final expression that returns immediately; longer checks and formatting belong in Setup Script or a script body.</p> <ul> <li>Ternary expression: condition ? trueValue : falseValue, useful for converting a boolean to text, color, or a numeric value.</li><li>Safe defaults: the second argument of ReadTagBoolean / ReadTagDouble and similar helpers is the fallback when the tag cannot be read.</li><li>Date/time text: use GetCurrentDate() for the current date, GetCurrentDateTime() for the current date-time, and FormatDateTime(...) for display formatting.</li><li>Multiple conditions: use a ternary for simple cases; use if / else to prepare variables before writing to a component or returning a behavior value.</li> </ul> <pre class="docs-code-block"><code>// date / time

const today = GetCurrentDate(); // yyyy-MM-dd

const nowText = GetCurrentDateTime(); // yyyy-MM-dd HH:mm:ss

const displayTime = FormatDateTime(nowText, "yyyy/MM/dd HH:mm:ss");

// Boolean status to text

const currentValue = ReadTagBoolean("PLC_LINE01.PUMP01.READY", false);

let text = currentValue ? "OK" : "Fault";

// Numeric banding

const speed = ReadTagDouble("PLC_LINE01.MOTOR01.SPEED", 0);

const levelText = speed >= 80 ? "High" : (speed >= 40 ? "Medium" : "Low");

// Quality guard: show communication fault first when quality is bad

if (!ReadTagQualityGood("PLC_LINE01.MOTOR01.SPEED")) {

text = "Communication fault";

}

hqVisuDesigner.setComponentText("StatusText", `${text} / ${displayTime}`);

hqVisuDesigner.setComponentText("LevelText", levelText);</code></pre> </article><article id="hqvisudesigner-runtime-item-7" class="docs-detail-row"> <strong>Common JS syntax: string concatenation, number formatting, arrays, and objects</strong> <p>Format Tag values with strings, numbers, arrays and objects in Setup Script or Page Script, then return the result to a behavior or write it to a component.</p> <ul> <li>String concatenation: use 'Speed: ' + speed for simple text; use template strings like `Speed: ${speed}` when several values are involved.</li><li>Number formatting: use Number(value).toFixed(1) to control decimal places.</li><li>Arrays: keep status lists, alarm lists, or multiple component names in arrays, then loop through them.</li><li>Objects: keep lookup tables such as state code to text, color, and priority.</li> </ul> <pre class="docs-code-block"><code>// String concatenation and template strings

const speed = ReadTagDouble('PLC_LINE01.MOTOR01.SPEED', 0);

const unit = ' rpm';

const speedText = `Speed: ${Number(speed).toFixed(1)}${unit}`;

const timeText = `Updated: ${GetCurrentDateTime()}`;

// Object map: state code to text and color

const state = ReadTagInteger('PLC_LINE01.MOTOR01.STATE', 0);

const stateMap = {

0: { text: 'Stopped', color: '#94A3B8' },

1: { text: 'Running', color: '#22C55E' },

2: { text: 'Fault', color: '#EF4444' }

};

const stateInfo = stateMap[state] ?? { text: 'Unknown', color: '#F59E0B' };

// Arrays: update several components

const targetNames = ['SpeedText', 'SpeedTextCopy'];

targetNames.forEach((name) => hqVisuDesigner.setComponentText(name, speedText));

hqVisuDesigner.setComponentText('StateText', `${stateInfo.text} / ${timeText}`);

hqVisuDesigner.setComponentFill('StateLamp', stateInfo.color);</code></pre> </article><article id="hqvisudesigner-runtime-item-8" class="docs-detail-row"> <strong>When to use it</strong> <p>Put shared page functions, constants and Tag prefixes at Page Script top level; put initialization in hqVisuDesignerPageReady. For advanced cross-page reuse, use the host runtime, custom SDK or templates. Use bracket bit reads to drive displays from an integer Tag’s Boolean bit.</p> <ul> <li>Put same-page helpers, constants, and Tag prefixes in the current page's Page Script</li><li>Use hqVisuDesigner.openPage(...) for same-package pages and hqVisuDesigner.openScreen(...) across packages; do not write disk-relative paths like ../../other-screen/index.html</li> </ul> </article><article id="hqvisudesigner-runtime-item-9" class="docs-detail-row"> <strong>Limitations and troubleshooting</strong> <p>Configuration requirements: (1) Bit-read must use exact "TAGNAME[bit]" syntax with no spaces, and bit numbers are 0-31. Bit writes use the parent integer Tag plus BitIndex; never write TAGNAME[3] as an ordinary Tag. (2) WriteTag is allowed during real user click, press or release actions and is still subject to host permission, confirmation, reason capture, and asynchronous outcome. (3) Async APIs belong only in script-body fields; await must be inside an async function and top-level await is unsupported. (4) import/export are module syntax and are not supported by page documents or animation expressions; advanced modules belong in the custom SDK.</p> </article> </div> <div class="docs-note-grid"> <figure id="hqvisudesigner-runtime-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/scripts/workspace.png" alt="Mingcedar Studio Script Workspace" loading="lazy" decoding="async"> <figcaption> <strong>Script Workspace</strong> <p>Edit JavaScript documents for the current page; at runtime use ReadTag and hqVisuDesigner to drive the screen.</p> </figcaption> </figure><figure id="hqvisudesigner-runtime-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/quick-methods.png" alt="Quick Methods library showing categories, methods, code example, and parameter details" loading="lazy" decoding="async"> <figcaption> <strong>Quick Methods library</strong> <p>Browse or search for a method, review its example and parameters, then click Insert. The visible count belongs to this plugin version.</p> </figcaption> </figure> </div> </section><section id="script-combos" class="docs-block"> <span class="section-kicker">Feature</span> <h2>Combine page parameters, scripts, and data export</h2> <p>Check script scope and execution limits, then configure page and popup parameters, type conversion and troubleshooting.</p> <div class="docs-detail-list"> <article id="script-combos-item-1" class="docs-detail-row"> <strong>Start with the five script locations</strong> <p>Code location determines scope, execution timing, and async/write permissions. Mingcedar Studio has no global script document spanning all pages.</p> <ul> <li>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.</li><li>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.</li><li>Setup Script: prepares variables and intermediate results for one behavior only; it is not a page-global area.</li><li>Condition / Value / Display Text / Fill / Border / Visibility / Source value: synchronous expression slots that must immediately return one result.</li><li>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.</li> </ul> </article><article id="script-combos-item-2" class="docs-detail-row"> <strong>Recommended animation-script split</strong> <p>Keep shared Tag prefixes, ranges, and conversion functions in Page Script. Color and text behaviors that provide Setup Script can prepare local results there. Move, Rotate, and Scale have no Setup Script or Post Operations field. Put reads and conversions directly in Source value or Rotation input and reusable helpers in Page Script.</p> <pre class="docs-code-block"><code>// Current Page Script

const tankTagPrefix = "PLC_LINE01.TANK01";

function percent(value, min, max) {

return Math.max(0, Math.min(100, (value - min) * 100 / (max - min)));

}

// Scale: Source value

percent(ReadTagDouble(tankTagPrefix + ".LEVEL", 0), 0, 10)

// Source minimum / maximum: 0 / 100

// Limit minimum / maximum: 0 / 100

// At limit minimum / maximum: 0 / 1

// Moving edge: Top</code></pre> </article><article id="script-combos-item-3" class="docs-detail-row"> <strong>Synchronous, asynchronous, and write boundaries</strong> <p>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.</p> </article><article id="script-combos-item-4" class="docs-detail-row"> <strong>Navigation parameters: supported content</strong> <p>In Open Link, select Internal page to enter values under Parameters (optional). For other Destinations, fill the fields for that target type. Scripted navigation passes parameters in the second hqVisuDesigner.openPage argument. Values may be strings, numbers, booleans, or null; the destination reads strings and reads null as an empty string.</p> <ul> <li>parameters must be an array whose entries have { key, value }.</li><li>The array preserves order and repeated keys. A plain object is not the formal openPage parameter shape.</li><li>frameTarget supports frame, fullscreen, and _blank; openInNewWindow: true is equivalent to _blank.</li><li>Use openPage within one package. Use openScreen(screenCode) across packages, but generic Jump Parameters are not guaranteed across a screen-package boundary.</li><li>Website / File URL parameters become URL query values and are read according to the destination system's query rules.</li> </ul> <pre class="docs-code-block"><code>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 }

]

});</code></pre> </article><article id="script-combos-item-5" class="docs-detail-row"> <strong>Destination reads and type conversion</strong> <p>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.</p> <pre class="docs-code-block"><code>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";</code></pre> </article><article id="script-combos-item-6" class="docs-detail-row"> <strong>Popup parameters and close results</strong> <p>The static Open Page as Popup input accepts a JSON object, not a top-level array. With Build page parameters with an expression enabled, the runtime accepts an object or an ordered array of { key, value } entries; use an array for 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.</p> </article><article id="script-combos-item-7" class="docs-detail-row"> <strong>Count, length, and security limits</strong> <p>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.</p> </article><article id="script-combos-item-8" class="docs-detail-row"> <strong>Separate four value mechanisms and troubleshoot in order</strong> <p>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.</p> </article><article id="script-combos-item-9" class="docs-detail-row"> <strong>1. Export structured JSON</strong> <p>ExportJson(value, fileName?) exports an object, array, or other serializable value. Its default filename is export.json. Strings remain strings. Read a JSON Tag with ReadTagJson first when exporting its structured value.</p> <pre class="docs-code-block"><code>ExportJson(

ReadTagJson("PLC_LINE01.REPORT01.SUMMARY", null),

"line01-production-summary.json"

);</code></pre> </article><article id="script-combos-item-10" class="docs-detail-row"> <strong>2. Export a current-page data table</strong> <p>ExportTable(nameOrId, fileName?, format?) supports built-in data tables on the current page. Formats are csv, json, xlsx, and excel (an xlsx alias), with CSV as the default. Supply the Table component's Name from Behavior Browser or its shapeId, with matching case. Use a unique component name; the displayed Table name is a title and cannot locate the component. The export includes all currently bound rows, including rows outside the scroll viewport, and preserves cell display text.</p> <pre class="docs-code-block"><code>ExportTable("Line01ProductionTable", "line01-production.csv", "csv");

ExportTable("Line01ProductionTable", "line01-production.xlsx", "xlsx");</code></pre> </article><article id="script-combos-item-11" class="docs-detail-row"> <strong>3. Export current Tag values and quality</strong> <p>ExportTags(tagNames, fileName?, format?) accepts one Tag name or a non-empty name array. It supports csv, json, and xlsx, defaulting to CSV. It exports current values without querying history. CSV / XLSX columns are Tag, Value, Quality; JSON records contain name, value, quality.</p> <pre class="docs-code-block"><code>ExportTags(

["PLC_LINE01.PUMP01.SPEED", "PLC_LINE01.PUMP01.RUN"],

"line01-pump-status.json",

"json"

);</code></pre> </article><article id="script-combos-item-12" class="docs-detail-row"> <strong>4. Preconditions and result meaning</strong> <p>Start downloads from a user click after data is loaded and the page has permission to read the relevant Tags. A returned filename confirms that downloading was initiated, not that the file was saved. Files go to the browser download location, not an Mingcedar server directory.</p> <ul> <li>Missing tables, unavailable Tags, and unsupported formats report errors instead of substituting zero.</li><li>Existing poor-quality values retain their quality label and are not valid field readings.</li><li>JSON distinguishes numbers, booleans, and null. Table exports use display text.</li><li>The browser or host can restrict downloads. Check page feedback and download permissions when an export fails.</li> </ul> </article> </div> </section>