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 (JSP or ASP.NET), to insert JavaScript code into the HTML output. There are separate sections below to describe how to use a <web:javascript> tag in each type of file. There is also a description of the syntax that must be used, based on the type of output or how that output is triggered.

• Defining <javascript> nodes

  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.  

• Using <web:javascript> tags with <javascript> nodes

  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.

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 whose eventName attribute has the same value as the event attribute of the <javascript> node.

Defining <javascript> nodes

You can define multiple <javascript> nodes for any page. 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:

• Each of the nodes must have a different value for the name attribute. 

• 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.

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.

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):

J2EE environment

.NET environment

Using <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 attribute 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. 

  J2EE environment

  <script>

      <web:javascript eventName="customWelcomePageOutput" />

  </script>

  .NET environment

  <script>

      <web:javascript eventName="customWelcomePageOutput" runat="server" />

  </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.

  J2EE environment

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

  .NET environment

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

• 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.

  J2EE environment

  <web:javascript  eventName="customWelcomePageOutput" />

  .NET environment

  <web:javascript  eventName="customWelcomePageOutput" runat="server" />

  The code samples above can be used in either a template file or a page section file, as described in the following sections.

Using 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.

J2EE environment

.NET environment

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.

Using 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.

J2EE environment

.NET environment

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.  

Description

The table below describes the elements and attributes in the <javascripts> node in pageConfig.xml. The four columns in the table include the following descriptive information:

Parent Element - Child Element 1 - Child Element 2	Indicates the name of the element described in the next three columns. If this is a parent element, the names of all possible child elements are listed below the parent element.
Number of Nodes	Specifies the number of nodes that are required or allowed for the corresponding element in the Parent Element column. For example, if the value is "1", there must be only one node - no more, no less. If the value is "0 or more", the node is not required ("0"), but there is no restriction on the number of nodes that can be added ("or more").
Parent Element Attributes	Lists the separate attributes that can be used with the corresponding element in the Parent Element column. Included in parentheses beneath each attribute name are the attribute type and an indication of whether the attribute is required or implied. For example, the config-src attribute for the <javascripts> element has an attribute type of "cdata" (character data) and is implied. The name attribute for the <javascript> element has an attribute type of "nmtoken" (name token)  and is required.
Description	Describes either a parent element in the Parent Element column or an attribute in the Parent Element Attributescolumn.