Databases Reference
In-Depth Information
aware of the Widget Factory and CSS Framework which came with them. These tools can help you
produce well-structured JavaScript code and user interfaces that can blend in with any APEX theme.
jQuery UI Widget Factory
Unless you're creating a process plug-in, JavaScript will likely be an important part of your plug-in. If
you come from an Oracle background, you may be comfortable working with PL/SQL but a little
apprehensive about JavaScript. Newcomers to JavaScript can spend a lot of time just figuring out a good
way to organize their code. The jQuery UI Widget Factory provides just that: a systematic approach to
writing JavaScript that provides organization as well as a number of other features.
Because this chapter is about writing plug-ins for APEX, I will use the term
widget
in place of
plug-in
when referring to the jQuery UI Widget Factory—although the terms are typically interchangeable. The
jQuery UI Widget Factory allows you to create stateful jQuery widgets with minimal effort.
Stateful
means that the widget keeps track of its attribute values and even allows attribute updates and method
calls after the widget has been initialized.
One of the best ways to learn about the jQuery UI Widget Factory is to see an example of how it is
used. The following tutorial will walk you through the steps needed to build a widget.
This tutorial will create a widget named
lengthLimit
. The
lengthLimit
widget will be used to
enhance standard input elements so that they warn users when the number of characters entered
approaches a defined maximum length. The widget will set the text color to a warning color when the
text reaches 80% of the maximum length and then to an error color when the limit is reached. The
widget will also trim any characters entered in the input that exceed the maximum length.
The
$.widget
function is called to create the widget. The first parameter passed to the function is the
namespace and name of the widget which are separated by a period. The
“ui”
namespace is used by all
of the widgets in the jQuery UI library. The second parameter (currently just an empty object) is the
prototype to be associated with the widget.
apex.jQuery.widget("ui.lengthLimit", {
//widget code here
});
Before continuing to build out the widget, it is important to take care of one important issue:
$
. Most
people who use jQuery are familiar with using the dollar sign as a shorthand reference to the jQuery
object rather than spelling out
jQuery
, or as it's been exposed in APEX,
apex.jQuery
. While it's possible to
use the dollar sign in your widget code, it's best to protect references to the dollar sign from collisions
with other JavaScript libraries. The technique used to do this is to wrap your code in an anonymous
function that passes the jQuery object as an actual parameter to itself as a formal parameter which uses
the dollar sign for its name. If this sounds complex and confusing don't worry— it requires only two lines
of code. Note that the previous reference to
apex.jQuery
has been replaced by the dollar sign now that it
is safe to do so.
(function($){
$.widget("ui.lengthLimit", {
//widget code here
});
})(apex.jQuery);
Let's continue building the widget by adding the
options
object. The options object is used to set
default values for configuration options used by your widget.
