HowTo Integrate

Overview

Database installation
Application Server/Oracle XE WebDave installation
Integration into your application
Documentation
Problems or Questions

Database installation

Follow the steps in HowTo Install to install the necessary views and packages in the database.

Application Server/Oracle XE WebDav Installation

This step is optional, but highly recommended, because if you put the files onto the Application Server, the browser can cache the files and doesn't have to load them for each page.

If you don't have access to the Application Server, you can also paste the content of the files into a page 0 region as described below.

On the Application Server go into the parent directory (that's the images directory) of the directory where the htmldb_get.js and htmldb_html_elements.js are located (images/javascript).
See APEX installation guide for details. For Oracle XE see Dietmar Aust's blog posting about file storage on XE.
Create a new directory called apexlib_1_7 in the images directory.

The version number has been added to the directory name, because the files are cached by the browser and just updating the files isn't always recognized by the browser. A different directory name helps to avoid this problem, so that the end users do not have to clear there browser cache.

Copy the following files from the JavaScript directory into this new directory:
- jquery_Compressed.js
- ApexLib_Compressed.js
- ApexLib_Lov.js
- ApexLib.css
- size_grip.png
After that you can integrate the files into your page templates. For details see Including JavaScript in a .js File Referenced by the Page Template.
The order has to be jquery_Compressed.js, ApexLib_Compressed.js and ApexLib.css
OR
If you don't want to touch all your page templates, you can also include the necessary commands into a page 0 region as described below.

Integration into your Application

Edit page 0, if it doesn't exist yet create a new page with type "blank page", set as page number "0", enter any name, no breadcrumbs, no tabs.

If you have not integrated the jquery_Compressed.js, ApexLib_Compressed.js and ApexLib.css into the page template, create a new region

Type: "HTML" and as subtype also HTML
Title: ApexLib - Javascript/CSS
Region template: no template
Display point: After Header

HTML Content

<script type="text/javascript" src="#IMAGE_PREFIX#apexlib_1_7/jquery_Compressed.js"></script>
<script type="text/javascript" src="#IMAGE_PREFIX#apexlib_1_7/ApexLib_Compressed.js"></script>
<link rel="stylesheet" href="#IMAGE_PREFIX#apexlib_1_7/ApexLib.css" type="text/css" />

Note: If you do not have access to the Application Server you can also create 3 regions for the different files and paste the content of the file into the regions. eg:

<script type="text/javascript" src="http://apexlib.oracleapex.info/v1.7/jquery_Compressed.js"></script>
Note: Because of some unknown reason the jquery library doesn't work if the content is pasted into the HTML region,
      but for testing purpose you can reference the last version from the apexlib.oracleapex.info web-site.

<script type="text/javascript">
Paste the ApexLib_Compressed.js content here
</script>

<style type="text/css">
Paste the ApexLib.css content here
</style>

Create a region on page 0

Type: "PL/SQL Dynamic Content"
Title: ApexLib - Before footer
Region template: no template
Display point: Before footer

PL/SQL source

---------------------------------------------
-- Get metadata of page
---------------------------------------------
ApexLib_Page.generateBrowserData;
---------------------------------------------
-- Get metadata of items and tabular forms.
---------------------------------------------
ApexLib_Item.generateBrowserData;
ApexLib_TabForm.generateBrowserData;

---------------------------------------------
-- Send data for cascading lovs
---------------------------------------------
ApexLib_Lov.generateBrowserData;

---------------------------------------------
-- Send NLS data for date formats and numeric
-- format masks and translated error messages
---------------------------------------------
ApexLib_Browser.setNlsData;
ApexLib_Browser.setApexLibMessages;

---------------------------------------------
-- Active different navigation improvements
---------------------------------------------
ApexLib_Browser.setLovIconsNonNavigable;
ApexLib_Browser.setLRButtonIconsNonNavigable
  ( pLeftClassName  => 'L'
  , pRightClassName => 'R'
  );
ApexLib_Browser.checkForLovKey;
ApexLib_Browser.checkForUpDownKey;

---------------------------------------------
-- Active different UI improvements
---------------------------------------------
/* optional
ApexLib_Browser.setTextareaProperty
  ( pProperty => ApexLib_Browser.VERTICAL_RESIZEABLE
  );
*/
---------------------------------------------
-- Init browser validation
---------------------------------------------
ApexLib_Browser.initValidation
  ( pShowRequiredWarning => TRUE
  );
---------------------------------------------
-- Has to be the last statement!
---------------------------------------------
ApexLib_Browser.flushJsBuffer;

For pLeftClassName and pRightClassName the class names of the surrounding button image TD has to be specified. Eg L and R or t1L and t1R, ... Use the Inspect function of Firebug or look into the HTML output to get the class names. If you don't use 3-part image buttons, you can remove that call.

Create a region on page 0
- Type: "HTML" and as subtype also HTML
- Name: ApexLib - Handle Error Page
- Region Template: no template
- Display point: Before footer
- HTML Content:
```
<script type="text/javascript">
apexlib.error.init
  ( "t7Messages"
  , "t7Notification"
  , "#6699cc"
  , "#000000"
  , apexlib.error.DISPLAY_LOCATION.FIELD_AND_NOTIFICATION
  );
apexlib.error.handleErrorPage();
</script>
```
  t7 has to be replaced by your theme number! The class name is case sensitive and has to match with the class name Oracle APEX is using to render the error notification.
  
  #6699cc is the background color and #000000 is the foreground color for cell highlighting.
  
  The last parameter is used to specify where error messages for page items are displayed.
  - FIELD_AND_NOTIFICATION
  - FIELD
  - NOTIFICATION
Create two new Application Items (Shared Components\Application Item) named
- APEXLIB_REFERENCE_TYPE and
- APEXLIB_REFERENCE_ID
Create an Application Process (Shared Components/Application Process)
- Name: ApexLib_getLovResult
- Process point: On Demand
- Process text
```
ApexLib_Lov.generateLovResult(:APEXLIB_REFERENCE_TYPE, :APEXLIB_REFERENCE_ID);
```
Create an Application Process (Shared Components\Application Process)
- Name: ApexLib-Before Computation/Validation
- Sequence: 1 (should be a number before any of your page level processes)
- On submit: After Page Submission - Before Computations and Validations
- Process Text:
```
BEGIN
    ApexLib_Item.trimItems;
    ApexLib_TabForm.trimColumns;
    ApexLib_Lov.clearLovNullValues;
    ApexLib_Item.validateItems;
    ApexLib_TabForm.validateColumns;
    --
    ApexLib_Error.showErrorStack;
END;
```
- Process Error Message: #SQLERRM#
If you want to change or translate the text used by the framework, create the following Text Messages (Shared Components/Text Message)
- Name: APEXLIB_ITEM_REQUIRED
- Text:
```
%label is required.
```
- Name: APEXLIB_ITEM_REQUIRED_INLINE
- Text:
```
Is required
```
- Name: APEXLIB_ITEM_INVALID_FORMAT
- ```
%label doesn't match to the format "%0" (eg %1).
```
- Name: APEXLIB_ITEM_INVALID_FORMAT_INLINE
- ```
Format "%0"<br>Eg %1
```
- Name: APEXLIB_ITEM_BETWEEN
- ```
%label has to be between %0 and %1.
```
- Name: APEXLIB_ITEM_BETWEEN_INLINE
- ```
Has to be between<br>%0 and %1
```
- Name: APEXLIB_ITEM_GREATER_OR_EQUAL
- ```
%label has to be greater or equal to %0.
```
- Name: APEXLIB_ITEM_GREATER_OR_EQUAL_INLINE
- ```
Has to be greater or<br>equal to %0
```
- Name: APEXLIB_ITEM_LESS_OR_EQUAL
- ```
%label has to be less or equal to %0.
```
- Name: APEXLIB_ITEM_LESS_OR_EQUAL_INLINE
- ```
Has to be less or<br>equal to %0
```
- Name: APEXLIB_TABFORM_COLUMN_REQUIRED
- Text:
```
%label is required.
```
- Name: APEXLIB_TABFORM_INVALID_FORMAT
- Text:
```
%label doesn't match to the format "%0" (eg %1).
```
- Name: APEXLIB_TABFORM_BETWEEN
- Text:
```
%label has to be between %0 and %1.
```
- Name: APEXLIB_TABFORM_GREATER_OR_EQUAL
- Text:
```
%label has to be greater or equal to %0.
```
- Name: APEXLIB_TABFORM_LESS_OR_EQUAL
- Text:
```
%label has to be less or equal to %0.
```
- Name: APEXLIB_TABFORM_ROW_PREFIX
- Text:
```
Row %0:
```
Go to Shared Components\Application Definition\Template Defaults\Error Page Template and get the template name of the Error Page Template

Open the Shared Components/Templates/Page/[your error page template] and go to the Error Page Template Control section. Paste the following HTML code

<div id="ApexLibErrorMessage" class="ApexLibErrorMessage" style="display:none">#MESSAGE#</div>
<a href="javascript:ApexLib_extractErrorPage()">#OK#</a>

<script language="javascript">
function ApexLib_extractErrorPage()
{
 var vElementList = null;
 var vErrorStack  = null;
 //----------------------------------------------------------------------------
 // Find our ErrorPageMessage and ApexLibErrorMessage div elements.
 // Extract and store them in a cookie
 //----------------------------------------------------------------------------
 vElementList = window.document.getElementsByTagName("div");
 for (i=0; i < vElementList.length; i++)
 {
   if ((vElementList[i].className == "ErrorPageMessage") ||
       (vElementList[i].className == "ApexLibErrorMessage"))
   {
     vErrorStack = (vErrorStack == null?"":vErrorStack+"<br />")+vElementList[i].innerHTML;
   }
 }
 // store the error message in a cookie
 var vCookieCount   = 0;
 var vCookieContent = null;
 while (vErrorStack != "")
 {
   vCookieCount++;
   vCookieContent = vErrorStack.substr(0, 4000);
   vErrorStack    = vErrorStack.substr(3999);
   document.cookie = "ApexLibErrorStack"+vCookieCount+"="+encodeURIComponent(vCookieContent);
 }
 //----------------------------------------------------------------------------
 // now go back the the previous page, on that page an onload event will check
 // if the cookie exists and paste it into the page.
 //----------------------------------------------------------------------------
 window.history.go(-1);
} // ApexLib_extractErrorPage

// If debug mode is enabled, don't do a redirect immediatly so that
// the debug info isn't lost
if (!html_GetElement('pdebug'))
{
  ApexLib_extractErrorPage();
}
else
{
  document.getElementById("ApexLibErrorMessage").style.display="block";
}
</script>

Depending on the theme you are using in your application, you also have to check the other page templates. There you have to search for
```
#SUCCESS_MESSAGE# #NOTIFICATION_MESSAGE#
```
in the Definition/Body section. If the text is not surrounded by
```
<div class="t7Messages">
#SUCCESS_MESSAGE# #NOTIFICATION_MESSAGE#
</div>
```
you have to replace it with the above text.

t7 has to be replaced by your theme number! It's also ok if the class name is called t13MessageHolder for example. In that case you have to adapt the apexlib.error.init call to use this class name. The class name is case sensitive!
Open the Shared Components/Templates/Popup List of Values/Popup LOV and go to the Page Attributes/Page Heading Text section. Paste the following HTML code
```
<script type="text/javascript" src="#IMAGE_PREFIX#apexlib_1_7/ApexLib_Lov.js"></script>
```
in front of the existing code. If you do not have access to the Application Server you can also paste the code directly into the section.
```
<script type="text/javascript">
Paste the ApexLib_Lov.js content here
</script>
```

That's it! Now you can use all the features of the ApexLib Framework!

Documentation

Check out the related ApexLib postings for an explanation and examples of the different features.

Also take a look at the package specifications (*.pks) of the different packages. This will show you all the APIs of the framework and they are very well documented (or at least I hope so :-) ).

