Microstrategy SDK - Javascript

SDK

How can we suppress the JavaScript error dialog?

In your global.js file, overwrite the log function:

if ((typeof(microstrategy) != 'undefined') && (typeof(microstrategy.errors) != 'undefined')) {
    microstrategy.errors.log = function() {
        // Suppress the JavaScript error
    }        
}

If you suspect that your code is causing the JavaScript error, you can put the debugger statement into this function, and your debugger will stop on this function. You can look at the call stack, pretty print the JavaScript code, and see if your JavaScript code is causing the problem.

How to determine the name of the page?

  1. Launch your favorite web browser
  2. Navigate to the page that you want to customize
  3. Launch the appropriate JavaScript debugger tool for your browser
  4. Evaluate the javascript expression: microstrategy.pageName

How to determine the project name using JavaScript?

This information is present in the pageState global variable.

How can we use the Web Customization Editor to determine the name of a page?

I DO NOT KNOW THIS INFORMATION YET. https://lw.microstrategy.com/msdz/MSDL/10/docs/projects/WebSDK/default.htm?_ga=1.229432604.1010257353.1411588911#topics/webcusteditor/WCE_Web_Customization_Editor.htm

How can we execute our own JavaScript?

See Adding Custom JavaScript

The developer library (C:\Program Files (x86)\MicroStrategy\SDK\docs\DeveloperLibrary.htm) contains a search functionality. Put the word JavaScript into that search box and do a search.

If we create a file name global.js in appropriate folder (plugins/CustomESM/javascript), MicroStrategy will automatically load that file. Depending on how we integrate MicroStrategy into our application, we may also use JavaScript in our application to dynamically insert a script tag into the MicroStrategy page as well.

What are the rules for adding our own JavaScript?

  1. The JavaScript file should be inside the "javascript" folder inside the plugin
  2. The JavaScript file should follow the naming convention of pageNamePage.js, such as reportPage.js or sharedPage.js
  3. To execute JavaScript on all pages, the JavaScript file should be named global.js.

How can we use the Web Customization Editor to create the JavaScript file?

We do not need to use the Web Customization Editor for this. Just go to your the javascript folder inside your plugin and create a file following the naming convention of "name of the page"Page.js such as reportPage.js

How can we run a JavaScript function when the report is ready?

If you want this code, you can add it only to the report page by naming your file reportPage.js. You can find more information about how to add code to a specific page from https://lw.microstrategy.com/msdz/MSDL/10/docs/projects/WebSDK/default.htm?_ga=1.229432604.1010257353.1411588911#topics/promptarch/PA_Adding_Custom_JavaScript.htm?Highlight=custom javascript

I don't think there is an easy way to find out (in the client side) when the data has been rendered. You can use the setTimeout function to make sure you wait enough time before executing yout javascript. You can also traverse the DOM in a look waiting for the HTML that renders the grid to appear. For example, let's say the parent node for the grid is something like this

<div id=grid .....>.....</div>

You can create a loop that is checking if there is an element with id=grid. If it is not there keep waiting. Once that it is added to the HTML, execute your code.

What is the mstrApp object?

I am not sure what this is, but perhaps I can use it somehow.

How can we make change to the Express page?

  1. Open the OIVM page in the WCE.
  2. Click modify next to the template field so the Mojo_Template.jsp gets copied into your plugin.
  3. This file then points to the Mojo_Section.jsp file. you need to go to the file system and copy this jsp into your plugin as well.
  4. Now back in the WCE after refreshing, change the jsp include in the Mojo_Template.jsp page to point to the copied Mojo_Section.jsp like this:
<jsp:include page='/plugins/pluginName/jsp/Mojo_Section.jsp' flush="true" />

Modify the Mojo_Section.jsp to move the following line out of the head section and all the way at the bottom of the page just before the ending <\body> tag:

<web:resource type="custom-javascript" />
</body>
</html>

Then add the following to your global.js file will grab the page name:

alert(mstrApp.pageName);

What is a JavaScript node?

The <javascript> node is a child of a <page> node in the Page Configuration file. It is used in conjunction with the <web:javascript> tag in either a page template file, such as mstrWeb, or a page section file, such as Project_Content, to insert JavaScript code into the HTML output. In the page template or page-section file, you add a <web:javascript> tag and associate it with output defined in a <javascript> node. You create this association by setting the eventName attribute in the <web:javascript> tag to the same value as the event attribute in the <javascript> node.

