Using Global Scripting Options in a Script to Enhance a Story

Objective

After completing this lesson, you will be able to enhance a story using global script options.

Global Script Variables and URL Parameters

Global Script Variables

In previous lessons, we worked with local script variables. They were defined with the var function within a single script block. The value was only accessible within that specific block and couldn't be accessed from outside.

Global script variables are defined as "own standing object on story level". This means that they can be accessed from all script blocks within the story.

In the example below, you can see an SAP Analytics Cloud story Outline tab and Script Variable panel. You can:

  1. Create a new script variable in the Outline tab of a story
  2. Name the script variable
  3. Select the data type of the script variable
  4. Enable the script variable to be used as a URL parameter. For array type variables and nonprimitive type variables (types other than string, boolean, integer, and number), the URL parameter function doesn't apply and the option is disabled by default.

Using global script variables, you can pass a parameter from the URL into the story. For example, you could:

  • Pass a value that is used as filter for a dimension
  • Pass a value that is used to define a specific layout

When you want to pass a global script variable as URL parameter, you must prefix the variable name with p_ in the URL using the following format: <yourAppURL>&p_<VariableName>=<VariableValue>.

For example, <yourAppURL>&p_viewMode=condensed. This scenario is used in an exercise, so you will see the steps in creating it later in this lesson.

Note

Performance: Where possible, use local script variables over global script variables.

Property Binding

In previous lessons, you looked at defining items for the widget manually using direct input and dynamically using scripting. In this lesson, we will look at defining the items dynamically for the widget using property binding.

The property binding function offers the story designer the option to bind the values to one of the following objects:

  • Script variables
  • Model variables
  • Tile filters and variables

Widget value binding is an easy way to create dynamic values for properties, for example, items of a List Box widget.

In the example below, you can see a list box that shows the defined filter values of the table. The selected entry is written back to a global script variable.

A simple widget's value can be bound to one of the following:

  • Primitive-type script variable
  • Application property
  • Tile filter and variable
  • Model variable

Note

The supported types vary with each widget.

Supported Binding Types by Widget

Value binding is available for various different widgets. The following list gives you an overview of the widgets and the supported binding types:

  1. Drop Down Box, Checkbox Group, Radio Button Group
    • Bindable values: ID, Display Text
    • Supported bindings: Script Variable, Tile Filter & Variable and Model Variable
  2. Input Field, Text Area
    • Bindable values: IDText
    • Supported bindings: Script Variable, Tile Filter & Variable, Model Variable and Story Property (including Current User/Time/Date, Last Modified Date, Last Modified Date/Time, Last Modifier, Creator)
  3. Slider
    • Bindable values: Current value
    • Supported bindings: Script Variable, Tile Filter & Variable, Model Variable
  4. Range Slider
    • Bindable values: Start value and End Value
    • Supported bindings: Script Variable, Tile Filter & Variable, Model Variable
  5. Image
    • Bindable values: Image URL
    • Supported bindings: Script Variable

You can also make use of the option of the Write-Back at Runtime feature. With this you can automatically assign the value a user selected to a global script variable that might get used in other scripts or widgets.

Global Script Objects and Functions

The global script object acts as a container or library. It's a nonvisible part of a story.

Global Script Objects (top, orange) and Global Script Functions (bottom, blue).

You can invoke a script function with the following syntax: <ScriptObjectName>.<ScriptFunctionName>();

As a story designer, you can use a function to encapsulate certain script logic that can be used in other script functions like event handlers. This keeps you from duplicating code and makes story maintenance easier. Once you've added a script object, you can create functions on this object. Each Script Function has:

  1. A configurable Name (mandatory)
  2. Return Type (optional)
  3. Arguments (optional)
Script Function builder panel with numbers 1 to 3 listed from top to bottom. 1. A configurable Name (mandatory), 2 Return Type (optional), and 3 Arguments (optional).

You can access the script object in scripts with its name like other widgets. Inside a function of the script object, you have access to all objects in the story such as widgets, global variables, or popups.

Using Input Arguments and Return Type

On the left side of the example below, you can see the script object Utils with a script function named deviceSize.

It uses width and height as input arguments and returns an array containing the size and orientation.

To the right you can see the following:

  1. The script within the script function
  2. The usage of the script function
  3. The results as displayed in the console
Script Function panel on the left with Return Types (blue) and Arguments (orange) highlighted . Numbers 1 to 3 show Script within the Script Function, 2. Usage of Script Function, and 3. Result in the Console. Both 1 and 2 have examples of Return Types and Arguments highlighted in blue and orange.

Working with Pattern-Based Functions

