tamaki.mes.utils

General-purpose helpers used throughout the TamakiMES Perspective project: opening popups and docks, formatting dates, durations and unit ratios, building Perspective dropdown options, encoding values, and a few logging and diagnostic utilities.

Note: session scope: The popup, dock, and session helpers (openModal, openNonModal, openEmbeddedSidebar, closeEmbeddedSidebar, the showError* / showValidationsPopup helpers, and forceRefreshSessionCustomVariables) only work inside a Perspective session: call them from a component event script, not the Designer script console.

Conversion & formatting

stripNulls

Returns a copy of a dictionary with all None-valued keys removed.

getJsonElement

Safely reads a key from a dictionary, returning a default if it is missing.

snakeToCamel

Converts a snake_case string to camelCase.

camelToTitle

Converts a camelCase string to Title Case.

formatUnitRatio

Formats a quantity unit and a time unit into a readable ratio such as bottles/minute.

colorClassToVar

Converts a colour CSS class name into a CSS var(--...) expression.

getReadableTextColor

Returns black or white (whichever is more readable) for a given hex background colour.

Dropdowns

listToDropdown

Converts a plain list into the {value, label} format used by Perspective dropdowns.

enumListToDropdown

Converts a list of Java enums into Perspective dropdown options.

objListToDropdown

Converts a list of objects into dropdown options using chosen label and value keys.

Dates & durations

formatDuration

Formats a numeric duration into HH:MM:SS.mmm.

formatDate

Formats milliseconds or a Date into a string using a Java date pattern and timezone.

convertTimezone

Converts a date to another timezone, returning a Date.

isoInstantStringToDate

Parses an ISO-8601 instant string (e.g. 2024-05-21T17:13:00Z) into a Date.

calculateOverlappingDuration

Returns the overlapping duration between two time intervals.

Encoding

base64_encode

Base64-encodes a byte string.

base64_decode_as_string

Decodes a base64 byte string back into a normal string.

Popups & docks

openModal

Opens a modal Perspective popup with a generated popupId.

openNonModal

Opens a non-modal Perspective popup that stays open until closed.

openEmbeddedSidebar

Opens the right-side dock with an embedded view.

closeEmbeddedSidebar

Closes the embedded-sidebar docks and reopens the top-navigation header.

showErrorPopup

Opens the standard Error popup showing the current traceback and exception.

showErrorPopupMessage

Opens the Error popup with a custom message and no traceback.

showErrorPopupWithMessage

Opens the Error popup with the current traceback and a custom message.

showValidationsPopup

Opens the Validation popup with markdown-formatted validation failures.

forceRefreshSessionCustomVariables

Resets the sidebar-selection custom session variables to empty dictionaries.

Datasets & files

excelFileToDS

Converts a sheet of an uploaded Excel file into a Dataset.

datasetsToZip

Zips multiple datasets into a byte array, one CSV file per dataset.

Diagnostics

printCurrentScope

Prints the current execution scope (Client, Designer, Gateway, or Perspective).

logString

Logs a string at INFO level under the DBFunctionCalled logger.

logDebCallingFunction

Decorator that logs a function's entry and exit.