There is a special case for the <web:javascript> tag where it is not used with an explicitly defined <javascript> node. When MicroStrategy Web encounters a <web:javascript type="domain"/> tag, it looks in microstrategy.xml for a jsDocumentDomain context parameter. If it finds one, it uses the value of this parameter to generate a piece of javascript code that sets the domain property as shown below:

<script language="javascript">document.domain = "value of jsDocumentDomain context parameter";</script>

What is the purpose of the event attribute in the <javascript> node?

The event attribute in the <javascript> node simply identifies the output produced by the javascript-code attribute. It may or may not be the same value as the name of an actual event, such as “onload”. The javascript-code attribute defines the string that will be retrieved when the application encounters a <web:javascript> tag.

How can we create a JavaScript node?

  1. In the Page Configuration file, you define one or more <javascript> nodes for a specific page. Each node defines output that is produced if the Web application encounters a corresponding <web:javascript> tag when it renders or executes the page.
  2. In a page template or page-section file, you add a <web:javascript> tag and associate it with output defined in a <javascript> node. You create the association by setting the eventName attribute in the <web:javascript> tag to the same value as the event attribute in the <javascript> node.

In the code sample below, two outputs are associated with "customWelcomePageOutput" on the Welcome page, one output is associated with "onload", and one output is associated with "onunload". Note that the first two outputs have the same value for the event attribute, but different values for the name attribute.

<page ... name="welcome">
...
  <javascripts>
    <javascript event="customWelcomePageOutput" javascript-code="alert('Welcome, Administrator');" feature-id="administrator" name="WelcomeMessage"/>
    <javascript event="customWelcomePageOutput" javascript-code="alert('Remember to check alerts');" feature-id="administrator" name="AlertReminder"/>
    <javascript event="onload" javascript-code="alert('You have returned to the Welcome page');" feature-id="administrator" name="onload"/>
    <javascript event="onunload" javascript-code="alert('You are now leaving the Welcome page');" feature-id="administrator" name="onUnload"/>
  </javascripts>
  ...
</page>

In the code sample above, the JavaScript is executed only if the user has administrative privileges—indicated by the feature-id attribute being set to "administrator". In this example, the check is made on the "welcome" page, which means that the user has already logged in. The feature-id check works correctly in this case because, once a user has logged in, MicroStrategy Web has knowledge of user privileges. However, if this feature-id check were made on a page that did not require login AND the user was not already logged in, the check would not necessarily work as expected. Without knowledge of user privileges (because the user is not logged in), MicroStrategy Web would not be able to confirm the feature-id attribute and would return the default value of "true". As a result, the JavaScript would be executed for any user—regardless of whether (s)he has administrative privileges. In order to test for this case and have the JavaScript be executed only for an administrative-level user, you would need to add the following code (in the appropriate template or page-section file) around the <web:javascript> tag(s):

<web:ifConnectionValue >
  <web:then >
    <web:ifFeature name="administrator" >
      <web:then >
         //insert javascript tag here
         ...
      </web:then >
    </web:ifFeature >
  </web:then >
</web:ifConnectionValue >

When the Web application encounters a <web:javascript> tag in a page template file or a page-section file, it retrieves the text string that is the value of the javascript-code attribute in the associated <javascript> node (that is the <javascript> node whose event attribute has the same value as the eventName atttribute of the <web:javascript> tag). It replaces the <web:javascript> tag with the retrieved text string. If the <web:javascript> tag is associated with multiple <javascript> nodes, all of the retrieved text strings are concatenated together. You can use the <web:javascript> tag in three ways:

1. If the retrieved text string is treated as JavaScript and needs to be evaluated immediately after it is inserted, enclose the tag in a set of <script> tags and insert them wherever you want the output to appear on the page. The browser will evaluate and execute the retrieved text string when it renders the page.

<script>
    <web:javascript eventName="customWelcomePageOutput" />
</script>

2. If the retrieved text string is treated as JavaScript and is evaluated only when a particular event occurs, use the <web:javascript> tag as the value of the desired event (such as "onload") in an HTML tag (such as a <body> tag) and insert the resulting line of HTML code wherever you want the output to appear on the page. The retrieved text string is evaluated and executed after the document is finished loading and happens only when the event is triggered.

