the open source, cost free,
reliable Add-On to Oracle Application Express

by Patrick Wolf and Peter Raganitsch

HowTo Integrate manually

Integration into your Application

For your convenience we automated the integration with the script ApexLib_integrate_into_application.sql, so you don't need to follow the steps below.

BUT: If you wan't to be really careful integrate by hand with the following instruction:

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 ApexLib_Full-min.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_2_1/ApexLib_Full-min.js">
</script>
<link rel="stylesheet" href="#IMAGE_PREFIX#apexlib_2_1/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">
Paste the ApexLib_Full-min.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 data for AJAX computations
---------------------------------------------
ApexLib_Computation.generateBrowserData;

---------------------------------------------
-- Send data for AJAX Page Process
---------------------------------------------
ApexLib_Process.generateBrowserData;

---------------------------------------------
-- Send data for button hotkeys
---------------------------------------------
ApexLib_Button.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
- APEXLIB_ROUTINE_TYPE
Create an Application Process (Shared Components/Application Process)
- Name: ApexLib_getGenericResult
- Process point: On Demand
- Process text
```
ApexLib_Generic.generateResult
  ( :APEXLIB_ROUTINE_TYPE
  , :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.setBoolDefault;
    ApexLib_Item.trimItems;
    ApexLib_TabForm.trimColumns;
    ApexLib_Lov.clearLovNullValues;
    ApexLib_Item.validateItems;
    ApexLib_TabForm.validateColumns;
    --
    ApexLib_Error.showErrorStack;
END;
```
- Process Error Message: #SQLERRM#
Create a static LOV (Shared Components\List of Values)
- Name: APEXLIB_BOOLEAN_1_0
- We need only on value - aka one sequence
- Display Value:
- Return Value: 1
Create a static LOV (Shared Components\List of Values)
- Name: APEXLIB_BOOLEAN_Y_N
- We need only on value
- Display Value:
- Return Value: Y
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:
```
You can enter these Text Messages manually or use the File Scripts\ApexLib_load_apexlib_messages_de.sql (containing german translations) as a template to do your own translation and add them to all applications you want to.
Please remember to connect to your applications parsing schema (e.g. SQLPLUS your_application_user/pwd) and to set a AL32UTF8 characterset (e.g. AMERICAN_AMERICA.AL32UTF8) before applying this scripts.

Windows example:

C:\ApexLib\Scripts> SET NLS_LANG=AMERICAN_AMERICA.AL32UTF8 C:\ApexLib\Scripts> SQLPLUS my_application_user/xxxyyyyxxx@somewhere SQL> @ApexLib_load_apexlib_messages_de

Then you will be asked for the application id where you want to add the Text Messages. Thats it!
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_2_1/ApexLib_Lov-min.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-min.js content here
</script>
```

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

the open source, cost free, reliable Add-On to Oracle Application Express

by Patrick Wolf and Peter Raganitsch

HowTo Integrate manually

the open source, cost free,
reliable Add-On to Oracle Application Express