Repository Function Documentation

This document describes common functions found in the repository.js examples. Each function is summarised with its purpose, typical parameters, and usage patterns.

init

init() runs when a widget or page is first created. It often sets default values (such as selected year or company) or returns a configuration object that describes how to fetch data from the server.

launch

launch() is usually bound to buttons or icons. It performs navigation or activates features, typically by calling Api.openPage() and optionally adjusting widget values beforehand.

perform

perform() is usually bound to icons. It performs navigation or activates features.

text_click

Handles click events on text widgets. Common uses include navigating back to a main page or triggering context-specific actions.

switch

Executed when a segmented control changes state. It is responsible for refreshing or updating related widgets to reflect the new segment.

initCondition

Evaluates whether the main init logic should run. Returning a truthy value allows initialization; otherwise it may be skipped.

initDefault

Provides a fallback initialization when no specific condition is met, ensuring the component has baseline data.

refreshFinished and initFinished

Run after initial loading or a refresh has completed. These hooks typically force dependent widgets to reload or synchronise state.

download

download() constructs parameters for exporting data, such as file name, segment selections, and query keys. Returned values are passed to the export service to generate a file.

upload

upload() prepares configuration for uploading files. It sets paths, validation settings, and optional callbacks to trigger processes after the upload completes.

execute

execute() performs an action immediately, often returning option lists for segmented controls or executing logic when a switch or init event fires.

script

script() transforms raw query results into custom structures when default parsing is insufficient. Used when parsingControl.type is script.

callback

callback() runs after an action (like upload or process execution) finishes. It is typically used to trigger refreshes or follow-up requests.

choose

choose() runs when a user selects an item in widgets like drop-downs. It typically sends the chosen value to the server and may refresh widgets or close popups afterwards.

write

write() submits edited values to the server. It patches cellsets or calls processes so grid or form changes persist.

writeEnd

writeEnd() fires after editing completes. It stores the final value and refreshes any dependent widgets or charts.

save

save() commits text box or single-field edits to the server, usually by patching a specific cell ordinal with a new value.

rightclick

rightclick() handles context menu actions on grid cells, often capturing the clicked cell and opening a popup with options.

RestRequest

RestRequest creates a configurable request object for server-side processes or writes, defining URL, method, payload, and callbacks.

Api functions

  • Api.openPage(page) navigates to the specified page.

  • Api.openPopup(id) displays a popup dialog.

  • Api.showPopup(id) reveals an already defined popup.

  • Api.closePopup(id) closes the given popup.

  • Api.goToStartPage() returns the user to the application’s start screen.

  • Api.logout() signs the current user out.

  • Api.forceRefresh(widget) reloads a widget’s data.

  • Api.forceRefreshWidgets([widgets]) reloads multiple widgets at once.

  • Api.forceRefreshWithoutLoader(widget) refreshes a widget without showing a loading indicator.

  • Api.updateContent(widget) updates the content of a single widget.

  • Api.updateContentWithoutLoader(widget) updates a widget without a loader.

  • Api.updateWidgetsContent([widgets]) updates several widgets.

  • Api.updateWidgetsContentWithoutLoader([widgets]) updates several widgets without loaders.

  • Api.removeWidgetValues([widgets]) clears cached values for the specified widgets.

  • Api.executeRequest(name) runs a named process or write request.

  • Api.executeQueryRequest(name) runs a query request and returns data.

  • Api.triggerWidgetEvent(widget, event) triggers a specific event on a widget.

  • Api.openPageWithState(page, state) opens a page and applies the provided state object.

  • Api.goToUrlNewTab(url) opens the specified URL in a new browser tab.

  • Api.hideWidgets([widgets]) hides the given widgets.

  • Api.showWidgets([widgets]) shows the specified widgets.

  • Api.togglePopup(id) toggles a popup’s visibility.

  • Api.toggleWidget(widget) toggles the visibility of a widget.

