APEX 5.0 Page Designer: Meet the Widgets

One of the primary things I worked on for APEX 5.0 is Page Designer. There have been a number of presentations and blog posts about what it is, how to use it, and how it increases productivity. What I want to talk about here is what Page Designer is made of. Page Designer was a huge undertaking and a number of people had their hands in it. I’ll focus on the parts I know best; the widgets.

If you are asking yourself, “Could my APEX application have pages as complex as Page Designer?”, the answer is Yes. The level of effort and skill needed is going to depend on what you are trying to achieve. The point is that Page Designer is not taking advantage of hidden or private APEX engine features. This doesn’t mean that all the building blocks of Page Designer are available for use in your applications but that the facilities are there for you to create and integrate your own building blocks. Knowing a little about the architecture of Page Designer may inspire you to create complex, highly dynamic and interactive pages in your applications.

First of all Page Designer is a normal APEX page. It is also an example of a very complex custom page. I say custom because it is not a simple form or report or something else you can choose from the create page wizard. One familiar with APEX might imagine that the page designer page contains many PL/SQL Dynamic Content regions with custom generated markup but that is not the case. It has just two and they are very small in both code size and amount of markup produced. Instead it uses a few specialized region templates and APEX plug-ins. The page is never submitted so the only processes it has are Ajax callback processes. Following best practices the processes simply make calls to PL/SQL packages where the business logic is implemented.

What really distinguishes Page Designer architecturally is the large amount of JavaScript code it has. As with any project in any language when you have a lot of code it is important that the code be well organized. Page Designer JavaScript code is organized into a data model layer, UI widgets, and controller code.

The data model layer provides controlled access to the application data. In this case it is the meta data that makes up the page being edited as well as shared component meta data. It also implements client side non-presentational business logic. Patrick was the main developer on the data model layer as well as the back end code to generate and process the data.

UI widgets are modular, reusable GUI building blocks encapsulating state, visual structure, behavior, and style. On web pages widgets are implemented with JavaScript. Different frameworks each have their own way of coding widgets. The jQuery UI framework has a nice foundation for creating widgets and since APEX already uses jQuery UI it makes sense for us to leverage it. Most of the new widgets in APEX 5.0 use the jQuery UI widget factory. APEX pages are not built directly out of widgets. The best way to make use of widgets from APEX is to wrap them in an APEX region or item plug-in and possibly along with dynamic action plug-ins. For widgets that augment existing markup it is also possible to make use of them by creating an APEX template and then including a little bit of initialization JavaScript code.

The controller code is what ties it all together. There is an overall page controller as well as controllers for the different areas of Page Designer such as trees, grid layout, and property editor. The controllers respond to events or model notifications and take appropriate actions; calling model or widget methods. Controller code implements presentational business logic. In a typical APEX page dynamic actions perform the role of controller. However in Page Designer there is so much controller logic that it is more efficient to put it all in JavaScript files. Unless you find your self dealing with a similar level of complexity as Page Designer you should continue to use dynamic actions because they are simpler and more declarative. All the Page Designer specific JavaScript is loaded in the standard way using the page’s JavaScript: File URLs attribute.

In previous APEX releases the directory images/libraries/apex contained documented APIs, and built-in widgets like interactive reports and shuttle item as well as code for the internal applications like Application Builder. With APEX 5.0 this has been cleaned up. Now the internal application code has been moved to images/apex_ui/js. You should not use any of the code under apex_ui as part of your applications. However, if your curious about how the builder UI does something feel free to take a look.

While creating new widgets we decided to put them in libraries/apex or apex_ui/js by answering the question “is this general purpose and something we foresee many of our customers wanting to use now or in the future?” If yes put it in libraries/apex otherwise apex_ui/js. I need to stress that just because code is in libraries/apex doesn’t mean that it is supported for you to use in your APEX apps. This folder contains a mix of documented supported APIs, legacy code, code used internally by APEX, and code that may be documented in the future but isn’t yet. More importantly this is my understanding of how the code is organized and not any official Oracle statement of support.

The rest of this post provides a little overview and information about each widget that makes up Page Designer and says if it is Application Builder specific or if and how it is available for you to use in your applications.

Menu widget

File: libraries/apex/widget.menu.js
The menu widget implements both popup menu and menu bar UI that is common in desktop applications. It follows the WAI-ARIA menu and menu bar design patterns. Popup menus can be opened by buttons or as a context menu with the mouse or keyboard. The menu bar has a few features not found in desktop apps. Specifically:

  • Current menu item: the current menu item has a distinct style to indicate that the current page is found under or related to that menu item.
  • Split menu item: this allows a menu bar item to take an action or drop down depending on where it is clicked (or with the keyboard if enter or down arrow is pressed).

These features were added to support previous APEX drop down tab behavior.

Before the 5.0 release APEX had a few different (mostly unsupported) menu implementations and each of them had limited functionality and various usability and accessibility issues. Now in 5.0 all APEX menus have been replaced with the same full featured, usable, accessible menu widget initially created for Page Designer. It is also used in interactive reports and web sheets.

The APEX 5.0 Universal Theme Navigation Menu feature uses the menu widget when navigation Position is set to Top. The Universal Theme includes list templates: Menu Popup, and Menu Bar that you can also use to add list driven menus in your application.

Tree View widget

