Example - Use Universal Display Files with AJAX

Overview

In this example, you can see how to use an RPG program with a Rich Display that uses AJAX to call a Universal Display File. We’ll show you how to display an autocomplete textbox that when an input value is added produces an output in a neighboring textbox. 

These are the different sources provided, to help you familiarize yourself with them here is a short description of what each file does:

• acme.js = JavaScript routines

• itmmasp.sql.txt = SQL script that will build the ITMMASP physical file. This is the Item Master used by the demo programs and contains the product information that will be returned.

• prodinfo2d.dspf.txt  = Universal Display File used to create a REST API that sends product information via AJAX

• prodinfo2c.clle.txt  = CL program that sets the library list needed by PRODINFO2R, below.

• prodinfo2r.rpgle.txt = RPG program that uses a Universal Display to create a REST API to return product information.

• invoice2d.dspf.txt   = Rich Display File that creates the screen that the user sees.

• invoice2r.rpgle.txt  = RPG program that drives the Rich Display File, above.

Configuring this Example

To access and run this example program we have broken down the instructions into 9 steps. After downloading the example folder follow the below procedure to install the code on your system. 

1. Decide which library you want this placed into and which Profound UI instance you will use. Make sure you know the library names of each. 

2. Create a database table (physical file) containing the item master information. There are two ways to do this: 

   1. Upload the file to a source member and run it with RUNSQLSTMT.

      How to do this: 

•  

  • Open the 5250 Green Screen 

  • Run the command: RUNSQLSTM SRCFILE(YOUR-LIBRARY/QSQLSRC) SRCMBR(ITMMASP) COMMIT(*NONE) DFTRDBCOL(YOUR-LIBRARY)

    • To view the table with inserted data run STRSQL then run the command SELECT * FROM ITMMASP 

                b. Copy/paste the contents of itmmasp.sql.txt into Run SQL Scripts. 

      How to do this:

•  

  • Open IBM I Access Client Solutions and select Run SQL Scripts

  • Copy and paste in the contents of the file itmmasp.sql.txt

  • Add in the line CL: chgcurlib YOUR-LIBRARY to the beginning of our program (as seen in the screenshot below).

  • Run the program, either by selecting Run /All or using Ctr-R

Open

   3. Upload the acme.js JavaScript code to your instance's userdata/custom directory. 

        acme.js ->  /www/YOUR-INSTANCE/htdocs/profoundui/userdata/custom/acme.js

   4. If you plan to use this from Genie, use the Genie Administrator to edit your skin's start.html file and add the following script tag. It should be the last script tag in the HTML (after things like custom.js, etc). You only need to do this if you plan to run it from Genie.

   5. Upload the RPG, CL, and DDS code to source members on your IBM i.  One easy way to do this is by using FTP to send the files in ASCII mode to the appropriate members. Another easy way is just to copy/paste the code into the member using RDi, VS Code (with Code for i), or similar. Below is an overview of where the files will be stored: 

   prodinfo2d.dspf.txt -> YOUR-LIBRARY/QDDSSRC,PRODINFO2D
   prodinfo2c.clle.txt -> YOUR-LIBRARY/QCLSRC,PRODINFO2C
   prodinfo2r.rpgle.txt -> YOUR-LIBRARY/QRPGLESRC,PRODINFO2R
   invoice2d.dspf.txt -> YOUR-LIBRARY/QDDSSRC,INVOICE2D
   invoice2r.rpgle.txt -> YOUR-LIBRARY/QRPGLESRC,INVOICE2R

   6.  Edit the PRODINFO2C CL code. This sets up the library list used by the REST API that was created via the Universal Display Tool. It will need to be changed to add the libraries containing (1) the RPG programs, (2) the ITMMASP file, and (3) the Profound UI instance you plan to run this on.

It is a fairly simple CL program, so it should be easy to make sure you have all of the libraries added properly. If you have your program saved in the same library as your file then you will only need one addlible line however, if you have the file and the program saved separately then you will need to set up two addlible. One for YOUR-FILE-LIBRARY and another for YOUR-PROGRAM-LIBRARY (see screenshot below). 