The behavior of the framework can be changed by adding hints into the comment text or link attributes (for report columns) of the different items. The following hints do exist so far, for an explanation see the postings.

$APEXLIB_IGNORE_LOV$
$APEXLIB_IGNORE_LOV_NULL$
$APEXLIB_ALWAYS_REFRESH$
$APEXLIB_IGNORE_VALIDATION$
$APEXLIB_REQUIRED$
$APEXLIB_UPPERCASE$
$APEXLIB_LOWERCASE$
$APEXLIB_CAPITALIZE$
$APEXLIB_V_RESIZE$
$APEXLIB_MAX_LENGTH=length$
- $APEXLIB_MAX_LENGTH=40$
$APEXLIB_MIN_VALUE=fixed value or column/item reference$
- $APEXLIB_MIN_VALUE=0$ => has to comply to the format mask of the column/item!
- $APEXLIB_MIN_VALUE=#HIRE_DATE#$ for a Tabular Form Column reference
- $APEXLIB_MIN_VALUE=&P4_HIRE_DATE.$ for a Page Item or Application Item reference
$APEXLIB_MAX_VALUE=fixed value or column/item reference$
- $APEXLIB_MAX_VALUE=5,000$ => has to comply to the format mask of the column/item!
- $APEXLIB_MAX_VALUE=#MAX_SALARY#$ for a Tabular Form Column reference
- $APEXLIB_MAX_VALUE=&P4_MAX_SALARY.$ for a Page Item or Application Item reference
$APEXLIB_HIDE_SELECT_ALL$

Problems or Questions

My page item isn't validated by your library!

Have you set a format mask for the numeric item?
Have you set a date picker?
Does the item/region have a condition/authorization?
Enable debug mode, there you see why the library isn't validating your item as soon as you press submit

I have tested the library with FireFox 2.0 and IE 6.0, if you have another browser where it doesn't work, let me know.

Should you have problems or questions about the integration. Or want to have a new features, don't hesitate to contact me at patrick.wolf@oracleapex.info!

HowTo Integrate

Download

Version 1.7

Navigation

HowTo Integrate

DownloadVersion 1.7

Navigation

Download

Version 1.7