Utils functions

  • Utils.openPopup(id) opens a client-side popup without server round trips.

  • Utils.closePopup(id) closes the specified popup.

  • Utils.togglePopup(id) toggles a popup’s visibility.

  • Utils.setWidgetValue(widget, value) assigns a value to a widget.

  • Utils.setWidgetValueIfNotExist(widget, value) assigns a value only if the widget is empty.

  • Utils.getGridTableCurrentCell(table) returns information about the currently selected cell.

  • Utils.getGridTableCurrentRow(table) returns the current row object or index.

  • Utils.getGridTableCellByRowAndColumn(table, row, column) retrieves a cell by coordinates.

  • Utils.isGridTableLoaded(table) checks whether a grid table has finished loading.

  • Utils.getDropBoxSelectedItemAttribute(dropbox, attribute) reads an attribute from the selected dropdown item.

  • Utils.getFormattedDate(date) converts a Date object to a formatted string.

  • Utils.parseNumber(text) converts a formatted string to a numeric value.

  • Utils.separatesThousands(number) adds thousand separators to a number.

  • Utils.modifyFileName(name) adjusts file names, often appending timestamps or context.

  • Utils.getImpersonatingUserName() returns the username being impersonated.

  • Utils.isImpersonated() indicates whether the current session is impersonated.

  • Utils.reloadApp() reloads the entire application.

  • Utils.getGridTableCell(table, column) gets a cell from the current row at the specified column.

  • Utils.getGridTableToggleValue(table, row) retrieves the toggle state for a row in a grid table.

  • Utils.saveGridTableToggles(table, column) saves the current toggle states for later use.

  • Utils.getNavigationUrl(params) builds a navigation URL based on the provided parameters.

  • Utils.getDecimalFromPercentString(text) converts a percentage string into a decimal number.

  • Utils.escapeText(text) escapes special characters in a string, useful for pasted data.

  • Utils.toTitleCase(text) converts a string to title case.

Additional widget events

Beyond the common handlers above, repository files often define supplementary widget events:

  • pick() handles DatePicker selections so that repository logic can push calendar choices back to TM1 or refresh related widgets.

  • cellEdit() captures inline edits from grid-style widgets and forwards the changes to processes or PATCH requests.

  • pasteCells() batches clipboard pastes into scrollable grids, combining the payload before sending a single write request.

  • text_change() and change() respond to live text edits in grid tables, allowing repositories to validate or persist keystrokes.

  • slide() fires when slider widgets move, which is useful for updating dependent calculations immediately.

  • writeKey() triggers on specific key presses in text boxes, enabling actions before focus leaves the field.

Additional Api helpers

The framework exposes further navigation and refresh helpers that appear in event-map driven integrations:

  • Api.scrollTo(widget) scrolls the viewport to the given widget while triggering its refresh event.

  • Api.jumpTo(widget) jumps to a widget without animated scrolling.

  • Api.openPrevPage() returns to the previously viewed page, and Api.openPrevPageWithState() restores it with cached state.

  • Api.openPageWithWaitingForEvent(...) and its “scroll to section” variant delay navigation until a specified widget event completes.

  • Api.forceRefreshWithDelay([widget, delay]) schedules a refresh after waiting for the supplied milliseconds.

  • Api.openPageAndScrollToSection(...) and related helpers combine navigation with scrolling and optional refresh lists.

  • Api.removePageValues(page) clears stored values for every widget on a page, while Api.removeValuesRecursively(page) also resets nested widgets.

Additional Utils helpers

Utility helpers extend far beyond value setters. Common patterns include:

  • Utils.sleep(ms) to pause async flows before chaining more repository actions.

  • Utils.stopEvent(event) to cancel DOM bubbling when custom controls wrap native inputs.

  • Utils.clone(object, deep) to create safe copies before mutating payloads.

  • Utils.scrollTop(duration) and Utils.scrollTo(target, duration, offset) for viewport management.

  • Utils.getRandomId() to generate stable identifiers for dynamic widget elements.

  • Utils.parseFormatStringToCSSClasses(text) to convert TM1-style format strings into CSS helper classes.

  • Utils.getTimestamp(date, forwardTime) and Utils.getToday(delimiter) to build TM1 friendly date strings.

  • Utils.stripHtml(text) and Utils.nl2br(text) when sanitising or reformatting rich text responses.

  • Utils.precisionRound(number, precision, toFixed) for consistent rounding logic in charting or grid summaries.