Tag names, typed reads, and writes | Mingcedar Studio

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.

• Full Tag name: `PLC_LINE01.PUMP01.SPEED`.
• Calculated Tag name: `Line01TotalFlow`, exactly as saved in the host.
• Runtime variables: `selectedSpeedTag` holds a name; `speedValue` holds a number.
• Template placeholders: `<PLC>` and `<PUMP_CODE>`, replaced with instance values.

// 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);

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.

• Fixed target: `PLC_LINE01.PUMP01.SPEED`.
• Name variable: `selectedSpeedTag`; define it first and ensure it returns a string.
• Object property: `=bindingConfig.speedTag`.
• Write Tag Bit takes the parent Tag name and a separate Bit Index from 0 to 31.

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.

• Fixed Input target: `PLC_LINE01.PUMP01.SPEED_SETPOINT`.
• Dynamic Input target: `=selectedSetpointTag`.
• Dynamic chart target: `=selectedSpeedTag`.
• JSON Tag: `PLC_LINE01.REPORT01.CHART_DATA`; use `=selectedJsonTag` for a dynamic name.

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.

• Fixed variable name without quotes: `speedSetpointDraft`.
• Dynamic Input variable: define `var selectedVariableName = "speedSetpointDraft";` in Page Script and enter `=selectedVariableName` in the field.
• Value and Condition are expression fields: enter `speedValue` or `speedValue > 1200` directly.
• In JavaScript, use `ReadTagDouble(selectedSpeedTag, 0)`. Do not pass `"=selectedSpeedTag"` as an API name argument.

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.

• Headers: `["Equipment", "Status"]`.
• Rows: `[["PUMP01", "Running"], ["PUMP02", "Stopped"]]`.
• Dynamic rows: `pumpRows` or `=buildPumpRows()`, returning an array.
• Literal title: `"Pump station operating record"`.

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.

// 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"

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.

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

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.

• Changing an Input target or binding mode cancels the old unsubmitted draft. Enter a new value for the new target.
• A write already sent is not recalled by a subsequent target change.
• A live chart clears samples from the previous target when its dynamic target changes.
• Runtime variables belong to the current page. Use page parameters to transfer context to another page.

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.

ReadCalculatedTag("Line01TotalFlow")
ReadCalculatedTag("Line01TotalFlow", null)
ReadCalculatedTag("Line01Ready", false)
hqVisuDesigner.ReadCalculatedTag("Line01TotalFlow", null)

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.

• Names are at most 128 characters. Use ASCII letters, digits, underscores, and separator dots; each segment starts with a letter or underscore.
• Bit suffixes such as [0] are not supported.
• An ordinary Tag with the same name is not read as a calculated result.
• Renaming an unpublished draft does not change the active published name. Update page references after publishing the new name.

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.

• Use null and display “--” when data is unavailable to distinguish it from a valid zero.
• Use false when a condition requires a boolean fallback.
• Use `ReadTagQuality("Line01TotalFlow")` to inspect quality. Data quality and process alarms have different meanings.

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.

// Setup Script
var calculatedTagName = "<CALCULATED_TAG>";
var totalFlow = ReadCalculatedTag(calculatedTagName, null);

// Script Text: Text
totalFlow === null ? "--" : totalFlow.toFixed(1) + " m³/h"

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.

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.

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.

• Scope: confirm that the target page is active.
• New or Ctrl+N: create a script document.
• Folder: optional slash-separated path.
• Name: document name without the .js extension.
• Enabled: a disabled document is retained but not exported or validated on Save.
• Script Library or Ctrl+J: insert a method or template at the caret.
• Save or Ctrl+S: validate and save the complete workspace.
• Help or F1: open script help.

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.

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.

• Before deleting, confirm no behavior or other document uses its functions or variables.
• Delete applies only to removable custom documents.
• alarm.js is protected; edit its configuration instead.
• Choose Cancel, not Save, when you want to discard all pending workspace edits.

Set window.hqVisuDesignerPageReady in Page Script for initialization; it runs once when the page runtime is ready. Common methods follow:

• Read tags, ReadTag family: ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString; the second argument is the fallback value used when the tag cannot be read
• 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, 时间, 日期
• 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
• 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)
• 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
• Drive components, hqVisuDesigner: setComponentText(nameOrId, value), setComponentFill, setComponentBorder, setComponentVisible, setComponentLayout, findComponent, getComponentData
• Navigation and variables, hqVisuDesigner: openPage("PageName"), openScreen("SCREEN_CODE"), openWebsite(url, openInNewWindow), writeVariable(name, value), and refreshView()

// 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();
};

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.

• Ternary expression: condition ? trueValue : falseValue, useful for converting a boolean to text, color, or a numeric value.
• Safe defaults: the second argument of ReadTagBoolean / ReadTagDouble and similar helpers is the fallback when the tag cannot be read.
• Date/time text: use GetCurrentDate() for the current date, GetCurrentDateTime() for the current date-time, and FormatDateTime(...) for display formatting.
• Multiple conditions: use a ternary for simple cases; use if / else to prepare variables before writing to a component or returning a behavior value.

// 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);

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.

• String concatenation: use 'Speed: ' + speed for simple text; use template strings like `Speed: ${speed}` when several values are involved.
• Number formatting: use Number(value).toFixed(1) to control decimal places.
• Arrays: keep status lists, alarm lists, or multiple component names in arrays, then loop through them.
• Objects: keep lookup tables such as state code to text, color, and priority.

// 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);

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.

• Put same-page helpers, constants, and Tag prefixes in the current page's Page Script
• Use hqVisuDesigner.openPage(...) for same-package pages and hqVisuDesigner.openScreen(...) across packages; do not write disk-relative paths like ../../other-screen/index.html

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.