<body onload="<web:javascript  eventName="customWelcomePageOutput" />"

3. If the retrieved text string is not treated as JavaScript (that is, it is a string literal), simply insert the tag wherever you want this text string to appear on the page.

<web:javascript  eventName="customWelcomePageOutput" />

Can we create multiple <javascript> nodes for each page?

Yes.

What are the requirements the we must satisfy in order to create a <javascript> node?

Each <javascript> node must have a name attribute, a javascript-code attribute, and an event attribute. More than one node can have the same value for the event attribute. If this is the case:

  1. Each of the nodes must have a different value for the name attribute.
  2. Each of the nodes must have a semi-colon (“;”) at the end of the value for the javascript-code attribute. The values for the javascript-code attributes are concatenated. Providing a semi-colon at the end of each ensures that the resulting code conforms to the proper syntax after the values are concatenated.

How can we use the <web:javascript> tag in a template file?

In the code sample in the Defining <javascript> nodes section above, you created a <javascript> node in the Page Configuration file for the Welcome page and set the event attribute to "customWelcomePageOutput" and the javascript-code attribute to "alert(‘Welcome, Administrator')". If you want the output you defined for the Welcome page to be produced by the page template file, modify mstrWeb (JSP or ASP .NET file), the default template file used by the Welcome page. In the example below, you modify the <body> definition of mstrWeb by adding the code shown in bold.

<body class="mstr"
  ...
onload="microstrategy.eventManager.executeFunction('microstrategy.eventManager.onload()');Init();<web:javascript eventName="onload"/>;<web:javascript eventName="customWelcomePageOutput" />"
  ...
</body>

When the application encounters a <web:javascript> tag, it checks the page it is executing to see if there are any <javascript> nodes defined for that page in pageConfig.xml. If it finds a <javascript> node whose event attribute has the same value as the eventName attribute in the <web:javascript> tag, it outputs to the browser the entire text string that is the value of the javascript-code attribute in the <javascript> node. In this example, because the script is not executed until the "onload" event occurs, it is not enclosed in <script> tags.

How can we use the <web:javascript> tag in a page section file?

You can also use the <web:javascript> tag in a page section file. In the code sample below, you modify Project_Content (JSP or ASP.NET file), the file that provides the "content" page section for the Welcome page. You add a <web:javascript> tag (shown in bold in the code sample) that will execute the JavaScript defined in the corresponding <javascript> node in the Page Configuration file. In this example, because the script is executed immediately, it must be enclosed in <script> tags.

<%
 /****
  * Project_Content.jsp
  * This page just displays all the children of the page using
  * their generateOutput() method.
  *
  * Copyright 2004 MicroStrategy Incorporated. All rights reserved.
  * version: 1.2
  * xhtml: true
  ****/
%><%@ page errorPage="JSP_Error.jsp"
%><%@ page contentType="text/html; charset=UTF-8"
%><%@ taglib uri="/webUtilTL.tld" prefix="web" %>
<%-- Execute javascript if specified in pageConfig.xml--%>
<script><web:javascript eventName="customWelcomePageOutput" /></script>
<%-- Render all the beans associated to the current page as specified in pageConfig.xml--%>
<web:displayBean/>

When the application renders a page with a page section file containing a <web:javascript> tag, it checks to see if the page contains any <javascript> nodes with the event attribute set to the same value as the eventName attribute for the corresponding <web:javascript> tag. In this example, the application checks for "customWelcomePageOutput". If it finds a match, the <web:javascript> tag is replaced by the text string defined in the corresponding <javascript> nodes for the page. In this example, the <web:javascript> tag in Project_Content is replaced by the text that is associated with "customWelcomePageOutput”.

Based on the event that you associate with the <javascript> node and the file in which you place the <web:javaScript> tag, you can control how, when and where the output is placed in the HTML for the page.

Where can I get more information on JavaScript node?

https://lw.microstrategy.com/msdz/MSDL/812/docs/Javascript_Node.htm

How can we use <web:javascript> tags with <javascript> nodes?

When the Web application encounters a <web:javascript> tag in a page template file or a page-section file, it retrieves the text string that is the value of the javascript-code attribute in the associated <javascript> node (that is the <javascript> node whose event attribute has the same value as the eventName atttribute of the <web:javascript> tag). It replaces the <web:javascript> tag with the retrieved text string. If the <web:javascript> tag is associated with multiple <javascript> nodes, all of the retrieved text strings are concatenated together.

