Product: Mingcedar Studio DESIGNER

Change component layout through scripts | Mingcedar Studio

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.

Published 2026-10-25T12:48:42.664767863Z Updated 2026-10-25T12:48:42.664767082Z

<section id="imperative-layout" class="docs-block docs-block-intro docs-block-current"> <span class="section-kicker">Feature</span> <h2>Change component layout through scripts</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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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="imperative-layout-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>