Skip to end of metadata
Go to start of metadata

SAP Screen Personas

Scripting: Including Global Javascript Libraries

SAP SCREEN PERSONAS KNOWLEDGE BASE - by Tamas Hoznek , Regina Sheynblat , Kranthi Kumar Muppala


This article shows how a Javascript library can be included within scripts so that functions from the library can be reused across scripts within a flavor or scripts across flavors. This feature helps remove code duplication in scripts and improves maintainability.


In order to include a Javascript library to be used in scripts, the Javascript file must be uploaded as a resource file using the SAP Screen Personas administration transaction and the uploaded resource ID can then be used as a parameter of the session.utils.include API. These steps are explained in detail in the following sections. There is also a section that mentions a few caveats on how the Javascript libraries need to be structured to work correctly in SAP GUI for Windows and SAP GUI for Java.

Upload the Javascript File

I will use a Javascript file with the following contents and will refer to the file name as 'TableControlUtilities.js' in this section.

 * Returns an array of rows containing information from the table control.
 * @param {string} sTableControlId - The ID of the table control.
 * @returns {Array[Object]} The contents array.
copyTableContents = function(sTableControlId) {
    // Fetch the table and its columns
    var oTableControl = session.findById(sTableControlId),
	aColumns = oTableControl.columns,
	aContents = [],
    if (oTableControl.rowCount > 0) {
        //Set the visible row to 0
        oTableControl.firstVisibleRow = 0;
        //Get the Max visible row number
        nTopRow = oTableControl.visibleRowCount - 1;
        //Loop through all the rows
        for (nRowIndex = 0; nRowIndex < oTableControl.rowCount; nRowIndex++) {
            oRow = {};
            if (nRowIndex > nTopRow) {
                // Set the first visible row to the next set of rows. If the next set goes beyond the maximum rows,
                // adjust it so that the set's last row is the table's last row.
                if (nTopRow + oTableControl.visibleRowCount > oTableControl.rowCount) {
                    oTableControl.firstVisibleRow = oTableControl.rowCount - oTableControl.visibleRowCount;
                } else {
                    oTableControl.firstVisibleRow = nTopRow + 1;
                nTopRow += oTableControl.visibleRowCount;
            // Populate the row information.
            for (i = 0; i < aColumns.length; i++) {
                sColumnName = aColumns.elementAt(i).name;
                oRow[sColumnName] = oTableControl.getCellValue(nRowIndex, sColumnName);
            // Break after the first blank row - the values usually contain all underscores like "____" for a 4 character column.
            if (!oRow[aColumns.elementAt(0).name].replace(/_/g, "")) {
    return aContents;
  1. Open the transaction /PERSONAS/ADMIN in your favorite SAP GUI application and navigate to Resources, then click on the 'Create' button..
  2. In the file selection dialog, change the file filter from 'Images...' to 'JavaScript Files (*.js)'.
  3. Choose the file 'TableControlUtilities.js' or any Javascript file from the file system. The library file is now uploaded as a new resource.
  4. Double-click the new resource in the grid to display its details. You can change the description to provide more information about the included functionality.
  5. Make a note or copy the value of the GUID field in the Metadata tab. This is the ID of the Javascript library that will be used in subsequent sections.

Include the Javascript Library

The uploaded Javascript library can be used in any script of any flavor using the session.util.include API. This function accepts two parameters:

scriptResourceId - this is the GUID of the uploaded resource file.

alwaysExecute: this accepts a Boolean value - if set to 'true', then the Javascript file is always executed when the include is called; if set to 'false', the Javascript file is only executed once when the include is called for the very first time in a session.

Here's an example of how the 'TableControlUtilities.js' library can be used to copy the contents of a table control.

  1. Go to transaction GUIT.
  2. In the OK Code field, input 1000 and hit enter key. This will open the table control test screen.
  3. Create a new flavor or open an existing flavor and open the script editor.
  4. Create a new script and input the following script contents:

    Script to Copy Contents of the GUIT - 1000 Table Control
    // Load the 'TableControlUtilities.js' library.
    session.utils.include("005056840F9E1ED792F82B5AA410703F", false);
    // Fetch the contents of the table control.
    var aContents = copyTableContents("wnd[0]/usr/tblSAPM_GUITEST_PORTABLETABLECONTROL");
    // Output the contents to the browser console.
  5. Save the script and execute it.
  6. Open the browser console and observe the output of the table control's contents.

Usage in SAP GUI for Windows and SAP GUI for Java

The session.utils.include API works as described in previous sections in SAP GUI for HTML. There are a couple of caveats for using the API in SAP GUI for Windows and SAP GUI for Java:

  1. The alwaysExecute parameter is ignored in SAP GUI for Windows and SAP GUI for Java. The included script is always executed.
  2. In SAP GUI for HTML, functions such as the copyTableContents from the example are available as a part of the window object and can be accessed directly from any script. However, this is not possible in SAP GUI for Windows and SAP GUI for Java. In order to use functions defined in the Javascript library in these GUI applications, the library file should return an object with the functions. Here's an example of a library that would work on all GUIs:

    Table Control Library that will Work on all GUIs
    var tableControlLibrary = {
    	copyTableContents: function(sTableControlId) {
    		// Implementation...
    	exportToSpreadsheet: function(sTableControlId) {
    		// Implementation...
    return tableControlLibrary;

    Here's the corresponding usage of the above library:

    Usage of the Table Control Library
    // Load the 'TableControlUtilities.js' library.
    var tableControlLibrary = session.utils.include("005056840F9E1ED792F82B5AA410703F", true);
    // Fetch the contents of the table control.
    var aContents = tableControlLibrary.copyTableContents("wnd[0]/usr/tblSAPM_GUITEST_PORTABLETABLECONTROL");

    Notice the difference in the way the copyTableContents function is invoked in the above example.

Related Content

Related Search Terms:

SAP Screen Personas, Scripting, Script Include, Global Scripts, session.utils.include