You can use the <web:javascript> tag in three ways.

If the retrieved text string is treated as JavaScript and needs to be evaluated immediately after it is inserted, enclose the tag in a set of <script> tags and insert them wherever you want the output to appear on the page. The browser will evaluate and execute the retrieved text string when it renders the page.

<script>
    <web:javascript eventName="customWelcomePageOutput" />
</script>

If the retrieved text string is treated as JavaScript and is evaluated only when a particular event occurs, use the <web:javascript> tag as the value of the desired event (such as "onload") in an HTML tag (such as a <body> tag) and insert the resulting line of HTML code wherever you want the output to appear on the page. The retrieved text string is evaluated and executed after the document is finished loading and happens only when the event is triggered.

<body onload="<web:javascript  eventName="customWelcomePageOutput" />"

If the retrieved text string is not treated as JavaScript (that is, it is a string literal), simply insert the tag wherever you want this text string to appear on the page.

<web:javascript  eventName="customWelcomePageOutput" />

How can we process events with JavaScript before submitting them?

In this customization scenario, you modify the <a> (anchor) tag to include an "onclick" attribute that executes JavaScript before an event is submitted for execution. The event in this scenario is any user action on the Folder Browsing page.

This involves creating a transform.

  1. Launch the Web Customization Editor
  2. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  3. Create a transform
    1. Right-click Styles and select Create Transform to launch the Transform Creation Wizard.
    2. Click Browse… next to the Source folder text field to select the src folder and click OK.
    3. Provide the information for the transform that we are creating. For the Superclass field, provide: "com.microstrategy.web.app.transforms.FolderViewTransform"
    4. Click Next
    5. Click the radio button for Uncheck all methods.
    6. Click Next.
    7. Click Finish. FolderViewTransformWithJSPreprocessing.java opens in the editor.
    8. For this scenario, you override the generateAnchor(WebEvent event) method, and make other modifications as required. The sample, FolderViewTransformWithJSPreprocessing.java, contains the entire code for this custom transform. You can use this code in FolderViewTransformWithJSPreprocessing.java that is open for editing.
    9. Save your changes.
  4. Associate your new transform to a Style
    1. Click on Styles in the Web Customization Editor to expand the list of styles used in MicroStrategy Web.
    2. Double-click the FolderStyleIcon style.
    3. Click the Change button next to the Transform text field.
    4. Enter the name of the transform you created (FolderViewTransformWithJSPreprocessing), select it from the Matching Types results and click OK.
    5. Save your changes.
    6. Double-click the FolderStyleList style.
    7. Click the Change button next to the Transform text field.
    8. Enter the name of the transform you created (FolderViewTransformWithJSPreprocessing), select it from the Matching Types results and click OK.
    9. Save your changes.
    10. Launch MicroStrategy Web to view the customization.

The code for FolderViewTransformWithJSPreprocessing.java:

package com.microstrategy.sdk.samples.transforms;

import com.microstrategy.web.app.transforms.FolderViewTransform;
import com.microstrategy.web.beans.WebEvent;
import com.microstrategy.web.tags.AnchorTag;
import com.microstrategy.web.beans.EnumFolderBeanEvents;

public class FolderViewTransformWithJSPreprocessing extends FolderViewTransform {

    /**
     * Creates an <code>&lt;a&gt;</code> tag from the EventManager.
     * @param event WebEvent
     * @return AnchorTag
     */
    public AnchorTag generateAnchor (WebEvent event) {
        //Retrieves the anchor tag from the parent transform
        AnchorTag result = super.generateAnchor(event);

        //Sets the 'onclick' attribute on the anchor tag to add JavaScript code
        //JavaScript code will be added only for folders (the event for folder browsing is associated to folders).
        if (event.getID() == EnumFolderBeanEvents.FOLDER_EVENT_BROWSE) {
            result.setAttribute("onclick", "return alert('Add code to process folder event here...');");
        }
        return result;
    }
}

The above code invoke the generateAnchor method from the parent class. It then invoke the setAttribute method of the result object to set the onclick attribute to a string which contains the JavaScript code. I do not know whether this will work for links that already have some default JavaScript code, and how I can cancel the click, etc.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License