Building a Query Portal – Part 1 (Portal and UI Map)
By ACShorten on Apr 18, 2011
One of the most powerful components of the Oracle Utilities Application Framework is the ability to build functionality without having to resort to java code (or even in COBOL for older products). The concept in the Oracle Utilities Application Framework is Configurable Objects.
The idea is simple. Customers and partners can extend base objects and functionality in the product using configuration to alter the product to suite their needs. One of the many features of this facility is the ability to build Query Zones. These zones are commonly akin to a customizable search and allow custom zones to be implemented.
In this series, I will illustrate this concept with an example I was given a few weeks back on a custom set of zones a customer was using to track To Do's in their implementation. The design is to allow the site to specify various filters on the To Do for a time period to determine the statistics overall and the statistics with the time period to help the user asses how the business is going with the processing of To Do records.
Note: The zone I will build was built using Oracle Utilities Application Framework V4.x, but should be able to be built using earlier versions of the Oracle Utilities Application Framework. Some options shown or discussed may not be available for earlier versions of the Oracle Utilities Application Framework. Alter as necessary.
An example of the finished zone is shown below with some sample data from a demonstration database.
The user can search for records based upon To Do Type, To Do Role and Priority between two dates. They can also suppress To Do entries that have a status of In Progress.
Now before we get into the first part of the design process I want to ensure you understand a few basic concepts:
- Query Zones basically execute SQL statement(s) with the appropriate filters.
- A zone has a zone type which determines how it is processed. The Oracle Utilities Application Framework ships with a set of zone types for particular purposes.
- A zone is housed in one or more portals. A portal can also contain one or more zones.
- Zones and Portals are subject to security just like any other object.
- The order of zones in a portal can be specified on the user or the portal (the latter is only supported in Oracle Utilities Application Framework 4.x or above).
- Portals are attached to navigation options which can in turn be associated with menus.
The first part of the process is really setting up the Portal ready for the zone. To do this, navigate to the Administration Menu -> P -> Portal+ menu item and add a custom Portal to house the zones in. An example is shown of this below:
You can add the Navigation Option to a menu, by selecting the "Add to Menu" option and selecting the appropriate menu (Submenu as well) to house the function. The Oracle Utilities Application Framework will generate a generic Application Service entry to use for security. To give users access to this portal you need to navigate to the User Group and add that service with the appropriate permissions. If you are using the Oracle Utilities Application Framework V4.x and above, if you click on the service name, you can use the new Application Service, Application Service portal to add the service with a few clicks. An example of this is shown below:
Once the portal is created we can start on the zone. The idea now is to create a Query Zone with the appropriate filters. Now, commonly you can specify the filters on the Query Zone specification but the layout of the fields is determined by the Oracle Utilities Application Framework. To make it look a bit more pleasing I am going to create a UI Map to house the filters. This is what the base product does to make the interface more consistent.
The filters I am going to need for the SQL are the following:
- To Do Type - I will need to use a Drop Down menu to allow people to select a valid To Do type from a list if desired.
- To Do Role - I will also use a drop down list of valid To Do Roles in the product, if desired.
- To Do Priority - I will need to also provide a drop down list for this one. In the Oracle Utilities Application Framework, flags are considered "Lookups". More about this later.
- Suppress In Progress - As the analysis is really about clearance rates, I will allow the users to ignore To Do records in progress.
- I want the user to specify a date range to compare the information. If dates are not supplied then all the records will be displayed. There will be start and end date fields (date format is taken from the users preferences).
To create a UI Map for the filters, I need to navigate to the Administration Menu -> U -> UI Map+ menu option and add the UI Map with the correct code. I used a sample already existing and modified it for my needs. The code is shown below (with the schema):
This HTML is basically a two column table with the following attributes:
- I added the ERRMSG-TEXT header to hold any error messages from the product.
- All the labels are Meta Data fields (even added custom ones). Why? Well, if you do not use meta data tags for labels then the zone is not multilingual. The implementation can add tag values for the meta data tags in multiple languages and therefore can be used by users across multiple languages. The tags of the correct language on the user profile is used, if the language pack is loaded into the product.
- For To Do Type and To Do Role fields I used a table based oraSelect tag to select data from their Meta Data Tables.
- For the To Do Priority and Suppress In Progress fields I used a lookup based oraSelect tag to select data from the lookup tables. The lookup table call uses the field name to get valid values (as well as the users language).
- For the Start and End Dates I used generic date fields and found some existing meta data tags that held the correct labels.
When I test the UI Map I get the desired results:
I can make the HTML better looking but I am happy with the results.
Note: The date fields automatically add the date lookups to pop up a calendar. This automatic addition of this information is one of the new features in Oracle Utilities Application Framework V4.x.
This is the end of the first part of this series. The next part, due soon, will build the zone that uses this filter UI Map and be attached to the portal to complete the zone definition.