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.
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.
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
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
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.
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
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
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.
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 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.
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
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.
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.