E-mail
Search in CenterView 3.1 Documentation
CenterView supports server-side Javascript, based on Rhino: JavaScript for Java (http://www.mozilla.org/rhino/), to define and manipulate dynamic dashboard content. Corda Technologies refers to this scripting capability as Server Script to denote that it runs only on the server and has no client-side components.
CenterView supports Server Script in .dashxml, .pagexml, .kpixml, .dfxml, and .dssxml files. Several objects are accessible to Server Script. The various dashboard Consoles (explained in the CenterView User Guide) provide a means of tracking changes to XML files during their processing, including the processing of any Server Script. Additionally, the Server Script Debugger helps identify script-specific code problems.
There are two ways to invoke Server Script from within CenterView XML files:
 | Warning: For best performance, do not use Server Script in dashboard datafunnel objects, unless absolutely necessary. CenterView Server executes Server Script in a dashboard object every time a page in the dashboard is requested. Server Script in a datafunnel object prevents the datafunnel from being cached, so each time the data is requested the datafunnel reruns the Server Script and retrieves the data all over again. Only simple variable replacement is allowed for inline Server Script and server-script objects. |
Server-Script Object
The server-script object is similar to the script object used in HTML, except that it is used to access CenterView objects instead of browser objects, and it runs exclusively on CenterView Server. The format of the server-script object is as follows:
<ct:server-script id="identifier" debug="true|false"> <![CDATA[Server Script code]]> </ct:server-script>
This notation works well except when the Server Script includes embedded CDATA sections. In this case, the ending braces of the CDATA section need to be string concatenated as shown in the example below.
Sample Server Script with embedded CDATA section
<ct:server-script>
<![CDATA[myXml = "<MyTag><![CDATA[h=3;]" + "]></MyTag>"]]>
</ct:server-script>
The following server-script attributes are available:
id (optional) Uniquely identifies this section of code. When errors are reported, the id is included to help you locate compile errors. If an id is not provided, the error report counts the sections of script code and reports the section number in which the error occurred.
debug (optional) Instructs CenterView Server, when set to True, to stop execution and launch Server Script Debugger when this section of code is entered. For more information, see Server Script Debugger. The default value is False.
Inline Server Script
Inline Server Script is typically used in an object attribute to insert a variable into the attribute value as it is processed. For example:
<ct:datasource src="kpis/${myVar};.kpixml" component="graph"/>
In the example above, ${myVar}; is replaced with the value of the last statement in the Server Script code. Server Script must be enclosed in braces {} and followed by a semicolon (;). White space (including new lines) is allowed only in the Server Script code inside the braces.
There are two variants of the command:
${Server Script}; Standard inline Server Script format, used for inserting variables into dashboard XML.
$!{Server Script}; Stops execution and launches Server Script Debugger when this section of code is entered. For more information, see Server Script Debugger.
Server Script Objects and Methods
The Corda Dashboard makes the following objects available to Server Script.
| Warning: Server Script parameters are not required. If any parameters are left undefined, or do not exist, then the default value is used, based on the parameter type. For String parameters the default is undefined; for Boolean parameters the default is false; for Int parameters the default is 0. |
CenterView Objects Accessible by Server Script
| Object | Method | Description | ||
|---|---|---|---|---|
| console | writeln(String msg) | Writes the specified message to the console page. | ||
| content | write(String xml) writeln(String xml) |
Writes XML to the .xml file. XML objects written in this manner are processed as if they were in the .xml file, replacing the code in the server-script object. | ||
| dashboard | varName | References or sets dashboard variables (accessible to all pages, KPIs, and Datafunnels in this dashboard). They are all strings. | ||
| dashboard | setRedirect(String url) | Specifies the URL to which the dashboard redirects the user. The remainder of the Server Script is still processed following the redirect, so use an if|else to enclose code that should not be executed when redirecting. | ||
| datafunnel | get(String dfName, String request-vars) | Static method that returns a datafunnel object created using the dfName (for example, datafunnels/myData.dfxml) and the request-vars. The request-vars are passed to the datafunnel as though they were set as part of the request. After instantiating a datafunnel object with datafunnel.get, manipulate the datafunnel instance using the methods listed in the Supported Methods for Instantiated Datafunnels table. | ||
| env | getDashboardPath() | Returns the path for this dashboard. | ||
| env | getThemePath() | Returns the path for the theme used by this dashboard. | ||
| env | getDashAccessList() | Returns an HTML table with a list of all the dashboards the current user can access (used for the list of dashboards in the Welcome dashboard). | ||
| env | getSharedPath() | Returns the file system path to the Shared folder under CenterView. | ||
| env | getServerRootPath() | Returns the file system path to the Server folder under CenterView. | ||
| env | getDocRootPath() | Returns the file system path to the doc_root folder. Normally this is found at product_root/Server/doc_root. | ||
| env | getDataRootPath() | Returns the file system path to the data_root folder. Normally this is found at product_root/Server/data_root. | ||
| env | getImageTemplatePath() | Returns the file system path to the image_templates folder under this dashboard. | ||
| request | addCookieValue(String name, String value) | Encrypts the name-value pair and adds the resulting string to the cookies with the expiration set to 6 weeks. | ||
| request | addCookieValueWithExp(String name, String value, String exp) | Encrypts the name-value pair and adds the resulting string to the cookies with the expiration set to the number of seconds indicated by exp. | ||
| request | getCookie(String name) | Returns the value of the named cookie variable that was not added using addCookieValue or addCookieValueWithExp. | ||
| request | getCookieNames() | Returns a string array of the cookie names that were not added using addCookieValue or addCookieValueWithExp. | ||
| request | getCookieValue(String name) | Gets the value of a cookie added using addCookieValue or a addCookieValueWithExp. This differs from the getCookie method because it decrypts the cookie name-value pair while getCookie does no decryption. | ||
| request | removeCookieValue(String name) | Removes a cookie added using addCookieValue or a addCookieValueWithExp from the list of cookies. | ||
| request | getHeader(String name) | Returns the value of the named HTTP header variable. | ||
| request | getHeaderNames() | Returns a string array of HTTP header names. | ||
| request | getLoginChallengeList() | Returns an XML String that has entry fields for all of the items for login. Typically, this is username and password, but custom authentication plugins can modify the list as needed for their specific needs. | ||
| request | varName | The request variables come from the parameters passed as part of the request that can be referenced or set. They are all strings. For example, the request dashboard/sales/kpis/my.kpixml?a=xyz&b=qwerty has two request variables a and b, each set to the value that follows the associated equal sign. | ||
| session | getAttributeNames() | Retrieves an array of the names of the attributes available in the session. | ||
| session | getAttribute(String name) | The session variables are accessible to all dashboards, pages and KPIs. They are all strings. The names and values are set in the http session by some process outside of the dashboard. This method allows access to these values. | ||
| session | getUsername | Deprecated. Use user.getUsername(). Returns the name of the currently logged-in user for the current dashboard or is undefined if the user is not logged in. |
||
| session | isLoggedIn | Deprecated. Use user.isLoggedIn(). Returns true if the user is logged in to the current dashboard and false if the user is not logged in. |
||
| session | LOGIN_MSG | A constant used with the session.getAttribute method to display login messages, including errors. Used when creating a login dashboard like the default Welcome dashboard. | ||
| snapshot | get(String dssxmlName, String requestVars) | Returns a snapshot object created using the dssxmlName (for example, snapshots/mySnapshot.dssxml) and the request-vars. The request-vars are passed to the snapshot as though they were set as part of the request. After instantiating a snapshot object with snapshot.get, manipulate the snapshot instance using the methods listed in Supported_Methods_for_Instantiated_Snapshots table. | ||
| user | varName | The user variables are read-only. The user variables come from the Authentication method. Often these values are set by the Authentication plugin, but can also be set using the LDAP or AD authentication method and using the ???? option to set user variables. | ||
| user | isAuthorized(String resourceName) | Returns true if the current user is authorized to access to the KPI or page resource. For example, myBoolean = user.isAuthorized(name.kpixml) | ||
| user | isLoggedIn() | Returns true if the user is logged in and false if the user is not logged in to the current dashboard. A user must be logged in for the other user methods to return useful results. |
||
| user | getEmailAddress() | Returns the current users email address. | ||
| user | getUsername() | Returns the name of the currently logged-in user for the current dashboard or is undefined if the user is not logged in. | ||
| user | isUserInGroup(String groupName) | Returns true if the current user is a member of the specified group. | ||
| user | getGroupList() | Returns a String Array of the names of all the groups the current user is a member of. If the user is not a member of any group an empty array will be returned. If the user is not logged in getGroupList() returns undefined. | ||
| userprop | varName | The user property variables are automatically saved across sessions for each user. This allows you to easily save user preferences and use them the next time the user accesses the dashboard. For more information, see Variables. | ||
| util | escapeSemicolons (String str) | Escape semicolons in the String str preceded by a backslash (so ; becomes \;). Use when creating a colon- or semi-colon- separated list (for example, name:value;name2:value2;). |
||
| util | getDate(String format) | Returns the current data/time in the format specified. The following tokens are replaced:
|
||
| util | getDrill(String drilltype, String requestVars, String clearVars, String popupName, String popupOptions) | Use to build drilldown that will work with CenterView's security and policy file for parameter passing. Options for drilltype are : 'update-page', 'update-kpi', 'goto-nav-id:pageNavID', 'update-kpilist:kpiID1,kpiID2', 'popup-page', 'popup-kpi', 'popup-url-post:http://www.somesite.com', 'popup-url-get:http://www.somesite.com', 'goto-url:http://www.somesite.com', 'goto-url-post:http://www.somesite.com', 'goto-url-get:http://www.somesite.com', 'popup-url-post-auto:http://www.somesite.com', 'popup-url-get-auto:http://www.somesite.com', 'goto-url-post-auto:http://www.somesite.com', 'goto-url-get-auto:http://www.somesite.com'.
|
||
| util | xmlEncode (String str) | XML encodes the specified string. Use when a variable will be output as part of the XML being processed by the CenterView Server. |
Supported Methods for Instantiated Datafunnels
| Method | Description |
|---|---|
| cell(row, col) | Returns the contents of the cell at row, col. The value returned is always a string and is undefined if the cell is outside the bounds of the datafunnel. The row and col values refer to row and column numbers starting at the top/left of the datafunnel. Use negative values to refer to row and column numbers starting at the bottom/right of the datafunnel. For example -1 specifies the last row/column, and -2 specifies the next to last row/column. |
| cellByNames(String rowName) String colName) |
Returns the contents of the cell located in the row where the value in the first column matches the rowName and the column where the value in the first row matches the colName. You can also pass numbers and the match will be done on that column number or row number. If there are columns or rows with a name that is the number it will match the column or row with the name. To force the method to use the value as a number prepend the pound sign (#) and enclose it in quotes. For example, #5 specifies row or column number 5. If no cell matches the specified name, an exception is thrown. |
| lookup(String lookupStr) int lookupCol int valueCol, boolean caseSensitive, String defaultValue) |
Returns the value from the valueCol in the same row where lookupStr is found in the lookupCol. If no match is found, the defaultValue is returned. If caseSensitive is true, then matching is case sensitive, otherwise case is ignored. |
| numRows() | Returns the number of rows in the datafunnel. |
| numCols() | Returns the number of columns in the datafunnel. |
| sum(String rowColAddr) | Returns the sum of the specified row or column. Row/Column addresses are of the form R2 (row 2) or C5 (column 5) or LR1 (last row) or LC2 (second to last column). |
| validate(String lookupStr) int lookupCol boolean caseSensitive) |
Validation that allows you to specify a case-sensitive comparison. |
Supported Methods for Instantiated Snapshots
| Method | Description |
|---|---|
| numCols() | Returns the number of columns in the snapshot datafunnel that will be written to the snapshot database. This is useful for pre-write testing of the datafunnel data. |
| numRows() | Returns the number of rows in the snapshot datafunnel that will be written to the snapshot database. This is useful for pre-write testing of the datafunnel data. |
| write() | Writes the contents to the snapshot. |
| clear() | Removes all data from the snapshot. |
| dataExists() | Returns true if there is data in the snapshot. |
Server Script Debugger
During the development and testing of Server Script for use in your dashboard, you can use the JavaScript Debugger in CenterView Server for troubleshooting. The debugger is part of the Rhino: JavaScript for Java (http://www.mozilla.org/rhino/) implementation used by CenterView. From the debugger, you can set breakpoints, inspect variables, step through code, run code, etc.
To use the Server Script Debugger, you must do the following:
- Enable the debugger on the appropriate CenterView Server.
- Specify the Server Script you want to debug in your dashboard.
To enable the Server Script Debugger
- Launch Corda Administrator.
For more information, see CenterView Administrator of the CenterView User Guide. - Modify the CenterView Server configuration and set JavaScript Debugging to On.
For more information, see Manage CenterView Servers of the CenterView User Guide. - Launch Image Template Editor, then open the desired dashboard.
- In the Object Browser, browse to and select the server-script object for which you want to enable debugging.
For more information on the server-script object, see Server-Script Object. - In Object Properties, set the debug attribute to True.
The debugger launches automatically when any Server Script with debug = true attempts to execute.
