How-To Document

Build Custom Popup Pages in Oracle Application Express (formerly HTML DB)

Author: Raj Mattamal

Date: 26-Nov-2003

After completing this How-To, you should understand:

  • How to make a custom popup window page in an HTML DB application
  • Passing values from a form page to a popup window.
  • Passing values back from a popup window to the opening form page.

Introduction

Although HTML DB allows application developers to declaratively add popup list of value (popup LOV) items to their pages, occasionally application design requires developers to create custom popup pages. This how to describes the steps to create such a custom popup page with some advanced functionality.

Software Requirements

  • Oracle HTML DB

  • Web browser such as Netscape 7+ or Internet Explorer 5.5+

Example Scenario

       The example described in this how to adds a custom popup LOV to a form on the SCOTT.EMP table. Clicking the popup LOV link on the form page will popup an LOV page that allows users to search by ENAME, JOB, and SAL. Selecting a value from this LOV page will close that popup LOV page and populate the ENAME, JOB, and SAL fields on the form page with the selected values. Additionally, had the user entered some data into the ENAME, JOB, and/or SAL fields on the form page, that data would be used in the initial search when the popup LOV page is first shown.

Step 1 - Create a simple form page on SCOTT.EMP

       To create the form page, simply step through the HTML DB "Form on a Table or View" wizard against the EMP table accepting the defaults.  For this example, create the form with a page number of one, and make sure to allow the ename, job, and sal fields to be editable. When the wizard completes, page 1 of the application should have the items P1_ENAME, P1_JOB, and P1_SAL on it as text fields.

Step 2 - Create a popup page with search fields

       Next, create a page that's to be used as the popup window: Page 2. Ultimately, this page will have javascript, a report region, and some buttons. For now, though, just create a page 2 with the items P2_ENAME, P2_JOB, and P2_SAL on it as text fields.

Step 3 - Add Javascript call to the popup page

       Because the popup page should filter its result set based on any values that the user might have entered onto the form page, you need to add a javascript function that would pass those values off. Add the following function to the "HTML Header" field of the page-level attributes screen for page 1 to accomplish this:

<script language="JavaScript" type="text/javascript">
  function callMyPopup (formItem1,formItem2,formItem3) {
    var formVal1 = document.getElementById(formItem1).value;
    var formVal2 = document.getElementById(formItem2).value;
    var formVal3 = document.getElementById(formItem3).value;
    var url;
  url = 'f?p=&APP_ID.:2:&APP_SESSION.::::P2_ENAME,P2_JOB,P2_SAL:' + formVal1 + ',' + formVal2 + ',' + formVal3 ;
  w = open(url,"winLov","Scrollbars=1,resizable=1,width=800,height=600");
  if (w.opener == null)
  w.opener = self;
  w.focus();
  }
</script>


Though you don't need to know how to read javascript for this example, it helps to understand that this function only does one important thing: it opens a popup window of page two in our application while passing values to P2_ENAME, P2_JOB, and P2_SAL. It gathers those values to pass from the names of the HTML DB items provided to it. The call to this function will be added in the next step below.



Step 4 - Add a popup link next to the P1_SAL field on the form page

      Add a link to the form page that will call the callMyPopup function above and pass it the values it needs.  To do so, place the following HTML in the "Post Element Text" field attribute of the P1_SAL item:

<a href="javascript:callMyPopup('P1_ENAME','P1_JOB','P1_SAL');">Click for LOV</a>



Step 5 - Add the LOV report to the popup page


       The next step is to create a report on the popup page based on the values passed from the form on page one.  The tricky part of this report is providing a means for the selected values to be passed back to the form page. This can be achieved by having a column of the report render as a javascript link that would close the popup window and pass the ename, job and sal values for that row back. Start by adding a simple report region to our popup page that uses a query such as:

      select ename, job, sal , 'placeholder' the_link
        from emp
       where ename like '%'||:P2_ENAME||'%'
         and (job = :P2_JOB or :P2_JOB is null)
         and (sal = :P2_SAL or :P2_SAL is null)



Note that the last column in this query is just a placeholder. once the region is created, turn that placeholder into a link by doing the following:
  1. Navigate to the Page Definition for page 2
  2. Next to the name of the report region created in step 5, Click Q
  3. Next to the column THE_LINK, click the edit icon
  4. In the "Link Text" field enter the string "select"
  5. In the URL field enter: javascript:passBack('#ENAME#','#JOB#','#SAL#');
  6. Click the "Apply Changes" button

Step 6 - Add the javascript function to the popup page to pass selected values to the form page

       In the previous step you added a call to a javascript function, passBack. Now add that function to the top of page 2. In the same manner as step 3 above, add that passBack function to the page 2 by putting it in the "HTML Header" field of the page-level attributes screen. The function should look similar to the following:

<script language="JavaScript">
   function passBack(passVal1, passVal2, passVal3)
   {
   opener.document.getElementById("P1_ENAME").value = passVal1;
   opener.document.getElementById("P1_JOB").value = passVal2;
   opener.document.getElementById("P1_SAL").value = passVal3;
   opener.document.getElementById("P1_SAL").focus();
   close();
   }
</script>



This function simply sets the values of P1_ENAME, P1_JOB, and P1_SAL with the values of the whatever's stored to the three HTML DB item names passed to it. It also closes the current window and puts the cursor back into the P1_SAL field.



Step 7 - Polishing

     The basic functionality of this custom popup window has been created in steps 1 though 6. To make its usage a little more friendly, it's advisable to add Cancel and Search buttons to the popup window page. The Search button should just be added as a regular button that branches back to the page 2. Adding this button allows users to re-query for LOV options without having to return to our form page. The Cancel button should be created with an "Action" of "Redirect to URL". The "URL Target" of the button should be "javascript:window.close()". As the code suggests, the Cancel button would just close the popup window (with no values returned). 

Additional Resources

Oracle HTML DB Home

Discuss this how-to in the Oracle HTML DB Discussion Forum .