File: libraries/apex/widget.treeView.js
The tree view widget implements the familiar tree UI. It follows the WAI-ARIA tree design pattern. This widget was created to replace the third party jsTree library, which no longer worked with the latest jQuery version and had usability and accessibility issues and old fashioned style. The APEX tree region was updated to use the tree view widget. It is not possible to automatically migrate old tree regions that use jsTree because they could include custom JavaScript code that called the jsTree API. All the places in the APEX internal apps and web sheets were updated to use the new tree view (APEX Tree). As you can see from Page Designer the tree view has a lot more functionality than is used by the tree region. I hope to cover more details about tree view in a future blog post.

You can use the tree view in your applications by using the standard APEX tree region. Also the APEX 5.0 Universal Theme Navigation Menu feature uses the tree view widget when the navigation Position is set to Side.

Icon List widget

File: libraries/apex/widget.iconList.js
Icon list is a 2D grid select list. The Grid Layout region, item, and button galleries are made up of icon list widgets. It is also used in some of the wizards. Icon list doesn’t directly support tooltips or drag and drop. For this jQuery UI tooltip widget and draggable interaction were used respectively. This widget is not officially supported but I have already shown how it can be used.

Splitter widget

File: libraries/apex/widget.splitter.js
The splitter widget is for dividing and adjusting the available space between two regions either horizontally or vertically. It has an option to collapse and expand to one side. It follows the WAI-ARIA window splitter design pattern. You can use the [Shift+]Ctrl+F6 keys to move to the previous or next splitter. It was originally created for Page Designer but it is also used in a few places in SQL Workshop. This is a case where a builder specific region plug-in is used to simplify the use of this widget from APEX. This widget or the plug-in is not officially supported. The biggest problem in doing so is that it works best when the web page is sized to exactly fit in the browser window. APEX pages have always scrolled as needed. I hope to describe the splitter and resizing the page to fit the browser window in more detail in a future blog post.

Tabs widget

Tabs are used in several places in Page Designer; the tree area, the center area, the grid layout gallery (these are styled differently but are still tabs) and even above the property editor is currently a single tab. We use the jQuery UI tabs widget. Although there has never been an official template (or region plug-in) based on jQuery UI tabs there is nothing stopping anyone from creating one since the jQuery UI library is included with APEX. Page Designer uses specific region templates and controller code to integrate with the tabs widget.

Dialog widget

Page Designer has many dialogs. Some use the new APEX 5.0 modal dialog page feature (Page Mode = Modal Dialog) for example the Create Form wizard. Others use a dialog region that is similar to, but not the same as, the Inline Dialog region template from Universal Theme. An example of this is the Lock Page dialog. The remaining dialogs are created directly from JavaScript code. For example the dialogs that open from the property editor fall into this category. No matter the source of the dialog or how it is controlled they all use the jQuery UI dialog widget. It is possible to use jQuery UI dialog widget directly from JavaScript code in your application but I don’t recommend it. If you are tempted to do so I recommend looking at the dialog code in libraries/apex/theme.js to get an idea of the various situations you may need to deal with. Now it is much simpler and better to use modal dialog pages or inline dialog regions depending on your needs.

The remaining widgets are all APEX specific and only intended for use by the APEX internal applications.

Grid Layout widget

This widget implements the APEX page layout UI in the Grid Layout tab. Even though the widget is abstracted away from the page data model it is still, out of necessity, very specific to APEX page layout. It is not a general purpose widget for moving boxes around. It uses the jQuery UI mouse mixin as part its own drag and drop logic. It also has a draggable plugin so that components from the gallery can be dropped on it.

Property Editor widget

This widget is responsible for editing all the properties (or attributes) of a component. It is completely meta data driven. It doesn’t have any hard coded knowledge of specific components such as chart regions or select list page items. It knows how to handle specific data types such as text, Boolean yes/no, JavaScript code etc. Each component or control including developer provided plug-ins has meta data that defines each of its attributes. This meta data includes its data type, group, label, and everything else the property editor needs. Anthony was the main developer of the property editor.

Code Editor widget

This widget is a wrapper around the CodeMirror text editor. The widget has a number of features to integrate with APEX including launching Query Builder, PL/SQL auto complete and validation. The code editor is also used from many places in the Application Builder and SQL Workshop. An APEX item or region plug-in is used to add code editors to these other APEX pages. The page designer doesn’t use the plug-in it uses the widget directly. Patrick and I both worked on the code editor. We don’t foresee many customers needing to provide a code editor as part of their app. If you need something like that the best thing to do is create your own APEX plug-in that uses the CodeMirror library that ships with APEX.

Summary

There are also a few minor widgets created just for Page Designer. These are for the Page Search tab, Messages tab and a specialization of jQuery UI dialog for list of values dialogs. Patrick and Anthony created these. We also make use of the jQuery UI tooltip Widget.

As you can see the effort that went into making Page Designer has a positive impact well beyond it. The Navigation Menu feature uses either the tree or menu widget. You can include menus, trees, and dialogs in your applications. The code editor, icon list, and splitter are used in many other places in the APEX builder. And this is just the widgets. Many other little details that first came up during the design and implementation of Page Designer have made APEX 5.0 a better product over all.

2 thoughts on “APEX 5.0 Page Designer: Meet the Widgets

  1. Fantastic blog.. Very informative.. Will have to come back again and re-read since there is a TON of information about the page designer..

    Thank you,

    Tony Miller
    LuvMuffin Software
    Salt Lake City, UT

Comments are closed.