Oracle Application Express 4.0 with Ext JS

Oracle Application Express 4.0 with Ext JS Deliver rich, desktop-styled Oracle APEX applications using the powerful Ex...
Author:  Mark Lancaster

49 downloads 1693 Views 19MB Size Report

This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!

Report copyright / DMCA form

id="el-8">eight


Ext provides the Ext.get method (shorthand for Ext.Element.get) to retrieve any element as an Ext.Element. Let's see it in action, running the following commands in the Firebug Console: var el = Ext.get('test'); console.dir(el);

[ 45 ]

Getting Acquainted with Ext

You should see something similar to screenshot we just saw, where we've constructed an Ext.element el using the Ext.get command, and then used the Firebug console.dir command to display the el object on the bottom left. Firebug shows the properties in a black font, the methods/functions in a green font, and constructor classes in a red font. When using Firebug to display JavaScript objects, be aware that you are seeing the raw JavaScript object, so both public and private methods are exposed. Ext documentation is included when you download the Ext JS SDK, and it is also available online at http://www.sencha.com/deploy/dev/docs/.

You should always consult the Ext documentation if you are unsure whether or not a method is private, as calling a private method out of context may have undesirable side effects.

Heavyweight versus flyweight

Ext.get accepts an ID of the node, a DOM Node, or an existing Ext.Element as a parameter, and returns an Ext.Element (or null when unmatched), so the following statements are all valid: // string Id var el1 = Ext.get('test'); // DOM node var el2 = Ext.get( document.getElementById('test') ); // Ext Element var el3 = Ext.get(el1);

Let's try using one of the Ext.Fx methods highlight, which is automatically applied to the Ext.Element interface, to highlight an element briefly: var el = Ext.get('test'); el.highlight();

The test div should change its background color to yellow and then fade out to its original color. We could have written the same instruction using JavaScript chaining as follows: Ext.get('test').highlight();

[ 46 ]

Chapter 2

If all we are doing with our test div is highlighting it once, the overhead of creating an Ext.Element is a wasteful of memory resources. The Ext team recognized this, and created the Ext.fly method (shorthand for Ext.Element.fly), which uses a global shared flyweight Ext.Element across the library. Ext.fly takes the same arguments as Ext.get, but should only ever be used for one-time references to DOM elements that are not going to be used again. So, for our previous example, we can write instead: Ext.fly('test').highlight();

For an example of using Ext.fly incorrectly: /*** example showing incorrect use of Ext.fly ***/ var el = Ext.fly('el-5'); Ext.fly('test').setWidth(400); Ext.fly('test').center(); el.highlight();

Here, we have assigned a variable to the global flyweight element for Dom element el-5, then used the flyweight to manipulate another DOM element test. When we apply the highlight method to our variable, it is accessing the global flyweight, no longer pointing at our original DOM element. This results in the wrong element being highlighted. Ext.fly should only ever be used for one-time references to DOM elements, which are not going to be used again.

Sizing and positioning Ext.Element provides methods for sizing and positioning elements. Let's try a few

of them out using the Firebug console. Set the width of the test element:

Ext.fly('test').setWidth(400);

Determine the height of the test element and conditionally resize it: var ht = Ext.fly('test').getHeight(); console.log('ht = %s', ht); if (ht < 200) { Ext.fly('test').setHeight(200); } [ 47 ]

Getting Acquainted with Ext

Center the test element in the middle of the page: Ext.fly('test').center();

Move the test element to a specific location at x=100, y=50 using animation: Ext.fly('test').setLocation(100,50,true);

Hide the test element: Ext.fly('test').hide();

Show the test element, with some animation: Ext.fly('test').show(true);

Relocate the test element to its original position: Ext.fly('test').clearPositioning();

As you can see, it's very easy to manipulate the size and positioning of DOM elements using Ext.Element. We haven't explored all the features here, but if you refer to the Ext.Element documentation at http://dev.sencha.com/deploy/dev/ docs/?class=Ext.Element, you will find comprehensive methods for getting and setting the margin, border, padding, and position of an element.

CSS classes and styling Ext.Element also has a set of methods for manipulating DOM elements using CSS

classes and styles, allowing you to query, add, remove, and replace classes and styles. Let's try a few. First, refresh your page, and resize and center the test div: Ext.fly('test').setWidth(400); Ext.fly('test').center();

To add a class to an element: Ext.fly('el-5').addClass('ux-selected');

[ 48 ]

Chapter 2

Your page should look like the following screenshot:

To remove a class: Ext.fly('el-5').removeClass('ux-selected');

To alternately add and remove a class, you can toggle it: Ext.fly('el-5').toggleClass('ux-selected');

To "stripe" the test elements' child elements so each alternate row is highlighted, and toggle the striping effect on and off: Ext.fly('test').select('div:even').toggleClass('ux-selected');

[ 49 ]

Getting Acquainted with Ext

The result is shown in the following screenshot:

To add a class to one element, and remove the same class from all siblings: Ext.fly('el-5').radioClass('ux-selected');

Methods also exist for styles, for example: Ext.fly('el-5').setStyle('border', '1px solid #FF0000');

DOM traversal In order to be able to navigate around the DOM tree from any given position, traversing both up and down the DOM in a browser, Ext provides a traversal API using CSS selectors to locate elements. Ext supports most of the CSS3 selectors, along with custom selectors and basic XPath. For a complete list of supported selectors, refer to the Ext API documentation for Ext.DomQuery at http://dev.sencha.com/deploy/dev/docs/?class=Ext.DomQuery. Open chapter02\Example 2.3.html, which includes all of the content of the earlier Example 2.2.html, along with the body containing additional HTML markup for an unordered list and a paragraph (ul and p elements).
one
two
three
four
five
  • 5.1
  • 5.2
  • 5.3
  • [ 50 ]

    Chapter 2
  • 5.4

a paragraph

six
seven
eight


Using the Firebug console once again, let's try some of the DOM traversal methods available in Ext.Element. Let's toggle a class for the first and last child elements of foo: Ext.fly('foo').first().toggleClass('ux-selected'); Ext.fly('foo').last().toggleClass('ux-selected');

The result is shown in the following screenshot:

Passing a selector filters for that selector: // no selector the toggles the list Ext.fly('el-5').first().toggleClass('ux-selected'); // using a selector, the paragraph is toggled instead Ext.fly('el-5').first(‘p’).toggleClass('ux-selected');

[ 51 ]

Getting Acquainted with Ext

To return the first child at any depth below the current element based on a passed in selector, we use the child method; whereas for the first direct child (1 level down), we use the down method: // child method finds the first list item Ext.fly('el-5').child('li').toggleClass('ux-selected'); // down method does not find the first list item Ext.fly('el-5').down('li').toggleClass('ux-selected');

Navigating between siblings is done using the next and prev methods; once again you can optionally pass selectors to filter for that selector: // toggle previous sibling Ext.fly('el-5').prev().toggleClass('ux-selected'); // toggle next sibling Ext.fly('el-5').next().toggleClass('ux-selected'); // toggle next sibling that is a div with class "pickme" // does not exist in the example file!! Ext.fly('el-5').next('div.pickme').toggleClass('ux-selected');

Traversing up the DOM path is just as easy using up and parent methods, which provide similar functionality but accept different parameters. To select the immediate parent: var el = Ext.get('foo').first(); el.parent().toggleClass('ux-selected');

Walking up the DOM, looking for a parent that matches the passed simple selector: // up( String selector, [Number/Mixed maxDepth] ) el.up('div.box').toggleClass('ux-selected');

This is equivalent to: // parent( [String selector], [Boolean returnDom] ) el.parent('div.box').toggleClass('ux-selected');

Selecting multiple elements In our DOM traversal examples so far, we have fetched only a single element to manipulate. More often than not, we are going to be more interested in interacting with multiple elements, which is where Ext.select and Ext.query come into play. [ 52 ]

Chapter 2

Ext.select takes a query and returns an Ext.CompositeElement or an array of Ext.Elements. This allows you to interact easily with every element returned by Ext.select without looping and modifying each one separately.

For example, we saw earlier to "stripe" the test elements' child elements, and toggle them on and off, is a one line command: Ext.fly('test').select('div:even').toggleClass('ux-selected');

Another way of writing the same command could be: Ext.select('div:even',false,'test').toggleClass('ux-selected');

To add and remove a CSS class when the mouse is over an element is just as easy: Ext.select('div',false,'test').addClassOnOver('ux-over');