Open

   7. Compile the REST API:

   8.  Install the REST API.  This is done by adding a row ("record") to the PUIMAPP file in your Profound UI instance. This can be done easily with the PUIWRKMAP utility from within a Genie session, or simply by running the following SQL statement from the 5250 Green Screen. 

This is setting the URL call for your library and mapping a URL to a program. If you would rather do it from Genie, run the PUIWRKMAP utility and add a record as follows:

    9. Compile the Rich Display and corresponding RPG program:

How to Launch

If you plan to run this from a Rich Display Launcher (/profoundui/start or Atrium Rich Display) make sure you have YOUR-LIBRARY in your library list, as described here: https://profoundlogicsupport.atlassian.net/wiki/x/JgXOCQ -- then make it your initial program in the Designer's Maintain Initial Programs dialog.  Finally, run the initial program via the Visual Designer's Launch Session option. Extended details on how to launch with each program are below. 

• To run the program in Genie, start your Genie Skin (the one you added the <script> tag to, above), sign on, and use the green-screen EDTLIBL tool to make sure YOUR-LIBRARY is in your library list. Then use the command CALL INVOICE2R to launch your program. 

• To run from Atrium navigate to your Control Panel (Settings/Control Panel). From the Users/Groups tab click on the user profile you want to use and click Edit. From there uncheck the Inherit Settings box and click the Add button within the Library List for Rich Display File Applications to add your program library and any other libraries you need (but you don't need to add the Profound UI instance library). As seen in the screenshot below. Save the configuration. 

         Next, select the Navigation tab and set up a Navigation Item. Instructions on how to do that here - https://profoundlogicsupport.atlassian.net/wiki/x/XPzNCQ. Once you have that setup fill in the Item Details with the Item name, Action type, Display file program library, and Display file program (as seen in the screenshot below). Click Update to update the Item Details and click the Close button to exit the Control Panel when you are finished.    

       Back on the home page of Atrium double click on Invoice example under the Navigation tab to launch. 

• To run from the Visual Designer click the Launch button then select Maintain Initial Programs... from there add in the program INVOICE2R and save the changes. Then select Launch Session to run the program.

End Result 

Once you launch the program you will see the below screen. Here you can type in an item number and a description for it will display in the far right column. If an incorrect item number is added the error message **ERROR: item not found will be shown in the description box. 

Understanding the Code

From the Visual Designer open INVOICE2D and select the [item] textbox located in the first column of the grid. On the right, the item properties will be displayed, navigate to the Events section to find the onkeyup property or search it in the Find Property search box. The onkeyup property initiates a client-side script when the user releases the keyboard key on this element. Simply put when the user enters the item number into the Item text box the line of code acme.getDescription(row); initiates the JavaScript function acme.getDescription in file acme.js. 

Open the file acme.js (this can be done using the Files tab in the Visual Designer) to see the function acme.getDescription from lines 62-87.  The following is an excerpt from acme.js:

Near the end of this excerpt (line 84 of the original acme.js) is the AJAX call, which uses acme.sendJSON to make an HTTP post request to the /prodinfo2 URI mapping for the Universal Display File that we set up, above.  This lets the JavaScript running in your web browser (which is on your PC) communicate with the Universal Display (and corresponding RPG program) that is running on the IBM i.  Its parameters tell it to send the inputData object to the RPG program, and to call the setDescription function asynchronously when the RPG program returns results.

The variable inputData (line 66) is build with information from the three grid columns (Item, Quantity, and Price) by calling the Grid's getDataValue() function. The function below it, setDescription (line 73) is receives the result object from the Universal Display File and checks to see if it is successful or not. The Universal Display built this objects using the two record formats named successFmt and errorFmt. To see these two record formats you can open the Universal Display file (prodinfo2d.dspf.txt) in the Universal Display File Editor (click here for instructions on how to do that or refer to the screenshots below.) Using an if, else statement the setDescription function sets the Description column's font color (with style.color) to either be gray (#333333) if successful or red (#FF0000) if an error, as well as populating it with either the item's corresponding description or "** ERROR".

We hope this document helped you understand how to use a Universal Display File with AJAX. Overall the invoice example files are meant for you to launch, examine and understand as well as to edit and tailor to fit your own program as need be.