Create a Custom Transform or Use the Default Transform in iOS

Before you create the plug-in for a custom widget properties editor, you need to decide whether to create a custom transform or use the default transform. The transform you decide to use will work together with a layout definition file to display the controls in the editor for each property, set default values for each property, populate the controls with a value (the previously selected value if one exists or the default value if no value has already been selected) for each property, capture the user's selections, and save the resulting property-value pairs to the metadata for the relevant report or document. These saved property values can then be read and used by a widget in a mobile application.

The default transform, VisualizationPropertiesTransform, provides code that a layout definition file can use for rendering the widget properties editor. It is part of the com.microstrategy.web.app.transforms package. If you create a custom transform, it must extend VisualizationPropertiesTransform and be part of the same package.

Using the default transform

You generally use the default transform when the widget properties editor displays simple controls such as check boxes, text fields, drop-down menus, and radio buttons that do not need to be dynamically generated.
Creating a custom transform

You generally choose to create a custom transform when the widget properties editor displays a list of elements that are generated dynamically for controls such as radio buttons and drop-down menus. For example, you would use a custom transform for listing all the attributes from the report in a drop-down menu. You also use a custom transform when you work with JavaScript files, as described below.

Transforms are discussed in detail in the Web SDK section of the MSDL under Customizing MicroStrategy Web -> Part I: Fundamentals of Customization -> Data Presentation -> Transforms.

Using JavaScript

You can use JavaScript in your custom transform to trigger an event, such as input validation, based on user actions in the widget properties editor. The custom transform specifies the location of the JavaScript file so that its content can be rendered along with the HTML for the properties editor. The code that calls the JavaScript function can be included in either the custom layout definition file or the custom transform.

The JavaScript is written in a separate file that is saved in the javascript subfolder inside the plug-in for the widget properties editor (that is, inside plugins\pluginName\javascript) in the MicroStrategy Web installation directory.

The code snippet shown below provides an example of how to render JavaScript from a custom transform. To use this code, simply replace pluginName and myJavaScript.js—shown in bold and italics below—with the name of your plug-in and the name of your JavaScript file.

You must import the com.microstrategy.web.app.utils.HTMLHelper package in order to use the renderJavascript method.

package com.microstrategy.web.app.transforms;

import com.microstrategy.web.app.transforms.VisualizationPropertiesTransform;

import com.microstrategy.web.app.utils.HTMLHelper;

...

protected void renderJavascript(MarkupOutput out) {

HTMLHelper.generateDynamicScript(out, getAppContext(), "../plugins/pluginName/javascript/myJavaScript.js", "microstrategy");

super.renderJavascript(out);

}

...

The code samples below illustrate how to create a properties editor that displays a text box for user input. In addition to code snippets for the custom transform, code snippets are also provided for the custom layout definition file and the JavaScript file. The JavaScript code validates the user input to make sure that only text is entered, and it removes any leading or trailing white spaces in the text input before saving the value in the metadata.

Code sample for the custom layout definition file

<!DOCTYPE mstrlayout:layout SYSTEM "mstrlayout.dtd">

<mstrlayout:layout>

<div>

<span style="font-weight:bold;">Enter a name for the font:</span>   

<mstrlayout:render name="MyTextBox"

<mstrlayout:argument type="String" value="name" />

</mstrlayout:render>

</div>

</mstrlayout:layout>

The custom layout definition file renders the text box. It calls the renderMyTextBox() method in the custom transform (code shown below) to display the text box and perform the JavaScript validation.

Code sample for the custom transform

package com.microstrategy.web.app.transforms;

import com.microstrategy.utils.HashList;

import com.microstrategy.web.app.utils.HTMLHelper;

import com.microstrategy.web.beans.MarkupOutput;

public class JSValidateCustomTransform extends

protected void renderJavascript(MarkupOutput out) {

HTMLHelper.generateDynamicScript(out, getAppContext(), "../plugins/JSValidate/javascript/validateInput.js", "microstrategy");

super.renderJavascript(out);

}

public void renderMyTextBox(MarkupOutput out, String propName) {

HashList<String, String> extraAtts = new HashList<String, String>();

extraAtts.add("isValid", "isText();");

extraAtts.add("getValue", "getValue();");

renderTextbox(out, propName, extraAtts);

}

The custom transform specifies the location of the JavaScript file and contains the logic for calling the appropriate functions from the JavaScript file (code shown below).

Code sample for the JavaScript file

function isText(){

elem = document.getElementById('name');

var numericExpression = /^[0-9]+$/;

if(elem.value.match(numericExpression)){

return "Please enter only text";

}else{

return true;

}

function getValue(){

elem = document.getElementById('name');

return trim(elem.value);

}

The JavaScript file contains the code for validating the user input. It also contains the code to check for invalid input (such as numbers) and to remove any leading or trailing white spaces in the text input.