Sometimes we may want to make several changes to the elements, so you can use the Ext.each method to iterate through an Array/NodeList: function doSomething() { this.highlight(); } var els = Ext.select('div',true,'test'); els.each(function(el) { // several commands.. el.on('click',doSomething, this); console.log(el.id); });

It is important point to note the second parameter in Ext. select syntax: Ext.select( String/Array selector, [Boolean unique], [HTMLElement/String root] ). unique, when true, returns a unique Ext.Element for each element (defaults to false, returning a shared flyweight object).

Try running the previous Ext.each example as is, then refresh the page and run the example replacing true with false. Note the changed behavior; regardless of which div you click, the last div is highlighted. Are you able to explain why this happens? Ext.query accepts CSS selector and root node like Ext.select, but instead returns

an array of DOM nodes.

[ 53 ]

Getting Acquainted with Ext

Reworking our previous example to use Ext.query: function doSomething() { this.highlight(); } var els = Ext.query('div','test'); Ext.each(els,function(el) { // el is a DOM node here Ext.get(el).on('click',doSomething); console.log(el.id); });

DOM manipulation Ext provides a strong API to allow us to add, modify, and remove elements in the DOM easily. We will be using chapter02\Example 2.3.html to test the Ext API once again. Let's start by creating some DOM elements: Ext.fly('test').createChild('
nine
'); Ext.fly('test').createChild({tag:'div',id:'el-10', html:'ten'});

Here, we used the Ext.Element.createChild method to create and append two div elements to the test element, each containing a text string. For the first div, we simply passed the HTML to include. The second example shows an alternative method using a Ext.DomHelper config, which provides an abstraction of the DOM allowing you to build up complex HTML fragments programmatically before applying them to the DOM. When using Ext.Element.createChild, an Ext.Element is returned, allowing you to do additional processing: var el = Ext.fly('test').createChild({tag:'div', html:'eleven'}); el.addClass('ux-selected'); console.log(el.id);

[ 54 ]

Chapter 2

In this example, an id for the div tag wasn't specified, instead Ext.Element, returned to the el variable, was used for additional processing. Take a moment to inspect the new div using the Firebug HTML inspector. You should see the div tag has automatically been assigned an id, as shown in the following screenshot:

Adding of elements relative to an existing DOM node is done using insertHTML, insertSibling, or using convenience methods insertBefore, insertAfter, insertFirst. Refresh the page, and let's try a few. Before we do, refresh the page and run the following code to add a border and some space around the div elements within the test dev: // add styling to existing div elements Ext.fly('test').select('div') .setStyle('border','1px solid #c0c0c0') .setStyle('margin','2px');

[ 55 ]

Getting Acquainted with Ext

Run the following code: // create a reusable template for text substitution var html = ' <span class="ux-selected">{text} '; var tpl = new Ext.DomHelper.createTemplate(html); // show insertHtml placement options var el = Ext.get('el-4'); el.insertHtml('beforeBegin',tpl.apply({text:'beforeBegin'})); el.insertHtml('afterBegin' ,tpl.apply({text:'afterBegin'})); el.insertHtml('beforeEnd' ,tpl.apply({text:'beforeEnd'})); el.insertHtml('afterEnd' ,tpl.apply({text:'afterEnd'})); // show insertSibling placement options var obj = Ext.get('el-7'); obj.insertSibling(tpl.apply({text: 'before Sib'}), 'before'); obj.insertSibling(tpl.apply({text: 'after Sib'}), 'after');

The result is shown in the following screenshot:

Notice the use of Ext.DomHelper.createTemplate in the code; it's something not previously mentioned. An Ext.Template defines a fragment of HTML code with some embedded placeholder tags, allowing you to substitute values quickly and easily. This is done repeatedly further down in the code using the apply method, which returns the HTML fragment with the substituted values. [ 56 ]

Chapter 2

The insertHtml method has four different locations to insert the HTML in relation to this element-beforeBegin, afterBegin, beforeEnd, afterEnd. The previous screenshot shows the difference between beforeBegin and afterBegin: beforeBegin creates a sibling node, whereas afterBegin creates a child node. The beforeEnd and afterEnd locations work similarly. As you would expect, insertSibling locations of before and after insert HTML as their names imply. The methods mentioned before for creating new elements—insertBefore, insertAfter, insertFirst—can also be used for relocating existing elements. Refresh your page and try these out: Ext.fly('el-7').insertBefore('el-5'); Ext.fly('test').select('div:even').insertBefore('el-1'); Ext.fly('test').insertFirst('el-6'); Ext.fly('el-2').insertAfter('el-4').highlight();

Removing nodes is trivial, either referring to the node ID or using CSS selectors: Ext.fly('test').select('div:even').remove(); Ext.fly('el-8').remove();

Another useful method is wrap that creates and wraps the element with another element: Ext.fly('foo').wrap({tag: 'div', class:'box'});

Wrapping an element is a very useful technique used many times within Ext components.

The Ext.Element.boxWrap wraps the specified element with a special 9-element markup/CSS block that renders by default as a gray container with a gradient background, rounded corners, and a four-way shadow.

[ 57 ]

Getting Acquainted with Ext

This special mark-up is used throughout Ext when box wrapping elements. Examples of elements using it include the Ext.Button, Ext.Panel when attribute frame=true is set, and Ext.Window. To see this in action, run the following code: Ext.get("el-5").boxWrap(); Ext.get("foo").boxWrap().addClass("x-box-blue");

This screenshot shows the expected output, where el-5 has been wrapped with the default gray container, and a four-way shadow. Element foo has been wrapped, and a class x-box-blue has been applied to the wrapper, resulting in a blue container. The x-box-blue CSS rules are included with Ext; to use an alternate class, you would need to provide the necessary CSS rules also.

Defining event handlers

Event-driven programming is supported in web browsers through the use of JavaScript to register event handlers and listeners on page elements in the DOM tree. Event handlers provide a mechanism to make a HTML page interactive, so when you click on page elements, or hover over something, JavaScript is executed, and the appearance or behavior of the page changes. Historically, developers used the Inline model to add event handlers directly to an element as an attribute of the element:
Click me

[ 58 ]

Chapter 2

Or developers also used the Traditional model to add event handlers via scripts, for example:
Click me
<script type="text/javascript> var dom = document.getElementById('test'); dom.onclick = function () { alert(this.id + ' was clicked'); };

This event-handling model is known as DOM Level 0, and allows only a single event handler for each event to be attached to a DOM node. The W3C designed a more flexible event handling model in DOM Level 2, to allow multiple events to be attached to a DOM node and uses methods including addEventListener, removeEventListener, and dispatchEvent. Unfortunately, Microsoft does not follow the W3C model, instead uses their own model using methods including attachEvent, detachEvent, and fireEvent, to provide similar functionality. Ext removes the need to deal with different browser event models by wrapping the browser's native event-object into Ext.EventObject, to provide normalized event processing, freeing us from dealing with cross-browser differences. Let's take a look at the ExtEventObject API. Open chapter02\Example 2.4.html, which includes all of the content of the earlier Example 2.3.html, with some additional formatting added to the div elements, and a new messages region included above, as shown in the following screenshot:

[ 59 ]

Getting Acquainted with Ext

To add an event handler or listener to an element, we use the addListener method, or preferably use the on method, which is shorthand for addListener: function handleClick(e, t){ e.preventDefault(); var target = Ext.get(t); target.highlight(); var msg = Ext.get('msg-ct'); msg.update('You clicked ' + target.id + ', with innerHtml ' + target.dom.innerHTML); msg.highlight(); } // add a click event to div el-6 Ext.fly('el-6').on('click',handleClick);

In this example, we added an event handler for a mouse-click event on a specific DOM element, el-6, to execute an action handler function handleClick. The handleClick function accepts two parameters: e, which is an Ext.EventObject, and t, the DOM element that was the target of the event. Our handleClick function is used here to highlight the target element and update the messages region with information about the target element and highlight the messages region. The preventDefault method is used to prevent the default handling of the event by a browser. It's not really necessary here, but if we had attached an event to a DOM link, it would prevent the browser opening the link address. Alternate syntaxes for adding the event handler: Ext.EventManager.on("el-6", 'click', handleClick); Ext.EventManager.addListener("el-6", 'click', handleClick);

To remove an event handler, we use the removeListener method, or the shorthand equivalent un method: Ext.fly('el-6').removeListener('click',handleClick); Ext.fly('el-6').un('click',handleClick);

You must include a reference to the function passed in the addListener call. All listeners attached to an element can be removed using removeAllListeners: Ext.fly('el-6').removeAllListeners();

[ 60 ]

Chapter 2

Using event delegation to reduce memory consumption Adding listeners to multiple elements can be done easily using CSS selectors: Ext.select('div:even','test').on('click',handleClick);

However, before you do add multiple selectors, you may want to consider event delegation. Rather than registering multiple event handlers for each element in a group of elements, you can register an event to a container element and take advantage of events bubbling up the DOM hierarchy. So, in Example 2.4.html, our HTML looks like this:
one
two
three
four
five
  • 5.1
  • 5.2
  • 5.3
  • 5.4

a paragraph

six
seven
eight


We could use event delegation as follows: function handleClick(e, t){ e.preventDefault(); var target = Ext.get(t); target.highlight(); var msg = Ext.get('msg-ct'); msg.update('You clicked ' + target.id + ', with innerHtml ' + target.dom.innerHTML); msg.highlight(); } [ 61 ]

Getting Acquainted with Ext Ext.fly('test').on( 'click', handleClick, this, {delegate: 'div:even'} );

//event name //function //scope //options object

Here, we have the optional scope and options parameters; within the options object we have used the delegate attribute to specify a CSS selector to be applied, filtering the descendants of the target, so that only the even div elements will fire the event. Event delegation reduces memory consumption, and reduces potential memory leaks.

Something else really neat about delegates is that the handler will work for any descendant of the target that matches that CSS selector, even if it is created in the future. Try adding two more div elements within the test div: Ext.fly('test').createChild('
nine
'); Ext.fly('test').createChild('
ten
');

Clicking on el-10 will execute the handleClick function because it matches the CSS selector.

One-off events To create a "one off" handler that fires once and then removes itself, we use the options object and single attribute: Ext.fly('test').on( 'click', handleClick, this, {single: true} );

//event name //function //scope //options object

You can use the buffer option to run a handler after a delay period (in milliseconds). If the event fires again within that period, the original event is cancelled and the new event invoked after the new delay. // buffer the handleClick for 1000ms (1 second) Ext.fly('test').on('click',handleClick, this,{buffer: 1000});

[ 62 ]

Chapter 2

The delay option fires the event after the delay period, but does not cancel events: // delay the handleClick for 1000ms (1 second) Ext.fly('test').on('click',handleClick, this,{delay: 1000});

Parameter passing using object notation Many of the APIs provided by Ext use a config object to pass configuration settings to a JavaScript function. So what exactly is this config object, and why use it? The config object is an object literal, which we will learn about shortly. We use it because it's more flexible and is self documenting.

Old-school parameters Using old school JavaScript programming, a typical function looked like this: function show_prompt(title, message, width) { // code }

To call that code, you would write: var answer = show_prompt('my title','a short message', 300);

While this isn't too bad for this example, as a developer you have to call the function passing parameters in the order specified, and you must pass all parameters. In a few months time, an issue gets raised, and looking at the function call you have absolutely no idea what 300 is about without digging around to find the function definition.

Using object notation The new way of passing parameters is done using object literals, popularized by Douglas Crockford as JSON (JavaScript Object Notation). Its structure is simple; it is a comma separated list of properties wrapped in curly braces. Each property is denoted by listing its name and value separated by a colon character. Here is a complete example, using object literals: var config = { title: 'Contact details', msg: 'Please enter your Name:', width: 300, buttons: Ext.MessageBox.OKCANCEL, [ 63 ]

Getting Acquainted with Ext multiline: true, fn: function (btn, answer, obj) { console.log('You typed: ' + answer); }, icon: Ext.MessageBox.INFO } Ext.Msg.show(config);

While this example is a little more complicated, it's more readable because we are passing parameter names and values, so in a few months time it's plain to see that 300 refers to the width. Object literals don't care about the order of parameters being passed, or whether all parameters are being passed, so the Ext team could add additional parameters to the Ext.Msg object and our code will still work. Naturally the Ext team would need to make the additional parameters optional, or assign default values, but they would need to update only the object definition. One other less obvious benefit is that by wrapping all our variables into an object literal, we aren't defining variables in the global namespace, reducing the chances of overwriting an existing variable. This is an increasingly important consideration as web pages rely more and more on JavaScript, and often include one or more JavaScript libraries as well as custom code.

Basic syntax

An object literal is an unordered set of properties using the following syntax rules: •

An object is enclosed by curly braces {}

•

Each property lists its name and value separated by a colon character

•

Name/value pairs are separated by a comma

•

Names can be almost any string except JavaScript-reserved keywords

•

Values can be of any data type, including array literals and object literals

•

Array literals are enclosed by square brackets, for example, [ 'a',{b: 100}, ['f','g','h'] ]

For further information on JSON, refer to http://www.json.org/. Beware the trailing comma after the last name/value pair. Firefox won't object if you add it, but Internet Explorer will trigger an error: Expected identifier, string or number. [ 64 ]

Chapter 2

Use namespacing to avoid collisions Something you have to be aware of when doing JavaScript programming is corruption of the global namespace. Every time you define a simple function, or other variable at the top level of a web page, the names you've chosen could potentially come in conflict with names used by other developers or libraries that you are using. In the browser, all global variables become properties of the window object. So when you declare a variable: var gDebug = false;

you're actually declaring: var window.gDebug = false;

More often than not, modern web browser applications use one or more JavaScript libraries, snippets of code from multiple sources, and code you've written as well. For our environment, APEX includes jQuery, jQuery UI, and APEX JavaScript libraries, and we've added Ext also. It's not safe to assume you can reference a variable or object in the global namespace without impacting an existing variable or object.

[ 65 ]

Getting Acquainted with Ext

When looking at Firebug's DOM tab in this screenshot, we have a basic APEX application that includes the highlighted apex, Ext, and Playpen namespaced objects. There are also a great many more variables shown that have been declared in the global namespace. If you expanded the Ext object, you would see Ext consolidates all of its classes into a single namespace of Ext and further organizes its classes into various packages. APEX has made a concerted effort to namespace it's JavaScript objects between the 3.2 and 4.0 releases, so is moving in the right direction, but isn't quite there yet. JavaScript rule for namespace collisions are simple: Last person to have their code included wins.

To see the impact of namespace collisions, open the chapter02\Example 2.1.html example and type into the Firebug console: Ext.Msg.alert('Hello World', 'Ext JS is very cool!');

The Ext modal alert should appear. Close it, and type into the Firebug console: var Ext = 'fred'; Ext.Msg.alert('Hello World', 'Ext JS is very cool!');

This time we have overwritten the Ext object, the namespace collision has removed the entire Ext object and all its components. To avoid namespace collisions, you should create your own namespace, and define all your JavaScript variables and functions within that namespace. Ext provides the Ext.namespace method to do this simply. [ 66 ]

Chapter 2

Ext.namespace Ext provides the Ext.namespace method (or the shorthand Ext.ns) which will set up namespaces for you, including checking if the namespace already exists. For example, to set up a namespace of Playpen and the packages regions and form: Ext.namespace('Playpen.regions', 'Playpen.form');

Then to define a new class, such as customerDetails within Playpen.regions: Playpen.regions.customerDetails = new Ext.Panel({ allowDomMove : false, applyTo: 'customerDetails', animCollapse: false, autoHeight: true, ... titleCollapse: true });

Ext.BLANK_IMAGE_URL

Ext uses a 1x1 pixel transparent .gif image to create inline icons with CSS background images, allowing Ext to size objects correctly in a cross-browser compatible way. In older versions of IE, this defaults to http://extjs.com/s.gif, which can cause issues if extjs.com is not accessible, or you're using SSL, which will raise security warnings in browsers. To prevent these issues, you need to set the Ext.BLANK_IMAGE_URL to a 1x1 pixel transparent .gif image on your local web server. If you're using a standard APEX install, you can reference: Ext.BLANK_IMAGE_URL = '/i/1px_trans.gif';

This needs to be included in your page template directly after the Ext JavaScript files, normally included in an external JavaScript file, but could be inline as follows: Example 2.1 <script type="text/javascript" src="../../extjs/adapter/ext/ext-base.js"> [ 67 ]

Getting Acquainted with Ext <script type="text/javascript" src="../../extjs/ext-all.js"> <script type="text/javascript"> Ext.BLANK_IMAGE_URL = '/i/1px_trans.gif';

Summary In this chapter we have spent time familiarizing ourselves with some of the underlying concepts and functionality Ext provides for manipulating the Document Object Model (DOM). By using simple standalone testing pages, we have done isolated testing without worrying about interaction with APEX, or trying to build end solutions. Using the Firebug Console, HTML, and DOM tabs, we have executed Ext code snippets and inspected the results both in the browser and within Firebug. We have investigated the Ext.Element component, exploring how it allows us to easily manipulate and navigate the DOM. We have used CSS3 selectors provided by Ext.DomQuery to retrieve elements of interest, and then modified them by using the Ext.Element API to add and remove classes, attach event handlers, and add or remove elements around them. We have explored more advanced event techniques such as delegation and one-off events, as well as modern JavaScript programming concepts such as object notation and the need for namespacing variables. Enough with the theory! Let's start building some APEX templates with Ext JS.

[ 68 ]

Building a Ext JS Theme into APEX This chapter starts our journey building a theme based application on Ext JS into APEX. It provides a background on APEX themes and discusses how to create an APEX theme from scratch. Instructions on how to integrate the Ext JS library into the page template are provided, together with potential issues you may encounter. This chapter includes: •

An overview of APEX themes, explaining the template types that make up a theme, as well as the benefits of separating the APEX engine, templates, and application functionality from each other.

•

Starting out creating a APEX Theme.

•

Building a Page Template based on the Ext.Viewport component. This covers the process of creating a template using a standalone prototype and integrating it into an APEX page template.

•

Discussion on how JavaScript DOM manipulation can result in input items appearing outside the form element, and the consequences that result. A customized version of the Ext.Viewport is created to ensure that input items always remain with the form.

Theme basics Out of the box, APEX comes with twenty themes, each theme comprising a collection of templates used to define the layout and appearance of an entire application. An application can have many themes, but only one theme is active at any time; switching themes is done at design time only.

Building a Ext JS Theme into APEX

You can create custom themes, which may be published, either within a workspace by a Workspace Manager or for the whole APEX instance by an Internal Workspace Manager. Publishing a theme encourages consistency across applications. A theme comprises nine template types: breadcrumb, button, calendar, label, list, page, popup list of values, region, and report. A theme must have at least one of each of the nine template types. Within each template type are a set of predefined classes and eight custom classes. For example, the label template has the following classes: •

- Not Identified -

•

No Label

•

Optional Label

•

Optional Label with Help

•

Required Label

•

Required Label with Help

•

Custom 1... Custom 8

Programmers use these templates to construct the HTML pages that make up an application. Each page is declaratively defined using metadata to select templates to be used for the presentation. The APEX engine dynamically renders an HTML page using the metadata, assembling relevant templates and injecting dynamic data into placeholders within the templates. The HTML page is viewed when you request a page through a web browser. When you submit a page, the APEX engine performs page processing, once again using declaratively defined metadata to perform computations, validations, processes, and branching. This type of processing is a typical Model-View-Controller(MVC) pattern, where the view is the HTML generated using the application templates. The APEX engine is the controller and receives the GET or POST input and decides what to do with it, handing over to domain objects. The domain objects model is encapsulated in the page definition and contains the business rules and functionality to carry out specific tasks.

Separation of concerns The MVC pattern also promotes another good design principle—separation of concerns. APEX has been designed so that the APEX engine, templates, and the application functionality can be optimized independently of each other.

[ 70 ]

Chapter 3

Clearly, the process of assembling and sequencing the steps necessary to render a page, and process a page are important to the overall solution. By separating this out and letting Oracle deal with the complexities of this through the APEX engine, it allows programmers to concentrate on providing business functionality. Equally, by separating presentation templates from the business logic, it allows each aspect to be maintained separately. This provides a number of advantages including ease of design change, allowing templates to be modified either by different people or at different times to enhance the interface without breaking the application. An excellent example of this is the standard themes provided in APEX, which have been designed to be completely interchangeable. Switching standard themes is simply a matter of loading a theme from the repository and then switching the active theme. APEX then remaps components to the new active theme using the template class identifiers.

Standard themes We will be building our own custom theme rather than using one of the twenty pre-built ones. Nevertheless, it's worthwhile knowing what they provide, as we will build our custom theme by using one of them as a "starter".

[ 71 ]

Building a Ext JS Theme into APEX

Looking at this image, we can see a preview of the standard APEX themes. Each theme provides a similar interface, so really each standard theme is just a visual variation on the others. The colors used are a little different, or the HTML layout is tweaked slightly, but in reality they are all much the same. Theme 4 is used by APEX as the "starter" theme and contains one template for each template class for all the template types—a total of 69 templates. Theme 19 is also worth noting as it's designed for mobile devices. Each of these themes are full of good HTML practices and show how and where to use the substitution strings.

Creating a theme When creating a theme, you can choose to copy one from the repository, create one from scratch or from an export file. The repository and export file options copy the entire theme, and you start editing the template to suit. Creating a theme from scratch creates a theme without any templates. You then need to define templates for each different type before you can switch from the active theme. In my opinion, the easiest way to build a new theme is to take the approach that the application should always be in a working state, and the way to do this is to create a new empty TEMPLATE application using a standard theme and build from there. From this working base, you can progressively convert the templates to use Ext functionality, building simple test pages as you go to verify the templates. These test pages also form part of your template documentation, allowing team members to examine and understand specific functionality in isolation. Once a theme has templates for each of the nine template types, you can publish the theme into the workspace to be used by your business applications. The following screenshot shows a dialog named Create Workspace Theme from the APEX wizard. Notice that you can change the theme number when you publish a theme, providing a very simple mechanism for you to version control your themes.

[ 72 ]

Chapter 3

A published theme can't be edited directly once it has been created, but using a TEMPLATE application, you can republish it using a different theme number. Applications can have multiple themes, but only one active theme. By switching themes, applications can easily test a new version, safe in the knowledge that changing back to the earlier version is just a matter of switching back to the prior theme. So before we go any further, create a new TEMPLATE application based on Theme 4, and let's begin the process of creating our Ext JS theme.

Building a Viewport Page template

Several of the examples provided with Ext feature the Viewport utility container, including the RSS Feed Viewer shown in the screenshot below. The Viewport automatically renders to the document body, sizing itself to the browser viewport and dividing the page into up to five distinct regions; the center region is mandatory, with north, south, east, and west regions being optional.

[ 73 ]

Building a Ext JS Theme into APEX

Viewport regions are configurable, and by setting a few simple attributes, you quickly find yourself with a very interactive page, with expanding/collapsing regions and splitters to resize regions by clicking and dragging with the mouse. We are going to build a basic viewport for our APEX page template including all five regions.

Starting with a standalone template Once again we're going to take a prototyping approach to building an APEX page template. It's easier to build a standalone HTML page and make sure we've got the JavaScript right, and then load it into APEX. #TITLE# <script type="text/javascript" src="../../extjs/adapter/ext/ext-base.js"> <script type="text/javascript" src="../../extjs/ext-all.js"> <script type="text/javascript" src="ex3-1-local-viewport.js">
[ 74 ]

Chapter 3 #NAVIGATION_BAR# #CUSTOMIZE# &APP_USER.
#REGION_POSITION_01#
#REGION_POSITION_02#
#FORM_OPEN#
#GLOBAL_NOTIFICATION##SUCCESS_ MESSAGE##NOTIFICATION_MESSAGE#
#BOX_BODY#
#FORM_CLOSE#
#REGION_POSITION_03#
footer contents go here


The code shows the content of the standalone HTML page located in chapter03/ ex3-1-local-viewport.html, which contains a mixture of HTML elements and APEX substitution tags (key words are enclosed by # characters).

Looking at the header section enclosed by HEAD tags, you can see the standard Ext components: stylesheet ext-all.css, adapter layer ext-base.js, and library extall.js are present. Also included are our application CSS and JavaScript files: ex31-local-viewport.css and ex3-1-local-viewport.js. The body section, enclosed by BODY markup tags, contains a series of DIV tags with region IDs, for example, app-north-panel, which will become panels in our viewport. APEX uses #FORM_OPEN# and #FORM_CLOSE# substitution tags to define the HTML form element wwvFlowForm used for all APEX pages. In this template, region tags #REGION_POSITION_01#, #REGION_POSITION_02#, and #REGION_POSITION_03# are outside of the #FORM_OPEN# and #FORM_CLOSE# substitution tags, so they cannot be used for APEX input items, which we will cover in more depth shortly in the Issue when input items are outside the form section. The accompanying JavaScript located in ex3-1-local-viewport.js is: Ext.onReady(function(){ Ext.BLANK_IMAGE_URL = '../../extjs/resources/images/default/s. gif'; new Ext.Viewport({ layout: 'border', defaults: { [ 75 ]

Building a Ext JS Theme into APEX animCollapse: false, autoScroll: true }, items: [{ applyTo: 'app-north-panel', autoHeight: true, autoScroll: false, region: 'north', style: {padding: '0 5px'}, xtype: 'box' }, { contentEl: 'app-south-panel', height: 30, region: 'south', style: {padding: '0 5px'}, xtype: 'box' }, { contentEl: 'app-west-panel', //collapseMode: 'mini', collapsible: true, margins: '0 0 0 5', maxSize: 500, minSize: 100, region: 'west', split: true, title: 'Navigation', width: 275 }, { contentEl: 'app-center-panel', region: 'center', title: document.title, xtype: 'panel' }, { contentEl: 'app-east-panel', collapseMode: 'mini', collapsible: true, margins: '0 5 0 0', maxSize: 500, minSize: 100, region: 'east', split: true, title: 'Actions', width: 275 }] }); });

[ 76 ]

Chapter 3

The JavaScript could be summarized as follows: Ext.onReady(function(){ Ext.BLANK_IMAGE_URL = '../../extjs/resources/images/default/s. gif'; new Ext.Viewport({ configuration }); });

Looking at the summarized version, we are passing an anonymous function to Ext.onReady, which executes the function after waiting for only the document structure to be fully parsed and the HTML converted into a DOM tree. This performs better than the traditional window.onload handler, which waits for the entire page to be fully loaded before executing. The anonymous function contains two statements; the first assigns the location image of the 1x1 pixel transparent spacer image using the following code: Ext.BLANK_IMAGE_URL = '../../extjs/resources/images/default/s.gif';

The second statement instantiates a new Ext.Viewport object passing its configuration settings as a config object: new Ext.Viewport({ ..configuration.. });

Ext.Viewport is a specialized container that renders to the document body,

automatically resizing when the browser window is resized. Viewports contain up to five pre-defined regions (or panels) defined in the items object, with the center region being mandatory. Each of these panels is separately configured, and can inherit default configurations from the viewport. new Ext.Viewport({ layout: 'border', defaults: { animCollapse: false, autoScroll: true }, items: [{ applyTo: 'app-north-panel', autoHeight: true, autoScroll: false, region: 'north', style: {padding: '0 5px'}, xtype: 'box' }, {

[ 77 ]

Building a Ext JS Theme into APEX contentEl: 'app-south-panel', autoScroll: false, height: 30, region: 'south', style: {padding: '0 5px'}, xtype: 'box' },

Looking at the first part of the Viewport configuration, you can see that defaults are set for animCollapse to switch off animation for collapsing regions, and autoScroll set to true, enabling scrollbars to appear in regions. These defaults are applied to all of the regions defined within items, unless specifically overridden, as shown in the north region. When using north or south regions, you must specify a height; similarly for east and west regions, you must specify a width. For the south region here, I've set the height property in pixels, and for the north region I've used set autoHeight: true to show an alternative method. Notice that the north region is using applyTo: 'app-north-panel', whereas the south region is using contentEl: 'app-south-panel'. The attributes produce a subtly different outcome when rendered; one takes an existing HTML element and places it into the layout of the viewport, where the other uses the existing DOM element as part of the layout. Can you work out which attribute does what? Consult the Ext documentation and inspect the HTML using Firebug and verify. In this example, the difference between using applyTo and contentEl doesn't adversely impact the behavior, but it's a little reminder to take a little extra time to understand what's happening.

In the west region is a commented-out line //collapseMode: 'mini'. Try collapsing and expanding the panel before comparing the behavior to the east region. When in mini mode the regions split bar displays a small collapse button appears in the center of the bar, and the region collapses to a thinner bar than in normal mode. Which collapseMode do you prefer? Finally, the CSS file ex3-1-local-viewport.css contains the following CSS: #app-navigation-bar { color:grey; position:absolute; right:5px; }

[ 78 ]

Chapter 3

There is almost nothing in our CSS file; just one rule to right align the app-navigation-bar DIV element in our template. With so little content in our CSS file, it's hardly worth having a separate file; we could instead just include it within the page. Remember here that we're taking the first step in building our application CSS, and we are going to be adding more rules as we go. So let's start a good habit and include the CSS that is going to be used by every page request using the template in a separate file, taking advantage of static file caching by the browser and reducing the size of our dynamically generated page.

This screenshot shows what our prototype looks like in the browser window. The north region on the left-hand side contains APEX substitution tags #LOGO# for the application logo, and #REGION_POSITION_01# for breadcrumbs. The right-hand side contains substitution tags for #NAVIGATION_BAR#, #CUSTOMIZE#, and &APP_USER.

[ 79 ]

Building a Ext JS Theme into APEX

The west region is titled Navigation, and contains the #REGION_POSITION_02# substitution tag. As the name suggests, you would include links in this panel to navigate your application. Similarly, the east region contains the #REGION_ POSITION_03# substitution tag, and could be used for actions specific to the page. The center region's title is dynamically assigned in our viewport definition to use JavaScript document.title property, which in our page is the #TITLE# substitution tag. The center region body contains the #FORM_OPEN# and #FORM_CLOSE# tags that enclose the notification and message substitution tags #GLOBAL_NOTIFICATION#, #SUCCESS_MESSAGE#, #NOTIFICATION_MESSAGE#, along with the #BOX_BODY# substitution tag for our page content. The south region here contains some plain text, and would typically be used for page referencing and copyright information.

Loading the page template into APEX So all that remains is to transfer the prototype into APEX as a page template, and then make a couple of minor adjustments. Currently the path to our included JavaScript and CSS files is: <script type="text/javascript" src="../../extjs/adapter/ext/ext-base.js"> <script type="text/javascript" src="../../extjs/ext-all.js"> <script type="text/javascript" src="ex3-1-local-viewport.js">

[ 80 ]

Chapter 3

You will need to modify the path for the src attributes to suit the location of the files on your web server. If you are using a hosted APEX environment, such as apex. oracle.com, you can reference Ext JS files using the CacheFly content delivery network, described in Chapter 1, Setting up an Oracle APEX and Ext JS Environment. For example, for ext-all.js, use http://extjs.cachefly.net/ext-3.3.1/ext-all.js.

The #HEAD# substitution tag needs to be added in the HTML header to include the standard APEX JavaScript in the page template. APEX will automatically add JavaScript and CSS includes replacing the substitution tag. It is best to add the tag before our JavaScript and CSS files, as it allows our custom code to override both CSS rules and JavaScript functions when needed. For this book the Ext library is stored on the web server under /ux/extjs/, and application assets under /ux/playpen/, so the path looks like: #HEAD#
href="/ux/extjs/resources/css/ext-all.css">
href="/ux/playpen/ex3-1-local-viewport.css"> <script type="text/javascript"

src="/ux/extjs/adapter/ext/ext-base.js"> <script type="text/javascript"

src="/ux/extjs/ext-all.js"> <script type="text/javascript" src="/ux/playpen/ex3-1-local-viewport.js">

The other change you will need to make is to change the ex3-1-local-viewport. js file modifying the location of the 1x1 pixel transparent spacer image to: Ext Ext. BLANK_IMAGE_URL = '/i/1px_trans.gif';. Here, we are referencing a blank image that is part of the standard APEX install.

[ 81 ]

Building a Ext JS Theme into APEX

Now, open one of the existing page templates. This example uses the No Tabs with Sidebar template. Replace content of the header, body, and footer regions with the updated content from the prototype, as shown in the following screenshot:

[ 82 ]

Chapter 3

Rename the template to EXTJS No Tabs with Sidebar, so it's easy to recognize the updated template and apply the changes. Finally, copy the ex3-1-local-viewport.js and ex3-1-local-viewport.js files onto your web server in the location referenced in the page template. Create a blank page using the newly created template, and run the page. It should look the next screenshot:

Looking at the North panel, we haven't specified a logo in the Application properties so the #LOGO# substitution tag has been replaced with an empty value. The layout issues on the right-hand side with the navigation bar and user name are caused by additional HTML included in the Subtemplate section of the page template. The appearance of the links in the header needs further refinement, which we will do a little later under breadcrumb templates. So, although we have made a good start on the page template, there is still more to do.

[ 83 ]

Building a Ext JS Theme into APEX

To fix the navigation bar on the right-hand side so that the user name is on the same line, update the page template, changing the Subtemplate as follows. Navigation Bar - remove the div tag Before
#BAR_BODY#
After

#BAR_BODY#

Navigation Bar Entry- remove the class attribute Before #TEXT# After

#TEXT#

While we are working on the Subtemplate, we might as well modify the Success Message and the Notification entries also.

The Success Message, shown at the top of the preceding screenshot, uses the following HTML:
 
#SUCCESS_MESSAGE#


And it requires the following CSS rule to be included in the CSS file: .app-success { background:none repeat scroll 0 0 #DFE8F6; border:1px dotted #99BBE8; color:#15428B; cursor:default; clear: both; font:normal 11px tahoma,arial,sans-serif; padding:5px 0; text-align:center; margin:10px 30%; width:40%; } [ 84 ]

Chapter 3

Functionally, it is the same as the standard APEX content it replaces; a DIV region displaying a message, with an image that deletes the region when clicked. JavaScript purists may complain about including JavaScript code in the highlighted onclick attribute. The "better" way would be to remove the onclick attribute and adding the following code to add a listener in your application JavaScript: Ext.onReady(function(){ /*… application code before…*/ if (Ext.fly('app-notification')) { Ext.fly('app-notification').on('click', function(){ this.remove(); }); } });

Both ways achieve the desired outcome; it's just a matter of personal preference which way you want to code. The Notification entry in the previous screenshot is a more complicated layout based on the HTML created by Ext.Alert, allowing the reuse of existing Ext CSS rules. It provides similar functionality to the Success Message; the HTML source is in chapter03/ex3-2-local-viewport.html. The page template now has all the page definition and also the Subtemplate sections completed. But that's not the end of the page template just yet! There is a nasty issue potentially lurking in the template, where input items can appear outside the FORM element, which needs to be addressed. Issue when input items are outside the form As web developers, we are becoming more reliant on using JavaScript to manipulate the page layout to provide functionality such as tab panels, accordion regions, popup dialogs, and the like. This leads to existing elements in the DOM being relocated to new positions, and form INPUT items can end up outside the FORM element.

[ 85 ]

Building a Ext JS Theme into APEX

Irrespective of what JavaScript library you use, DOM manipulation can lead to form INPUT items appearing outside the FORM element. In fact, you don't even need to use JavaScript at all to cause the issue, as we will show in this example.

This screenshot shows the Page Definition within APEX Builder for a simple page containing the following items of interest: •

The Contact Details region to be rendered in location Body (3) [#BOX_ BODY#], with input items P30_FIRST_NAME, P30_LAST_NAME, and P30_ ADDRESS.

•

The Region outside FORM region to be rendered in location Position 2 [#REGION_POSITION_02#], containing item P30_PHONE.

If you refer to the earlier page template, it shows the #REGION_POSITION_02# clearly outside the #FORM_OPEN# and #FORM_CLOSE# substitution tags.

[ 86 ]

Chapter 3

When the page is rendered, and after the layout has been changed using JavaScript, a simplified view of the HTML looks like this:


This shows the highlighted input item, where ID P30_PHONE is clearly outside the FORM tags. From the HTML code shown, you can see the action for the form is wwv_flow. accept and the item names are p_t01 .. p_t04, corresponding to the database

package procedure and parameters being executed by the mod_plsql HTTP request. When the form is submitted, the values for the inputs are loaded into session state, page processing occurs, and the APEX engine branches to a page. In this example, there is no processing, simply branching to the same page, so the page is rendered again with the passed values. So, given the P30_PHONE item is not in the form it shouldn't be processed, but what about the items within the form? The following is the result of submitting the form, showing submitted and returned values: ID P30_PHONE

Name p_t01

Submitted value aaa

Returned value bbb ccc

P30_FIRST_NAME

p_t02

bbb

P30_LAST_NAME P30_ADDRESS

p_t03 p_t04

ccc ddd

-

So as expected, no value is returned for P30_PHONE, because it was outside the form. However, there is an unexpected displacement of the values, shifting them down, so the P30_FIRST_NAME submitted value of bbb is returned in P30_LAST_NAME, and similarly the value for P30_LAST_NAME is returned in P30_ADDRESS. The whereabouts of the value for P30_ADDRESS is unknown and is not easily explained. [ 87 ]

Building a Ext JS Theme into APEX

Without having access to the source code for the APEX engine, it is only possible to speculate on why this occurs. Nevertheless, we still need to deal with the issue and come up with a strategy to prevent it from occurring.

Ensuring that input items always remain with the form To ensure form items always remain within the FORM element, we need to address both the static HTML issue and potential JavaScript DOM manipulation. Modify the page template so that all region substitution tags are contained within the #FORM_OPEN# and #FORM_CLOSE# substitution tags, as shown in the following screenshot:

[ 88 ]

Chapter 3

The previous screenshot shows the updated Viewport template, addressing the static HTML side of the issue. The #FORM_OPEN# tag now appears immediately after the markup, and the #FORM_CLOSE# tag immediately before the markup. The only other change is that the application JavaScript file is now ex3-1-custom-viewport.js, which addresses the JavaScript DOM manipulation. To ensure form items always remain within the form element, we can use a customized version of Ext.Viewport, which uses the APEX form element wwvFlowForm as the container for the viewport, instead of the body element. // create custom namespace if doesn't exist Ext.ns('Ext.apex'); // custom container Ext.apex.Viewport = Ext.extend(Ext.Container, { initComponent : function() { Ext.apex.Viewport.superclass.initComponent.call(this); // APEX specific code this.el = Ext.get('wwvFlowForm'); if(this.el){ this.el.addClass('x-viewport'); var debug = Ext.getDom('pdebug'); if (!(debug && (debug.value == 'YES'))) { document.getElementsByTagName('html')[0].className += ' x-viewport'; } } else { this.el = Ext.getBody(); document.getElementsByTagName('html')[0].className += ' x-viewport'; } this.el.setHeight = Ext.emptyFn; this.el.setWidth = Ext.emptyFn; this.el.setSize = Ext.emptyFn; this.el.dom.scroll = 'no'; this.allowDomMove = false; this.autoWidth = true; this.autoHeight = true; Ext.EventManager.onWindowResize(this.fireResize, this); this.renderTo = this.el; },

[ 89 ]

Building a Ext JS Theme into APEX fireResize : function(w, h){ this.fireEvent('resize', this, w, h, w, h); } }); // Register container so that lazy instantiation may be used Ext.reg('apex-viewport', Ext.apex.Viewport);

The script starts by creating a custom namespace, Ext.apex, to ensure that we don't pollute the global namespace. The Ext.apex.Viewport is then defined, which is a direct copy of the Ext.Viewport, excepting the highlighted APEX specific code. For APEX, the code checks to see if the APEX form element with the wwvFlowForm ID is present in the page, and if yes, whether it uses this as containing item for the Viewport. When wwvFlowForm is not present, it reverts to standard Ext.Viewport functionality, using the document body instead. This is useful when previewing the page template, or selecting the location for a region in the APEX Builder. Finally, the container is registered so that lazy instantiation can be used using the xtype attribute value of apex-viewport. See the panel definitions in the application code for examples of xtypes box and panel. A check is also done to see if APEX is in debug mode, and if yes, it ensures the HTML page allows scrolling, otherwise scrolling is disabled for the page and scrolling is managed within the viewport using Ext features. To use the custom viewport, we simply replace calls to Ext.Viewport with Ext.

apex.Viewport like this:

Ext.onReady(function(){ Ext.BLANK_IMAGE_URL = '../../extjs/resources/images/default/s. gif'; new Ext.apex.Viewport({ configuration }); });

The custom viewport needs to appear before the application code in the JavaScript file. The application code has also been modified to show the east panel only when its container app-east-panel has child nodes other than text. Ext.onReady(function(){ var items = []; Ext.BLANK_IMAGE_URL = '/i/1px_trans.gif'; items.push({ [ 90 ]

Chapter 3 applyTo: 'app-north-panel', autoHeight: true, autoScroll: false, region: 'north', style: {padding: '0 5px'}, xtype: 'box' }, { contentEl: 'app-south-panel', autoScroll: false, height: 30, region: 'south', style: {padding: '0 5px'}, xtype: 'box' }, { contentEl: 'app-west-panel', //collapseMode: 'mini', collapsible: true, margins: '0 0 0 5', maxSize: 500, minSize: 100, region: 'west', split: true, title: 'Navigation', width: 275 }, { contentEl: 'app-center-panel', region: 'center', title: document.title, xtype: 'panel' }); // conditionally add east panel if it contains child nodes if (Ext.fly('app-east-panel') && Ext.fly('app-east-panel').first()) { items.push({ contentEl: 'app-east-panel', collapseMode: 'mini', collapsible: true, margins: '0 5 0 0', maxSize: 500, minSize: 100, region: 'east', split: true, title: 'Actions', [ 91 ]

Building a Ext JS Theme into APEX width: 275 }); } new Ext.apex.Viewport({ layout: 'border', defaults: { animCollapse: false, autoScroll: true }, items: items }); });

The page template is now complete and the issue of input items appearing outside the form element has been resolved.

Summary We have seen how APEX page processing fits a typical Model-View-Controller (MVC) pattern, where the view is the HTML generated using the application templates. The APEX engine is the controller and receives the GET or POST input and decides what to do with it, handing it over to domain objects. The domain objects model is encapsulated in the page definition and contains the business rules and functionality to carry out specific tasks. This separation of concerns provided by the MVC pattern allows APEX to easily swap themes for an application. The publishing mechanism allows new versions of a theme to be built separately from the application. By switching themes, applications can easily test a new version, safe in the knowledge that we can revert to the earlier version if required. We then set about creating a page template, using a standalone prototype initially to make sure the markup and JavaScript works correctly before loading it into APEX. Once a few adjustments were made to load it, the page template was up and running in APEX. This revealed some layout issues with the navigation sub-template (which was corrected), as along with the success and error notifications.

[ 92 ]

Chapter 3

Finally, the issue of JavaScript DOM manipulation potentially causing input items appearing outside the form element was demonstrated. A custom version of Ext. Viewport was developed to ensure that this would never happen in our page template. While we won't be going through any more page templates here, it is very worthwhile to put some time into the "Login" template before you preview your application to anyone. After all, first impressions count, and the first page people will see is the Login page. In the next chapter we turn our attention to other APEX template types used within the page template for regions, labels, and lists.

[ 93 ]

Ext Themed Regions, Labels, and Lists This chapter continues building a theme based on Ext into APEX, developing templates for the regions, labels, and lists. Regions act as the basic building block for content within a page. Each page can hold an unlimited number of regions. The appearance of regions is controlled using Region templates, which can use a mixture of HTML markup, CSS, and JavaScript to control the visual and structural layout. HTML lists are enormously versatile when combined with CSS layouts, due to their graphically flexible nature. In this chapter we will develop list templates, which use traditional CSS styling, as well as using list templates to act as a JavaScript generator to integrate with the Ext JS TreePanel component. In this chapter we will cover: •

Creating region templates using Ext JS panels

•

Adding JavaScript functionality to region templates

•

Creating simple label templates

•

Using Ext JS QuickTips for error messages

•

Styling simple list templates relying on just HTML and CSS

•

Using list templates to integrate the Ext JS TreePanel component

Ext Themed Regions, Labels, and Lists

Region templates The APEX Theme 4 we are using as our "starter" theme contains 22 region templates, one for each of the region template classes. Using this many template classes in an application can only lead to confusion and inconsistencies. Oracle has provided so many alternatives to give you a wide range of templates from which to pick and choose when designing your application layout, but don't expect that you would use them all. Well-designed APEX applications will typically rationalize this down to a small number of region templates used for the everyday functionality covering most of the application, and then perhaps add a few "specialized" region templates. Region templates must contain a #BODY# token; all other allowable tokens are optional. Tokens for the title #TITLE#, #REGION_ID# or #REGION_STATIC_ID#, and #REGION_ATTRIBUTES# are commonly included. Button position names, such as #EDIT#, #CLOSE#, #CREATE#, #CREATE2#, #EXPAND#, #HELP#, #DELETE#, #COPY#, #NEXT#, and #PREVIOUS# are also commonly included. Similar to reducing the number of template types, it's a good idea to rationalize the number of button position names to just a few. Because buttons can be assigned to any button position name, the ordering of buttons can be mostly managed through sequencing of buttons within the page region.

Report Region The Ext Basic Panel works well here for the Report Region template, which is typically used for "classic" reports.

To construct the "Basic Panel, No JavaScript" template shown in the previous screenshot, the following HTML has been used:
<span class="x-panel-header-text">#TITLE# [ 96 ]

Chapter 4
#PREVIOUS##NEXT##DELETE##COPY##CHANGE#

#BODY#



If you refer the Ext documentation for Ext.Panel - frame config option, available at http://dev.sencha.com/deploy/dev/docs/?class=Ext.Panel, you will see the same HTML is generated for a dynamically constructed panel. We are including the panel-specific structural markup to reproduce the visual appearance of the Ext. Panel component. Two minor additions to the Ext markup have been included, both shown in bold. Adding the ux-panel CSS class to the outer DIV allows customization of the DIV and its child components without affecting other objects using the Ext CSS classes. For example, the following CSS adds a margin at the bottom of the Panel to create a vertical spacing between panels. Also added is some padding to the body of the panel, so contained elements are not hard up against the border. .ux-panel {margin-bottom: 10;} .ux-panel .x-panel-body {padding: 5px}

The other change included is the align="right" attribute to the x-panel-tbar DIV, used to right align button elements. To make the Report Region template collapsible, simply add the following JavaScript immediately after the HTML in the template body: <script type="text/javascript"> Ext.onReady(function(){ new Ext.Panel({ allowDomMove : false, applyTo: '#REGION_STATIC_ID#', animCollapse: false, autoHeight: true, collapsible:true, titleCollapse: true }); }); [ 97 ]

Ext Themed Regions, Labels, and Lists

Setting config option applyTo with the #REGION_STATIC_ID# tag will render the Panel to the corresponding DOM node. When applyTo is used, the Ext.Panel code checks the DOM node for constituent parts of the panel specified by CSS class names within the main element. The panel will automatically create those components from that markup. Any required components not specified in the markup will be auto-generated if necessary. The following class names are supported (baseCls defaults to x-panel): • • • • • • •

baseCls + '-header' baseCls + '-header-text' baseCls + '-bwrap' baseCls + '-tbar' baseCls + '-body' baseCls + '-bbar' baseCls + '-footer'

The other config options make the panel collapsible, adding a collapse icon in the top right of the header bar. When the icon is clicked, the panel body collapses to be completely hidden. The icon inverts, and clicking on it again restores the panel body. Setting the titleCollapse option to true allows you to click anywhere in the title to collapse the panel body.

Form Region In case of Form Regions, it is useful to distinguish them visually from non-editable regions. Once again we will use the Ext Basic Panel, this time using the "framed" look.

[ 98 ]

Chapter 4

The following is the HTML code for the Framed Panel, No JavaScript, shown in the previous screenshot:
<span class="x-panel-header-text">#TITLE#
#PREVIOUS##NEXT##DELETE##COPY##CHANGE#

#BODY#



Like the Basic Panel used for the Reports Region template, it contains the same basic "structural" DIV elements, with the addition of a series of DIVs to provide the rounded corners. The CSS rules applied to the panel body are different, providing the blue background color, and more significant visual difference, we are after.

[ 99 ]

Ext Themed Regions, Labels, and Lists

The HTML code for the Framed Panel, Collapsible region is much simpler. It is quite similar to that used for the Basic Panel in the Reports Region template.
<span class="x-panel-header-text">#TITLE#
#PREVIOUS##NEXT##DELETE##COPY##CHANGE#

#BODY#



The differences being the x-panel-bwrap DIV is not present, and the x-panel-tbar DIV is a sibling instead of a child node of the x-panel-body DIV.

The previous screenshot shows the HTML without the JavaScript to convert it into a Framed Panel. It looks like an imperfect version of the Basic Panel. The reason behind this much simpler HTML gets back to the applyTo config option for Ext.Panel, which is looking for the "structural" class names to convert within the main element. If we kept the Framed Panel, No JavaScript version, the Ext.Panel JavaScript does not check for the "visual classes", so they are ignored leading to a questionable result. The JavaScript to create the Framed Panel is once again almost identical, the only difference being the frame: true config option: <script type="text/javascript"> Ext.onReady(function(){ new Ext.Panel({ applyTo: '#REGION_STATIC_ID#', animCollapse: false, autoHeight: true, collapsible:true, frame: true, titleCollapse: true }); });

[ 100 ]

Chapter 4

Additional region templates Undoubtedly you will need more region templates than we have created here. As we progress through the chapters, we will be adding more specialized templates as we go, and revisiting the ones we have created. For the Form Region and Report Region templates, and some additional variations of both, which include a toolbar region, see chapter04/ex-4-panels.html.

Label templates Label templates have only five predefined classes: •

No Label

•

Optional Label

•

Optional Label with Help

•

Required Label

•

Required Label with Help

Probably the only real decision required for which classes you need to define templates is whether or not your application is going to use item-level help. The need to distinguish between optional and mandatory labels visually, as well as the need to easily hide labels, indicates that you will need to define a template for each of these classes.

[ 101 ]

Ext Themed Regions, Labels, and Lists

This screenshot shows the optional and mandatory labels we will be creating, with the mandatory label including a red asterisk to differentiate it visually. The appearance of the labels is similar to that used for Ext labels; however, the HTML markup and CSS used has to be completely customized because APEX uses HTML tables to layout items and labels.

Optional label The HTML for the optional label is as follows: Before label: <span id="#CURRENT_ITEM_NAME#-label" class="ux-form-item-label">

On error before label:


On error after label:


The CSS that is used with the label is: .ux-form-item-label{ font:normal 11px tahoma,arial,helvetica,sans-serif; } .ux-status-error { background: transparent no-repeat 3px 2px; background-image: url(/ux/extjs/resources/images/default/form/ exclamation.gif); color: #CC3333; cursor: pointer; display: inline; line-height:16px; padding:2px 2px 2px 25px; }

[ 102 ]

Chapter 4

The HTML used for the label is very basic, simply a label element referencing its item using the #CURRENT_ITEM_NAME# tag, which is then enclosed by a span element. The purpose for wrapping the label with a span element is that it allows more CSS rules to be applied than the label element. For example, you could specify a CSS rule setting a fixed width for the span, but if you tried to do the same for the label element, the rule would simply be ignored.

QuickTips for error messages Looking at following screenshot, you can see one of the issues faced when displaying inline error messages. The input items have been pushed to the right, the length of the error message forcing the input item to be partially obscured. So, how can we overcome this problem while still providing meaningful inline error messages?

One way is to include a small error image and include the error message in the title and alt attributes, so when the mouse hovers over it the message is revealed as a tooltip. Ext has taken this concept and improved it with Ext.QuickTips, as shown in the following screenshot:

[ 103 ]

Ext Themed Regions, Labels, and Lists

Ext.QuickTips provides attractive and customizable tooltips for any element, and can be configured via tag attributes directly in markup. Ext documentation summarizes the supported attributes (optional unless otherwise noted). •

hide: Specifying "user" is equivalent to setting autoHide = false. Any other value will be the same as autoHide = true.

•

qclass: A CSS class to be applied to the quick tip (equivalent to the "cls"

•

qtip (required): The quick tip text (equivalent to the "text" target

target element config).

element config).

•

qtitle: The quick tip title (equivalent to the "title" target element config).

•

qwidth: The quick tip width (equivalent to the "width" target

element config).

You can also configure the QuickTips singleton in addition to the supported attributes. To enable Ext.QuickTips, you need to include a call to Ext.QuickTips.init in your application JavaScript. Ext.onReady(function(){ // Init the singleton. // Any tag-based quick tips will start working. Ext.QuickTips.init(); // Apply a set of config properties to the singleton. // Use interceptTitles to pick up title attribute, // excepting IE as cannot prevent tooltip appearing also. Ext.apply(Ext.QuickTips.getQuickTip(), { interceptTitles: (!Ext.isIE), maxWidth: 300, minWidth: 100, showDelay: 50, trackMouse: true }); // more code });

[ 104 ]

Chapter 4

For the example provided in the previous screenshot, the markup for the Last Name label with its error message looks like:
<span id="P30_LAST_NAME-label" class="ux-form-item-label">


The DIV element has a class attribute of ux-status-error, which displays a background image, padding the element sufficiently to display the image and provide some spacing before the label text. Specifying the ext:qclass="x-form-invalid-tip" attribute means the QuickTip will use an Ext CSS rule specifically designed for errors, rather than the standard QuickTip styling.

Optional label with help The HTML is identical to that of the optional label, with an additional link element: Before label: <span id="#CURRENT_ITEM_NAME#-label" class="ux-form-item-label">

On error before label:


On Error after label:


[ 105 ]

Ext Themed Regions, Labels, and Lists

The CSS that is used with the label is: .ux-form-item-label a { color:#1E4176; cursor:pointer; text-decoration:none; -moz-outline: none; outline: none; } .ux-form-item-label a:hover { text-decoration:underline; }

The HTML used here is the same as for the optional label, with the inclusion of a link , which calls the APEX JavaScript to display item help in a popup window. Additional CSS has been included to make the link visually similar, but not the same as the optional label, with a subtle color difference and different cursor to provide visual cues for a different behavior. When the mouse hovers over the label, it is underlined, reinforcing again the cue for a different behavior.

Mandatory label The HTML for the mandatory label is almost identical to the optional label: Before label: <span id="#CURRENT_ITEM_NAME#-label" class="ux-form-item-label">

On error before label:


[ 106 ]

Chapter 4

On error after label:


The only difference between the optional and mandatory labels is the addition of the <em>* markup in the After Label section, and the additional CSS rule to make the asterisk red: .ux-form-item-label em {color:#CC3333;}

Mandatory label with help The HTML is identical to that of the mandatory label, with an additional link element used to display field-level, context-sensitive help: Before label: <span id="#CURRENT_ITEM_NAME#-label" class="ux-form-item-label">

On error before label:


On error after label:


No additional CSS is required for the link element, which uses the same CSS rules as the optional label with help.

Hidden label The HTML for the hidden label is even simpler: Before label: <span class="x-hidden"> [ 107 ]

Ext Themed Regions, Labels, and Lists

After label:

On error before label:


On error after label:  


For this label, we are using a SPAN element with an Ext class named x-hidden to hide the label text. The On error label markup remains the same as the optional label, allowing errors to be displayed even when no label is visible. An extra HTML string ( ) has been added to ensure the error icon displays correctly when no text has been provided for the label. This wraps up the section on Label templates, which really are quite straightforward, just requiring a minimal amount HTML markup and some CSS styling. The addition of Ext.QuickTips here neatly solves the problem of error messages ruining region layouts while retaining APEX provided functionality for item-level, context-sensitive help.

List templates Lists are one of the most versatile HTML elements, providing a way to display content and information in a very easy way to scan and read. APEX contains a great variety of lists already with its built-in themes, as is evident by the template classes for lists: •

Button List

•

Hierarchical Expanded

•

Hierarchical Expanding

•

Horizontal Images with Label List

•

Horizontal Links List

•

Pull Down Menu

•

Pull Down Menu with Image

•

Tabbed Navigation List

•

Vertical Images List

•

Vertical Ordered List [ 108 ]

Chapter 4

•

Vertical Sidebar List

•

Vertical Unordered List with Bullets

•

Vertical Unordered List without Bullets

•

Wizard Progress List

The list templates display data defined in APEX lists, and may be flat or hierarchical in structure. A list is considered to be hierarchical when a parent-child relationship has been defined in the list for one or more entries.

If your lists become overly complicated or lose their simplicity, you will have lost the essence of the list and will lose your visitors' interest as well. To start with, let's create the list templates shown in previous screenshot.

Vertical unordered list without bullets

The list template has a large number of fields available to use; only the ones being populated are shown here. •

Name: EXTJS vertical unordered list without bullets

•

Template Class: Vertical unordered list without bullets

List template before rows:


    List template current:
  • #TEXT#


  • [ 109 ]

    Ext Themed Regions, Labels, and Lists

    List template current with sub list items:
  • #TEXT#


    • List template noncurrent:
    • #TEXT#


    • List template noncurrent with sub list items:
    • #TEXT#


      • Sublist template current:
      • #TEXT#


      • Sublist template current with sub list items:
      • #TEXT#


        • Sublist template noncurrent:
        • #TEXT#


        • Sublist template noncurrent with sub list items:
        • #TEXT#


          • Sublist template after rows:


For a flat list, the sublist fields are unnecessary, and removing the sublist markup would make absolutely no difference. However, not having the sublist markup would mean a hierarchical list would only display the top-level list items. For this reason, it's a good practice to define the sublist markup and apply CSS styling to suit. Ext includes some CSS rules to "reset" unordered lists and list items, removing margins, padding, and list item indicators; so, before we add any CSS rules of our own, both a flat list and a hierarchical list look like Before CSS styling list in the following screenshot, which is close to the desired result:

[ 110 ]

Chapter 4

The following CSS will produce the look of the After CSS styling list shown earlier in previous screenshot: .ux-list { background:#fff; padding:10px; text-align:left; border:0 none transparent; } .ux-list li { color:#ccc; line-height:16px; font-family: helvetica,arial,tahoma,sans-serif !important; font-size:11px; } .ux-list .ux-list-selected { background-color:#D9E8FB; } .ux-list a { color:#555555; padding-left:2px; } .ux-list a:link, .ux-list a:visited, .ux-list a:active { color:#555555; text-decoration:none; [ 111 ]

Ext Themed Regions, Labels, and Lists } .ux-list a:hover { color:#0464BB; text-decoration:underline; } .ux-list .ux-list-selected a { color:#000000; }

By wrapping a DIV tag around the list and assigning a class name of ux-list to the DIV tag, all unordered list and list items within don't need any class attributes. This reduces the size of the generated markup slightly, and also makes it easy to restyle the list by changing the class name for the DIV, as we will see in the next template. For the "Current" fields, the ux-list-selected class has been added, but because the corresponding CSS rules are prefixed by ux-list, changing the class name for the DIV will follow on to any "current" list item.

Vertical unordered list with bullets

To create this template, all we need to do is copy the "EXTJS vertical unordered list without bullets" template using the APEX copy feature on the Shared Components | Templates page within APEX Application Builder and make the following edits: Name: EXTJS Vertical Unordered List with Bullets Template Class: Vertical Unordered List with Bullets List Template Before Rows:


    Surprised at how little was changed? Because the structure of the list isn't being changed, only the CSS class needs to be modified and additional CSS rules added: .ux-list-bullet ul { list-style-type: square; margin-left:13px; }

    [ 112 ]

    Chapter 4

    In this case, the original class ux-list was kept and a second class name ux-list-bullet added. For CSS styling it means the original classes are applied and any new classes have their attributes added.

    The addition of the one CSS rule adds the square bullet to the list, with the left margin indenting the list, and for hierarchical sublists, the indent is multiplied by the number of levels. The previous screenshot shows the difference between a flat list and a hierarchical list using the template.

    Building an Ext JS tree template using lists

    Every computer user is immediately familiar with using a tree view for navigating in an application. Tree components allow hierarchical data to be presented in a compact and structured manner, allowing the user to interact to hide or show information. APEX hierarchical lists are ideal for presenting static data, and using the built-in lists to store and display the data provide some advantages over a custom table-based solution. Built-in lists allow you to use conditional logic when displaying list entries using either the "Conditions" fields, or "Authorization Scheme". This means you can conditionally show items depending on security privileges, or show or hide items based on some application state.

    [ 113 ]

    Ext Themed Regions, Labels, and Lists

    A second advantage is the list data is part of the APEX application export, so you don't need to remember to migrate data from application tables.

    Let's take a look at the prototype, chapter04/ex-4-tree-panel.html, shown in previous screenshot, and examine the JavaScript used to construct the tree.
    <script type="text/javascript"> Ext.onReady(function(){ // define tree data as an object var treeData = {text:"Root Node", expanded:true, children:[ {id:"L01",text:"Cars", href:"#",leaf:false,children: [ {id:"L02",text:"Passenger", href:"#",leaf:true}, {id:"L03",text:"4WD", href:"#",leaf:true}]}, {id:"L04",text:"Marine", href:"#",leaf:false,children: [ {id:"L05",text:"Motorized", href:"#",leaf:false,children: [ {id:"L06",text:"Diesel", href:"#",leaf:true}]}, {id:"L07",text:"Sail", href:"#",leaf:true}]}, {id:"L08",text:"Motorcycles",href:"#",leaf:false,children: [ {id:"L09",text:"Road", href:"#",leaf:true}, {id:"L10",text:"Off Road", href:"#",leaf:true}]} ]}; // create the tree new Ext.tree.TreePanel({ renderTo:'tree-div', useArrows:true, [ 114 ]

    Chapter 4 autoScroll:true, animate:true, border:false, rootVisible: false, root: treeData }); });

    Looking at the prototype code, you can see two separate code blocks, the first being a JavaScript object of tree node definitions. Each tree node has the id, text, href, and leaf properties defined, except the root node, which just has the text and expanded properties defined. Ext JS automatically assigns an ID to each tree node if it doesn't already have an ID assigned, so the ID is optional. The generated ID is a text string in the form extgenN, with N being replaced with a number. The reason behind assigning an ID to the other elements is the fact that we are interacting with the backend server, asynchronously loading tree nodes or manipulating nodes, and those nodes are associated with backend data such as a database records primary key, so it's very useful to be able to match nodes with the backend data. However, the root node is an artificial construct, required by Ext.tree.TreePanel, because every tree must have only one root node. The second code block instantiates an Ext.tree.TreePanel object, passing a configuration block. Along with configuring how the tree is to be displayed, it also assigns the root to the treeData object defined in the first code block, and sets the renderTo:'tree-dev' property to use the DIV markup immediately before the script block.

    APEX 4.0 tree template Release 4 of APEX added the "Template Definitions for First Entry" section to the List Template, including four new fields: •

    List Template Current (First)

    •

    List Template Current with Sub List Items (First)

    •

    List Template Noncurrent (First)

    •

    List Template Noncurrent with Sub List Items (First)

    [ 115 ]

    Ext Themed Regions, Labels, and Lists

    These new fields assist in generating a unique ID for the target DIV tag, used to render the tree. I will show you an alternative version for earlier releases of APEX shortly, but let's first look at the APEX 4 version. List template current: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true, isCurrent:true}

    List template current with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, isCurrent:true, children:[

    List template noncurrent: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true}

    List template noncurrent with Sub List Items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, children:[

    Between List Elements: ,

    List template current (first):
    <script type="text/javascript"> Ext.onReady(function(){ var treeRegion = 'tree#LIST_ITEM_ID#'; var treeData = {text:"Root Node", expanded:true, children: [{id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true, isCurrent:true }

    List template current with sub list items (first):
    <script type="text/javascript"> Ext.onReady(function(){ var treeRegion = 'tree#LIST_ITEM_ID#';

    [ 116 ]

    Chapter 4 var treeData = {text:"Root Node", expanded:true, children: [{id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, isCurrent:true, children: [

    List template noncurrent (first):
    <script type="text/javascript"> Ext.onReady(function(){ var treeRegion = 'tree#LIST_ITEM_ID#'; var treeData = {text:"Root Node", expanded:true, children: [{id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true}

    List template noncurrent with sub list items (first):
    <script type="text/javascript"> Ext.onReady(function(){ var treeRegion = 'tree#LIST_ITEM_ID#'; var treeData = {text:"Root Node", expanded:true, children: [{id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, children: [

    Sub list template current: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true, isCurrent:true }

    Sub list template current with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, isCurrent:true, children: [

    Sub list template noncurrent: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true}

    [ 117 ]

    Ext Themed Regions, Labels, and Lists

    Sublist template noncurrent with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, children: [

    Between sub list items: ,

    Sublist template after rows: ]}

    List template after rows: ]}; new Ext.tree.TreePanel({ renderTo:treeRegion, useArrows:true, autoScroll:true, animate:true, border:false, rootVisible: false, root: treeData }); });

    Traditionally, templates contain HTML markup and occasionally a little JavaScript. Here we are doing exactly the opposite with just a single DIV element, and using the rest of the template to generate JavaScript code. Despite appearances, the template is close to our original prototype; however, there is one adjustment that had to be made. In the prototype, the DIV tag the TreePanel component will be rendered into is specified by the renderTo attribute as a string: // create the tree new Ext.tree.TreePanel({ renderTo:'tree-div', useArrows:true, autoScroll:true, animate:true, border:false, rootVisible: false, root: treeData }); [ 118 ]

    Chapter 4

    In the APEX template, a variable has been defined and referenced:
    <script type="text/javascript"> Ext.onReady(function(){ var treeRegion = 'tree#LIST_ITEM_ID#'; // code... new Ext.tree.TreePanel({ renderTo:treeRegion, useArrows:true, autoScroll:true, animate:true, border:false, rootVisible: false, root: treeData });

    The reason for doing this is that the list template does not allow #REGION_ID# or some equivalent substitution tag to be used in the List template before rows field. To generate a unique ID for DIV, the #LIST_ITEM_ID# has been used in the first list item. Because this cannot be referenced later in the List Template After Rows field, the ID has to be passed by variable reference. In case you're wondering, the treeRegion variable is local to the anonymous function enclosed by Ext.onReady, so you could have multiple instances of the variable without any issue.

    Prior APEX versions tree template APEX versions prior to APEX 4.0 don't have the "Template Definitions for First Entry" section, so it is a two-part solution to create a tree component using a list template. The tree definition remains mostly unchanged in the list template, the code in the "First Entry" field needs to be moved to a customized region template. The markup for the "EXTJS Tree Panel" region is as follows:
    <script type="text/javascript"> Ext.onReady(function(){ var treeRegion = '#REGION_STATIC_ID#';

    [ 119 ]

    Ext Themed Regions, Labels, and Lists // define tree data as an object var treeData = {text:"Root Node", expanded:true, children:[ #BODY# ]}; new Ext.tree.TreePanel({ renderTo:treeRegion, useArrows:true, autoScroll:true, animate:true, border:false, rootVisible: false, root: treeData }); });

    The region creates a DIV element with an ID populated by the #REGION_STATIC_ID# substitution tag. The #BODY# tag will be populated by the list definition: List template current: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true, isCurrent:true}

    List template current with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, isCurrent:true, children:[

    List template noncurrent: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true}

    List template noncurrent with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, children:[

    Between list elements: ,

    Sub list template current: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true, isCurrent:true}

    [ 120 ]

    Chapter 4

    Sub list template current with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, isCurrent:true, children: [

    Sub list template noncurrent: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:true}

    Sublist template noncurrent with sub list items: {id:"#LIST_ITEM_ID#",text:"#TEXT#",href:"#LINK#",leaf:false, children: [

    Between sub list items: ,

    Sublist template after rows: ]}

    The only differences between this and the APEX 4.0 version are that the Template Definitions for First Entry section doesn't exist, and the List Template After Rows field is blank.

    Highlighting the current node To highlight the "current" node in our tree, as shown in the following screenshot, the list template use the attribute isCurrent:true for the current entries.

    For example the "Sub List Template Current" looks like: {id:"#LIST_ITEM_ID#", text:"#TEXT#", href:"#LINK#", leaf:true, isCurrent:true}

    [ 121 ]

    Ext Themed Regions, Labels, and Lists

    Now we need to modify the JavaScript to detect this attribute and use built-in Ext. tree.treePanel functionality to select the node. Because you're most likely to be using the tree regularly, it's worthwhile creating a custom component and saving it to your application JavaScript file, rather than embedding the code within the page. A nice way of doing this is by extending the Ext JS component. The code shown here is in chapter04/Ext.apex.tree.TreePanel.js. // create custom namespace if doesn't exist Ext.ns('Ext.apex.tree'); /** * @class Ext.apex.tree.TreePanel * @extends Ext.tree.TreePanel *

    The APEX TreePanel highlights the first node with "isCurrent" set to true.

    */ Ext.apex.tree.TreePanel = Ext.extend(Ext.tree.TreePanel, { afterRender: function(){ Ext.apex.tree.TreePanel.superclass.afterRender.call(this); this.highlightCurrentNode(); }, highlightCurrentNode: function(){ var path = this.getCurrentNodePath(this.root.attributes); this.expandPath(path, 'id', function(isSuccess, currentNode){ if (isSuccess) { currentNode.select(); currentNode.ensureVisible(); } }); }, getCurrentNodePath: function(node){ if (node.isCurrent) { return this.pathSeparator + node.id; } else { if (node.children) { for (var i = 0; node.children.length > i; i += 1) { var result = this.getCurrentNodePath(node.children[i]); if (result) { return this.pathSeparator + node.id + result; } [ 122 ]

    Chapter 4 } } } // not found return null; } }); // Register container so that lazy instantiation may be used Ext.reg('apex-treepanel', Ext.apex.tree.TreePanel);

    Ext uses lazy loading an Ext.tree.TreeNode's child nodes, meaning the child nodes are loaded only when a tree node is expanded. This reduces the number of DOM nodes rendered by the initial tree load and improves performance, particularly for large trees. However, it's somewhat inconvenient here, as the Ext.tree.treePanel API doesn't provide a mechanism to search for nodes that haven't been rendered yet. As the data for the tree is contained within the page, and not being fetched by an AJAX request, it's safe to extend the Ext.tree.treePanel to search the tree data for the unrendered nodes. And that's what we are doing—searching down the hierarchy path of the root node: highlightCurrentNode: function(){ var path = this.getCurrentNodePath(this.root.attributes);

    this.expandPath(path, 'id', function(isSuccess, currentNode){ if (isSuccess) { currentNode.select(); currentNode.ensureVisible(); } }); },

    Once the current node is detected, we use the Ext.tree.treePanel API call currentNode.select(); to select (and render) the node, and then scroll it into view using currentNode.ensureVisible();. To call the extension, just modify the template replacing the reference to Ext.tree.TreePanel with Ext.apex.tree.TreePanel.

    [ 123 ]

    Ext Themed Regions, Labels, and Lists

    Customizing individual nodes APEX provides spare substitution tags #A01#...#A10# for list items, allowing you to add additional content to list items if your list template supports it. It is good practice to use these spare tags for special templates, and use the standard tags for lists so that you can easily swap templates on a page-by-page basis. So, modify all the template items to include #A02# after the leaf tag, for example: {id:"#LIST_ITEM_ID#", text:"#TEXT#", href:"#LINK#", leaf:true#A02#}

    Now you have a list item field that stores 2000 characters of additional data. For example, to change the appearance of a node: Define a CSS rule for the node icon in your application CSS file, using the !important attribute to override the normal node icon: .ux-lock { background-image: url(/ux/extjs/resources/images/default/grid/ hmenu-lock.gif) !important; }

    Then add the following text in the A02 field for a node (note the leading comma): ,iconCls: "ux-lock"

    The nodes appearance is now a padlock, as shown in the following screenshot:

    With 2000 characters available with which to play, you can do quite a bit, and if that's not enough, you still have nine of the remaining #A01#..#A10# substitution tags up your sleeve.

    [ 124 ]

    Chapter 4

    Here's another example, attaching a click handler to a node: ,iconCls:'ux-lock', listeners:{click:function(node, e){ // stop standard event e.stopEvent(); Ext.MessageBox.show({ title: 'Credits', msg: 'Website developed by Snazzy Websites', buttons: Ext.MessageBox.OK }); }}

    We will be covering much more on Ext trees in later chapters, but as you can see, you can do quite a bit just using the list template as your data source.

    Summary In this chapter we've covered Region templates, showing how to create static versions of the Ext.Panel with framed and unframed variants. Then, to make the regions collapsible, a few lines of JavaScript were added with minor modifications to the static templates. For Label templates, we created simple HTML templates using custom CSS to approximate the Ext look. Inline error messages can create display issues, pushing items off the display area. By modifying the error attributes for labels to make use of Ext.QuickTips, a small error icon is displayed instead; when the mouse hovers over the icon, an error message is revealed. For List templates, we started by creating some very simple templates relying on just HTML and CSS, all using the same list structure. By modifying only the class of a DIV wrapper element, different appearances could be achieved with minimal additional CSS rules. APEX lists are ideal for presenting static data, and using the built-in lists has advantages over a custom table-based solution. Built-in lists allow you to display entries conditionally based on "Conditions" fields, or "Authorization Scheme". List data is also part of the application export, so you don't need to remember to include data from database tables as part of your application promotions.

    [ 125 ]

    Ext Themed Regions, Labels, and Lists

    Using List templates, we implemented the Ext.tree.TreePanel, showing how templates can also be used to produce JavaScript code and JSON objects, and not just HTML. Two versions of the Tree Template were created—one for APEX 4.0 and the other for earlier versions of APEX. Using the current list item template field to identify the current tree node, the Ext.tree.TreePanel was extended to create a custom component, allowing the current tree node to be selected and scrolled into view. Finally, we saw how to customize the appearance of individual tree nodes using the A01#..#A10# substitution tags available for each list item, as well as add specific JavaScript code. In the next chapter we continue developing templates for the remaining template types, emphasizing a rich and responsive interface for buttons, popups, calendars, and reports.

    [ 126 ]

    Ext Themed Buttons, Popups, Calendars, and Reports Have you ever stopped and asked yourself "What's the difference between a link and button"? You press a button when you want something to happen, just as in everyday life. You press a button to switch on a light, change channels on TV, or start your computer, washing machine, car, and so on. The BRB, or big red button, is often featured in movies with the person in charge sweating over the decision of triggering a self-destructive process. "Whatever you do, do not press the big red button." When you press a button, there are consequences! On the other hand, the main purpose of a link is to navigate to another location, not really affecting anything and no real consequences. In other words, the humble button on your web application is a really important component and needs to be given serious design consideration. We continue building up a theme based on Ext into APEX, developing templates for the remaining template types: buttons, popup list of values, breadcrumbs, calendars, and reports. The modern website user experience is now about rich and responsive user interfaces, with interfaces displaying intuitive visual cues to communicate the status of the users' interaction with the system. For instance, clicking on a button often changes the appearance from "normal" to a "pressed" look, giving immediate feedback to the user, confirming their action has triggered an action with the system. By the end of the chapter, you will have a "minimal" theme ready to publish.

    Ext Themed Buttons, Popups, Calendars, and Reports

    Button templates

    APEX allows you to create three styles of buttons: HTML, Template, and Image. The HTML button creates the native browser-based button with attributes you can specify; the rendered appearance differs based on your operating system and browser. The HTML button is lightweight for HTTP requests, but limited in how you can manipulate its appearance. The Image button allows you to control the appearance by specifying the image used and the image attributes. A significant limitation of image-based buttons is that you have to specify the image details every time you create a button—a real productivity killer. For this reason alone, I would strongly encourage you not to use image-based buttons, but rather create a template-based button with the image details included. The Template button provides you with far greater design flexibility, allowing you to duplicate the HTML generated by either the HTML or Image style buttons, or create something with greater functionality. The additional flexibility Template buttons offer, without the drawbacks of either of the other button styles, make it the obvious choice for all your buttons. Over the next few pages, we will explore the following alternative approaches to buttons: •

    Creating a custom markup button using Sliding Doors and CSS sprites

    •

    An Ext static markup template button

    •

    JavaScript enabling the Ext button

    •

    Toolbar buttons using pure JavaScript

    Sliding doors meet CSS sprites Here, we are creating a custom markup button using the sliding doors method to provide horizontal scalability and creating multiple states by applying different background images contained in a sprite image. The following screen shows what we are trying to achieve—a normal button appearance, that is, a light blue background when the mouse hovers over, and a darker blue background when the button is pressed. The Apply Changes button shows the appearance of the button is maintained for variable widths.

    [ 128 ]

    Chapter 5

    A standalone example of the finished buttons can be found in chapter05/ex-5-

    buttons.html.

    The Sliding Doors technique was first introduced on A List Apart (http://www. alistapart.com/articles/slidingdoors/). The principle involves making

    two images slide over each other, allowing the button to stretch horizontally to accommodate the button content, as shown in the following diagram. By making one of the images sufficiently wide, you can accommodate a large range of button widths.

    The simplified HTML for this button is:

    To hide the buttons border and a ensure consistent layout for different browsers, the following CSS rules are applied: button.ux-btn-alt{ border:0; background:none; cursor: pointer; padding:0; margin:0; width:auto; overflow: visible; /* removes extra side padding in IE */ text-align:center;

    [ 129 ]

    Ext Themed Buttons, Popups, Calendars, and Reports white-space:nowrap; height: 22px; } .ux-btn-alt span, .ux-btn-alt span em { display: block; height: 22px; line-height: 22px; } /* override extra padding in Firefox */ .ux-btn-alt::-moz-focus-inner { border: 0; padding: 0; } /* prevent RH edge disappearing when pressed */ .ext-opera .ux-btn-alt span { margin-right:2px; margin-bottom:1px; } .ux-btn-alt em{ color:#333333; font:11px arial,tahoma,helvetica,sans-serif; }

    The border:0 setting removes the border from the button; the remaining settings ensure the height of the button is the same as the images used and ensure that the text positioning and appearance is consistent across different browsers. One way of minimizing HTTP requests is to combine multiple images into a single image, or sprite, and using the CSS background-image and background-position properties to display the desired image segment. Here, we are using the sprite shown in the following figure, which holds left and right images for the button on a transparent background. The button positions for the "Normal" state are shown with the left button at (0,0) and the right button at (right,-100px).

    [ 130 ]

    Chapter 5

    .ux-btn-alt em{ padding-left:10px; background:url(btn-sprite.gif) no-repeat 0 0; } .ux-btn-alt span{ padding-right:0 10px 0 0; background:url(btn-sprite.gif) no-repeat right -100px; }

    The images for the button are specified using the CSS background property, a shorthand way of specifying background-image and background-position properties. The EM element is used for the left image, and the SPAN element is used for right image. Here, both images have been combined into a single image, using CSS offsets to reference the right image. To create the "hover" and "active" appearance for the buttons, we use the CSS selectors of the same name with the !important attribute to override the background-position of the SPAN and EM elements: .ux-btn-alt:hover em, .ux-btn-alt-over em { background-position: 0 -30px !important; } .ux-btn-alt:hover span, .ux-btn-alt-over span { background-position: right -130px !important; } .ux-btn-alt:active em, .ux-btn-alt-click em{ [ 131 ]

    Ext Themed Buttons, Popups, Calendars, and Reports color:#000000; background-position: 0 -60px !important; } .ux-btn-alt:active span, .ux-btn-alt-click span { background-position: right -160px !important; }

    All modern browsers support the :active pseudo selector; however, when it comes to supporting the :hover pseudo selector, there is an exception of IE6 and IE7. The additional ux-btn-alt-over selector was added to be able to include JavaScript to address this deficiency. For toolbars, the button borders can be hidden until the mouse hovers over using: .x-toolbar .ux-btn-alt span, .x-toolbar .ux-btn-alt em { background-position: 0 -100px; }

    APEX sliding door CSS sprite button template To include this little gem as an APEX button template, add the CSS rules and button sprite to your resource files, and create the following button template:

    The complete CSS for the button can be found in chapter05/ex-5-buttons.html, and is shown below. Just add the images to your resources, and include the CSS in your project CSS file, adjusting the paths for the images as necessary. button.ux-btn-alt{ border:0; background:none; cursor: pointer; padding:0; margin:0; width:auto; overflow: visible; /* removes extra side padding in IE */ text-align:center; white-space:nowrap; height: 22px; }

    [ 132 ]

    Chapter 5 .ux-btn-alt span, .ux-btn-alt span em { display: block; height: 22px; line-height: 22px; } /* override extra padding in Firefox */ .ux-btn-alt::-moz-focus-inner { border: 0; padding: 0; } /* prevent RH edge disappearing when pressed */ .ext-opera .ux-btn-alt span { margin-right:2px; margin-bottom:1px; } .ux-btn-alt em{ color:#333333; font:11px arial,tahoma,helvetica,sans-serif; } .ux-btn-alt em{ padding-left:10px; background:url(btn-sprite.gif) no-repeat 0 0; } .ux-btn-alt span{ padding:0 10px 0 0; background:url(btn-sprite.gif) no-repeat right -100px; } .ux-btn-alt:hover em, .ux-btn-alt-over em { background-position: 0 -30px !important; } .ux-btn-alt:hover span, .ux-btn-alt-over span { background-position: right -130px !important; } .ux-btn-alt:active em, .ux-btn-alt-click em{ color:#000000; background-position: 0 -60px !important; [ 133 ]

    Ext Themed Buttons, Popups, Calendars, and Reports } .ux-btn-alt:active span, .ux-btn-alt-click span { background-position: right -160px !important; } .x-toolbar .ux-btn-alt span, .x-toolbar .ux-btn-alt em { background-position: 0 -100px; }

    So, there you have it, a cross-browser method for custom styling button elements using sliding door sprites to provide interactive feedback on hover and when clicked. Let's have a look now at how we can create an Ext.Button from markup.

    Building a hideous Ext.Button

    The markup used for the standard Ext.Button is made up using in the Ext team's own words "a hideous table template". Hideous it may be, but the advantage of using this complex table structure is that it provides enormous flexibility in its dimensions. The following screenshot shows some of the layouts that can be created using an Ext.Button:

    To create a button template duplicating the Ext layout, the first thing we need to do is get the markup generated for an Ext.button. This can be done quite easily using Firebug.

    [ 134 ]

    Chapter 5

    Open an example page that has the Ext JavaScript files attached, and run the following commands from the Firebug console: Ext.get(document.body).update('
    '); new Ext.Button({ text: '#TITLE#', scale:'small', renderTo: 'test' });

    The first command replaces the entire HTML document body, with a single DIV element having an ID of test. The second command renders an Ext.Button into the DIV. I'm using the small scaled button here, but you may prefer the "medium" or "large" buttons for your application. From there, locate the test DIV in the Firebug HTML tab, as shown in the following screenshot. select it, and using the right-click menu, choose the Copy innerHTML option and paste it into your favorite text editor.

    With a little formatting, the markup looks something like this: [ 135 ]

    x-btn-

    Ext Themed Buttons, Popups, Calendars, and Reports
       
      <em class="" unselectable="on">  
       


    To convert this into an APEX button template only requires us to strip out the ID attributes, and add in the APEX substitution tags for #LINK# and #BUTTON_ATTRIBUTES#. Like every good lazy programmer, I had already included the #LABEL# tag when creating the button. The finished markup for the EXTJS Button template is: [ 136 ]

    Chapter 5
       
      <em unselectable="on" class="">  
       


    The opening TABLE element highlighted in the template needs some explanation. First, using the onclick="#LINK#" attribute allows the button to work quite happily using standard APEX functionality without any further JavaScript manipulation whatsoever. This provides robustness to the design. As soon as the button has been rendered, a user can click on the button, and it will execute. For very simple pages, such as wizards with sensible default values, an experienced user will click through the page rapidly. The class="ux-btn ux-btn-markup x-btn x-btn-noicon" has two non-standard class attributes: ux-btn-markup acts as a marker that will be used shortly to add some JavaScript functionality. ux-btn is used to apply the following CSS rules, ensuring standard

    Ext buttons created using tables (which are block level elements) are changed to inline-block elements to allow side-by-side layout.

    Ext usually renders buttons in separate table cells to avoid this issue; we need to allow for this not being the case. IE provides support only for inline-block in version 8 and upwards in some modes, so for IE, use inline instead. table.ux-btn {display:inline-block} .ext-ie table.ux-btn {display:inline}

    Finally, the #BUTTON_ATTRIBUTES# substitution tag allows the developer to assign a specific ID attribute to a button. The following shows how you assign the ID in the Button Display Attributes section of the button:

    [ 137 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    APEX supports a #BUTTON_ID# substitution tag, but performs substitutions only for buttons in Region positions and not for button items. Use button attributes instead to assign a specific ID.

    So now we have a functioning button that looks just like an Ext button, but doesn't behave like one. The "hover" and "active" effects aren't happening, and they aren't registered Ext components, so we can't manipulate them easily. We also haven't covered adding icons and menus to the buttons. It's time to convert the button to take advantage of the rich Ext API.

    Converting our buttons Before we look at the JavaScript to convert our static markup buttons to Ext buttons, it is worthwhile discussing why we want to convert them in the first place. The "hover" and "active" effects for our buttons are a nice to have feature, rather than a must have. Converting buttons to Ext buttons opens additional display and functional options, with the rich Ext API allowing you to add icons easily, or make buttons toggle on and off. Ext also provides menus so that clicking a menu button displays a drop-down menu, or in the split button case, provides a "primary action" when you click the main button region and shows a drop-down menu when the drop-down region is clicked. You can see these features in the following screenshot. When you create an Ext.Button, it is automatically registered with the Ext.ComponentMgr, providing a mechanism to easily access all Ext components by component ID. So, you could easily disable or enable buttons based on the state of some page item, or show or hide items based on a button's state.

    To convert our buttons to Ext buttons, we first need to override the Ext.Button object to modify its functionality, in order to allow the button object to be applied to our markup. [ 138 ]

    Chapter 5

    In Chapter 4, Ext Themed Regions, Labels, and Lists, we saw Ext.Panel detect panel-specific structural markup when using the applyTo configuration attribute, converting static APEX region templates into an Ext.Panel. The Ext.Button, however, does not provide equivalent functionality to detect structural markup, so we need to add it ourselves. Ext contains Ext.Extend and Ext.Override utility functions, providing the mechanism for simulating class inheritance. Using these functions gives you the ability to modify or extend the base functionality of any JavaScript class without making code changes directly to the class. If you are adding or changing the behavior of a class, usually you would use Ext.Extend to create a new class; however, in this case I've chosen to override the Ext.Button class because I want the changes to flow through to its child classes. The following screenshot, taken from the Ext documentation, shows the inheritance path for Ext.SplitButton; observe that SplitButton extends Button. By using Ext.Override, the changes to the Button class will be inherited by SplitButton, which in turn subclasses CycleButton.

    The code for the button override is contained in chapter05/Override.Ext.Button. js and includes commenting, which has been stripped out here for brevity. Ext.override(Ext.Button, { // private isRendered: false, arrowSelector: 'em', initComponent: function(){ if (this.transformEl) { this.isRendered = true; this.applyTo = this.transformEl; delete this.transformEl; } Ext.Button.superclass.initComponent.call(this); [ 139 ]

    Ext Themed Buttons, Popups, Calendars, and Reports this.addEvents( 'click', 'toggle', 'mouseover', 'mouseout', 'menushow', 'menuhide', 'menutriggerover', 'menutriggerout' ); if(this.menu){ this.menu = Ext.menu.MenuMgr.get(this.menu); } if(Ext.isString(this.toggleGroup)){ this.enableToggle = true; } },

    So, here we can see a couple of additional variables, isRendered and arrowSelector, being declared. In the initComponent function, a small piece of code has been added to detect when a button has been instantiated, with a transformEl attribute identifying the markup button to be converted. After setting the isRendered variable to true, the transformEl variable is reassigned to the applyTo variable, to be used by the standard Ext.Button code. onRender: function(ct, position){ if (!this.template) { if (!Ext.Button.buttonTemplate) { // hideous table template Ext.Button.buttonTemplate = new Ext.Template( '', '', '', '', '', '', '', '', '', '', '', '
      
     ', '<em class="{2}" unselectable="on">', ' 
      
    '); Ext.Button.buttonTemplate.compile(); [ 140 ]

    Chapter 5 } this.template = Ext.Button.buttonTemplate; } var btn, targs = this.getTemplateArgs(); if (this.isRendered) { btn = this.el; // remove class from transformed btn btn.removeClass('ux-btn-markup'); // remove onclick from DOM and make button event var clickString = btn.getAttribute('onclick'); if (clickString) { btn.dom.onclick = null; // config handler overrides onclick attribute if (!this.handler) { if (Ext.isIE) { eval("this.on('click', " + clickString + ");"); } else { eval("this.on('click', function(){ " + clickString + "});"); } } } // assign config text or markup when not specified if (!this.text) { this.btnEl = btn.child(this.buttonSelector); this.text = this.btnEl.dom.innerHTML; } btn.child('tbody').dom.className = targs[1]; // Menu - assign class if specified if (this.menu && targs[2]) { btn.child(this.arrowSelector).addClass(targs[2]); } } else { if (position) { [ 141 ]

    Ext Themed Buttons, Popups, Calendars, and Reports btn = this.template.insertBefore(position, targs, true); } else { btn = this.template.append(ct, targs, true); } } this.btnEl = this.btnEl || btn.child(this.buttonSelector); this.mon(this.btnEl, { scope: this, focus: this.onFocus, blur: this.onBlur }); this.initButtonEl(btn, this.btnEl); Ext.ButtonToggleMgr.register(this); } });

    While there is quite a lot of code in the listing, we need to focus only on the highlighted code, as everything else has been copied directly from Ext.Button. The isRendered variable is picked up in the onRender function, executing our custom code. Overrides to Ext components should be included in a script immediately after the Ext library, and before application scripts. This ensures the overrides are applied and available to your application scripts.

    Let's not get bogged down in the detail of the onRender function. Basically, we are converting the markup button including the onclick attribute into an Ext.Button, unless the configuration for the new button overrides the markup. Whew—that saved some time explaining the boring bits!

    [ 142 ]

    Chapter 5

    Much more interesting is looking at an example usage shown in previous screenshot, and found in chapter05/ex-5-buttons-transform.html: Ext.onReady(function(){ // Page specific code new Ext.SplitButton({ transformEl: 'P40_APPLY_CHANGES', id:'P40_APPLY_CHANGES', iconCls: 'ux-icon-tick', menu: { // dropdown menu items when the arrow is clicked items: [{ text: 'Item 1', request:'ITEM1', handler: onMenuItemClick }, { text: 'Item 2', request:'ITEM2', handler: onMenuItemClick }] } }); function onMenuItemClick(item){ //apex.submit(item.request); Ext.Msg.alert('Menu Item Click', 'You clicked the "' + item.text + '" item with request "' + item.request + '".'); } }); // Application code Ext.onReady(function(){ // Convert remaining markup buttons to Ext components // assigns id if exists, otherwise Ext will generate var els = Ext.select("table.ux-btn-markup", true); els.each(function(el){ new Ext.Button({transformEl: el, id:el.dom.id}); }); });

    This shows some page-specific code, which is doing the task of transforming the P40_APPLY_CHANGES button, assigning the same ID to the button component, and adding an icon and a menu with a function to process the menu items. [ 143 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    In this example, an icon is added using: iconCls: 'ux-icon-tick',

    Ext assigns the class to the button as part of the transform; you just need to include a CSS rule specifying the background-image attribute for your image: .ux-icon-tick { background-image:url(tick-square.gif) !important; }

    The !important attribute used here raises the specificity of the CSS rule, ensuring that this background is used in preference to the Ext-supplied rule. A menu has also been added to the button using: menu: { // dropdown menu items when the arrow is clicked items: [{ text: 'Item 1', request:'ITEM1', handler: onMenuItemClick }, { text: 'Item 2', request:'ITEM2', handler: onMenuItemClick }] }

    In this case, a separate click-handler function has been assigned to each menu item, so you could call completely different functions for each item. Ext also lets you assign default values for the menu, which are applied to every menu item unless overridden at the menu item level: menu: { // defaults for all menu items, unless overridden defaults: { handler: doSomethingDifferent }, items: [{ text: 'Item 1', request:'ITEM1' }, { text: 'Item 2', request:'ITEM2', handler: onMenuItemClick }] } [ 144 ]

    Chapter 5

    In this code snippet, Item 1 uses the menu's default click handler to doSomethingDifferent, whereas Item 2 uses onMenuItemClick. The onMenuItemClick function is showing an Ext alert, but notice the commented line: function onMenuItemClick(item){ //apex.submit(item.request); Ext.Msg.alert('Menu Item Click', 'You clicked the "' + item.text + '" item with request "' + item.request + '".'); }

    Uncommenting this would pick up the standard APEX page submit code, passing a request matching the menu items request attribute. This is how you would tie your menu items in to your APEX page processing. Finally, at the end of the script is the application code: // Application code Ext.onReady(function(){ // Convert remaining markup buttons to Ext components // assigns id if exists, otherwise Ext will generate var els = Ext.select("table.ux-btn-markup", true); els.each(function(el){ new Ext.Button({transformEl: el, id:el.dom.id}); }); });

    This code would be included in your application JavaScript file and executed after any page specific scripts. The code converts any buttons using the table-based template that haven't already been converted—a set and forget feature. We've spent quite a bit of time looking at buttons. Initially, we saw how to use a HTML and CSS-only approach using Sliding Doors and CSS Sprites to create your own custom buttons. We then covered creating a static version of an Ext button as an APEX template, showing how the button can work without any further changes. And finally, we looked at how to convert the static Ext button into a fully functioning button, opening up a range of possibilities that the Ext.Button API offers. Let's move on to the remaining template types.

    [ 145 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Popup List of Values template

    The Popup List of Values template controls how the popup list of values items are displayed in the APEX application for all items of type POPUP. Unlike other template types, only one popup template is allowed per theme.

    The popup template is more restricted than other templates in how you can modify the layout, but it is still possible to change its appearance to give it an Ext look, and make some minor functional improvements. The previous screenshot shows the popup page in use. The header and footer regions use Ext styling, and use fixed CSS positioning to ensure that both regions are always visible when scrolling large lists.

    [ 146 ]

    Chapter 5

    The template responsible to make this happen is: Before field text:


    Filter text attributes: For pre APEX 4.0, versions only, add the following line: id="search-item"

    In APEX 4.0 this value is automatically included. After field text:


    This wraps a DIV tag around the search field, and assigns an ID to the field, so we can modify the appearance using CSS. Pagination result row X of Y: Row(s) #FIRST_ROW# - #LAST_ROW#

    Before result set:


    After result set:


    Page body attributes: onload="first_field()"

    Page footer text:


    Similarly, wrapping the result set with a DIV tag allows padding to be added using an inline style attribute. A DIV tag for the bottom toolbar is also added, and the Pagination Result Row X of Y has all HTML tags removed, leaving just the text. At this point, all that remains to be done is to add the CSS rules. Because the popup page has only a few elements to style, rather than linking to an external CSS file, you can embed the styles directly in the page header instead.

    [ 147 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Page HTML Head: <style type="text/css"> body {background-color:#FFFFFF;margin:0} * {font: normal 12px tahoma,arial,helvetica,sans-serif;} a:link, a:visited, a:active { font: normal 12px tahoma,arial,helvetica,sans-serif; color: #0464BB; text-decoration:none; } a:hover { color: #1C417C; text-decoration: underline; } .ux-top-toolbar { background-color:#D0DEF0; background:none repeat-x scroll left top transparent; background-image: url("/ux/extjs/resources/images/default/toolbar/ bg.gif"); border-color:#A9BFD3; border-style:solid; display:block; overflow:hidden; padding:2px; width:100%; border-width:0 0 1px; left:0; position:fixed; top:0; } .ux-btm-toolbar { background-color:#D0DEF0; background:none repeat-x scroll left top transparent; background-image: url("/ux/extjs/resources/images/default/toolbar/ bg.gif"); border-color:#A9BFD3; border-style:solid; display:block; overflow:hidden; padding:2px; width:100%; border-width:1px 0 0; top:auto; [ 148 ]

    Chapter 5 left:0; position:fixed; bottom:0; } #search-item { background-color:#FFFFFF; background-image: url("/ux/extjs/resources/images/default/form/textbg.gif"); border:1px solid #B5B8C8; line-height:normal; padding:3px 3px 0; vertical-align:middle; }

    The CSS styles the body search item and link elements, as well as uses fixed positioning to ensure that the top and bottom toolbars remain in position regardless of scrolling. Popup List of Values are fine to use, but we will see better alternatives in later chapters when we look at AJAX-enabled combo boxes.

    Breadcrumb templates

    Breadcrumbs or breadcrumb trails provide a navigation aid to assist in identifying the user's location in a website. Breadcrumbs typically are used as a secondary navigation scheme, and appear horizontally near the top of a page, showing the path taken to reach the current page. Typical breadcrumbs look like this: Home page > Section page > Subsection page

    There are three types of web breadcrumbs: •

    Path breadcrumbs are dynamic, and show the user the exact steps they have taken to arrive at their current location.

    •

    Location breadcrumbs are static, showing where the page is located in the website hierarchy.

    •

    Attribute breadcrumbs give information that categorizes the current page, for example, Electronics > Televisions > Plasma TV.

    APEX supports only location and attribute breadcrumbs, because it uses static hierarchies to define breadcrumbs. [ 149 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Benefits of using breadcrumbs

    Breadcrumbs work well in websites that have a large amount of content organized in a hierarchical manner, such as e-commerce websites, in which a large variety of products are grouped into logical categories. Some of the benefits of using a breadcrumb trail are: •

    Reduced clicks to return to higher-level pages: APEX-generated pages often use a Cancel or Back button to return to an earlier page. Using breadcrumbs, users can return to a higher-level page with a single click instead of navigating back through the pages, saving multiple page loads.

    •

    Consumption of minimal screen real estate: Typically, breadcrumbs are horizontally oriented and use plain styling, consuming minimal screen space and minimal overhead to page content.

    •

    Alternative uses: Breadcrumbs can be used for specific page groups, such as wizards or guided tours. The following screenshot shows how Flickr uses a breadcrumb trail, indicating the number of sections in the Flickr tour:

    When not to use breadcrumbs Breadcrumb trails have a linear structure, so using them will be difficult if your pages can't be classified into neat categories. Deciding whether to use breadcrumbs largely depends on how you've designed your website hierarchy. If you can navigate to a lower-level page from more than one location or category, breadcrumb trails are ineffective, inaccurate, and confusing to the user.

    Basic horizontal breadcrumb template

    The breadcrumb template shown in the next screenshot uses a simple unordered list and some CSS to define a horizontal breadcrumb trail:

    [ 150 ]

    Chapter 5

    The source for the breadcrumb template is: Start with: Parent to Leaf Before first:

    Maximum Levels: 12 The template is just the minimal markup required to define an unordered list, with non-current pages containing a link element with a title attribute. The list is wrapped by a DIV element with a class attribute. So, the only thing controlling the horizontal layout of the list is the CSS: .breadcrumb { color: grey; display:block; left:0; overflow:hidden; padding:2px; position:relative; top:0; } .breadcrumb li { float: left; display: inline; margin-right: 4px; } .breadcrumb a { color: #222; background: url(/i/r_arrow.gif) no-repeat scroll right center; padding-right: 12px; text-decoration: none; } [ 151 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Using display: inline changes the list from a vertical to a horizontal list. Everything else is visual styling. Breadcrumbs are usually contained in a Region template of type "Breadcrumb Region". As the template defined here is self contained, the region template is just a wrapper: Template Class: Breadcrumb Region Template:
    #BODY#


    Breadcrumbs are simple to implement and effective to use; let's move onto something a little more challenging in Report templates.

    Report templates APEX has two report types, the "Classic Report" and the "Interactive Report". Classic reports have been in APEX since its inception, and are the formatted result of the SELECT statement of SQL language. The report templates used to control the layout of a classic report can either be "Generic Column" or "Named Column" templates. The main difference being that Generic Column templates render every column using the same column sub-template, whereas Named Column templates allow you to render each column differently, but need to define each column in the template. The overwhelming majority of APEX applications will predominantly use Generic Column templates, reserving Named Column templates for very specific report layouts. We will be looking only at the Generic Column Report template in this chapter, as this will give you the maximum benefit in creating your initial Ext JS theme. Interactive Reports were first introduced in APEX 3.1, providing the user with the ability to customize the appearance of the data through a searching, filtering, sorting, column selection, highlighting, and other data manipulations. They were the "killer feature" of the APEX 3.1 release, causing both developers and application users to clamor at managers doors demanding to "Upgrade immediately!". In APEX 4.0, a whole series of new features have been added to Interactive Reports, including icon and detail views, the ability to have multiple "saved reports", e-mailing reports, and more. While all this makes Interactive Reports even more compelling to use, they don't have templates, so we won't be covering them here. Another limitation of Interactive Reports is that you are limited to one Interactive Report per page, leaving a huge hole to be filled by Classic reports. [ 152 ]

    Chapter 5

    It's a classic The Ext Grid is one of the most advanced and widely used components of Ext JS. You can use it to simply display and paginate tabular data using AJAX, edit data inline, drag–and-drop columns, hide and show columns, have expanding and collapsing rows, and so on. In this template we are going to "fake it", using the built-in functionality of an APEX Classic report and combining it with some CSS, so it looks like a read-only Ext Grid with AJAX paging. The following screenshot shows what our report template looks like, sitting inside a collapsible Report Region template. Notice how some of the elements we have already covered are all coming together—the report is sitting very nicely within a collapsible panel, looking very integrated with the panel. The buttons for the pagination and the CSV download use CSS sprite techniques we also covered earlier in this chapter.

    Create a new report template, populating the fields shown here. Report Template Name: EXTJS Standard Template Class: Standard Before rows:
    [ 153 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Before column heading:

    Column heading template:

    When using a version prior to APEX 4.0, leave out the #COLUMN_WIDTH# attribute. After column heading:

    Before each row:

    Column template 1:

    Column template 1 condition: Use for odd numbered rows Column template 2:

    Column template 2 condition: Use for even numbered rows After each row:

    After rows:
    #COLUMN_HEADER#
    #COLUMN_VALUE# #COLUMN_VALUE#
    [ 154 ]

    Chapter 5
    #PAGINATION#
    <span class="xtb-sep"> #CSV_LINK# #EXTERNAL_LINK#


    Background color for checked row: #cfe0f1

    Background color for current row: #efefef

    Pagination template: Displaying #TEXT#

    Next page template: <span>

    class="x-

    Previous page template: <span>

    [ 155 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Next set template: <span>

    class="ux-

    Previous set template: <span>

    Looking at the earlier fields for the template, you can see we are using a very standard table layout, integrating the relevant APEX substitution tags as we go. It's really all quite ordinary in fact! If you are using APEX versions earlier than APEX 4.0 for the Column Heading Template, the #COLUMN_WIDTH# substitution tag is not available. You can fix column widths without it anyway, using CSS rules picking up the table ID and column ID. So for this template, if the region used a static region name of customer and the column name was first_name you could set the column width using a CSS rule in the page header: #report-customer #first_name {width: 80px}

    The After Rows field looks quite complicated, but that's only because APEX insists on creating the #PAGINATION# sub-template as a table row, using table cells with a "pagination" class attribute. To get this to fit into the Ext toolbar markup and right align the #CSV_LINK# on the same line, some fancy footwork has been done, introducing some additional embedded tables as a means to achieving a result. For the Pagination components, starting at After Rows all the way down to Previous Set Template, two techniques have been repeatedly used to create the pagination icons and the CSV download icon.

    [ 156 ]

    Chapter 5

    For the button outline, the CSS sprite technique discussed at the beginning of the chapter has been reused, this time with a fixed width image, as all the icons used are of a known size. Once again the "hover" and "active" appearance for the buttons have been achieved using the CSS background-image and background-position properties to display the desired image segment. The following diagram shows the image used for the button outline:

    The icons for the "next" and "previous" indicators and CSV download use a transparent image with a fixed size of 16x16 pixels, and a class specifying the CSS background-image attribute for the icon. For example, the "next" page indicator uses the following markup for the image:

    class="x-tbar-

    The x-tbar-page-prev class attribute picks up the Ext CSS rule for the icon: .x-tbar-page-prev{ background-image: url(../images/default/grid/page-prev.gif) !important; }

    It is worth remembering that by using the background-image attribute instead of directly assigning the image source, you can easily update the image by modifying the CSS file once, rather than in every place you reference the image source.

    [ 157 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    A better sorting indicator For the column-sorting indicator, APEX gives you some predefined choices, and if you don't like those choices it can be difficult to reference another image. The reason behind it being difficult is that APEX prefixes whatever image name you specify in the Ascending Image and Descending Image fields in the Sorting section of the Report Attributes for a Report Region with /i/, and not the #IMAGE_PREFIX# substitution tag as you would expect. Fortunately, among the standard images supplied with APEX in that folder is a one-pixel transparent image, allowing you to use the CSS background-image technique to use the transparent image once again, and specify a class to pick up the image you want to use. The following screenshot shows how to assign the image and classes:

    The CSS for the sorting indicator is: .ux-sort-asc { background-image:url(/ux/extjs/resources/images/default/grid/sort_ asc.gif); background-repeat:no-repeat; display:inline; height:4px; margin-left:3px; vertical-align:middle; width:13px; } .ux-sort-desc { background-image:url(/ux/extjs/resources/images/default/grid/sort_ desc.gif); [ 158 ]

    Chapter 5 background-repeat:no-repeat; display:inline; height:4px; margin-left:3px; vertical-align:middle; width:13px; }

    CSS for the standard report There is quite a lot of CSS behind this report template, so rather than showing it all here, I will just refer you to the CSS file located in chapter5/playpen-book.css. Look for the section under "Reports".

    Calendar templates Calendar templates are unusual because they contain multiple layouts within a single template. Within a Calendar template, there are separate templates for monthly, weekly, and daily calendars, and in APEX 4.0 there is an additional custom calendar template. The calendar we will be creating is shown in the following screenshot. It scales to the width of the enclosing region, and scales vertically based on the content of the calendar items. To restrict the size of the calendar, set the enclosing regions width in the Region Attributes field for the region.

    [ 159 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Create a new Calendar template, name it EXTJS Calendar, and populate the fields for the Monthly Calendar: Month formats: Month title format
    <em style="border-leftwidth:0">#IMONTH# #YYYY#


    Day of week format <span>#IDY#

    Month open format

    Month close format


    Week formats: Week open format

    Week close format

    Weekday formats: Day title format
    #DD#


    Day open format

    Day close format

    Today open format [ 160 ]

    Chapter 5

    Non-day formats: Non-day title format
    #DD#


    Non-day open format

    Non-day close format

    Weekend formats: Weekend title format
    #DD#


    Weekend open format

    Weekend close format

    The weekly and daily calendars are very similar; the main differences to note is the enclosing DIV element has an additional class attribute—ux-calendar-weekly or ux-calendar-daily. The weekly template is: Month title format
    <em style="border-left-width:0">#WTITLE#


    Day of week format <span>#IDY#
    #MM#/#DD#

    Month open format

    Month close format
    [ 161 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Hour formats Hour open format

    Hour close format

    Weekday formats: Day open format

    Day close format

    Today open format

    Time formats: Time title format #TIME#

    Time open format

    Time close format

    Weekend formats: Weekend open format

    Weekend close format

    [ 162 ]

    Chapter 5

    And the Daily Calendar template is: Month formats: Month title format
    <em style="border-left-width:0">#IMONTH# #DD#, #YYYY#


    Day of week format
    #IDAY# #DD#/#MM#


    Month open format

    Month close format


    Hour formats: Hour open format

    Hour close format

    Weekday formats: Day open format

    Day close format

    Today open format

    [ 163 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Time formats: Time title format #TIME#

    Time open format

    Time close format

    So finally, after three whole chapters, we have created each type of template, and now have a "minimal" theme. Hooray!! Let's clean up and publish our theme.

    Removing unused templates quickly Now is the time to go through your templates deciding, which ones to keep and which ones aren't needed for the time being. We will temporarily remove all those we don't need before we publish our APEX theme. Throughout the book, all the templates have been created using EXTJS as a prefix, making it easy to identify which ones to keep; hopefully you've done something similar. In Chapter 1, Setting up an Oracle APEX and Ext JS Environment, two APEX utilities included in the source were mentioned—the APEXExport and APEXExportSplitter Java classes located in the Oracle APEX distribution in utilities/oracle/apex directory. At the time we set up a batch script to run the APEXExport utility. We are now going to make use of the APEXExportSplitter. First, export your theme from Application Builder | Export, as shown in the following screenshot:

    [ 164 ]

    Chapter 5

    Save the file onto your computer and copy it to a second file, which I'll name theme.sql here. From the command prompt, you then need to set your Java CLASSPATH and run the APEXExportSplitter. I'm doing it here from a DOS prompt; Unix users will need to adjust accordingly. If you're using database 11g, set the CLASSPATH to ojdbc6.jar. set CLASSPATH=%CLASSPATH%;<path>\ojdbc6.jar

    For database 10g, set the CLASSPATH to classes12.jar. set CLASSPATH=%CLASSPATH%;<path>\classes12.jar

    Also, set the CLASSPATH to include the utilities directory containing the APEXExportSplitter. set CLASSPATH=%CLASSPATH%;<path>\utilities

    Now you can run the splitter. In case of my local environment: set CLASSPATH=%CLASSPATH%;C:\playpen\oracle\instantclient_10_2\ classes12.jar set CLASSPATH=%CLASSPATH%;C:\playpen\oracle\utilities java oracle.apex.APEXExportSplitter theme.sql

    This splits the file into the individual components in subfolders, as shown in the following screenshot:

    [ 165 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    Locate the install.sql file in the top folder and edit it, commenting out all the unwanted templates. I've modified the text replacing shared_components/user_ interface/templates with … in following code for layout purposes. You simply need to comment out the lines containing unwanted templates.

    Now, if you run the install.sql script from a SQL*Plus session as the database user for your APEX workspace, the theme will be deleted and recreated with just the uncommented components. If you missed a file or two, you can edit and rerun this script as often as you like.

    Publishing your theme You are now in a position to publish your "minimal" theme. At this point you have at least one template for each of the template types (breadcrumb, button, calendar, label, list, page, popup list of values, region, and report), but lack templates for every template class within each template type. Publishing a theme takes a copy of your theme and stores it in the theme repository for the workspace. The published theme cannot be edited directly; to modify it you need to create an application with the theme, modify it, and then publish it to the theme repository. Having a TEMPLATE application, where you keep the current version of your theme within your workspace, is a really good idea. Apart from having the latest copy on hand, it also lends weight to the argument if you have a policy of no changes to be made to templates within an application without thorough testing. By ensuring that template changes are made in your TEMPLATE application, you can have all your use cases and developer usage documentation in a tidy little bundle—also useful when bringing in new people to your team. [ 166 ]

    Chapter 5

    The actual process of publishing a theme is very simple. From within Application Builder, navigate to Shared Components | Themes | Manage Workspace Themes. From there, you step through a simple wizard to publish your theme. The following screenshot shows the most complicated step—coming up with a name for your theme!

    APEX Instance Administrators can publish your theme as a public theme. Public themes are available to all workspaces. Generally, it's advisable to have templates for each of the template types, as well as each of the classes within each type, before making a theme public.

    Summary In this chapter, we had a good long look at buttons, creating a custom markup button using the sliding doors method to provide horizontal scalability, and creating multiple states by applying different background images contained in a sprite image. We then integrated the "horrible" Ext button, starting out using static markup, showing how the button can work without any further changes. After that we converted the static Ext button into a fully functioning button, opening up a range of possibilities that the Ext.Button API offers, including transforming it to include drop-down menus and icons. Popup list of values and breadcrumbs were covered next, tweaking the template types to create the Ext look, with some simple changes.

    [ 167 ]

    Ext Themed Buttons, Popups, Calendars, and Reports

    The Classic report template was then given a makeover, "faking it" so it looks and behaves like a basic Ext Grid, using the built-in APEX functionality. The report template demonstrated how some of the earlier templates and techniques covered are all coming together, with the report working very nicely within a collapsible panel. The Calendar template was covered next, once again adding some visual polish to an already functional APEX component. You saw how to delete all the unwanted templates quickly from the APEX theme using the APEXExportSplitter Java class, and discussed the process of publishing the theme. Also pointed out are the benefits of maintaining a TEMPLATE application, providing a place to modify your theme templates, and also have all your use cases and developer usage documentation in a tidy little bundle. Now have our working theme up and running. The next chapter starts introducing some Ext widgets into our application.

    [ 168 ]

    Adding Ext Layout Elements In consulting circles the term "low-hanging fruit" is often used to describe quick-win solutions, where a minor change significantly improves some aspect of an application with a broad impact across the entire application. Consultants and developers in general love "low-hanging fruit" solutions because they are easy to reach, and help keep the forward momentum of a project going. With estimating task complexity and duration in software development not being an exact science, some activities take far longer than originally estimated while others come in well under time. Having a few "low-hanging fruit" solutions available means you can smooth out some of the overruns and buy some time by reporting "feature X was held back this release because we implemented feature Y across the entire application". Having said that, the term evokes visual imagery of fruit-laden trees and ironically in orchards, picking the low-hanging fruit first is the worst thing to do. Experienced pickers start at the top of the tree where the fruit is ripest. Starting at the top makes the job easier, as you rest the bag, which is around your neck and shoulders on the ladder. You fill as you go down, so the bag is full when you get to the bottom. In this chapter, we will cover the following "low-hanging fruit": •

    Converting APEX Classic dates to the Ext.DatePicker

    •

    Making all text areas resizable, or better still, auto-sizing

    •

    Transforming select lists to auto-completing combo boxes

    •

    Building tab panels using subregions

    •

    Building toolbars and menus

    Adding Ext Layout Elements

    Speed dating with a Date Picker In versions prior to APEX 4.0, the Date Picker component displays a text field with a calendar icon next to it. When clicked, the icon displays a small calendar in a pop-up window as a separate page request. Selecting a date passes back the value to the text field, and closes the pop-up window. This date picker still exists in APEX 4.0, as the Date Picker (Classic), shown on the left of the following screenshot:

    The Ext alternative to this classic date picker is the Ext.DatePicker, a highly configurable component, which dynamically constructs a calendar within the page when the icon is clicked. It also allows you to rapidly scroll through months and years using keyboard shortcuts; it also features auto-complete functionality, allowing you to type partial dates or use alternative date formats, which are automatically converted when you tab out of the field. In APEX 4.0, the Date Picker item type uses the jQuery UI Datepicker as the replacement for the Date Picker (Classic). It offers similar functionality to the Ext. DatePicker component, rendering a calendar dynamically within the page and uses keyboard shortcuts to rapidly scroll through months and years. It comes with the added advantage that as a native APEX item, it has a number of settings that can be applied declaratively by the developer, as can be seen in the following screenshot:

    [ 170 ]

    Chapter 6

    Applications upgrading to APEX 4.0 can easily upgrade Date Picker (Classic) items to the new Date Picker using the Application Builder | Utilities | Upgrade Application | "Upgrade Date Picker (Classic) to new Date Picker" interface. For APEX versions prior to APEX 4.0, the Ext.DatePicker makes very good sense to use in preference to the Date Picker (Classic), whereas in APEX 4.0, the new Date Picker offers similar functionality with better declarative support. So, if you're currently using a version prior to APEX 4.0, converting to the Ext. DatePicker is very worthwhile. The conversion approach simply adds a little generic JavaScript to the application, resulting in minimal effort to add, and minimal effort to remove. When you eventually upgrade to APEX 4.0, you can decide whether or not to switch to the new APEX Date Picker. For new applications in APEX 4.0, unless you're hell-bent on using the Ext. DatePicker and write an APEX plugin to give you similar declarative functionality, the APEX Date Picker is the way to go. If you like the look of the date item, you can duplicate it using CSS anyway, as I've done in the previous screenshot and in the included playpen-book.css file.

    Converting Classic Dates to the Ext. DatePicker The technique described will convert all Classic Dates to use the Ext.DatePicker, so we are making the assumption that you use the same date format for all your dates in your application. Usually this is done by setting the Application Date Format, found in Application Builder under Shared Components | Globalization Attributes. [ 171 ]

    Adding Ext Layout Elements

    For most applications, this is a reasonable assumption, but if you're using multiple date formats, you can alter the code to include or exclude items with a specific class only, which you assign to individual date items in the HTML form element attributes. Classic Dates are rendered in a HTML table like this:
    Calendar


    The key points to note here is that the date is rendered in a table with class="datepicker", and the input item holding the date is in the first TD element, and the icon is in the second TD element. To use the Ext.DatePicker, you would include the following code in your application JavaScript file: Ext.onReady(function(){ var els = Ext.select("table.datepicker", true); els.each(function(el){ // remove the datepicker class, to remove any styling el.removeClass('datepicker'); Ext.fly(el).child('.datepicker').removeClass('datepicker');

    [ 172 ]

    Chapter 6 // remove the icon's table cell el.select('td:even').remove(); // retrieve the date item as a dom node var dt = Ext.fly(el).child('input[type=text]', true); // convert to date new Ext.form.DateField({ id: dt.id, applyTo: dt, "format": 'd-M-Y', "altFormats": 'j|j/n|j/n/y|j/n/Y|j-M|j-M-y|j-M-Y' }); }) });

    The code starts out by parsing the DOM, retrieving any tables with the class="datepicker" attribute, and saving the results in an array els. Each table is then processed in a loop: var els = Ext.select("table.datepicker", true); els.each(function(el){ // process each datepicker... })

    Within the loop, each datepicker table is modified, removing the datepicker class from the table and any child elements: // remove the datepicker class, to remove any styling el.removeClass('datepicker'); Ext.fly(el).child('.datepicker').removeClass('datepicker'); // remove the icon's table cell el.select('td:even').remove();

    Then the input item is selected and converted to an Ext.DatePicker; the item name and values are retained as part of the conversion: // retrieve the date item as a dom node var dt = Ext.fly(el).child('input[type=text]', true); // convert to date new Ext.form.DateField({ id: dt.id, applyTo: dt, "format": 'd-M-Y', "altFormats": 'j|j/n|j/n/y|j/n/Y|j-M|j-M-y|j-M-Y' }); [ 173 ]

    Adding Ext Layout Elements

    The database date format I'm using is DD-Mon-YYYY, which corresponds to the Ext date format d-M-Y. For a complete list of format masks available, consult the Ext documentation at http://www.extjs.com/deploy/dev/docs/?class=Date. The "altFormats" attribute shown in the preceding code snippet includes a number of alternative formats, which can be used for data entry. So, for example, typing 1 and then tabbing out of the date would automatically be converted to the first day of the current month and year. Similarly, typing 1/3 would convert to the first of March for the current year. If you prefer the format DD-MON-YYYY for your dates, it's not available using the date formats listed for Ext, but can be done by overriding the default Ext date names with the following line of JavaScript at the beginning of your application JavaScript file: Date.monthNames =["JANUARY","FEBRUARY","MARCH","APRIL","MAY", "JUNE","JULY","AUGUST","SEPTEMBER","OCTOBER","NOVEMBER", "DECEMBER"];

    This is the Ext way of internationalizing dates, so it's fully supported, and forces the JavaScript date format "d-M-Y" to return the month in uppercase. So there you have it, a simple "drop in" solution that you can incorporate into existing pre-APEX 4.0 applications and give them enhanced functionality. The more interesting question is once you have moved to APEX 4.0, are you going to keep the Ext DatePicker, or switch to the APEX jQuery version?

    Resizable text areas In APEX 4.0, text areas have a resizable option, when enabled allowing users to resize text areas, so they can see all the text. I'm sure you're already too familiar with how frustrating it is using the APEX Builder when you're trying to edit code in a text area much smaller than your code. As developers, we normally have local administration rights on our computers, so it's very easy to overcome this issue by using a browser add-on, such as the Firefox "Text Area Resizer and Mover", available at https://addons.mozilla.org/en-US/ firefox/addon/8287. Our corporate users aren't usually so lucky, with lockeddown computers, so they can't alter their set up. The following screenshot shows the Ext version of the resizable text area compared with the APEX 4.0 resizable text area—quite similar visually, and provides similar functionality.

    [ 174 ]

    Chapter 6

    The Google browser has similar functionality built into the browser, making all text areas resizable. I believe this is a very sensible approach; after all, why should only some text areas be resizable? To convert your text areas, just include the following code in your application JavaScript: Ext.onReady(function() { var els=Ext.select("textarea",true); els.each(function(el){ new Ext.Resizable(el, { wrap:true, pinned:true, handles: 's', width:el.getWidth(), height:el.getHeight(), minWidth:el.getWidth(), minHeight: el.getHeight() }); }) });

    The script finds all text area elements on the page, and then applies the Ext. Resizable class to the element. This applies drag handles to the element to make it

    resizable, the original text area remains unchanged—very handy if you have enabled the character counter on a text area! As usual, Ext provides a number of configuration options, allowing you to set which handles to include, either 'all' or any of 'n s e w ne nw se sw', whether the handles "pinned" to ensure they are always visible, or only visible when the user mouses over the resizable borders, or transparent so the handles don't appear at all.

    [ 175 ]

    Adding Ext Layout Elements

    The Ext.Resizable class can be used on more than just text areas; resizable images are very effective also. In the examples provided with the Ext JS SDK library, the examples/resizable/basic.html file demonstrates the full range of options available, including options such as animated transitions, preserved ratios, and snapping.

    Auto-sizing text areas Having implemented resizable text areas over three years ago in some APEX applications, my application users take this feature very much for granted. So much so, that they started to complain about having to resize the text area every time they visited a page to see the full content. If like my users, you spend your entire day in an application racking up over 2000 page hits individually, you can understand how something little like this really starts to be too much effort for a minor detail. Having scoured the Internet looking for a solution at the time, it appears Facebook was the first website to introduce an auto-growing text area that gets bigger as you type into it. After spending some time looking at some of the different solutions available, I cobbled together a solution for Ext using techniques borrowed from other people's great ideas. Now you don't have to, it's a configuration option in the Ext.form.TextArea To make all your text areas automatically grow, add the following code to your application JavaScript: Ext.onReady(function() { var els=Ext.select("textarea",true); els.each(function(el){ new Ext.form.TextArea({ applyTo: el, grow: true, width: el.getWidth() }); }) });

    Setting the width configuration option retains the original width of the text area.

    [ 176 ]

    Chapter 6

    To limit the size of your text areas, Ext.form.TextArea includes configuration options growMax to set maximum height to allow when grow=true (defaults to 1000), and growMin to set the minimum height to allow when grow=true (defaults to 60). No more messing about with grab handles to resize your text boxes; they are always sized to the content. Now my users are happy, for a little while.

    Auto-completing text fields

    The Ext.Combo provides an alternative to the text field with auto-complete item type, which was introduced in APEX 4.0. The text field with auto complete item type shows a list of possible values when the user starts typing in the field, progressively filtering the data as more keys are typed. The following screenshot shows an example of the text field with auto-complete item type displaying a list of countries, with the field on the right showing that the additional character has further reduced the list of matching values.

    The values are based on the defined List of Values (LOV) SQL statement returning a single column, for example: SELECT country_name FROM countries ORDER BY country_name

    As the text field with auto-complete item type does not prevent additional values not already in the LOV SQL statement being entered, it is your responsibility as the developer to determine how existing and new values are processed. Assume we are processing a purchase order (PO) record in the PURCHASE_ORDERS table, and currently looking up the country names from the COUNTRIES table using the earlier query. [ 177 ]

    Adding Ext Layout Elements

    Consider the following options for the country field from the preceding screenshot when the page is submitted to the APEX engine for processing: Use Case

    Action

    Existing value entered, country stored

    Verify existing country. Process PO record.

    Existing value entered, country ID stored

    Fetch country ID using country name. Process PO record.

    New value entered, country stored

    Verify existing country => NOT FOUND.

    New values for country are allowed

    Add country to COUNTRIES table. Process PO record.

    New value entered, country ID stored New values for country are allowed

    Fetch country ID using country name => NOT FOUND. Add country to COUNTRIES table, returning country ID. Process PO record.

    Change LOV SQL to query PO table

    Process PO record.

    New value entered, country stored New values for country are allowed

    Looking at the Use Cases, it becomes evident that most of the time you need to do additional validation and processing for the text field with auto complete item type. If it is used as a free-text field, which accepts any input, including new values not already in the LOV SQL statement, then this is an appropriate choice. For most applications, this is a less common scenario, much more typically you want to limit allowable values for an item to a pre-determined set, only allowing additional values to be added through administration forms by privileged users, if at all. For this typical lookup scenario, the humble select list is appropriate for relatively short lists of values, and the Popup LOV item type for longer lists. In fact, for the internal APEX applications, which make up the APEX Application Builder, the select list is by far the most commonly used input item, being used for roughly 25% of all input items.

    [ 178 ]

    Chapter 6

    Select Lists have a display value and a returned value for each option. Continuing our purchase order example for the country field, the values could be based on the defined LOV SQL statement: SELECT country_name d ,id r FROM countries ORDER BY country_name

    The APEX engine would generate HTML markup for the select list as: <select size="1" id="P70_SELECT_LIST" name="p_t08">

    The results in a user-friendly country description displayed to the user, and the ID value returned when the page is submitted. Looking at the highlighted code, the displayed value is Yemen and the returned value is 117. The Action for our earlier Use Cases when the APEX engine processes the page is simply "Process PO record", because we have the value we wish to store. Select lists are very useful for limiting inputs to a set of allowable values, but don't have auto-complete functionality. This is where the Ext.form.ComboBox comes into play.

    Adding auto-complete to select lists The Ext.form.ComboBox can be used as a direct replacement for the HTML select list. It provides the same drop-down list of values, as well as auto-completing filtering functionality, enabling users to find and select a value quickly.

    [ 179 ]

    Adding Ext Layout Elements

    The following screenshot shows a select list with a large set of values, and a combo box showing the same set of values filtered on the first 3 characters using the auto-complete functionality.

    To convert select lists without an onchange attribute to combo boxes is very simple: Ext.onReady(function() { var els=Ext.select("select[multiple!='multiple']",true); els.each(function(el){ new Ext.form.ComboBox({ id: 'cb-'+el.id, hiddenId: el.id, disabled: el.dom.disabled, typeAhead: true, triggerAction: 'all', transform:el, width:el.getWidth(), forceSelection:true }); }) });

    [ 180 ]

    Chapter 6

    Once again we are using the Ext.select function to retrieve all single-line select lists. All of the work to convert each select list into a combo box is done using the highlighted transform configuration option to identify the select list. The other configuration options define the behavior we want for the combo box. However, we have only solved part of the problem! The APEX 4.0 Application Builder has five different page actions when a select list item type is changed, as shown in the following screenshot:

    Apart from the "None (Default)" option, each of the options adds an onchange attribute to the HTML markup for the select list. For example, the APEX engine would generate HTML markup for the Submit page select list as: <select class="selectlist" onchange="apex.submit('P90_SL_SUBMIT');" size="1" id="P90_SL_SUBMIT" name="p_t05">

    [ 181 ]

    Adding Ext Layout Elements

    The following table shows an example of the onchange HTML markup for each option: Option

    onchange

    None (Default) Submit Page

    apex.submit('P90_SL_SUBMIT');

    Redirect and Set Value

    location.href='f?p=103:90:2624308855119166::NO:: P90_SL_REDIRECT:'+ this.options[selectedIndex].value;

    Redirect to Page (based on selected value)

    location.href='f?p=103:'+this.options[selectedIndex].value+

    Redirect to URL (based on selected value)

    location.href=this.options[selectedIndex].value;

    ':2624308855119166::NO';

    The auto-sizing text area we modified previously simply adds JavaScript events to the existing DOM element, so existing onchange attributes and existing JavaScript events are retained. When the select list is transformed to a Ext.form.ComboBox, the JavaScript code creates new DOM elements to make up the Ext.form.ComboBox, and then deletes the select list DOM element together with its onchange attributes. To convert select lists including logic from onchange attributes to combo boxes: Ext.onReady(function() { var els=Ext.select("select[multiple!='multiple']",true); els.each(function(el){ // save attribute as a string var attr = el.dom.getAttribute('onchange'); if (attr && attr.indexOf('this.options[selectedIndex].value') !=  -1 ) { // replace Select List logic with ComboBox equivalent attr = attr.replace('this.options[selectedIndex].value',  'this.getValue()'); } // transform Select List to ComboBox var cb = new Ext.form.ComboBox({ id: 'cb-'+el.id, hiddenId: el.id, disabled: el.dom.disabled, typeAhead: true, triggerAction: 'all', transform:el, [ 182 ]

    Chapter 6 width:el.getWidth(), forceSelection:true }); // add on select event if (attr) { eval( "cb.on('select', function(){ " + attr + "});" ); } }) });

    Looking at the highlighted code, we first save the value of the onchange attribute into a variable and then replace any instance of the string 'this. options[selectedIndex].value' with 'this.getValue()': if (attr && attr.indexOf('this.options[selectedIndex].value') != -1 ) { // replace Select List logic with ComboBox equivalent attr = attr.replace('this.options[selectedIndex].value', 'this.getValue()'); }

    Replacing the string changes the logic to fetch the selected value within the select list with its Ext equivalent to fetch the selected value for the combo box. Once we transform the select list into a combo box, we then conditionally add a listener that executes a function when the 'select' event is fired: // add on select listener if (attr) { eval( "cb.on('select', function(){ " + attr + "});" ); }

    The listener is added using the JavaScript eval command, which evaluates the concatenated string and executes the statement. For example, from the earlier table for the redirect to URL option, the onchange attribute value was originally location.href=this.options[selectedIndex]. value;, which was modified to the string location.href=this.getValue();. The string was then concatenated into the statement cb.on('select', function() {location.href=this.getValue();});, which was finally executed to add a select

    listener to the combo box.

    Hopefully, I haven't lost you in all the detail. We now are able to transform select lists, including those with onchange attributes, into combo boxes. Are we done yet? [ 183 ]

    Adding Ext Layout Elements

    No, we're still not done! There's one more thing to take into account. For pre-APEX 4.0 versions, we have covered all the out-of-the-box scenarios, so unless you have written custom JavaScript, you are reasonably safe. However, APEX 4.0 introduced new functionality, such as cascading select lists and dynamic actions, resulting in far more JavaScript based interaction between different elements on the page. Consequently, there will be some circumstances where you don't want to convert specific select lists. A simple way to manage this is by adding a class to the select list, and coding to not transform select lists with this class. In the following screenshot, the class attribute has been added with the noTransform class, along with another class in the HTML form element attributes field for a select list page item within the APEX Application Builder.

    Finally, a check is added to the code to skip select lists with the noTransform class: Ext.onReady(function() { var els=Ext.select("select[multiple!='multiple']",true); els.each(function(el){ if (!el.hasClass('noTransform')) { // save attribute as a string var attr = el.dom.getAttribute('onchange'); if (attr && attr.indexOf('this.options[selectedIndex].value') != -1 ) { // replace Select List logic with ComboBox equivalent [ 184 ]

    Chapter 6 attr = attr.replace('this.options[selectedIndex].value', 'this.getValue()'); } // transform Select List to ComboBox var cb = new Ext.form.ComboBox({ id: 'cb-'+el.id, hiddenId: el.id, disabled: el.dom.disabled, typeAhead: true, triggerAction: 'all', transform:el, width:el.getWidth(), forceSelection:true }); // add on select event if (attr) { eval( "cb.on('select', function(){ " + attr + "});" ); } } }) });

    So at last, we now have a complete solution, which can be dropped into your Application JavaScript.

    Building tab panels using subregions

    APEX 4.0 introduced subregions, allowing regions to be nested within other regions in a parent-child relationship. This provides display opportunities, such as breaking up large forms into a series of separate sections while still maintaining visual coherence.

    [ 185 ]

    Adding Ext Layout Elements

    Support for subregions was also included in region templates. Adding sections for subregion header templates, together with subregion header entry templates, provide the possibility to generate a list of region titles of all the subregions of the current region. Mix in a little JavaScript with your subregion templates, and building tab panels like the one shown in the following screenshot becomes very easy:

    Creating Ext.TabPanels from existing HTML markup can be done using: •

    Pre-structured markup: A container DIV with one or more nested tab DIVs with class 'x-tab'. Setting the Ext.TabPanel configuration option of autoTabs to true will automatically query and convert the nested DIVs.

    •

    Un-structured markup: A tab panel can be rendered from markup that is not strictly structured by specifying by ID the elements making up the container and the tabs. Using this method, tab content can be pulled from different elements within the page by ID regardless of the page structure.

    We will be using the un-structured markup approach, mainly because the IDs for each of the tab panels are known. Specifying the IDs directly instead of querying the DOM to find DIVs with the class 'x-tab' has a slight performance advantage when the browsers JavaScript engine is manipulating the page.

    [ 186 ]

    Chapter 6

    Using the un-structured markup approach, the JavaScript shown: Ext.onReady(function(){ new Ext.TabPanel({ renderTo: 'my-tabs', activeTab: 0, items:[ {contentEl:'tab1', title:'Tab 1'}, {contentEl:'tab2', title:'Tab 2'} ] }); });

    would convert this markup into a tab panel:
    A simple tab
    Another one


    Adding the class "x-hide-display" to each of the DIVs stops them from being displayed outside the tabs, and reduces your page content from jumping around when it's being rendered and then manipulated by the page JavaScript. Ext uses this same class to hide or show the tab panels.

    Building the tab panel template

    The easiest approach to building the template is to start by constructing a page with some nested subregions, and building a solution from there. This way, you can check your progress as you go. Start off by creating a simple page with several regions, with one for the tab panel; assign the others as subregions of the tab panel. Assigning a region as a subregion is done in Application Builder by setting the parent region attribute, as shown in the following screenshot:

    You don't need to assign a template to the subregions for this solution. If you do, it will change the appearance for the content of the individual tab, but not the tab panel itself. [ 187 ]

    Adding Ext Layout Elements

    The following screenshot shows the Application Builder view of the tab panel example shown earlier:

    Within the Maintain User Details region are some region buttons and a tab panel region as a subregion. The tab panel region in turn contains five subregions and some items within those regions. No items are included in the tab panel, as the template we are creating is designed simply to be a container for the panels within. Next, create a new region template with the following properties: Name: EXTJS TabPanel

    [ 188 ]

    Chapter 6

    Template class: Custom 1

    Template:
    #SUB_REGIONS# #SUB_REGION_HEADERS#

    For the subregion elements: Header template: <pre> Ext.onReady(function(){ var subs = []; #ENTRIES# new Ext.TabPanel({ renderTo: '#REGION_STATIC_ID#', activeTab: 0, items:subs }); });

    Header entry template: subs.push({ contentEl:'#SUB_REGION_ID#-tab', title:'#SUB_REGION_TITLE#' });

    Subregion template:
    #SUB_REGION#


    Rather than my explaining the code we have just added to the template immediately, you should assign the template to the tab panel region in the test form you created earlier. Then run the page to view the output. Did it look like what you expected?

    [ 189 ]

    Adding Ext Layout Elements

    The output for the example used throughout this section is shown in the following screenshot. It shows the contents of the Maintain User Details panel and its buttons, but instead of a tab panel, there is just some JavaScript code. No sign of the fields from the first tab panel subregion at all.

    Replacing script tags with pre tags around the JavaScript components in the template allows us to view the generated content.

    Now for some explanation, working our way from the bottom of the template up: Subregion template:
    #SUB_REGION#


    Here we are wrapping the subregions with additional HTML code. In this case, a DIV tag encloses the #SUB_REGION# substitution tag. The DIV tag uses the #SUB_REGION_ ID# substitution tag with -tab appended to create a unique ID. Assigning the class x-hide-display hides the contents of the subregion until the Ext.TabPanel code is ready to display the subregion. Header entry template: subs.push({ contentEl:'#SUB_REGION_ID#-tab', title:'#SUB_REGION_TITLE#' }); [ 190 ]

    Chapter 6

    Subregion header entry templates can be used to construct a list of region titles of all the subregions for the current region. We are adding our own twist by constructing JavaScript instead of HTML. The command is pushing an object literal onto an array, the object literal containing the name of the DIV we wrapped around each subregion, together with the subregion title. This is done by using the #SUB_REGION_ID# and #SUB_REGION_TITLE# substitution tags. Header template: <script type="text/javascript"> Ext.onReady(function(){ var subs = []; #ENTRIES# new Ext.TabPanel({ renderTo: '#REGION_STATIC_ID#', activeTab: 0, items:subs }); });

    The subregion header template is mainly used to assemble the accumulated results from the header entry template in the #ENTRIES# substitution tag. Also included here is the JavaScript to create the Ext.TabPanel, which is rendered into the DIV in the template using the ID generated from the #REGION_STATIC_ ID# substitution tag. This time the pre tags have been replaced with the script tags. Template:
    #SUB_REGIONS# #SUB_REGION_HEADERS#

    The template is a simple DIV element the Ext.TabPanel will be rendered into. The #REGION_STATIC_ID# is used to identify the region; the #REGION_ATTRIBUTES# allows attributes to be assigned from the Edit Region Form. This is very useful for sizing the DIV region, for example style="width:595px; height:240px". The #SUB_REGIONS# and #SUB_REGION_HEADERS# are used to hold the content of the subregions and the JavaScript we have created in the subregion header template. Now that the script tags are in place, the tab panel will render properly using the minimal configuration we provided.

    [ 191 ]

    Adding Ext Layout Elements

    Configuring the tab panel template

    The Ext.TabPanel is highly configurable; so far we have used a minimal configuration when creating the tab panel in the template definition. Our minimal configuration means the individual tab panel's size to their contents. Looking at the following screenshot, you can see the height of the User Information tab is much larger than the empty History tab shown below it. Depending on your requirements, that may be perfectly fine. Let's look at a couple of alternative configurations.

    Setting the tab panel's attributes value to style="width:450px; height:240px", as shown in the following screenshot, controls the height and width of the containing DIV the tab panel is rendered into through the #REGION_ATTRIBUTES# substitution tag:

    [ 192 ]

    Chapter 6

    This automatically limits the width of the tab panel, which sizes to the parent container. Using the following configuration allows the height of the individual tabs to be set to the same value: new Ext.TabPanel({ renderTo: '#REGION_STATIC_ID#', activeTab: 0, height: Ext.fly('#REGION_STATIC_ID#').getHeight()||'auto', defaults: {autoScroll:true, boxMinHeight: 100}, cls: 'blue-tabs', plain: true, items:subs });

    The height config option is set to the height of the containing DIV if specified, otherwise falls back to the 'auto' setting and uses the height of the tabs contents. The defaults config option sets all tabs to include a scrollbar automatically if the content overflows the fixed tab region instead of clipping the content, and specifying boxMinHeight sets a minimum height if the 'auto' setting is applied. Adding cls: 'blue-tabs' picks up the custom CSS style: .blue-tabs .x-panel-bwrap .x-panel-body { background-color:#e0ecfc; padding:10px }

    Setting plain: true removes the background from the tab strip. The result of all these configuration options is the very different looking tab panel in the following screenshot:

    [ 193 ]

    Adding Ext Layout Elements

    Flipping the tab strip from the top of the tab panel to the bottom is done by simply setting the configuration option tabPosition: 'bottom'; the result is shown in the following screenshot:

    There are still a large number of configuration options we haven't explored here, so it's well worth spending some time experimenting to work out what suits your application best.

    Toolbars and menus Back in Chapter 4, Ext Themed Regions, Labels, and Lists, we went through a solution to creating a hierarchical tree component using a list template to build a script and generate an Ext.tree.TreePanel, as shown on the left-hand side of the following figure:

    [ 194 ]

    Chapter 6

    This time we are going to use much the same approach to produce the toolbar on the right hand side of the preceding figure. One thing really nice about this solution is that the tree and toolbar are using the same list as the data source. As the solution is so similar to the Ext.tree.TreePanel solution in Chapter 4, we will only cover the APEX 4.0 solution. If you are still using an earlier APEX version, you can easily adapt the pre APEX 4.0 solution in Chapter 4 in the same manner. Create a new List Template: Name: EXTJS Toolbar List Template class: Hierarchical Expanding List template current: {id:"#LIST_ITEM_ID#","text":"#TEXT#","href":"#LINK#"#A02#}

    List template current with sub list items: {id:"#LIST_ITEM_ID#","text":"#TEXT#","href":"#LINK#"#A02#,menu:{ items:[

    List template noncurrent: {id:"#LIST_ITEM_ID#","text":"#TEXT#","href":"#LINK#"#A02#}

    List template noncurrent with sub list items: {id:"#LIST_ITEM_ID#","text":"#TEXT#","href":"#LINK#"#A02#,menu:{ items:[

    Between list elements: ,

    List template current (first): <script type="text/javascript"> Ext.onReady(function(){ var menuRegion = 'menu#LIST_ITEM_ID#'; var menuData = [{id:"#LIST_ITEM_ID#","text":"#TEXT#", "href":"#LINK#"#A02#,menu:{ items:[

    [ 195 ]

    Adding Ext Layout Elements

    List template current with sublist items (first): <script type="text/javascript"> Ext.onReady(function(){ var menuRegion = 'menu#LIST_ITEM_ID#'; var menuData = [{id:"#LIST_ITEM_ID#","text":"#TEXT#", "href":"#LINK#"#A02#}

    List template noncurrent (first): <script type="text/javascript"> Ext.onReady(function(){ var menuRegion = 'menu#LIST_ITEM_ID#'; var menuData = [{id:"#LIST_ITEM_ID#","text":"#TEXT#", "href":"#LINK#"#A02#}

    List template noncurrent with sublist items (first): <script type="text/javascript"> Ext.onReady(function(){ var menuRegion = 'menu#LIST_ITEM_ID#'; var menuData = [{id:"#LIST_ITEM_ID#","text":"#TEXT#", "href":"#LINK#"#A02#,menu:{

    items:[ Sublist template current: {id:"#LIST_ITEM_ID#","text":"#TEXT#","href":"#LINK#"#A02#}

    Sublist template current with sublist items: {id:"#LIST_ITEM_ID#","text":"#TEXT#", "href":"#LINK#"#A02#,menu:{ items:[

    [ 196 ]

    Chapter 6

    Sublist template noncurrent: {id:"#LIST_ITEM_ID#","text":"#TEXT#","href":"#LINK#"#A02#}

    Sublist template noncurrent with sublist items: {id:"#LIST_ITEM_ID#","text":"#TEXT#", "href":"#LINK#"#A02#,menu:{ items:[

    Between sublist items: ,

    Sublist template after rows: ]}}

    List template after rows: ]; new Ext.Toolbar({ renderTo: menuRegion, style: {border: '1px solid #99BBE8'}, items: menuData }); });

    We won't go through a detailed explanation of the code here; it really is just repeating what was covered in Chapter 4, with minor adjustments to produce an Ext. toolbar instead of an Ext.tree.TreePanel. The main points to remember: Using APEX lists allow conditions on individual entries, allowing you to show items conditionally depending on security privileges of application state. APEX lists are automatically included in exports, so you don't need to migrate data manually. The #A02# substitution tag allows you to add extra JavaScript code against individual menu items, for example, to change the appearance or add a custom 'click' action.

    [ 197 ]

    Adding Ext Layout Elements

    Attaching the toolbar to the center panel If you want to integrate the toolbar into the center panel so it is directly attached to the header of the center panel, as shown in the following screenshot, there are a few simple changes to make:

    First, you will need to change your page template to include an empty toolbar in the center region. This is necessary because Ext cannot add a toolbar to a panel once it has been rendered. So, for a simplified Viewport, the highlighted line adds a hidden toolbar to the center panel: new Ext.Viewport({ layout: 'border', defaults: { animCollapse: false, autoScroll: true }, items: [{ contentEl: 'app-west-panel', collapsible: true, region: 'west', split: true, title: 'Navigation', width: 275 }, { id: 'gen-center-panel', contentEl: 'app-center-panel', region: 'center', title: document.title, tbar: {hidden:true, items:[]}, xtype: 'panel' }] }); }); [ 198 ]

    Chapter 6

    The other item to note is that we have set the ID 'gen-center-panel' for the center panel, making it easy to reference later. Then either copy or modify the toolbar list template, changing the following section: List template after rows: ]; var tb = Ext.getCmp('gen-center-panel').getTopToolbar(); tb.add(menuData); if (!tb.isVisible()) tb.setVisible(true); tb.doLayout(); });

    Now, instead of rendering the toolbar to a DIV element, we are looking up the existing toolbar using the ID of the center panel. Once we have this, the menu items in the array menuData are added to the toolbar. Finally, we set the toolbar to visible and update the layout. The references to the DIV element the menu was originally rendered into can also be removed from the template. We have barely scratched the surface of what you can do with the Ext.toolbar here. There are many more features and options available, so spend some time exploring the toolbar examples included with the Ext library.

    Summary In this chapter, we have introduced some "low-hanging fruit" Ext JS components that add functionality to applications with minimal effort to set them up. For the date picker, resizable or auto-sizing text areas, and the combo boxes, we have simply improved existing HTML components. The tab panels and toolbar menus introduce new functionality not previously available in our theme. In some ways, using the template approach is ultimately limited, because you are restricted to hard-coding your configuration options into the template. We saw for the tab panels to have several different variations requires you to have multiple templates. Plugins, also introduced in APEX 4.0, offer much more flexibility, which we will see in the next chapter. [ 199 ]

    Working with Plug-ins and Dynamic Actions Plug-ins and dynamic actions are the two most exciting new features for developers in APEX 4.0. Combining them with Ext JS components is a recipe for success. For the first time we now have the ability to add custom "widgets" directly into APEX that can be used declaratively in the same way as native APEX components. Plug-ins and dynamic actions are supported with back end integration, allowing developers to make use of APEX provided PL/SQL APIs to simplify component development. Plug-ins give developers a supported mechanism to enhance the existing built-in functionality by writing custom PL/SQL components for item types, regions, and processes. Dynamic actions provide developers with a way to define client-side behavior declaratively without needing to know JavaScript. Using a simple wizard, developers can select a page item and a condition, enter a value, and select an action (for example, Show, Hide, Enable, and Show Item Row). Most APEX developers come from a database development background. So, they are much more comfortable coding with PL/SQL than JavaScript. The sooner work is focused on PL/SQL development the more productive APEX developers become. The ability to create plug-ins that can be used declaratively means developers don't have to write page-specific JavaScript for items on a page, or use messy "hacks" to attach additional JavaScript functionality to standard APEX items. Ext JS provides a rich library of sophisticated JavaScript components just waiting to be integrated into APEX using plug-ins.

    Working with Plug-ins and Dynamic Actions

    Over the next chapters, we will be looking at plug-ins and dynamic actions and how they interact together. This chapter will cover in detail the development process for creating a simple NumberField plug-in, allowing you to focus on the process rather than the widget.

    A home for your plug-ins and dynamic actions APEX allows you to create plug-ins for item, region, dynamic action, and process types. Like templates and themes, plug-ins are designed to be shared, so they can be easily exported and imported from one workspace application to another. Plug-ins can also be subscribed, providing a way to easily share and update common attributes between plug-ins. In Chapter 3 Building a Ext theme into APEX, I discussed the benefits of building your theme in a dedicated TEMPLATE application, and building simple test pages as you go to verify the templates. These test pages also form part of your template documentation, allowing team members to examine and understand specific functionality in isolation. The same principle applies for building plug-ins and dynamic actions.

    Building a better Number Field

    APEX 4.0 introduced the Number Field as a new item type, allowing you to configure number-range checks by optionally specifying minimum and maximum value attributes. It also automatically checks that the entered value is a number, and performs NOT NULL validation as well. You can also specify a format mask for the number as well, presumably to enforce decimal places. This all sounds great, and it does work as described, but only after you have submitted the page for processing on the server. The following screenshot shows the APEX and Ext versions of the Number Field, both setup with a valid number range of 1 to 10,000. The APEX version allows you to enter any characters you want, including letters. The Ext version automatically filters the keys pressed to only accept numbers, conditionally the decimal separator, and the negative sign. It also highlights invalid values when you go outside the valid number range.

    [ 202 ]

    Chapter 7

    We are going to build a better Number Field using APEX plug-ins to provide better functionality on the client side, and still maintain the same level of server-side validation. The Number Field is quite a simple example, allowing us to be introduced to how APEX plug-ins work without getting bogged down in the details. The process of building a plug-in requires the following: •

    Creating a plug-in in your application workspace

    •

    Creating a test page containing your plug-in and necessary extras to test it

    •

    Running your application to test functionality

    •

    Repeating the build/test cycle, progressively adding more features until satisfied with the result.

    Creating a plug-in item For our Number Field, we will be creating an item plug-in. So, navigate to the plug-ins page in Application Builder, found under Application Builder | Application xxx | Shared Components | Plug-ins, and press Create to open the Plug-in Create/Edit page. Start filling in the following fields: •

    Name: Ext.form.NumberField. Here, I'm using the Ext naming for the widget, but that's just for a convenience.

    •

    Internal Name: Oracle's recommendation here is to use your organization's domain name as a prefix. So for example, a company domain of mycompany. com would prefix a plug-in named Slider, would result in an internal name of COM.MYCOMPANY.SLIDER.

    [ 203 ]

    Working with Plug-ins and Dynamic Actions

    •

    File Prefix: As we are referencing the Ext JavaScript libraries in our page template, we can skip this field completely. For specialized plug-ins that are only used on a handful of specific pages, you would attach a JavaScript file here.

    •

    Source: For the PL/SQL source code required to implement our plug-in, you can either enter it as a PL/SQL anonymous block of code that contains functions for rendering, validating and AJAX callbacks, or refer to code in a PL/SQL package in the database.

    You get better performance using PL/SQL packages in the database, so that's the smart way to go. Simply include your package function names in the Callbacks section, as shown in the following screenshot, noting that no AJAX function name is specified as no AJAX functionality is required for this plug-in. The package doesn't need to exist at this time—the form will submit successfully anyway.

    Standard attributes: In addition to being able to create up to ten custom attributes, the APEX team has made the standard attributes available for plug-ins to use. This is really useful, because the standard attributes comprise elements that are useful for most components, such as width and height. They also have items such as List of Values (LOV), which have more complicated validation rules already built-in, checking SQL queries used for the LOV source are valid queries, and so on. For the Number Field, only a few attributes have been checked: •

    Is Visible Widget: Indicating the element will be displayed

    [ 204 ]

    Chapter 7

    • • •

    Session State Changeable: So that APEX knows to store the value of the

    item in session state

    Has Read Only Attribute: So that conditional logic can be used to make the

    item read only

    Has Width Attributes: Allowing the width of the item to be set

    Notice that some of the attributes are disabled in the following screenshot. This is because the APEX Builder conditionally enables the checkboxes that are dependent on another attribute. So, in this screenshot the List of Values Required, Has LOV Display Null Attributes, and Has Cascading LOV Attributes checkboxes are disabled, because they are dependant on the Has List of Values checkbox. Once it is checked, the other checkboxes are enabled.

    Custom attributes: Defining the custom attributes for our Number Field is largely an exercise in reviewing the configuration options available in the documentation for Ext.form. NumberField, and deciding which options are most useful to be included. You need to also take into account that some configuration options are already included when you define an APEX item using your plug-in. For example, Item Label is included with an APEX item, but is rendered separately from the item, so don't need to be included. Likewise Value Required is a validation rule, and is also separate when rendering the APEX item.

    [ 205 ]

    Working with Plug-ins and Dynamic Actions

    The following next screenshot shows some Ext.form.NumberField configuration options, overlaid with the custom attributes defined in APEX for the plug-in:

    I've chosen not to include the allowBlank config option as a custom attribute, simply because this can be determined by the APEX Value Required property. Other Configuration options, such as allowDecimals and allowNegative, are included as custom attributes as Yes/No types. The custom attributes created are listed in the following table: Label

    Type

    Required

    Allow Decimals

    Yes/No

    Yes

    Allow Negative

    Yes/No

    Yes

    Decimal Precision

    Number

    No

    Minimum Value

    Number

    No

    Maximum Value

    Number

    No

    Number Alignment

    Select List

    No

    Depending on

    Values

    Allow Decimals

    left, center, right

    [ 206 ]

    Chapter 7

    Custom events: Custom events are used to define JavaScript event that can be exposed to dynamic actions. For this simple plug-in, there is no need to define any custom events. At this point, we are done defining the Number Field in APEX; it's time to turn our attention to building the database package to execute the Callbacks to render and validate the plug-in.

    Defining the plug-in Callback functions

    Plug-ins must implement a fixed interface, defined for the plug-in type (item, region, dynamic action) and the Callback function (Render, AJAX, Validation). For example, the item type plug-in Render Functions must implement the following interface: function ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result

    So, for the Number Field plug-in, I'm using a package name plug_ext_form_ numberfield, and function names render, ajax, and validate. The PL/SQL package specification becomes: CREATE OR REPLACE PACKAGE plug_ext_form_numberfield AS function render ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result; function ajax ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin ) return apex_plugin.t_page_item_ajax_result; function validate ( [ 207 ]

    Working with Plug-ins and Dynamic Actions p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) return apex_plugin.t_page_item_validation_result; END; /

    For the PL/SQL package body, we'll start out by building working stubs for the functions, and fill in the details, as we work through the solution. CREATE OR REPLACE PACKAGE BODY plug_ext_form_numberfield AS FUNCTION render ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result IS l_result apex_plugin.t_page_item_render_result; subtype attr is apex_application_page_items.attribute_01%type; -- assign local names to l_allow_decimals attr l_allow_negative attr l_decimal_precision attr l_min_value attr l_max_value attr l_align attr

    attributes := p_item.attribute_01; := p_item.attribute_02; := p_item.attribute_03; := p_item.attribute_04; := p_item.attribute_05; := p_item.attribute_06;

    -- Only use escaped value for the HTML output! l_code varchar2(32767); l_escaped_value varchar2(32767) := sys.htf.escape_sc(p_value); l_name varchar2(30); BEGIN -- Debug information if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item, [ 208 ]

    Chapter 7 p_value => p_value, p_is_readonly => p_is_readonly, p_is_printer_friendly => p_is_printer_friendly ); end if; if p_is_readonly or p_is_printer_friendly then -- emit hidden field if necessary apex_plugin_util.print_hidden_if_readonly ( p_item_name => p_item.name, p_value => p_value, p_is_readonly => p_is_readonly, p_is_printer_friendly => p_is_printer_friendly ); -- emit display span with the value apex_plugin_util.print_display_only ( p_item_name => p_item.name, p_display_value => p_value, p_show_line_breaks => false, p_escape => true, p_attributes => p_item.element_attributes ); else -- If a page item saves state, we have to call the -- get_input_name_for_page_item to render the internal -- hidden p_arg_names field. It will also return the -- HTML field name which we have to use when we render -- the HTML input field. l_name := apex_plugin.get_input_name_for_page_item(false); sys.htp.p('');

    -- **************************************************** -- @todo - write code for widget here -- **************************************************** l_code := 'Ext.onReady(function(){'|| 'alert("@todo - write widget code");'|| '});';

    [ 209 ]

    Working with Plug-ins and Dynamic Actions -- Initialize page item when the page has been rendered. apex_javascript.add_onload_code(p_code => l_code); -- Tell APEX engine that field is navigable, in case -- it's the first item on the page, and APEX page is -- configured to navigate to first item (by default). l_result.is_navigable := true; end if; return l_result; END render;

    FUNCTION ajax ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin ) return apex_plugin.t_page_item_ajax_result IS l_result apex_plugin.t_page_item_ajax_result; BEGIN -- @note - not using AJAX for this widget -- usually logic goes here -- not used by APEX yet return l_result; END ajax;

    FUNCTION validate ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) return apex_plugin.t_page_item_validation_result IS l_result apex_plugin.t_page_item_validation_result; BEGIN -- Debug information if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item ); end if; -- @todo - write validation code [ 210 ]

    Chapter 7 return l_result; END validate; END plug_ext_form_numberfield; /

    Once the PL/SQL package specification and body has been compiled in the same schema as the parsing schema for the APEX Application, you have a fully functional "stub" for an item plug-in. The "stub" is a basic template pattern for item plug-ins; you simply insert the relevant code for your particular plug-in where the @todo comments are shown. I'm not going to spend much time going through this PL/SQL code; that would be like "teaching your Grandmother how to suck eggs", as the saying goes. There are a few important points worth noting though. The APEX plug-in engine does a lot of work for you before it calls the plug-in code to render, validate, or execute AJAX processing on an item. The engine gathers the relevant metadata for the specific APEX page item, performing substitutions along the way before passing that information through to the plug-in as record-type parameters. So, looking at the render function specification, FUNCTION render ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result

    you can see the the function is being passed record types apex_plugin.t_page_ item and apex_plugin.t_plugin, and returning t_page_item_render_result. The definitions for the record types are contained in the APEX_PLUGIN (APEX_040000.WWV_FLOW_PLUGIN) package specification, and include the following type declarations: type t_plugin is name file_prefix attribute_01 ... attribute_10

    record ( varchar2(45), varchar2(4000), varchar2(32767), varchar2(32767) );

    [ 211 ]

    Working with Plug-ins and Dynamic Actions type t_page_item is record ( id name label plain_label format_mask is_required lov_definition lov_display_extra lov_display_null lov_null_text lov_null_value lov_cascade_parent_items ajax_items_to_submit ajax_optimize_refresh element_width element_max_length element_height element_attributes element_option_attributes escape_output attribute_01 ... attribute_10

    number, varchar2(255), varchar2(4000), varchar2(4000), varchar2(255), boolean, varchar2(4000), boolean, boolean, varchar2(255), varchar2(255), varchar2(255), varchar2(255), boolean, number, number, number, varchar2(2000), varchar2(4000), boolean, varchar2(32767), varchar2(32767) );

    type t_page_item_render_result is record ( is_navigable boolean default false, navigable_dom_id varchar2(255) );

    As you can see, there is a fairly substantial amount of metadata available for you to use when generating code for your plug-in. Once you start writing, your plug-in the package APEX_PLUGIN_UTIL (APEX_040000. WWV_FLOW_PLUGIN_UTIL) contains some very useful procedures to help you build plug-ins quickly. A number of them have already been included in our stub plug-in.

    [ 212 ]

    Chapter 7

    One of the utility procedures most useful when starting out building your plug-in is the debugging procedure, called using the following code: if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item ); end if;

    With debugging enabled for a page containing your plug-in, the debugging page shows the parameters values being passed to your plug-in package, as can be seen in the following screenshot:

    At this point, it's a good time to create a page and include the number plug-in, so we can do some testing and progressively add functionality to the plug-in.

    [ 213 ]

    Working with Plug-ins and Dynamic Actions

    Creating a page item based on the Number Field plug-in Creating a page item based on your plug-in is done exactly the same way you would any standard APEX item. Simply create the item, then select your plug-in under the Display option, and start filling in the details for the item as usual. The standard attributes available are determined by the plug-in definition; we didn't select the standard attribute Has List of Values for the plug-in earlier, so that section isn't available for our Number Field. The custom attributes we defined for the Number Field appear in the Settings section, as you can see in the following screenshot:

    So, go ahead and create a test page with your shiny new Number Field plug-in, and give it a test run. If everything is working as expected, then it should look and behave exactly like a standard APEX Text Field. It will accept any text you enter, submit and store the result in Session state, and render it as a read-only field if you set the Read-Only Condition.

    [ 214 ]

    Chapter 7

    The only inconvenient thing about it is that annoying JavaScript alert shown in preceding screenshot, reminding us that we haven't finished writing the plug-in source. Let's remedy that now.

    Render functionality for the Number Field plug-in Our stub function already includes enough logic to behave as a standard APEX Text field. To make it behave as an Ext.form.NumberField, providing automatic keystroke filtering and number validation, we need to generate JavaScript code to convert it. The generated JavaScript will look similar to the following: Ext.onReady(function(){ new Ext.form.NumberField({ applyTo: 'P120_NUMBER_FIELD', allowDecimals: false allowNegative: false, decimalPrecision: 2, minValue: 1, maxValue: 10000, value: 54 }); });

    You can easily test this on your test page by pasting the preceding code into the Firebug console in Firefox, changing the applyTo value to match your page item, and running it. Looking at the generated JavaScript, it's readily apparent that the code generator simply needs to build up the text, adding the parameters and dynamic values as it goes. The final version of the render function is as follows: FUNCTION render ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result IS l_result apex_plugin.t_page_item_render_result; [ 215 ]

    Working with Plug-ins and Dynamic Actions subtype attr is apex_application_page_items.attribute_01%type; -- assign local names to l_allow_decimals attr l_allow_negative attr l_decimal_precision attr l_min_value attr l_max_value attr l_align attr

    attributes := p_item.attribute_01; := p_item.attribute_02; := p_item.attribute_03; := p_item.attribute_04; := p_item.attribute_05; := p_item.attribute_06;

    -- Only use escaped value for the HTML output! l_code varchar2(32767); l_escaped_value varchar2(32767) := sys.htf.escape_sc(p_value); l_name varchar2(30);

    To improve the readability of your code, it's worthwhile assigning the p_item attribute values to local variables. Also highly recommended is escaping any values passed from the HTML page using the Oracle provided sys.htf.escape_sc function to prevent SQL injection attacks. A malicious person can easily circumvent any HTML page protection using developer tools, such as Firebug, to force the page to submit SQL injection text. BEGIN -- Debug information if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item, p_value => p_value, p_is_readonly => p_is_readonly, p_is_printer_friendly => p_is_printer_friendly ); end if; if p_is_readonly or p_is_printer_friendly then -- emit hidden field if necessary apex_plugin_util.print_hidden_if_readonly ( p_item_name => p_item.name, p_value => p_value, p_is_readonly => p_is_readonly, p_is_printer_friendly => p_is_printer_friendly ); -- emit display span with the value [ 216 ]

    Chapter 7 apex_plugin_util.print_display_only ( p_item_name => p_item.name, p_display_value => p_value, p_show_line_breaks => false, p_escape => true, p_attributes => p_item.element_attributes ); else -- If a page item saves state, we have to call the -- get_input_name_for_page_item to render the internal -- hidden p_arg_names field. It will also return the -- HTML field name which we have to use when we render -- the HTML input field. l_name := apex_plugin.get_input_name_for_page_item(false); sys.htp.p('');

    The first section of the procedure remains exactly the same as the earlier version. Now we remove the stubbed code: -- **************************************************** -- @todo - write code for widget here -- **************************************************** l_code := 'Ext.onReady(function(){'|| 'alert("@todo - write widget code");'|| '});';

    The stubbed code is replaced with the following highlighted code: -- build Ext.form.NumberField properties l_code := wwv_flow_javascript.add_attribute( 'applyTo', p_item.name) ||wwv_flow_javascript.add_attribute( 'allowDecimals' ,case when l_allow_decimals = 'N' then 'false' end) ||wwv_flow_javascript.add_attribute( 'allowNegative' ,case when l_allow_negative = 'N' then 'false' end) ||wwv_flow_javascript.add_attribute( 'decimalPrecision', l_decimal_precision) [ 217 ]

    Working with Plug-ins and Dynamic Actions ||wwv_flow_javascript.add_attribute( 'minValue',l_min_value) ||wwv_flow_javascript.add_attribute( 'maxValue',l_max_value) ||wwv_flow_javascript.add_attribute( 'value',l_escaped_value); -- can't use add_attribute() as it escapes double quotes if l_align is not null then l_code := l_code||'"style": {"text-align":"' ||l_align||'"},'; end if; l_code := l_code||wwv_flow_javascript.add_attribute( p_name => 'ajaxIdentifier', p_value => apex_plugin.get_ajax_identifier, p_add_comma => false); l_code := 'Ext.onReady(function(){new Ext.form.NumberField({' ||l_code||'});});'; -- Initialize page item when the page has been rendered. apex_javascript.add_onload_code(p_code => l_code); -- Tell APEX engine that field is navigable, in case -- it's the first item on the page, and APEX page is -- configured to navigate to first item (by default). l_result.is_navigable := true; end if; return l_result; END render;

    The highlighted code shows the changes to the stubbed version, simply replacing the alert message with the final JavaScript we want, dynamically assigning the property values using the APEX items metadata. Once again, APEX has provided utilities in the APEX_JAVASCRIPT (APEX_040000.WWV_FLOW_JAVASCRIPT) package to simplify the process.

    [ 218 ]

    Chapter 7

    Validation functionality for the Number Field plug-in Currently, the validation function for the Number Field plug-in does absolutely nothing; it's just a stub that compiles and nothing more. Even so, APEX does some validation for us, checking for mandatory items. The final code for the validation function verifies the page item value is a number with a value conforming to the rules specified for the page item: FUNCTION validate ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) return apex_plugin.t_page_item_validation_result IS subtype attr is apex_application_page_items.attribute_01%type; -- assign local names to attributes l_allow_decimals attr := p_item.attribute_01; l_allow_negative attr := p_item.attribute_02; l_precision number := to_number(p_item.attribute_03); l_min_value number := to_number(p_item.attribute_04); l_max_value number := to_number(p_item.attribute_05); n number; l_result apex_plugin.t_page_item_validation_result; BEGIN -- Debug information if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item ); end if; -- Nothing to do when null (APEX checks for mandatory items) if p_value is null then return l_result; end if; -- verify value is numeric begin n := to_number(p_value); exception when value_error then [ 219 ]

    Working with Plug-ins and Dynamic Actions l_result.message := 'Value for '|| p_item.plain_label||' must be a number'; return l_result; end; case when l_allow_decimals = 'N' and n <> trunc(n) then l_result.message := 'Decimals not allowed for '|| p_item.plain_label; when l_precision is not null and n <> trunc(n,l_decimal_precision) then l_result.message := 'Decimals places cannot exceed '|| l_precision||' for '||p_item.plain_label; when l_allow_negative = 'N' and n <> abs(n) then l_result.message := 'Negative numbers not allowed'|| ' for '||p_item.plain_label; when l_min_value is not null and n < l_min_value then l_result.message := 'The minimum value for '|| p_item.plain_label||' is '||l_min_value; when l_max_value is not null and n > l_max_value then l_result.message := 'The maximum value for '|| p_item.plain_label||' is '||l_max_value; else null; end case; -- return l_result with error message, success => null return l_result; END validate;

    That wraps up the implementation for the Number Field Plug-in; the final package specification and package body are found in the files included with the book under Chapter 7.

    [ 220 ]

    Chapter 7

    Summary In this chapter, we have covered the development process for creating an item type plug-in, showing how to define the plug-in and its parameters in APEX. We initially created a "stub" PL/SQL package for the Plug-in, allowing us to create a test page for our Plug-in and start using it as a standard APEX text item. Once the stub was working, we then were able to add in the enhanced JavaScript functionality progressively on the web page, before completing the Plug-in by adding the server-side validation. Since the NumberField is just enhancing a standard HTML input field and does not add additional HTML elements, the standard Dynamic Actions will work quite happily without change. We haven't implemented any AJAX functionality because there hasn't been any requirement. Chapter 8 implements a much more sophisticated component, the Ext.form. ComboBox, as a Plug-in, and deals with both AJAX functionality and Dynamic Actions, so we will have a look at that next.

    [ 221 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions Data Stores provide the Ext JS framework with the ability to store data on the browser client acting much like an in-memory database. This provides enormous flexibility for data-aware components, such as the ComboBox, GridPanel, and TreePanel, as it logically separates the component from the data. This makes the process of integrating AJAX functionality into plug-ins far simpler, because the AJAX processes will be focused on just passing data between the browser client and the database. The Ext components already contain the client-side functionality to update the display. On the database side, APEX provides rich PL/SQL APIs to speed up the development of plug-ins. We will be making good use of the APEX-provided PL/ SQL APIs to simplify component development. In this chapter we will cover: •

    Storing data on the browser client using Ext.data.Store

    •

    Creating a complex ComboBox Plug-in, dealing with more advanced plugin concepts including AJAX processing and interacting with dynamic actions

    •

    Overriding standard Ext.form.ComboBox functionality to work within the APEX Dynamic Actions framework

    •

    Creating APEX Custom Events for the ComboBox plugin

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    It makes for an interesting chapter, by really bringing the client-side Ext JS framework together with the server-side capabilities of APEX to harness their full potential.

    Storing data on the browser client The Ext.data.Store class is used to store data on the browser client acting much like an in-memory database. The Store class caches Record objects that are used by data-aware components such as the ComboBox, GridPanel, and TreePanel. Data is loaded into a Store using different formats such as JavaScript Arrays, XML, or JSON through the Ext.data.DataReader class. The DataReader class has subclasses ArrayReader, JsonReader, and XmlReader that read structured data from a data source in a specific format, converting it into Record objects and metadata for use by a Store object. A number of Store types are available such as ArrayStore, JsonStore, and XmlStore, customized and pre-configured for use with a specific DataReader. These custom store types act as a helper class to provide a simpler shorthand way of implementing the same solution. For example, a basic Data Store to consume an Array looks like: // data array of records var countryData = [ ["Afghanistan","65"] ,["Aland Islands","131"] ,["Albania, Republic of","118"] /*..snipped..*/ ,["Zambia, Republic of","64"] ,["Zimbabwe","54"] ]; // define the record type structure var countryRecord = Ext.data.Record.create([ { name: 'countryName', mapping : 1 }, { name: 'countryId', mapping : 2 } ]); // create a reader, assigning the record type var arrayReader = new Ext.data.ArrayReader({}, countryRecord); // create a store, assigning the reader var store = new Ext.data.Store({ [ 224 ]

    Chapter 8 reader : arrayReader }); // manually load the store store.loadData(countryData);

    It can be re-written using the Ext.data.ArrayStore, when it simply becomes: // data array of records var countryData = [ ["Afghanistan","65"] ,["Aland Islands","131"] ,["Albania, Republic of","118"] /*..snipped..*/ ,["Zambia, Republic of","64"] ,["Zimbabwe","54"] ]; // create the store, assigning fields var store = new Ext.data.ArrayStore({ fields: ["countryName", "countryId"], data: countryData });

    We will be using Ext.data.ArrayStore when data is locally defined in the page. The ArrayStore is configured with an Ext.data.ArrayReader that automatically calls the store's load method after creation to load the data into the store. The following function should be included as part of a database package to render the ArrayStore: FUNCTION render_local_store ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) RETURN sys.dbms_sql.desc_tab2 IS l_sql_handler apex_plugin_util.t_sql_handler; l_col_value_list apex_plugin_util.t_column_value_list; l_col_count number; BEGIN -- open sql cursor and get description for sql statement l_sql_handler := apex_plugin_util.get_sql_handler ( p_sql_statement => p_item.lov_definition, [ 225 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions p_min_columns => 1, p_max_columns => 999, p_component_name => p_item.id ); l_col_count := l_sql_handler.column_list.count(); -- binds all page item bind variables apex_plugin_util.prepare_query ( p_sql_handler => l_sql_handler ); -- fetch the data l_col_value_list := apex_plugin_util.get_data ( p_sql_handler => l_sql_handler ); -- close the open cursor created by get_sql_handler apex_plugin_util.free_sql_handler(l_sql_handler); -- start script sys.htp.p('<script type="text/javascript">'); sys.htp.p('Ext.onReady(function(){'); sys.htp.p('var ns = Ext.ns("Ext.apex.'||p_item.name||'");'); -- print data if l_col_value_list.exists(1) then sys.htp.p('ns.data = ['); for i in 1 .. l_col_value_list(1).count loop sys.htp.prn(case when i > 1 then ',' else ' ' end||'['); for j in 1 .. l_col_count loop sys.htp.prn(case when j > 1 then ',' end|| '"'||apex_plugin_util.escape( l_col_value_list(j)(i),true)||'"'); end loop; sys.htp.p(']'); end loop; sys.htp.p('];'); else sys.htp.p('ns.data = [];'); end if; -- print store sys.htp.p('// simple array store'); sys.htp.p('ns.store = new Ext.data.ArrayStore({'); sys.htp.prn(' fields: ['); [ 226 ]

    Chapter 8 for i in 1 .. l_col_count loop sys.htp.prn(case when i > 1 then ',' end|| '"'||l_sql_handler.column_list(i).col_name||'"'); end loop; sys.htp.p('],'); sys.htp.p(' data : ns.data'); sys.htp.p('});'); -- end script sys.htp.p('});'); sys.htp.p(''); return l_sql_handler.column_list; EXCEPTION when others then apex_plugin_util.free_sql_handler(l_sql_handler); raise; END render_local_store;

    The render_local_store uses the APEX_PLUGIN_UTIL (WWV_FLOW_PLUGIN_UTIL) package to prepare the SQL query, bind session state variables, and retrieve the data. That's quite a bit of work done for you by APEX, leaving you to render the data in the desired format, in this case as a data store. The JavaScript produced by the render_local_store function looks like the following: <script type="text/javascript"> Ext.onReady(function(){ var ns = Ext.ns("Ext.apex.P120_COMBO"); ns.data = [ ["Afghanistan","65"] ,["Aland Islands","131"] ,["Albania, Republic of","118"] /* ..snipped .. */ ,["Zambia, Republic of","64"] ,["Zimbabwe","54"] ]; // simple array store ns.store = new Ext.data.ArrayStore({ fields: ["CODE_DESCRIPTION","ID"], data : ns.data [ 227 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions }); });

    The only difference from our earlier example of an ArrayStore is that the store has been namespaced: var ns = Ext.ns("Ext.apex.P120_COMBO"); ... ns.store = new Ext.data.ArrayStore({ fields: ["CODE_DESCRIPTION","ID"], data : ns.data });

    The Ext.apex.P120_COMBO namespace has been defined using the Ext.ns (namespace) function. By assigning local variable ns to the namespace, an "alias" has been defined, allowing you to code using the generic, abbreviated version. The store is an object within this namespace, and can be referenced from JavaScript elsewhere in a page using the fully qualified name Ext.apex.P120_COMBO.store.

    Using Data Stores with large datasets It's not practical for large datasets to be stored locally in the page, so when returning large datasets, the sensible approach is to fetch only a subset of data using an AJAX request, letting the user remotely load the data and use pagination and filtering functionality to filter the results. For large datasets, we will use Ext.data.JsonStore, which is automatically configured with Ext.data.JsonReader, and implicitly creates Ext.data.HttpProxy if a URL is specified. The HttpProxy uses the browser's XHR (XML Http Request) object to perform generic AJAX requests. For APEX plug-ins, a JsonStore would look like: var store = new Ext.data.JsonStore({ url: 'wwv_flow.show', root: 'rowset', idProperty: 1, fields: ["countryName", "countryId"], baseParams: { p_flow_id: Ext.getDom('pFlowId').value, p_flow_step_id: Ext.getDom('pFlowStepId').value, p_instance: Ext.getDom('pInstance').value, p_request: 'PLUGIN=4A6E248DAACFAED09B96..7261F1E1F7E' }, [ 228 ]

    Chapter 8 paramNames: { start:'p_widget_action_mod', limit:'p_widget_action' } });

    The JsonStore calls the named url, passing parameter names and values sourced from the baseParams and paramNames config options. The following PL/SQL function render_remote_store generates the JavaScript for a remote store definition, and should be included in a database package: FUNCTION render_remote_store ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) RETURN sys.dbms_sql.desc_tab2 IS l_sql_handler l_col_value_list l_col_count l_col_names

    apex_plugin_util.t_sql_handler; apex_plugin_util.t_column_value_list; number; varchar2(32767);

    l_script varchar2(32767) := q'^ Ext.onReady(function(){ var ns = Ext.ns('Ext.apex.#ITEM_NAME#'); // simple array store ns.store = new Ext.data.JsonStore({ url: 'wwv_flow.show', root: 'rowset', fields: [#FIELD_LIST#], baseParams: { p_flow_id: Ext.getDom('pFlowId').value, p_flow_step_id: Ext.getDom('pFlowStepId').value, p_instance: Ext.getDom('pInstance').value, p_request: 'PLUGIN=#AJAX_IDENTIFIER#' }, paramNames: { start:'p_widget_action_mod', limit:'p_widget_action' } }); }); ^'; [ 229 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    The baseParams specified are all required by APEX to perform AJAX processing successfully. These parameters identify the application, page, session, and plugin on the page. Specifying them in the baseParams attribute ensures they are passed to the server with every AJAX request for this component. Parameter names passed by the Ext AJAX process must correspond to parameter names for the APEX database procedure wwv_flow.show, otherwise APEX will error, raising a HTTP Status 500 - System Unavailable message.

    Overriding the names passed by the JsonStore to identify the starting record and limit records returned to 'p_widget_action_mod' and 'p_widget_action' is necessary to match the parameter names of the called database procedure wwv_flow.show, identified here in the url attribute. BEGIN -- for remote store we only need to describe the store -- open sql cursor and get description for sql statement l_sql_handler := apex_plugin_util.get_sql_handler ( p_sql_statement => p_item.lov_definition, p_min_columns => 1, p_max_columns => 999, p_component_name => p_item.id ); -- close the open cursor created by get_sql_handler apex_plugin_util.free_sql_handler(l_sql_handler); l_col_count := l_sql_handler.column_list.count(); -- build comma separated string list of column names for i in 1 .. l_col_count loop l_col_names := l_col_names|| case when i > 1 then ',' end|| '"'||l_sql_handler.column_list(i).col_name||'"'; end loop; -- substitute values into placeholders wwv_flow_utilities.fast_replace(l_script, '#ITEM_NAME#',p_item.name); wwv_flow_utilities.fast_replace(l_script,

    [ 230 ]

    Chapter 8 '#FIELD_LIST#',l_col_names); wwv_flow_utilities.fast_replace(l_script, '#AJAX_IDENTIFIER#',apex_plugin.get_ajax_identifier); -- add JS to bottom of page apex_javascript.add_onload_code ( p_code => l_script ); return l_sql_handler.column_list; EXCEPTION when others then apex_plugin_util.free_sql_handler(l_sql_handler); raise; END render_remote_store;

    Again, the APEX_PLUGIN_UTIL package is used to parse the query and retrieve the column names. This time we don't need to return any data because this will be done by the Ext data-aware component when it initiates a XHR request. Instead, we are just defining the structure of the records held in the data store, and defining the parameters for the HttpRequest object. The code to retrieve the data will be dependent on each custom plug-in and handled by the PL/SQL code for AJAX requests, so we won't provide the details here. For a simple tabular component such as a ComboBox or Grid, data returned would look like: {"total":20,"rowset":[ {"CODE_DESCRIPTION": "Bahamas, Commonwealth of the","ID": "170"} ,{"CODE_DESCRIPTION": "Bahrain, Kingdom of","ID": "67"} ,{"CODE_DESCRIPTION": "Bangladesh, People's Republic of","ID": "68"} ,{"CODE_DESCRIPTION": "Barbados","ID": "171"} ,{"CODE_DESCRIPTION": "Belarus","ID": "124"} ,{"CODE_DESCRIPTION": "Belgium, Kingdom of","ID": "121"} ,{"CODE_DESCRIPTION": "Belize","ID": "173"} ,{"CODE_DESCRIPTION": "Benin, People's Republic of","ID": "20"} ,{"CODE_DESCRIPTION": "Bermuda","ID": "172"} ,{"CODE_DESCRIPTION": " Belize","ID": "173"} ]}

    Here, the total number of records is shown for the filtered result set for the query. This example shows countries starting with "B". There are a total of 20 matching records; the records shown are the first results returned for a pageSize limit of 10 records.

    [ 231 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Data Stores are a critical component for data-aware components, but are quite straightforward to understand once you start using them. Let's move onto the ComboBox plug-in to see them in action.

    Building a ComboBox plug-in

    We introduced Ext.form.ComboBox in Chapter 6, Adding Ext Layout Elements, showing how it can be used as a direct replacement for the HTML Select List. It provides the same drop-down list of values, as well as auto-completing filtering functionality, enabling users to find and select a value quickly. But that's only scratching the surface of what the ComboBox can do! In this section, we will cover creating a plug-in ComboBox, enabling functionality for it to do both local and remote loading of data. The ComboBox can use all of the Ext data store classes for its input data, so we will cover using the ArrayStore for local ComboBoxes, and the JsonStore for remote ComboBoxes. Unlike the new APEX 4.0 Auto-complete item type and the HTML Select List, ComboBoxes are not limited to just one or two columns for data. We will also cover how to use the Ext.XTemplate to provide enhanced formatting options to show more information to your application users. The example in the following screenshot shows a person's name, address fields, and a credit limit using CSS-formatted text and images—all displayed using conditional logic.

    [ 232 ]

    Chapter 8

    The ComboBox can also be used as a direct replacement for the native APEX Popup List of Values. Those clunky popups in a separate browser window will be a thing of the past! Finally, we will cover how Dynamic Actions interact with widgets made up of multiple DOM elements like the ComboBox.

    Defining the ComboBox plug-in

    We will be picking up the pace in our ComboBox definition, as defining plug-ins is about following a pattern. The new functionality will be covered in greater detail; the full source for the database package is included in the Chapter 8 source code files available on Packt's site . Plugin name: Ext.form.ComboBox

    Callbacks: •

    Render function name:

    plug_ext_form_combo.render

    •

    AJAX function name:

    plug_ext_form_combo.ajax

    •

    Validation function name:

    plug_ext_form_combo.validate

    Standard attributes:

    [ 233 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Having the List of Values enabled is the key to defining the query for our ComboBox. We will be adding an extra column as part of the solution, limiting the number of allowable columns to just 998 columns! As a design choice, I've decided a minimum of two columns are required, these columns are the description and value fields. Custom attributes: Label

    Type

    Required

    Depending on

    Mode

    Select List

    Yes

    Empty text

    Text

    No

    Template config

    Textarea

    No

    Page size

    Number

    No

    Mode

    Min. characters

    Integer

    No

    Mode

    Values remote, local

    Events: Name

    Internal name

    onSelect

    select

    Defining the ComboBox plug-in callback functions The PL/SQL package specification for the ComboBox is identical to the NumberField package specification, apart from the changing of the name: CREATE OR REPLACE PACKAGE plug_ext_form_combo AS function render ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result; function ajax ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin ) return apex_plugin.t_page_item_ajax_result;

    [ 234 ]

    Chapter 8 function validate ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) return apex_plugin.t_page_item_validation_result; END; /

    Once again we will look at the details of each function separately; the full package body and specification are included in the Chapter 8 source files available for download on Packt's site.

    Rendering functionality for the ComboBox plug-in The PL/SQL render function uses the metadata passed to it to generate HTML and JavaScript to fulfill the following requirements: •

    For a display-only item, create a stateful HTML element as a SPAN element

    •

    Create an HTML element that will be transformed into a ComboBox

    •

    Generate JavaScript defining a data store either locally with the data in a JavaScript array, or as a remote data store with parameters for an XHR request

    •

    Generate JavaScript code defining the ComboBox and referencing the store

    OR

    The PL/SQL code for the render function is as follows: FUNCTION render ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result IS l_result apex_plugin.t_page_item_render_result; subtype attr is apex_application_page_items.attribute_01%type;

    [ 235 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions -- assign local names to attributes l_mode attr := p_item.attribute_01; l_emptyText attr := p_item.attribute_02; l_tpl attr := p_item.attribute_03; l_pageSize number := to_number(p_item.attribute_04); l_minChars number := to_number(p_item.attribute_05); -- Only use escaped value for the HTML output! l_code varchar2(32767); l_escaped_value varchar2(32767) := sys.htf.escape_sc(p_value); l_name varchar2(30); l_columns sys.dbms_sql.desc_tab2; BEGIN -- Debug information if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item, p_value => p_value, p_is_readonly => p_is_readonly, p_is_printer_friendly => p_is_printer_friendly ); end if; if p_is_readonly or p_is_printer_friendly then -- emit hidden field if necessary apex_plugin_util.print_hidden_if_readonly ( p_item_name => p_item.name, p_value => p_value, p_is_readonly => p_is_readonly, p_is_printer_friendly => p_is_printer_friendly ); -- emit display span with the value apex_plugin_util.print_display_only ( p_item_name => p_item.name, p_display_value => p_value, p_show_line_breaks => false, p_escape => true, p_attributes => p_item.element_attributes ); else -- If a page item saves state, we have to call the -- get_input_name_for_page_item to render the internal -- hidden p_arg_names field. It will also return the [ 236 ]

    Chapter 8 -- HTML field name which we have to use when we render -- the HTML input field. l_name := apex_plugin.get_input_name_for_page_item(false); -- emit the input item to be transformed sys.htp.p(''); -- call store rendering routine if l_mode = 'local' then l_columns := render_local_store ( p_item => p_item, p_plugin => p_plugin, p_value => p_value ); else l_columns := render_remote_store ( p_item => p_item, p_plugin => p_plugin, p_value => p_value ); end if;

    -- build combo properties -- local procedure PUSH adds values to associative array -- (index by table) -- use convention ext-xxx, where xxx is the item name -- makes it easy to lookup components using Ext.getCmp(). push('id' ,'''ext-'||p_item.name||''''); push('hiddenName' ,''''||l_name||''''); push('hiddenValue' ,''''||l_escaped_value||''''); push('applyTo' ,''''||p_item.name||''''); push('mode' push('forceSelection' push('triggerAction' push('selectOnFocus' push('resizable'

    ,''''||l_mode||''''); ,'true'); ,'''all'''); ,'true'); ,'true');

    [ 237 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions push('store' ,'Ext.apex.'||p_item.name||'.store'); push('displayField',''''||l_columns(1).col_name||''''); push('valueField' ,''''||l_columns(2).col_name||''''); push('emptyText' ,''''||escape_json(l_emptyText)||''''); -- detect DOM node disabled -- allows developers to set element attribute to disabled push('disabled', 'Ext.fly('''||p_item.name||''').dom.disabled' ); -- Can create a customized layout using Ext.XTemplates -- otherwise uses Ext.form.ComboBox default if l_tpl is not null then push('itemSelector' ,'''div.search-item'''); push('tpl', 'new Ext.XTemplate('||CRLF||l_tpl||')' ); end if; -- lookup the display value when the value is not null if p_value is not null then push('value', '"'||escape_json( apex_plugin_util.get_display_data ( p_sql_statement => p_item.lov_definition, p_min_columns => 2, p_max_columns => 999, p_component_name => p_item.name, p_search_string => p_value, p_display_extra => false) )||'"' ); end if; -- remote combos have extra params if l_mode = 'remote' then -- the APEX ajaxIdentifier is required to -- identify the item and session for AJAX processes push('ajaxIdentifier', ''''||apex_plugin.get_ajax_identifier||'''' ); push('queryParam' push('idProperty',

    ,'''x01''');

    [ 238 ]

    Chapter 8 ''''||l_columns(2).col_name||'''' ); push('triggerClass','''x-form-search-trigger'''); push('pageSize' ,l_pageSize); push('minChars' ,l_minChars); push('getParams' ,'function(q){var p = {};'|| 'if (this.pageSize) {p[''p_widget_action_mod''] = 0;'|| 'p[''p_widget_action''] = this.pageSize;}return p;}'); end if;

    -- assemble the code, retrieving the "pushed" parameters -- as a varchar2 string l_code := CRLF|| 'Ext.onReady(function(){'||CRLF|| ' new Ext.form.ComboBox({'||CRLF|| get_properties(8)||' });'||CRLF|| '});'||CRLF; -- Initialize page item when the page has been rendered. apex_javascript.add_onload_code ( p_code => l_code ); ---if

    Tell APEX engine that field is navigable, in case it's the first item on the page, and APEX page is configured to navigate to first item (by default). p_is_readonly or p_is_printer_friendly then l_result.is_navigable := false; else l_result.is_navigable := true; -- set navigable element when not same as item name -- l_result.navigable_dom_id := 'some other DOM id'; end if; end if; return l_result; END render;

    We won't be going into great detail for the render function, as much of the code is very similar to the code for the NumberField plug-in. Some areas are new, which do need some discussion.

    [ 239 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Some convenience routines not used in the NumberField example have been added, those being push, escape_json, and get_properties. The push procedure temporarily stores name and value attributes in an associative array (index by table) for later retrieval by the get_properties function. Using an associative array indexed by the attribute name means the attributes can be sent as output in alphabetical order when it suits later in the code. Having the attributes in alphabetical order isn't necessary, but it does help when debugging JavaScript. Using custom routines instead of the APEX supplied wwv_flow_javascript.add_ attribute routine gives a little more control for JSON escaping text, which is done by the escape_json function. The second area of interest is the render_local_store and render_remote_store functions that build store definitions. The code to render both the local and remote stores was covered earlier in the chapter, so all we are doing here is calling the PL/SQL routines to generate the code. To show the JavaScript generated, I've created a simple ComboBox item using a local store. The settings and LOV query are shown in the following screenshot:

    [ 240 ]

    Chapter 8

    The JavaScript output for only the ComboBox is: apex.jQuery(document).ready(function(){ (function(){ Ext.onReady(function(){ new Ext.form.ComboBox({ applyTo: 'P120_COMBO', disabled: Ext.fly('P120_COMBO').dom.disabled, emptyText: 'Select a Country...', forceSelection: true, hiddenName: 'p_t05', hiddenValue: '221', id: 'ext-P120_COMBO', mode: 'local', resizable: true, selectOnFocus: true, triggerAction: 'all', value: 'Australia, Commonwealth of', displayField: 'CODE_DESCRIPTION', store: Ext.apex.P120_COMBO.store, valueField: 'ID' }); }); })(); });

    The JavaScript code generated by the ComboBox plug-in has been wrapped by an anonymous function, and a apex.jQuery(document).ready function. APEX automatically added these extra functions when we called the apex_javascript.add_ onload_code procedure to ensure that JavaScript is not executed until the browser has the DOM tree loaded (without waiting for external resources). To ensure that the Ext library has been loaded, I would also like to include the Ext.onReady call. References to the Store have been highlighted; the Store is identified by its fully qualified name Ext.apex.P120_COMBO.store, with the ComboBox's display and value fields assigned to use the Store records CODE_DESCRIPTION and ID columns. In this example, the value and hiddenValue attributes have been assigned by the render function, performing a lookup on the APEX session state value for the P120_COMBO item. The final area of interest is around the use of Ext.XTemplate to provide enhanced formatting options, which we will cover together with retrieving data for ComboBox using XHR requests under the AJAX section.

    [ 241 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    AJAX functionality for the ComboBox plug-in

    For large datasets, the ComboBox can be configured to fetch a subset of data using an AJAX request to load the data remotely, and use pagination and type-ahead search functionality to filter the results. FUNCTION ajax ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin ) return apex_plugin.t_page_item_ajax_result IS l_result apex_plugin.t_page_item_ajax_result; BEGIN -- indicate we are returning application/json data apex_plugin_util.print_json_http_header; emit_json_data p_item => p_plugin => p_value => );

    ( p_item, p_plugin, null

    -- not used by APEX yet return l_result; END;

    The AJAX function here just calls an APEX procedure to print a JSON mime-type header, indicating the data being returned is in JSON format and shouldn't be cached. The actual text returned in the HTML Response header is: Content-Type: application/json Cache-Control: no-cache Pragma: no-cache

    The real work is done by the following the EMIT_JSON_DATA procedure: PROCEDURE emit_json_data ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) IS l_sql_handler apex_plugin_util.t_sql_handler; l_new_sql varchar2(32767); l_col_value_list apex_plugin_util.t_column_value_list; /** @todo assign from combo attributes */ [ 242 ]

    Chapter 8 l_search_type varchar2(20) := 'EXACT_IGNORE'; l_search_col varchar2(32767); l_col_count number; -- assign values from ajax parameters l_start number := coalesce(apex_application.g_widget_action_mod, 0); l_limit number := coalesce(apex_application.g_widget_action, 100); l_search_string varchar2(32767) := apex_application.g_x01; BEGIN

    Ext Stores need to know the total number of records in the result set, so it's necessary to enclose the original query within a select statement to return the total as an extra column named ext$totalrows: -- add ext$totalrows column to sql statement l_new_sql := 'select q.* ,count(*) over () ext$totalrows'|| ' from ('||p_item.lov_definition||') q';

    The total number of records is used by the Ext.PagingToolbar object, a subcomponent of the ComboBox, to provide automatic paging control. l_sql_handler := apex_plugin_util.get_sql_handler ( p_sql_statement => l_new_sql, p_min_columns => 1, p_max_columns => 999, p_component_name => p_item.name ); apex_plugin_util.free_sql_handler(l_sql_handler); l_col_count := l_sql_handler.column_list.count() - 1;

    -- can't use APEX search because need to display totals -- where clause has to be included at this level if l_search_string is not null then l_search_string := apex_plugin_util.get_search_string( p_search_type => l_search_type, p_search_string => l_search_string ); [ 243 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions l_search_col := l_sql_handler.column_list(1).col_name; l_new_sql := l_new_sql||CRLF|| case l_search_type when 'CONTAINS_CASE' then 'where instr('||l_search_col||', '''|| l_search_string||''') > 0' when 'CONTAINS_IGNORE' then 'where instr(upper('||l_search_col||'), '''|| l_search_string||''') > 0' when 'EXACT_CASE' then 'where '||l_search_col||' like '''|| l_search_string||'%''' when 'EXACT_IGNORE' then 'where upper('||l_search_col||') like '''|| l_search_string||'%''' when 'LOOKUP' then 'where '||l_search_col||' = '''|| l_search_string||'''' end; end if;

    The where clause needs to be included here to return the correct value for total matching records, because APEX wraps the passed query inside another query to limit the rows returned and the position of the first row returned, for example, returning rows 100 to 110 of the result set. -- get data based on our new sql statement l_col_value_list := apex_plugin_util.get_data ( p_sql_statement => l_new_sql, p_min_columns => 1, p_max_columns => 999, p_component_name => p_item.id, p_first_row => l_start, p_max_rows => l_limit ); -- print data if l_col_value_list.exists(1) then sys.htp.p('{"total":'|| l_col_value_list(l_col_count + 1)(1)||',"rowset":[' [ 244 ]

    Chapter 8 ); for i in 1 .. l_col_value_list(1).count loop sys.htp.prn(case when i > 1 then ',' else ' ' end||'{'); for j in 1 .. l_col_count loop sys.htp.prn(case when j > 1 then ',' end|| '"'||l_sql_handler.column_list(j).col_name||'": '|| '"'||escape_json(l_col_value_list(j)(i))||'"' ); end loop; sys.htp.p('}'); end loop; sys.htp.p(']}'); else sys.htp.prn('{"total":0,"rowset":[]}'); end if; EXCEPTION when no_data_found then apex_plugin_util.free_sql_handler(l_sql_handler); sys.htp.prn('{"total":0,"rowset":[]}'); when others then apex_plugin_util.free_sql_handler(l_sql_handler); raise; END emit_json_data;

    Once again, the APEX-provided APIs do most of the work processing the final query, binding any session state variables, and returning the data, which we render using JSON notation.

    Using the Ext.XTemplate to provide enhanced formatting The Ext.XTemplate class provides a templating mechanism that can be used to render arrays of records automatically. It provides advanced functionality such as conditional processing with basic comparison operators, basic math functions, and executing arbitrary inline code using template variables.

    [ 245 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    To show how the Ext.XTemplate is used for ComboBoxes, I've created a remote ComboBox using the settings shown in the following screenshot:

    The SQL query used for the LOV on this ComboBox is: select c.cust_first_name||' '||c.cust_last_name customer_name ,c.customer_id ,c.cust_street_address1 ,c.cust_street_address2 ,c.cust_city ,c.cust_state ,c.cust_postal_code ,c.credit_limit from demo_customers c order by lower(c.cust_first_name||' '||c.cust_last_name)

    We are not particularly interested in the query itself; it obeys the rules for our ComboBox plug-in, with the first column returned to be displayField, and the second column valueField. It also retrieves a number of other fields that can also be displayed by using XTemplates. The PL/SQL PLUG_EXT_FORM_COMBO.RENDER function generates the following JavaScript for our ComboBox on a webpage: Ext.onReady(function(){ new Ext.form.ComboBox({ applyTo: 'P120_AJAX_COMBO', disabled: Ext.fly('P120_AJAX_COMBO').dom.disabled, [ 246 ]

    Chapter 8 displayField: 'CUSTOMER_NAME', emptyText: 'Customer Name...', forceSelection: true, getParams: function(q){ var p = {}; if (this.pageSize) { p['p_widget_action_mod'] = 0; p['p_widget_action'] = this.pageSize; }return p; }, hiddenName: 'p_t06', hiddenValue: '', id: 'ext-P120_AJAX_COMBO', idProperty: 'CUSTOMER_ID', itemSelector: 'div.search-item', minChars: 2, mode: 'remote', pageSize: 20, queryParam: 'x01', resizable: true, selectOnFocus: true, store: Ext.apex.P120_AJAX_COMBO.store, tpl: new Ext.XTemplate( '<tpl for=".">
    ', '

    <span class="app-award">{CREDIT_LIMIT}{CUSTOMER_NAME}

    ', '{CUST_STREET_ADDRESS1}
    ', '<tpl if="(CUST_STREET_ADDRESS2)">', '{CUST_STREET_ADDRESS2}
    ', '', '{CUST_CITY} {CUST_STATE} {CUST_POSTAL_CODE}', '
    ', {compiled: true}), triggerAction: 'all', triggerClass: 'x-form-search-trigger', valueField: 'CUSTOMER_ID' }); });

    The JavaScript shows the ComboBox configuration, including references to the data store and the XTemplate definition, which has been highlighted.

    [ 247 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Typing the characters "be" in the ComboBox initiates an AJAX request to load the data store. Two matching records are returned by the PLUG_EXT_FORM_COMBO.AJAX function to the browser. {"total":2,"rowset":[ {"CUSTOMER_NAME": "Benjamin Freeman", "CUSTOMER_ID": "25560", "CUST_STREET_ADDRESS1": "2", "CUST_STREET_ADDRESS2": "19 Princes St", "CUST_CITY": "KALPOWAR", "CUST_STATE": "QLD", "CUST_POSTAL_CODE": "4630", "CREDIT_LIMIT": ""} ,{"CUSTOMER_NAME": "Bernard Newman", "CUSTOMER_ID": "25649", "CUST_STREET_ADDRESS1": "4 Bartlett Gr", "CUST_STREET_ADDRESS2": "", "CUST_CITY": "FLINDERS LANE", "CUST_STATE": "VIC", "CUST_POSTAL_CODE": "8009", "CREDIT_LIMIT": ""} ]}

    At this point the data store fires the datachanged event, and the ComboBox refreshes its view using the specified XTemplate to render the data. When a XTemplate is not provided, the ComboBox uses the default template string. '<tpl for=".">
    {' + this.displayField + '}
    '

    The XTemplate for this example is: '<tpl for=".">
    ', '

    <span class="app-award">{CREDIT_LIMIT}{CUSTOMER_NAME}

    ', '{CUST_STREET_ADDRESS1}
    ', '<tpl if="(CUST_STREET_ADDRESS2)">', '{CUST_STREET_ADDRESS2}
    ', '', '{CUST_CITY} {CUST_STATE} {CUST_POSTAL_CODE}', '
    ', {compiled: true}

    [ 248 ]

    Chapter 8

    The XTemplate tpl tag and the for operator are used to process the data object for the ComboBox. The for="." operator loops through the entire data object starting at the root node. Each array record is processed, substituting the column values into the column name placeholders, for example {CUSTOMER_NAME}. Conditional logic can be applied using the tpl tag and the if operator to provide conditional checks to determine whether or not to render parts of the template. Consider the following rule: '<tpl if="(CUST_STREET_ADDRESS2)">', '{CUST_STREET_ADDRESS2}
    ', '',

    In this example, this rule is used to produce output text only when the CUST_STREET_ADDRESS2 field has a value. When the XTemplate is being used to process multiple records, the compiled: true attribute should be set for optimized performance.

    The HTML produced on the browser by the XTemplate for the highlighted record shown in the previous screenshot is:

    <span class="app-award">1000 Adam Fripp

    10 Kentish Dr
    UPPER WOODSTOCK TAS 7150


    [ 249 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Additional CSS rules need to be provided, either in the APEX page or the application CSS file to produce the actual HTML formatting. The following CSS rules were applied for this example: .search-item { border-color:#FFFFFF #FFFFFF #EEEEEE; border-style:solid; border-width:1px; color:#555555; font:11px tahoma,arial,helvetica,sans-serif; padding:3px 10px; white-space:normal; } .search-item h3 { color:#222222; display:block; font-weight:bold; } .search-item h3 span { clear:none; display:block; float:right; font-weight:normal; margin:0 0 5px 5px; line-height: 18px; } .cc-limit { color:#c0272b; font:normal 11px tahoma, arial, helvetica, sans-serif; background: transparent no-repeat 0 2px; background-image:url(/ux/playpen/resources/images/icon/ creditcards.gif); padding-left:18px; }

    So as you can see, XTemplates provide a powerful mechanism to render HTML on the browser client. For AJAX-based processes, this removes the need to return formatted HTML, or the necessity to have complicated JavaScript coding to render HTML tags inserting values from the JSON data, when returning JSON data only.

    [ 250 ]

    Chapter 8

    Validation functionality for the ComboBox plug-in After the relatively lengthy code for the RENDER and AJAX functionality, the code to validate the ComboBox is quite trivial: FUNCTION validate ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2 ) return apex_plugin.t_page_item_validation_result IS l_display_value varchar2(32767); l_result apex_plugin.t_page_item_validation_result; BEGIN -- Debug information if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin, p_page_item => p_item ); end if; -- Nothing to do when null (APEX checks for mandatory items) if p_value is null then return l_result; end if; -- lookup the display value when the value is not null if p_value is not null then l_display_value := apex_plugin_util.get_display_data ( p_sql_statement => p_item.lov_definition, p_min_columns => 2, p_max_columns => 999, p_component_name => p_item.name, p_search_string => p_value, p_display_extra => false); -- return error when no display value found if l_display_value is null then l_result.message := 'Error: no display value found for '|| p_item.name||' value '||p_value||'.'; end if; end if; -- populate l_result with error message, otherwise null return l_result; END;

    The validate function uses the APEX-provided utilities to verify that matching display value exists for the supplied value using the LOV query. If not, it raises an error. [ 251 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Mixing ComboBoxes with Dynamic Actions Dynamic Actions provide a declarative mechanism for generating JavaScript to provide client-side behaviors. Native actions include simple actions that show, hide, enable, and disable page elements when a page item's value changes. More advanced native actions include setting item values, executing JavaScript code, and executing PL/SQL code via AJAX calls. Native actions work immediately for custom plug-ins based on simple DOM elements, such as the NumberField plugin in Chapter 7, Working with Plug-ins and Dynamic Actions. For plugins based on multiple DOM elements such as the ComboBox, or the built-in APEX shuttle-box, some additional work has to be done before the native dynamic actions will work correctly. The following screenshot shows the before and after views of a dynamic action to hide the three items in the region. The APEX Auto-complete item uses a simple DOM text item, with the other two items being Ext ComboBoxes, each built using multiple DOM elements.

    The APEX-generated code for the Hide Item dynamic action references the APEX item names, assuming the items are simple DOM elements. For ComboBoxes, this results in the text item component being hidden, leaving the trigger icon visible. Similarly, when using the Disable Item dynamic action, the text item component is disabled, leaving the trigger icon still enabled! So, despite attempting to restrict users from modifying the item, the trigger icon allows users to change the value. Fortunately for us, the APEX team has addressed the issue when developing complex native items, building the apex.widget.initPageItem function to integrate plug-in items with the Dynamic Actions code seamlessly.

    [ 252 ]

    Chapter 8

    Integrating plugins with the Dynamic Action framework The apex.widget.initPageItem function definition is: apex.widget.initPageItem = function (pName, pOptions) { apex.item(pName, pOptions); };

    It accepts two parameters—the item name and an object literal containing callback configurations for any or all of the functions: getValue, setValue, enable, disable, show, hide, nullValue. An example initialization for an item P1_MY_ITEM is: apex.widget.initPageItem("P1_MY_ITEM", { getValue: function(){}, setValue: function(){}, nullValue: "%null%" });

    You would write suitable code for each of the functions shown to get and set the item values. In this example, the nullValue doesn't use a function; instead, it is a simple string value. The apex.widget.initPageItem function is located in the APEX installation files at apex\images\javascript\uncompressed\apex_widget_4_0.js. Further examples on its use can be seen in this file for some of the native APEX items. The Ext.form.ComboBox already has methods for getValue, setValue, enable, disable, show, and hide. Our task is to initialize a ComboBox with the Dynamic Action framework, so that any code associated with the APEX item name will be redirected to use functions referencing the ComboBox methods.

    [ 253 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    Before writing the JavaScript, it's best to build a testing harness so that you can validate your code as you go. The following screenshot shows the test page set up for this example. Each of the Dynamic Actions modifies all of the items in the region below.

    The Dynamic Actions created are summarized in the following table: Name

    When event

    When elements

    When condition

    Actions

    Set State

    Change (bind)

    P120_SET_STATE (Item)

    equal to: Enabled

    Enable: when true

    Set Item Display

    Change (bind)

    P120_SET_DISPLAY (Item)

    equal to: Show

    Show: when true

    Set Value

    Change (bind)

    P120_SET_VALUE (Item)

    is not null

    Disable: when false Hide: when false JavaScript Expression: $v('P120_SET_VALUE')

    The ComboBox plugin we have created is rendered by first creating a simple input text item and then using JavaScript to transform it into a ComboBox using the applyTo attribute. This becomes the logical place to call the apex.widget.initPageItem function.

    [ 254 ]

    Chapter 8

    By overriding the standard ComboBox, this change can be made in the application JavaScript library. Ext.override(Ext.form.ComboBox, { applyToMarkup: function(el){ Ext.form.ComboBox.superclass.applyToMarkup.call(this, el); // remove APEX applied class Ext.fly(el).removeClass('apex_disabled'); // get the Ext id for the component var x = this.getId(); // Register customized standard actions for the // originating DOM element. // Original element has been replaced with ComboBox. apex.widget.initPageItem(el, { getValue: function(){ return Ext.getCmp(x).getValue(); }, setValue: function(v){ Ext.getCmp(x).setValue(v); }, enable: function(){ Ext.getCmp(x).enable(); }, disable: function(){ Ext.getCmp(x).disable(); }, show: function(){ Ext.getCmp(x).show(); Ext.select(el + '-label').show(); }, hide: function(){ Ext.getCmp(x).hide(); // Hide label // Relies on using label templates, and label naming // convention. Could check parent TD for label element // for this el, and parent's prev sibling TD for // label also. Ext.select(el + '-label').hide(); } });

    [ 255 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions // trigger APEX DA event when value selected this.on('select', function(o, record, index){ apex.jQuery('#' + o.el.id).trigger('select'); }); } });

    The first few lines perform some basic housekeeping before we register our customized dynamic actions. Ext.override(Ext.form.ComboBox, { applyToMarkup: function(el){ Ext.form.ComboBox.superclass.applyToMarkup.call(this, el); // remove APEX applied class Ext.fly(el).removeClass('apex_disabled');

    The highlighted line executes the standard applyToMarkup functionality for a ComboBox, which doesn't reside in the ComboBox object, but resides a few levels up the object inheritance hierarchy in the Component object. APEX may have applied a apex_disabled class to the text item to be transformed into a ComboBox, so it is necessary to remove the class. We then fetch the ID of the ComboBox we are creating to use in subsequent function calls. // get the Ext id for the component var x = this.getId(); // Register customized standard actions for the // originating DOM element. // Original element has been replaced with ComboBox. apex.widget.initPageItem(el, { getValue: function(){ return Ext.getCmp(x).getValue(); }, setValue: function(v){ Ext.getCmp(x).setValue(v); },

    The apex.widget.initPageItem function is called, passing the original APEX item name in the el parameter, and defining the callback functions. Because Ext has existing functions to enable/disable, show/hide, and set values, our task is to redirect the code to the ComboBox using the Ext.getCmp(x) call to select the component. [ 256 ]

    Chapter 8

    Testing shows the ComboBox correctly performs the enable/disable and show/hide actions. The setValue function works correctly for the local ComboBox, but the following screenshot shows it does not retrieve the description for the AJAX ComboBox, which needs to retrieve the data remotely from the database.

    To fix this, a second override needs to be made to the standard Ext.form.ComboBox, this time modifying the setValue function. Typically, the override would be included with the earlier override, but it can also be applied separately as done here. Ext.override(Ext.form.ComboBox, { oneShot: false, setValue: function(v){ var text = v; if (this.valueField) { var r = this.findRecord(this.valueField, v); if (r) { this.oneShot = false; text = r.data[this.displayField]; } else { // do extra step for remote mode if (this.mode == 'remote' && this.oneShot == false) { this.oneShot = true; this.store.on('load', this.setValue.createDelegate(this, arguments), null, { single: true }); this.store.load({ params: { 'p_widget_num_return': v } [ 257 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions }); return; } else { this.oneShot = false; if (Ext.isDefined(this.valueNotFoundText)) { text = this.valueNotFoundText; } } } } this.lastSelectionText = text; if (this.hiddenField) { this.hiddenField.value = Ext.value(v, ''); } Ext.form.ComboBox.superclass.setValue.call(this, text); this.value = v; return this; } });

    This time the highlighted code contains the modified functionality. When the setValue function doesn't find the value cached in the JavaScript store, ComboBoxes with remote stores will make one attempt to retrieve the display value from the database via an AJAX request, setting this.oneShot = true; before loading the data returned for the value passed by the parameter p_widget_num_return. The store loads any returned records and executes the setValue function again using the createDelegate function. Refer to the following screenshot, and you will realize that the AJAX ComboBox now correctly shows the display value:

    If the display value was still not found, the ComboBox uses default functionality to show the valueNotFoundText text if configured, or the hidden value. Submitting this value to the server would result in a validation error. [ 258 ]

    Chapter 8

    Defining custom events for the ComboBox

    You can create custom events for plug-ins, allowing them to be exposed to dynamic actions. This allows the developer to create custom dynamic actions initiated by a plug-in to interact with other page items on the client. The following screenshot shows a custom event added for the ComboBox:

    The event is triggered by client-side JavaScript for the plug-in, so for our ComboBox the event would be added to the code as follows: Ext.override(Ext.form.ComboBox, { applyToMarkup: function(el){ Ext.form.ComboBox.superclass.applyToMarkup.call(this, el); // ***snipped*** // // trigger APEX DA event when value selected this.on('select', function(o, record, index){ apex.jQuery('#' + o.el.id).trigger('select'); }); } });

    Here, a listener has been added for the Ext.form.ComboBox select event, calling a function to trigger the apex.jQuery select event for the APEX item. The APEX Dynamic Action framework then executes any dynamic actions listening for the event. Note that the event name triggered is the internal name for the custom event.

    [ 259 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    The following screenshot shows a custom onSelect [Ext.form.ComboBox] event added to a ComboBox item. It has a single action associated with it, when the event is triggered, setting the value for another page item.

    The details for the Set Value action are: Identification Dynamic Action: set_numberfield Action: Set Value Execution options Fire when event result is: True Fire on page load: Unchecked Stop execution on error: Checked

    [ 260 ]

    Chapter 8

    Settings Set type: JavaScript Expression JavaScript expression: Ext.getCmp('ext-' + this.triggeringElement.

    id).getValue();

    Affected elements Selection type: Item(s) Item(s): P120_APEX_NUMBER_FIELD From the details of the Set Value action, the JavaScript Expression used for settings is slightly unusual. It relies on the naming convention that the ComboBox component ID is the APEX item name prefixed with ext-, something set up in the PL/SQL package for our plug-in ComboBox. Using the ComboBox component name, it returns the value of the ComboBox to the Dynamic Actions framework, which populates the affected elements with the value. This closes the loop for our ComboBox; it is now fully integrated to use standard dynamic actions, as well as triggering custom actions that can affect other page items.

    Summary In this chapter, we integrated the Ext ComboBox component into APEX. The ComboBox is a data-aware component that uses Ext Data Stores to hold record-based information in the browser client. The ComboBox utilizes all aspects of creating a custom plug-in, implementing render, AJAX, and validation callbacks. The plug-in makes use of many of the standard attributes available to plug-ins, taking full advantage of the built-in LOV functionality. It also uses custom attributes to expose additional parameters to the developer, as well as a custom event to be used by Dynamic Actions. The APEX provided PL/SQL APIs for plug-ins greatly sped up the development of the server-side functionality. On the client side, the Ext ComboBox component was able to be integrated with the Dynamic Actions framework using the apex.widget.initPageItem function to declaratively override standard dynamic actions to show/hide, enable/disable and get/set values.

    [ 261 ]

    Data Stores, AJAX-enabled Plug-ins, and Dynamic Actions

    The functionality was integrated using the Ext.override method to add custom code, and extend the existing functionality when setting values for ComboBoxes with remote data stores. We achieved a great deal in this chapter, covering many of the complexities of integrating Ext components into APEX. For our next challenge, we will look at integrating Ext JS GridPanels into APEX.

    [ 262 ]

    Getting Interactive with GridPanels GridPanels are, without doubt, one of the most powerful and most often-used components within the Ext framework. Even the most basic implementations of the GridPanel provide column management features including sorting, resizing, drag-and-drop column reordering, and show/hide columns. Data presentation is handled separately from data retrieval within GridPanels, with data retrieval done using a Data Store component. For GridPanels with paging and remote sorting enabled, changes made on the client browser, such as hiding or re-ordering columns, are automatically maintained when new data is loaded. As if that's not impressive enough, GridPanels support plugins (not to be confused with APEX Plug-ins), which allow additional functionality, such as expander rows and "Group By" header menu options, to be integrated. GridPanels provide a way for you to add functionality to your Classic Reports that's currently only available in Interactive Reports, with the added advantage that you can have multiple Classic Reports on one page. In this chapter we will cover: •

    GridPanel components: Data Store, Column Model, Grid View, and Selection Model

    •

    Key concepts for getting GridPanels into APEX

    •

    Creating a GridPanel Region Plug-in

    •

    Making a GridPanel Stateful

    •

    Using the GridPanel to convert Classic Reports

    Getting Interactive with GridPanels

    Components making up a GridPanel The Ext.grid.GridPanel brings together a number of other supporting components to present data in a tabular format. Those components are the Store, Column model, View, and Selection model. Let's take a look at standalone example of the GridPanel to see how these supporting components each play their part, before we attempt to integrate it into APEX.

    We will be going through the code for the GridPanel shown in the previous screenshot; it's also included in chapter09/ ex-9-simple-grid.html. The overall structure of the page is:
    <script type="text/javascript"> Ext.onReady(function() { [ 264 ]

    Chapter 9 /** details snipped localJsonStore, columnModel, gridView, selectionModel */ var grid = new id : store : colModel : view : selModel : height : width : renderTo : stripeRows : title : }); });

    Ext.grid.GridPanel({ 'my-grid', localJsonStore, columnModel, gridView, selectionModel, 260, 450, 'gridRegion', true, 'Commonwealth Games 2010 Medal Talley'



    The overall structure of our standalone page is really quite straightforward. The header includes the usual Ext library and CSS includes, and the body of the page contains a DIV region with ID of gridRegion, into which our GridPanel will be rendered. JavaScript code instantiates a new Ext.grid.GridPanel object,