Using code libraries

Contents[Hide]

1. Overview

Code libraries allow developer users to create and manage reusable scripts and localizations to add to dashboards and other views.

For example, use JavaScript code libraries for helper functions that you want to call from multiple dashboards, or even to reference from other code libraries. Localization code libraries store localized strings in different languages that can be loaded and displayed automatically in your views depending on each user's culture.

2. Create a code library

You can create a code library while you have a file open for editing such as a dashboard or another type of view.

In the Explore window, right-click the Code Libraries folder, then choose New JavaScript Library or New Localization Library

In the dialog that opens, click into the Name field to name the library and confirm the save location in the Save dialog that appears next. Optionally create a new subfolder by right-clicking the Code Libraries folder and choosing New Folder, then typing a name and the enter/return key. Click to save at the bottom to return the code library dialog.

Adding content is different for the JavaScript libraries detailed next versus localization libraries described later.

2.1. JavaScript libraries

For a JavaScript library, click Add reference if you have other code libraries containing script that this code library should be able to refer to or should otherwise be included whenever this code library is used.

You can write or paste your script directly into the editor shown in the dialog, which has many of the same features as the script editor shown when editing a view, including auto-complete popups. You can also click Choose File or Browse... (depending on the browser) to upload a file with a .js file extension.

Code library JavaScript will run immediately when a view that references it is loaded, as a <script> element on its page. You can include any JavaScript that should be included on these pages, such as functions that should be called from script actions added to events in a dashboard. Below are some examples:

function mySimpleFunction() {
    return "Hello!";
}

window.corporateLibrary = {
 
    palette: ["#418cf0", "#fcb441", "#e0400a", "#056492", "#bfbfbf", "#1a3c69", "#e1e480", "#119cdd", "#cb6a49", "#005cdb", "#f4d288", "#506381", "#f1b9a8", "#e0830a", "#7893be"],
 
    applyPaletteColors: function (colorRules) {
        var discreteRules = colorRules.filter(function (rule) {
            return rule instanceof dundas.controls.DiscreteColorRule;
        });
        discreteRules.forEach(function (rule, index) {
            var colorString = corporateLibrary.palette[index % corporateLibrary.palette.length];
            rule.value = dundas.controls.Color.fromString(colorString);
        });
    }
};

Click Save at the bottom of the dialog to save and check in the code library in the location you chose within the Code Libraries folder.

To edit the code library later, find it in the Explore window and double-click it, or right-click it and choose Edit.

2.2. Localization libraries

A localization library acts as a container for the separate localizations you add for different languages/cultures, so you usually just enter a name in its initial dialog. Click Save at the bottom to save and check in the localization library in the location you chose within the Code Libraries folder.

Next, right-click your localization library in the Explore window, and for each language or culture you are entering text for, choose New Localization. Enter a Name for your own reference, then customize the default XML that's populated initially.

Adding a localization to a localization library

The default XML consists of a localization element like the following where the culture attribute is initially set to en, representing English for no particular culture. Change this to another culture name or language tag depending on which localization you are adding. An extensive list of the ones you can enter is available here.

Use a simple two-letter language code when you want one localization to apply for multiple cultures, for example en applies to users to cultures en-US (United States), en-GB (United Kingdom), en-AU (Australia), and others. You can add a mix of a localizations with and without specific culture/region codes, and the most specific match to each user's culture will be loaded if available.

<?xml version="1.0" encoding="utf-8"?>
<localization xmlns="http://dundas.com/schemas/BI/customLocalization.xsd" culture="en">
  <group name="General">
    <string key="LabelName1">This is a localized label</string>
  </group>
</localization>

Add string elements with a key attribute setting whatever name you want to use to refer to this string, then enter the localized text inside the element that you want displayed. You can add them inside group elements like in this example – these are optional and used for your own convenience to maintain some organization for the strings.

After clicking Save, you will find the localization under the localization library after expanding it. Right-click the localization and choose Edit when you want to re-open the dialog.

3. Using a code library

When editing a dashboard, report, or other view, you can add a code library in the Properties window for that view. If any element or control is selected, click an empty part of the canvas to de-deselect it and show the view's own properties instead.

Under the Actions category, expand Code Libraries then click the + button.

Add a code library to a view in Properties

In the Open dialog that appears, select the code library that you want to use and click the submit button at the bottom.

3.1. JavaScript libraries

Code library script often needs to be accessed or called from script actions. Using the script editor accessed for an event such as Loading or Ready on the dashboard or view itself, or Click on a visualization or other control, you can now refer to the code library's script.

Using a code library in dashboard Loading script

JavaScript libraries added to a view are included on the page when that view is first opened. Click Sandbox View in the toolbar to immediately open the dashboard in view mode in a new tab or window with all JavaScript libraries loaded and scripts running.

Tip

If your code library script is causing a problem with your view even in edit mode, you can add ?IgnoreBuiltInResources=true to the URL in your browser's address bar (or &IgnoreBuiltInResources=true following other parameters).

Note

When using a view container to embed a view, JavaScript libraries from both views will be added to the page.

You can also re-open the current file or refresh the page for any newly added JavaScript libraries to be loaded, but note that script actions only run in view mode, and dashboards must be opened directly into view mode for script actions to run.

Example result after clicking Sandbox View

3.2. Localization libraries

With your dashboard or other view open in edit mode, you can 'globalize' any displayable text setting by entering one of the keys you specified in your localization library surrounded on either side by the characters $%$.

For example, to use the default localization string from the example shown earlier, enter the following as a label's text:

$%$LabelName1$%$

Any other text set up for a visualization, component, or filter in the Properties window can be set the same way, such as Tooltip Text, a column's Header Text in a table, a filter's built-in label text, and so on. You can combine your localization key with any other text characters or placeholder keywords you want displayed.

You can also localize settings in the metric sets you've added to your view, for example by opening the Data Analysis Panel, clicking to edit a measure or hierarchy, and setting their Caption to use your localization key. Or click the edit icon next to the metric set name in the Data Analysis Panel to edit overall settings such as Name, which can be displayed to viewers when setting up some notifications.

Using localization keys in a dashboard and metric set

In general, your localization keys will be displayed in edit mode as you entered them. Switch to View mode from the toolbar to see your localized text take effect for your own culture (you can check your current culture from your profile).

To view the dashboard with a different culture, you can either log on as a user with a different culture set up, or you can add ?cultureName=<culture> to the logon URL with a culture name that corresponds to one of your localizations. For more details on culture names and different ways you can set them, see that section of the article Localization and multi-language support.

The following shows the result when viewing the same dashboard as in the previous two images above, with a localization added for culture fr (French) and after logging on with the culture name fr-FR (French - France):

Viewing a localized dashboard as a French user

Code libraries are used only for settings that are set directly while editing views such as dashboards and reports (and their metric sets). Other features can be localized separately:

The entire application's user interface or any required portion of it can be localized by administrators as shown in Localization and multi-language support.
Tokens shown in filters such as All or Current year can be localized for various languages/cultures when editing the token's name or caption.
Localization is not performed for data from your data source (i.e., rows of data or data points) on its own, but a data source may localize the data for each user if impersonation is supported and set up in its data connector. In a data cube, a calculated element's script can access the current session's culture name to determine data to return, or Current Culture Name is one of the built-in attribute tokens that can be passed as a filter parameter, query placeholder, or to a stored procedure.

Dundas BI, Managed Dashboards & Reports Support