With pattern-based functions, you can create string-based functions by only providing input and output examples instead of writing script code. For example, you can transform e-mail addresses like john.doe@sap.com to names like John Doe.

You can create a pattern-based function as a child of an Script Object from the Outline of a story.

1. Pattern-Based Function

Select Add Pattern-Based Function to add it to your story. Once you have done this, you must create the pattern through input and output training examples.

2. Properties

Add a name for the function in the Name field. You can also add an optional Description to the function.

3. Create Pattern

Select the Addicon next to Create Pattern. Under Training Example, define the input and output (for example Input: max.mustermann@sap.com will become Output: Max Mustermann).

Sometimes one example isn't enough due to potential ambiguity. In this case, you can use up to three training examples by choosing the Addicon for each training example.

4. Create/Reset

Select Create so that a machine learning algorithm starts looking for a pattern that matches every example.

As soon as you change a training example, the pattern falls back to its default, which is just returning the input. If you want to undo your changes on new or modified training examples, choose Reset. This sets the pattern-based function to the last working pattern.

5. Verify Pattern

If the pattern creation has been successful, you can verify the pattern by entering input examples that follow the training example pattern. If you input examples that do not follow the pattern above, then the function will keep its default pattern, which is just outputting the input. To verify the pattern, select the Addicon next to Verify Pattern. Type a test example in the Input field and in the Output field, you should see the correct output.

cast() Function

You learned already that you define the data type of a local script variable by assigning a value to it. That works good for all simple data types like boolean, string or integer.

In the example above, you can see a simple filter highlighted in yellow. A script for the simple filter would be:

Code Snippet
123
var mySimpleFilter = "201901";
Table_1.getDataSource().setDimensionFilter("0CALMONTH", mySimpleFilter);

But that approach won't work if you try to assign, for example, a JSON format that should represent a Multiple Filter Value format.

Code Snippet
1
var myComplexFilterfilter = {values:["201901", "201902"], exclude: true};

The code above will show an error message as the system doesn't know how to interpret the JSON {values:["201901", "201902"], exclude: true}.

With the help of the cast(type, arg) function you can specify the data type and pass an argument.

Code Snippet
1
var myComplexFilterfilter = cast(Type.MultipleFilterValue, {values:["201901", "201902"], exclude: true});

The code above indicates the script engine to use the data type MultipleFilterValue for the given JSON {values:["201901", "201902"], exclude: true}.

Add a Global Script Variable as a URL Parameter

Business Scenario: Some report viewers on your team like to see only the KPI tiles when they open the story and others would like to see the complete story when they open it.

As you don't want to maintain two different versions of the story in the future, you decide to introduce a URL parameter to be able to enable a condensed or full start up behavior.

You add and configure a global script variable, then add the following code to the story using the onIntitialization action:

Code Snippet
12345
if (viewMode === "condensed") {
  TS_Content.setVisible(false);
} else {
  TS_Content.setVisible(true);
}

To each group, you provide a different URL:

  • You add &p_viewMode=condensed to the URL for the report viewers who only want to see KPI tiles in the story when they open it.
  • You add &p_viewMode=full to the URL for the report viewers who want to see the detailed story when they open it.

This short video will walk you through the final story and scripting required.

Simulate the Steps

The practice exercise below simulates being in Advanced Mode in SAP Analytics Cloud and takes you through adding the scripting required to create the final story shown in the demo video.

Task Flow: In this practice exercise, you will:

  • Add the global script variable viewMode to the story
  • Add scripting to the onIntitialization action
  • Test the URL parameters for the story
ExerciseStart Exercise

Pass Variable Values to Other Pages

Business Scenario: Earlier, you enhanced a story with scripting using buttons to filter a table. You team requests additional functionality to be able to see some more detailed data on a separate story page. The expectation is that the filter that is applied on the first page by using the buttons is also applied on the detail page.

You add a global script variable to your story and then for the onClick events for the buttons, you add year = "2018";, year = "2019";, and year = "all"; respectively.

Once you have created the new page, you add the following scripting to the onActive event:

Code Snippet
12345
if (year === "all") {
  TBL_Details.getDataSource().removeDimensionFilter("0CALYEAR");
} else {
  TBL_Details.getDataSource().setDimensionFilter("0CALYEAR", year);
}

This short video will walk you through the final story and scripting required.

Simulate the Steps

The practice exercise below simulates being in Advanced Mode in SAP Analytics Cloud and takes you through adding the scripting required to create the final story shown in the demo video.

Task Flow: In this practice exercise, you will:

  • Add the global script variable year to your story
  • Add scripting to the onActive event
  • Test the story
ExerciseStart Exercise

Log in to track your progress & complete quizzes

Learning

SAP FacebookSAP YoutubeSAP LinkedIn