APEX and AJAX – Where to Start
June 2010
Tim St. Hilaire
Story – Why I Love ODTUG
Introduction
We will walk through a series of examples that achieve the basic
components of dynamic actions within APEX
•
•
•
•
•
•
•
Partial Page Refresh reports
Calling On Demand Processes
Setting Session Variables with AJAX
APEX 4.0 options
Consuming Pages
Consuming Partial Pages
Debugging Notes
Note Taking
Reference
Report Refresh – Current Behavior
• Every standard button press will submit the entire page
• When a page is submitted, it re-draws the entire content
• NOTE – As APEX continues to improve, other components employ
sophisticated partial page and dynamic refresh capabilities. Example –
Pagination in Partial Page Refresh template reports and Interactive
reports
Demonstration
Report Refresh – Basic Refresh
•
•
•
Using a feature that is provided with APEX to support partial page refresh
capabilities for pagination.
The example shows how a java script call can re-query a report region.
Two important pieces are required
1. Definition of the Refresh Capability
2. Initializing an Instance of the Object
Definition
Report Refresh – Basic Refresh
Initialize the Object
Calling the Refresh
• Note: The initialize is easiest to place in the region header
Why?
• The Template Substitution Variable #REGION_ID# will only work within
the APEX region you are in.
Report Refresh – Basic Refresh
• Issue: The report is refreshed, but the SEARCH box is not used in the
report
Demonstration
Report Refresh – Session Variable
• Understanding the values of session variables is very important with
AJAX inside of APEX. The frameworks session variable construct is
very powerful and flexible.
• Using an ON DEMAND process as a simple request to allow the
session variable to be set
Note on JS Sources
•
•
•
•
The sources for this code is available on the APEX installation media
Note: a_report actually calls htmldb_Get
APEX 4.0 file located: apex\images\javascript\uncompressed\apex_4_0.js
APEX 3.2.1 – the $a_report and the htmldb_get function are in two files
apex\images\javascript\uncompressed\apex_get_3_1.js
apex\images\javascript\uncompressed\apex_3_1.js
On Demand Processes – Basic Example
• An On Demand Process are officially located under Application
Processes and can be called as part of page processing, but are
defined at the APPLICATION level as a Shared Component
On Demand Processes – APEX 4.0 Note
•
•
•
•
In APEX 4.0 – On Demand Processes can be defined at the PAGE level
This allows encapsulation of code on a page
This MAY also require duplication depending on application design
To Avoid the need for duplication of business logic
• Use Packages
• Continue to use Application Level Processes
• Use descriptive names wherever possible
• 255 characters…..
On Demand Processes – Basic Example
• The On Demand Process is an easy gateway for the PL/SQL developer
to access their PL/SQL code
Demonstration of On-Demand Usage
Page, Application, or Global Session Variables?
You may have noticed, in the last example, that the On-Demand Process
used an undeclared type of variable.
• In PL/SQL  wwv_flow.g_x01 through wwv_flow.g_x10
• In JavaScript  Parameter name x01 through x10
• Handy, but use carefully – generic placeholders with complex logic can
get confusing
• Page or Application items serve the same purpose, but need to be
declared. A little extra time up front, but clarity in where and how used.
• Compare to:
On Demand Processes – Naming
• As part of the design activity, keep in mind that you may have multiple
On Demand Processes in an application. Take some time to name
them in a way that is easy to understand and manage as your
application grows.
• Example Process name = AJAX_MULTI_INSERT
• Example Process name = AJAX_MULTI_DELETE
How could these names be improved?
On Demand Processes
The flow used in the example shown is as
follows:
• The JavaScript call initiates the On
Demand Process call
• The On Demand process – contains
the logic required to gather the session
parameters and pass them to the
PL/SQL layer
• The PL/SQL layer contains the
business logic to interact with the table
data
• After the On Demand process is
completed, the previously shown
feature to refresh the report in initiated
by the JavaScript
JavaScript
On Demand Process
PL/SQL
Tables
AJAX – Report Refresh
Dynamic Actions – 4.0
Using similar logic, the same can be
accomplished using Dynamic Actions
• First - Bind the Dynamic Action to an
event
• Second – Define the steps to take
place in Action Sets
• Set Value – for PL/SQL to act on a
parameter value, it needs to be in
session state
• Execute PL/SQL – Using the newly set
value in session state
• Refresh the report
APEX 4.0 – Dynamic Actions
Dynamic Actions – 4.0
Action Binding - Preparations
In order to get the event to BIND to each row, a jQuery selector will be
used. In order to easily identify the rows, a CLASS is applied to the
LINK attribute. (Thanks Dimitri Gielis)
An aditional attribute (my_attribute) is also added to the link. This will be
used for easy and consistent retrieval of the value needed for PL/SQL to
act on
Dynamic Actions – 4.0
Action Binding
The binding of the Dynamic Action is using the Selection Type of jQuery
Selector
This allows the use of the simple dot syntax to reference all DOM elements
with the class “bind_to_me_for_delete”
Dynamic Actions – 4.0
Action Binding
Special Note – because the region for “removals” is dynamically refreshed
per the design, the data bindings to the “removal” Dynamic Action
needs to be classified as LIVE. The default of BIND will cause the
bindings to be lost when the region is refreshed the first time.
Dynamic Actions – 4.0
Action Steps
Set Value
A small bit of JavaScript
is used to retrieve the
attribute value we set
in the report. This
attribute is retrieved,
then set to the
session variable we
defined to allow the
PL/SQL to act on the
value.
Note: This is NOT in
session state, only on
the client.
Dynamic Actions – 4.0
JavaScripting Note
The APEX Framework places wrappers on the Dynamic Action bind objects
This provides additional details and functionality for use.
This enables the code: $(this.triggeringElement).attr('my_attribute');
(Thank you Patrick Wolf)
Dynamic Actions – 4.0
Action Steps
Execute PL/SQL
Like the on demand
processes at the
application level,
PL/SQL packages
can be called using
session parameters.
The “Items to Submit”
sets the session
state on the server
prior to executing
the PL/SQL code.
(as explicitly done in
the previous
example)
Debug Notes
On Demand processes are not the easiest thing to debug…
Using the NET feature of Firebug makes the job much easier:
AJAX  HTML Injection
• No – Not Hacking
• Modification of the DOM to change the user interface is the primary goal
• It is necessary to understand where you desire the HTML injected into
I want my HTML to go here
Demonstration
Consuming APEX Pages
• Using the HTMLDB_GET, it is
possible to consume entire
APEX pages.
• Although you can, doesn’t
mean you should…. There
are issues with branching and
processing using this method
• Additional features inside the
HTMLDB_GET package
allows the partial retrieval of
pages
Consuming APEX Pages (partial)
Two settings helped make this
example work
1. Custom Page Template
2. Option on the .get method
On Demand Processes – Design Notes
• As with any programming, it is easy to get caught up in the multiple
places to put variables and code
• Where is JavaScript code placed?
• Per Page in the Header
• Page 0
• Region Source with no template
• Region Header
• Region Footer
• Where is business Logic?
• PL/SQL Packages
• Page Processes
• On Demand Processes
• Where is UI Logic?
• Come up with a practice that works for you / your organization
• Document it
• Communicate it
• Follow it
Supportability Note
Please Note –JavaScript outlined here is
available – but not openly supported
http://download.oracle.com/docs/cd/E17556_01/
doc/apirefs.40/e15519/toc.htm
Questions?
References
Many thanks to all those that have come before me, and for those that take the
time to help others grow and improve their skills by sharing their time an
knowledge.
APEX
• http://apex.oracle.com – Forum, Docs, Hosted Workspace
• http://apex.oracle.com/pls/otn/f?p=38462 - Carl Backstrom JSON & AJAX
• http://apex.oracle.com/pls/otn/f?p=11933 – Carl Backstrom Variety Examples
• http://apex.oracle.com/pls/otn/f?p=31517 – Denes Kubicek – Everything!
Other Notes
• Syntax Highlighter
•
http://code.google.com/p/syntaxhighlighter/
Author
Updated and corrected presentation will be available on my blog
http://wphilltech.com
http://apex.oracle.com/pls/otn/f?p=226 – This example application
Tim St. Hilaire - tim@wphilltech.com
Disclaimer
•
•
•
Marks and Brands are the property of their respective owners. Usage is for discussion
purposes only. No ownership assumed or implied.
The comments and opinions expressed here are sole responsibility of the author and not
of his employer or any other party
No trees were harmed during the creation of this presentation. However, a great number
of electrons were terribly inconvenienced.