If you elect to copy a theme from another application, select Yes when prompted to Copy Shared Components from Another Application, and then select User Interface Themes, as shown in Figure 10-2.

Figure 10.2. Copying a theme

On the next screen, you can select which theme to copy (if the application contains more than one) and whether to validate the theme, as shown in Figure 10-3. Validating the theme will inspect it to ensure that all template classes have been defined. Your choice of whether or not to validate the theme depends on how many and which types of templates you need.

Figure 10.3. Selecting a default theme and validation rule

If you choose to use a prebuilt theme, you will be prompted to select one of the 20 themes before completing the application-creation wizard.

When you choose a built-in theme, a copy of that theme will be added to your application. Any changes or modifications that you make to the templates in that theme will not be propagated back to the master copy of that theme. Thus, feel free to experiment with altering the templates of the built-in themes, as you can easily restore a clean copy of the original theme. You will always get a clean copy of a theme when adding it to your application.

The Application Templates report simply lists each template associated with a specific theme or with all themes in your application. Clicking any of the template names will bring you to the Template Details page, where you can make changes to the individual templates.

Each template has the following two major attributes:

You'll learn more about template types and classes in the "Understanding Template Types and Classes" section later in this chapter.

The Theme Template Counts report displays every possible iteration of template types and classes with a count of each. If the Show Custom check box is checked, the report will also include all of the custom classes. None of the APEX built-in themes contain any templates associated with a "custom" class, so expect to see a 0 for the Template Count for any template that starts with "Custom" when viewing a report for a built-in theme.

The File References report is aimed at making it easy to discern which files are referenced throughout the templates, shared components, and page components of an application. It allows the developer to search for a number of commonly used file extensions (.gif, .jpeg/.jpg, .png, .js, .ico, .swf, and .css) and identify which template, shared component, and/or page component references those types of files.

Files can be displayed with or without context.

When using either option of this report, there is one thing to consider: it will not identify any files of any type that are generated as a result of a named PL/SQL program unit. You will need to search for files in your named PL/SQL program units—packages, procedures, and functions—separately.

The Class References report functions in almost the exact same manner as the File References report does, but locates Cascading Style Sheet (CSS) class references as opposed to file references.

As with the File References report, the Class References report does not search any named PL/SQL objects for CSS class definitions. It also does not search any CSS files that may be in the file system of the Apache webserver (if you are using a separate HTTP server).

This report searches for and identifies CSS classes, not the template classes that were previously mentioned. They are two very different and distinct constructs.

The Template Substitution Strings report will identify all possible, probable, and actual usages of substitution strings found in a given theme's templates. This report has limited practical use, as it attempts to combine possible values with actual values, and when used with the built-in themes, contains a lot of repetitive data.

The simplest of the theme attributes, Name allows you to change the name of your theme. Only developers will see the name of a theme; end users will not see this value anywhere in an APEX application.

The Component Defaults section, shown in Figure 10-8, allows you to specify a default template when new components are added to your application via the APEX wizards. Defaults that are assigned to APEX components can always be overridden when creating or modifying components in the Application Builder.

Figure 10.8. Mapping templates to components

Similar to Component Defaults, the Region Defaults section, shown in Figure 10-9, allows you to specify which region templates to use when creating regions with the APEX wizards.

Figure 10.9. Specifying default region templates

APEX themes will have at least one region for each type of page component: report, form, chart, calendar, and so on. While this approach gives you maximum flexibility for your template design, it can add unnecessary complexity and actually make your application's user interface harder to manage.

In most applications, there is no difference between the appearances of region templates for charts, reports, forms, and calendars. In fact, you can assign the Chart Region template to a Form region and vice versa. No validations are performed when assigning templates to regions. Thus, there is little reason to have four separate templates—one for each component type. In fact, having four templates makes managing your templates four times as difficult.

You can consolidate even further by removing rarely used region templates from your theme. Some of the less popular region themes include all of the Alternative 1 regions, both Button regions, the Bracketed region, and both Wizard regions. See the "Removing Unused Templates" section later in this chapter for the case for getting rid of unused templates.

The Calendar Icon Details attribute allows you to change the default icon used when rendering a date-picker item. By default, the date picker will look something similar to the one shown in Figure 10-10 (results will vary based on which theme you use).

Figure 10.10. The default date picker

This option allows you to override the standard icon and use a custom image to represent a date picker. While this option is rarely used, it is nice to know that it does exist and where to find it.

By default, the Templates subtab, shown in Figure 10-11, lists only templates for the theme that you are viewing. By using the Theme select list, you can select a different theme (if one exists) or see all templates associated with any theme in your application.

Figure 10.11. The Templates subtab displaying only page templates. The default page template is indicated with a check mark.

You can further refine the report with the Show select list, which lets you select a template type. This select list will filter the report based on a specific template type: page, region, label, list, popup list of values, calendar, breadcrumb, button, or report. Using the Show select list comes in quite handy when editing a single type of template.

Another filter is the Referenced select list, which has three choices: All Templates, Templates Referenced, or Templates Not Referenced. This filter is particularly useful when determining which templates can be removed from your theme without impacting any existing pages.

Regardless of the filter settings, you can do one of three things with any template: preview it by clicking the stoplight icon, edit it by clicking its name, or copy it by clicking the copy icon.

Template Previews

Page, region, and report templates have an additional option: Preview. Clicking the preview icon, which will be available for only these three template types, will display a rough preview of what that template will look like when rendered in your application. This preview is intended to illustrate the structure of a template, rather than show exactly how it will appear in an application. There is no way to see how a template will really look aside from actually running it in an application.

The page template preview will give you an understanding of how the core structure of the page is designed by rendering all of the substitution strings and region positions found in a given page template. It will also attempt to lay out these items in the same way that the actual page template will place them. Some user interface components will be included, but most will not. Figure 10-12 shows an example of a Two Level Tabs Page template.

Figure 10.12. The preview of the Two Level Tabs Page template from Theme 12

Region template previews will render more information about a specific region template, but offer an even cruder view of how the template will look. In addition to the Title and Body tokens, each button position will be rendered as part of the preview. Immediately following the visual preview, a list of substitution strings and whether or not they are referenced is displayed. This list will give you a quick summary as to which button positions are referenced in the region template. Finally, the actual source of the region template is displayed on the page in a read-only fashion. Figure 10-13 shows an example of a Form Region template.

Figure 10.13. The preview of the Form Region template from Theme 12

The report preview is perhaps the roughest of the bunch. Aside from where the report template is based on named or generic columns, only the core structure of how a report template will render is provided. Each preview uses only four columns when constructing the preview. As rough as this preview may be, it does give you an idea of the basic underlying table structure of a report template. Figure 10-14 shows an example of a Standard Report template preview.

Figure 10.14. The preview of the Standard Report template from Theme 12

Template Tasks

The Templates subtab also displays the Tasks region (it does not appear on the Utilization, Subscription, Publish or History subtabs), as shown in Figure 10-15. The Theme Reports option, will take you back to the associated reports for a given theme.

Figure 10.15. Template tasks

The other tasks are a bit more complex. "Replace templates in this application with templates from another application" does, well, just that. Instead of switching an entire theme, you may need to copy over some individual templates from one application to another. This item will facilitate such a copy. First, you will need to select the application from which you want to copy templates. Next, you can map which templates will be replaced with the new selections. Templates can simply be copied over or copied over and subscribed to (see the "Template Subscriptions" section later in this chapter).

The "View page template region position utilization" option displays a report of which region positions contain content based on page templates.

The Utilization subtab, shown in Figure 10-16, gives you a slightly more detailed, but inconsistent, view of which templates are being used in your application. If a template is being referenced in your application, this subtab will display a count of how many times it is referenced. Some template types will provide a link to the page where the template is used; others will not. You can get a better view of which templates are being referenced from the Templates subtab.

Figure 10.16. The Utilization report for page templates

The Subscriptions subtab, shown in Figure 10-17, contains a report of which templates are subscribed from another application. Any or all subscriptions can be refreshed from this report by checking the corresponding template and clicking the Refresh Checked button. Subscriptions are discussed in more detail in the "Templates Subscriptions" section later in this chapter.

Figure 10.17. The Subscription report for templates

For a historical view of who made the most recent modification to either page or region templates, take a look at the History subtab, shown in Figure 10-18. Historical changes for templates of other types are not tracked by APEX. This report will show only the last person to edit a specific template and how long ago that change occurred; specific changes and multiple edits are not tracked by APEX.

Figure 10.18. Recently updated page templates shown on the History subtab

In APEX, it is possible to upload and store images or CSS files in the database. While this method is convenient and simplifies deployment, it is not recommended in many cases, as it will potentially degrade the overall performance of your applications. If you are using the Embedded PL/SQL Gateway, the easiest way to handle images is to store them in the database. You can use the filesystem of the database server to store images, but you would have to build a custom PL/SQL procedure to access them.

When an image is uploaded to the database, it is stored as a Binary Large Object (BLOB) in a shared table called WWV_FLOW_IMAGE_REPOSITORY. This table is segmented so that files are secured from other workspaces. When accessing a file from this table, you can use either the #WORKSPACE_IMAGE# or #APPLICATION_IMAGES# syntax, depending on how the image was uploaded. When your page renders, APEX will translate either of those tokens with a call to the APEX function wwv_flow_file_mgr.get_file. This, in turn, will query the database for your file and then send it over the network to the client.

Images can be classified into two types based on their usage: template images and content, or "transactional," images. The type of images is based on how it is used; APEX makes no distinction between the two. Template images are those that make up the actual template of an application. Tab corners, logos, and images used to construct the borders of a region are good examples. Content images are those that are associated with an item in your data. A picture of a product is an excellent example of a content image.

Content images can be stored in the database, and in some cases, this is a better solution. This is because content images are not rendered on every page of an application; they are rendered only when requested. Think of a web site based on a catalog of music. Content images are rendered only as each user searches for different types of music and views album artwork. You will (or at least should) never have a single page that always renders all content images.

There is no simple metric that you can inspect to determine where to store content images. You can consider a number of variables, and then make an educated decision. If you anticipate a very high volume of transactions, you may want to consider storing your content images in the file system and storing a pointer to the corresponding image in the database. If a good portion of your target audience is connected via slower connections, the file system makes more sense as well, as each client will cache your images, so in the case of a repeat request, it will not need to query the database and send the image again.

On the other hand, if you anticipate a lower volume of transactions, and want to simplify the overall management of your site, you may opt to store content images in the database. This way, you will not need to rely on a system administrator to grant you access to the HTTP server. Also, when the DBA backs up your schema, all of the content images will also get backed up.

As an example, let's assume that you use a small image to make up the right corner of a noncurrent tab. Let's also assume that your application has five tabs, any four of which can be noncurrent. Thus, for each page in your application, you will need to render this image four times. If you have 100 users using your application, each with 20 page views, the procedure that calls the tab image stored in the database will be executed 8,000 times per day! (100 users × 20 page views × 4 tabs per page). A single week will yield 40,000 calls to the same procedure for the same image. Now what if you have a different image for the left side of a tab? Double the calls to the same procedure, for a new total of 80,000 executions per week—just for the tab images!

Still assuming that you get 2,000 page views per day, and adding the assumption that each tab image is 2KB to the equation, you will generate about an additional 16MB of network traffic per day, or almost 80MB per week! (2,000 page views × 4 tab images × 2KB each image). And again, this is just to render the tabs.

As if this isn't bad enough, the URL format that APEX uses with images stored in the database is executed as if it were a call to a procedure each time it is encountered. If we leave the browser to its own devices, it will never refer to its local image cache before pulling the image from the server for images stored in the database. For more details on static file storage, see the "Image, CSS, and JavaScript Storage" section coming up shortly.

While HTML controls the structure of a page, CSS files are often used to control the user interface or style of a page. Think of HTML as the foundation, frames, and drywall, and CSS as the paint, trim, and carpeting.

It is a good idea to keep all styles in CSS files, and rely on HTML only for the core structure of a template. This will provide a few advantages. First, it will keep your HTML lean and easy to read. This will aid in the overall manageability of your applications. Second, keeping all style definitions in a CSS file is more efficient. Styles need to be defined in only a single place, and if a change is required, it can be quickly and immediately applied.

But perhaps the most important reason to put all style definitions in a CSS file is for Section 508 compliance. In the United States, the Rehabilitation Act was amended in 1998 to ensure that those with limited or no vision can still use computers as effectively as others. In a nutshell, this means that any web application needs to adhere to a set of standards that make it compatible with either high-contrast colors and large fonts and/or screen readers.

In either case, the necessary modifications require the separation of the structure of the user interface and the style. Thus, if you use CSS files to control the style, your application will be easier to make compliant with Section 508.

You may include JavaScript with an APEX application in a number of places: in a page header, as a static or dynamic region on a page, or in a static file referenced as part of the template. Typically, JavaScript libraries contain a number of functions that a developer can refer to from an APEX page, component, or item.

All APEX pages will automatically include five built-in JavaScript libraries: apex_4_0.js, apex_legacy_4_0.js, apex_widget_4_0.js, apex_dynamic_actions_4_0.js, and jquery-ui-1.8.custom.min.js. These libraries contain a number of prebuilt functions that are used in APEX itself, as well as in applications created by APEX. While most of these functions are undocumented, there are plans to provide more documentation in a future release of APEX. Should you wish to take advantage of some of these functions, it may be a good idea to copy them to a custom directory and then refer to them there. This will ensure that when the next release of APEX is applied and some of the functions are changed or removed, your applications will not be impacted.

To investigate the impact of where files were stored, we created a simple APEX application with five tabs and pages, using Theme 12. We then copied this to a new application, where all references to the tab images stored in the file system were replaced with references to the exact same images stored in the database as shared components. Using Mozilla Firefox with the Firebug extension (www.getfirebug.com), we loaded each page with image timings enabled.

We performed the first test with the application whose images were stored in the database. The total time to render these images was 152 milliseconds (ms), as shown in Figure 10-19. What is more important to note is that only 2KB out of 8KB, or 25% of the images used, were retrieved from the cache. A full 75%, or 6KB, were retrieved from the database server. Of the 2KB retrieved from the cache, neither file was part of the changes we made to the templates—e.gif is the embedded edit link, and is burned into APEX, and ParentTabBase.gif is referred to in the associated CSS file.

Figure 10.19. The results of loading templates images stored in the database

When we ran the same test on the application that stored its images in the file system, it took only 139 ms to render the images, as shown in Figure 10-20. In the grand scheme of things, this does not represent a significant savings. However, 100% of the images used were retrieved from the image cache! Not a single round-trip to the HTTP server or call to the database was necessary to render the images. This cost savings are drastic when the results are scaled up to more complex pages and/or more page views.

Figure 10.20. The results of loading templates images stored in the file system

The moral to this story is to put all images, CSS files, and JavaScript libraries that will be referred to frequently in the file system. The performance gain is far worth any extra effort required to manage these files.

Despite the obvious gains, there is one drawback to storing files—particularly CSS and JavaScript libraries—on the file system. When a change to a file is made, a browser may not immediately see that change, as it will refer to the cached version instead. In order to prevent this, you may want to append a version number to your CSS and JavaScript files. Each time you make a change to the file, change the name of the file to reflect a new version. This way, when a change is made, the browser will see a completely new file and always pull it from the server rather than use a cached version.

It is clear that storing files in the file system of the HTTP server is much more efficient than storing them in the database. But where on the HTTP server should these files be stored? One place that they should not be stored is the APEX images directory, commonly aliased as /i/. The files in /i/ are controlled by Oracle, and they can change or be renamed at any time. For example, suppose that you created a new CSS file called main.css and put it in the virtual directory /i/. Now suppose that Oracle releases the next version of APEX, and has decided to rename one of its CSS files to main.css. During the upgrade, you simply copy over the new images directory. All of a sudden, main.css is a completely different file, and your version is lost forever.

While copying your own files to /i/ is bad, referring to images, CSS files, or even JavaScript in /i/ can be equally as dangerous. If you have taken the time to examine the contents of the /i/ directory, you will have seen that it contains a wealth of images and JavaScript libraries. You may even be using some of these images and/or JavaScript libraries in your own applications. The danger in that is that if Oracle decides to change the contents of an image or JavaScript file, your application will also unintentionally change as well.

The recommended best practice for storing CSS, JavaScript, and images on the HTTP server is to use a completely different physical and virtual path. This way, your custom directory will be completely isolated from any changes that Oracle may decide to make, ensuring the integrity of your contents.

In keeping with APEX's tradition of simplicity, create a virtual directory called /c/, map that to a physical location on the HTTP server, and then upload your content there. Creating a new virtual directory is quite simple. All you need to do is add a single line to the httpd.conf file and restart the Apache server. For example, if you wanted to alias /c/ to the physical path /usr/local/custom_images, you would add the following line to your httpd.conf file and then restart Apache:

alias /c/ "/usr/local/custom_images/"

As simple and safe as this process is, you will typically run into resistance when you ask the system administrator to actually do it. Most system administrators don't like the idea of giving anyone access to anything. Thus, your challenge will be to convince the administrator that all you need is an operating system user that can read and write to a single directory, and do nothing else. Explain the savings in bandwidth that will be realized by moving images to the file system, citing the previously mentioned examples. Get the DBA's support, and approach the system administrator together as a united front. And if all else fails, find out her favorite restaurant, coffee spot, or retail store and include a gift card with your request.

The template source is where you can put everything together to make up your user interface. Images, CSS files, JavaScript libraries, and HTML are all molded into a single place in the template itself. In addition to referencing content in the file system, all templates have a number of substitution strings or tokens that can also be embedded in the template source.

There is nothing special or proprietary about the HTML used in APEX templates. In fact, it may help you understand how templates are structured if you copy and paste the source of a template into an HTML editor. This will show you a rough representation of how the template will look when rendered in APEX.

Breadcrumbs were formerly called menus in previous versions of APEX. They are typically found at the top of the page and help facilitate navigation. Their name is derived from the Brothers Grimm fable Hansel and Gretel, where the main characters leave a trail of breadcrumbs to mark their way back home. Unlike the ones in the aforementioned fable, birds will typically not eat APEX breadcrumbs, so you can feel quite confident when using them in your application.

Breadcrumbs can be either current or noncurrent, and the structure of the template reflects that. The template provides attributes for some HTML to open and close the breadcrumb. Finally, there is a place to define which character or characters will be used to separate the breadcrumbs.

Most of the APEX themes will enclose the breadcrumb in a DIV region, thus using <div> for the region Before First attribute and </div> for the After Last attribute. If you are not comfortable with this approach, you could opt to use <table><tr> and </tr></table> in lieu of DIVs. Just remember to enclose the breadcrumb entry in a <td> and </td> if you elect to use HTML tables.

Although it is rare, sometimes a template will allow you to specify how an APEX component behaves. In the breadcrumb template, the Maximum Levels attribute is an example of this. Once the breadcrumb has expanded to this level, no additional levels will be rendered, no matter what. It is a good idea to keep this value artificially high, so you never accidentally run into this limitation.

In theory, the breadcrumb link attributes should render inside an anchor tag. However, it seems as if this functionality does not quite work. If you do need to define attributes of an anchor tag, you can simply do so directly in-line in the Current Page or Non-Current Page Breadcrumb Entry attribute.

#NAME# and #LINK# are the most commonly used tokens with breadcrumbs. Alternatively, you can also reference #LONG_NAME# to render the long name, as per the breadcrumb entry definition.

APEX supports three types of buttons: HTML, image, and template. It is best to create and stick to a single button template in your applications. HTML buttons will look different on different browsers and different operating systems, as illustrated in Figure 10-21. Using them will produce slightly different-looking user interfaces for each operating system and browser combination that your user base has. This can cause some pages to look different from how they were intended to appear and lead to confusion.

Figure 10.21. The same HTML button rendered in Internet Explorer 8, Firefox for Windows, Firefox for Linux

Using image buttons as your default button type should also be discouraged. Not only will they generate additional overhead that needs to be sent to each client, but they are also difficult to maintain. For example, if you have a button called "Save Changes" and want to change it to Apply Changes, you will need to re-create the image and upload it to the server. Any image that contains words is also not Section 508-compliant unless it has a corresponding title tag, so use image buttons with discretion.

Template-based buttons give you the best of both worlds. You can use CSS to create an attractive-looking button and also retain full control over what it says, changing it as often as you like. Creating a template-based button is quite straightforward, as it is the simplest type of template. You can change only a single region for a template-based button. Like breadcrumbs, buttons can be either DIV-based or table-based.

The #LINK# and #LABEL# tokens are the most important to note with buttons. #LINK# will be substituted to the button's corresponding link, if it has one. #LABEL# will contain the name of the button, per the APEX definition in your application.

A button template can be as simple as the one shown in Figure 10-22. All of the style for this button is defined in the CSS class called button-gray.

button.button-gray {
        background: url(../images/bt-gray-r.png) right no-repeat;
}

Figure 10.22. A sample button template

While all of that may seem like a foreign language, rest assured that a number of CSS editors are available, and they make editing CSS classes a breeze.

Region templates are twice as complex as button templates, meaning that they have two attributes that can be defined: the template itself and the HTML table attributes. Figure 10-23 shows an example of a region template.

Figure 10.23. A sample region template

Region templates must at minimum contain a #BODY# token, which will be substituted with the contents of the region it is associated with: a calendar, report, form, chart, and so on. In addition to the #BODY# token, it is quite common to also incorporate a #TITLE# token in a region template. This will be replaced with the title of the region at runtime.

Most, but not all, regions will also contain a number of button positions. These button positions will be available when creating buttons that are bound to a region position. APEX has several predefined button position names. You cannot add your own to this list. Currently supported button positions are #CLOSE#,#PREVIOUS#,#NEXT#,#DELETE#,#EDIT#,#CHANGE#,#CREATE#,#CREATE2#,#EXPAND#,#COPY#, and #HELP#. Most regions from the APEX built-in themes will include most (or all) of these button positions.

Similar to template classes, the names of button positions do not necessarily need to represent their content. You can have a button called Create and assign it to the #HELP# position, as APEX does not check to see if the purpose of the button and button position match.

To keep things simple, it is not a bad idea to have only a couple button positions, and then rely on the sequences of individual buttons to control how they render on a page. This allows you to control button layout at the page level, rather than at the template level. It also offers more flexibility, as you can sequence buttons differently on a page-by-page basis, all with a single button template.

If you want to control the class of the items within a region, you can define it in the HTML table attributes. This class will then be applied to all items within a specific region.

Continuing with the trend of exponential complexity, label templates are twice as complex as region templates, with a total of four editable attributes. There are a pair of attributes for each label template itself and for the label template that displays when there is an error.

Unlike with button or region templates, you do not need to define a token for the content. There is no #LABEL# token, as APEX will automatically append that between the Before Label and After Label attributes.

Most of the prebuilt APEX themes have four types of label templates: Required, Optional, Required with Help, and Optional with Help. The Required and Optional label templates are the simpler types; clicking them will yield nothing. The Required with Help and Optional with Help label templates will open a pop-up window and display any help associated with their respective item. Figure 10-24 shows an example of a Required with Help label template.

Figure 10.24. A sample Required with Help label template

In any case, it is a good idea to start any label template with the <label> tag. This will provide speech-based browsers with a concise label to read, rather than the often-cryptic item name. All item templates from the APEX built-in themes use the <label> tag.

For labels that provide item-level help, a JavaScript function is included as part of the template. The JavaScript popupFieldHelp function accepts two parameters: the current item ID, which is referred to with the token #CURRENT_ITEM_ID#, and the current application session. When called with these two parameters, a pop-up window that contains the item-level help will render.

When a validation throws an error that is associated with an item, the label template will use the On Error Before Label and On Error After Label attributes to render the item in question. The token #ERROR_MESSAGE# can be used in these attributes, and will be replaced with the error message of the validation that failed. Most prebuilt label templates simply use a different CSS class for the error attributes to render the label in red or a different color than the standard labels.

Lists are one of the more complex templates, with 14 attributes to define. Fortunately, you will rarely need to define more than four or five of these attributes. APEX has the following two types of lists, as illustrated in Figure 10-25:

Figure 10.25. A hierarchical list and a flat list

The templates required for flat lists and hierarchical lists will vary. A flat list needs only the Template Definition section defined, whereas a hierarchical list will need both the Template Definition and the Sublist Entry sections defined. The only way to tell for certain which type of list is associated with a template is to edit the list template itself and inspect the Sublist attributes. As mentioned earlier in the chapter, the class of a template is designed to facilitate switching from one theme to another. Classes can be completely arbitrarily assigned and do not necessarily describe the template with which they are associated.

When creating a list, a list template must be associated with it. If the list being created will be hierarchical, be sure to select a hierarchical list template. If you do not, then when your list renders, you will see only the top-level list entries. If you are creating a flat list and select a hierarchical template, you will be OK in most cases, as the top level of the hierarchy is all that you will have defined. You can always override the list template when creating a list region in your application, as shown in Figure 10-26.

Figure 10.26. Overriding the default list template when creating a list region

List templates themselves are quite simple to understand. The list itself is sandwiched between two attributes: List Template Before Rows and List Template After Rows. In most cases, these two attributes are used to open an HTML list or table and then close it. Class definitions for the list itself can be included.

Once the list is opened, each list entry will then be rendered according to its sequence. If a list entry is the current entry, per its Current on Page attribute, then the List Template Current attribute will be used. Otherwise, the list entry will be rendered using the List Template Noncurrent attribute. Often, these two attributes are identical, except that the current entries are bolded. The substitution strings #LINK# and #TEXT# can be used to automatically generate the associated link and name of each list entry.

This is all that needs to be defined for a flat list. All of the remaining attributes for lists have to do with hierarchical lists. The hierarchical list templates included with APEX vary greatly as to how they render. Some will render all list items at once; others employ Dynamic HTML (DHTML) to provide an expand and contract function. In the simpler cases, the additional Subitem attributes are identical to the regular items. Others, such as the DHTML templates, are much more complex. If you need to create your own hierarchical list templates, it's best to begin with a copy of one of the built-in templates and modify that, rather than to start from scratch.

Page templates make up the foundation of the APEX template system. All other templates can map back to some portion of a page template. The three major classifications of page templates in APEX are no tabs, one level of tabs, and two levels of tabs. In addition to these three types, there are also specific page types for the login page and pop-up pages.

Page templates control more than their names may lead you to believe. In addition to storing the basic structure of the page, page templates also control the breadcrumbs, navigation bar, success and notification messages, error page, and both standard and parent tabs. At the bottom of every page template is a report of the associated substitution strings and whether or not they were referenced in this specific template.

The core structure of a page can be subdivided into three parts: the header, body, and footer. The header and body are required elements in a page template. The header portion of the page template is relatively constant in all APEX themes, as it is used to set up the default attributes of an APEX page and little else.

<html lang="&BROWSER_LANGUAGE." xmlns:htmldb="http://htmldb.oracle.com">

<head>
<title>#TITLE#</title>
<link rel="stylesheet" href="#IMAGE_PREFIX#themes/theme_1/theme_V3.css" type=
   "text/css" />
#HEAD#
</head>
<body #ONLOAD#>#FORM_OPEN#

Page Body

Next is the body of a page. Technically, all that is required here is the #BOX_BODY# token, which will be replaced with the three fixed regions in APEX, Page Template Body 1 through 3. All of the other tokens are optional, but many are almost always used, as excluding them will limit the functionality of your APEX application.

Page Template Body 1 through 3 are fixed positions, in that they will all render stacked on top of one another. There is no way to alter this behavior. If you need a more flexible layout, you can use APEX's other fixed region positions—#REGION_POSITION_01# through #REGION_POSITION_08#—which can be added anywhere in the body template. Once added to a page template, any region on a page associated with that template can be assigned to these region positions. If only three are referenced in the template, only those three will be available when assigning regions to region positions. Repeating a region position definition in a page template is permitted, but be aware that the content will be rendered in each place the region position is defined in the template.

In the APEX built-in templates, some of the region positions have been assigned to specific purposes. #REGION_POSITION_01# is almost always used for the Breadcrumb region, #REGION_POSITION_02# is used for the Sidebar Content region, and #REGION_POSITION_03# is typically right-justified. If you need to repurpose any of these region positions for other needs, you can safely do so. However, be warned that if you do switch back to an APEX built-in theme, some of the components may not render in their intended positions.

The #LOGO# token will be replaced with a reference to the application's logo, per the application definition. #GLOBAL_NOTIFICATION#, #NOTIFICATION_MESSAGE#, and #SUCCESS_MESSAGE# will be replaced with the site's global notification message, any error messages or validation messages, and success messages, respectively. These three tokens usually appear consecutively in the body region of the page templates. Both the notification message and success message will actually be replaced with their corresponding regions in the page template. This allows the developer to incorporate some additional HTML or CSS references that can enhance the style of how these messages are rendered. For instance, it is common to render the notification message in a red font and the success message in a green font.

The #NAVIGATION_BAR# token will also be replaced with another template definition: Navigation Bar. This region is used to define the characteristics of the navigation bar itself, not each individual entry. When the navigation bar renders, it will replace the token #BAR_BODY# with an instantiation of the Navigation Bar Entry template for each item in the navigation bar. The Navigation Bar Entry template requires both a #LINK# and a #TEXT# token to render the corresponding link and name for each entry. Other tokens that can be used when specifying navigation bar entries include #IMAGE#, #WIDTH#, #HEIGHT#, and #ALT#. It's no coincidence that when defining navigation bar entries, the same attributes are available.

When placing regions on a page, one of the options is in which column to render the region. This allows you to place two regions next to one another, rather than on top of one another. When multiple columns are used, APEX will automatically manage the underlying HTML table structure required. As a developer, you can specify the options of that table in the Region Table attributes, as shown in Figure 10-27. You can specify attributes directly in the table tag, or you can include a class.

Figure 10.27. Developers can specify the table options for multi-column regions.

The report template is one of the most sophisticated template types in APEX. It is also one of the few template types that contain logic or business rules. Each report in APEX will have an associated report template. Keep in mind that each report is technically an APEX region, and thus will also have a region template associated with it. Think of the region template as the container for the report, and the report template as the rows and columns of the report itself.

You can choose from two main types of report templates: generic column and named column. Generic column report templates can be used for any query. Named column report templates include references to specific columns, and they can be used only with specific reports.

Generic Column Templates

Generic column templates or just column templates are the more common of the two template types. They can be used for any valid SQL report without any special provisions. In fact, all of the report templates that ship with APEX are generic column templates. The term column template is also used to describe generic column templates, because all columns will render from the same template.

When using a generic column template, think of it as a layered approach to building the report. First, the outermost layer needs to be defined. Then the definition of each row needs to be defined. Next, the headings are defined, and they typically have a slightly different look than the actual data. Finally, the cell or data elements are defined. You then zoom back out and define how to end each row and the actual table itself. It sounds more complex than it really is. Figure 10-28 shows an example of the Standard Report template from Theme 15. Notice that the Column Heading Template now includes both before and after column templates, new in APEX 4.0, along with the column heading template giving you even more control over the appearance of reports.

Figure 10.28. The Standard Report template from Theme 15

A report template in APEX is actually nothing more than an HTML table with its associated rows and columns, and some substitution strings or tokens. When this report is rendered, it will look something like Figure 10-29.

Figure 10.29. The Standard Report template rendered in an application

In the Before Rows attribute, an HTML table tag is opened. The only token used here is #REGION_STATIC_ID#, which is a unique internal ID that APEX will assign to this region. It is possible to use some other tokens, such as #TOP_PAGINATION# and even column names here.

Next, there is a separate attribute for the column headings. In many cases, the column headings will have a different font style and/or background color than the rest of the report. Including the #ALIGNMENT# token here will allow APEX to substitute the alignment setting defined in the report attributes. #COLUMN_HEADER# will be replaced with the formatted column header name, per the report attributes, whereas #COLUMN_HEADER_NAME# will represent the setting of the column alias. In the example in Figure 10-29, the #COLUMN_HEADER# for the first column would be Empno, and the #COLUMN_HEADER_NAME would be EMPNO.

The Before Each Row and After Each Row attributes denote the HTML used to open and close each row in a report. Often, they are simply set to <tr> and </tr>, respectively. Three possible tokens can be included at the Before Each Row level: #ROWNUM#, #COLCOUNT#, and #HIGHLIGHT_ROW#. The first two are used to assist in advanced page layout, but #HIGHLIGHT_ROW# is much simpler to understand. If included as part of the <tr> tag, #HIGHLIGHT_ROW# will automatically add some code to the report template that will change the color of the row that your mouse is hovering over to the color specified in the Background Color for Current Row attribute.

Each generic column report has four column templates. Only one is required for a report to render. The rest are there to facilitate some basic logic that can be embedded directly in the template. Three conditions are available for each column template: Use for Even Number Rows, Use for Odd Number Rows, and Use Based on a PL/SQL function. For example, if you changed the report shown in Figure 10-28 to use the Standard, Alternating Row Colors template, the column templates would look something like Figure 10-30.

Two column templates are defined: one is set to render for even rows, and the other is set to render for odd rows. The only difference between the two is the CSS class referenced: t13data versus t13altdata.

Figure 10.30. The column template for the Standard, Alternating Rows report template

When run, the rows in the report will alternate between the two CSS styles, which in this case, means alternating between a white and gray background, as shown in Figure 10-31.

Figure 10.31. A report with alternating column templates running

In addition to simple odd and even rows, a PL/SQL expression can be evaluated, and if it is true, a different column template can be used. Thus, you can inspect the value of a column, apply a function, and if the value meets some criteria, that row can be rendered in a different font, color, or style. In order for PL/SQL expressions in report templates to work, they must be applied before any odd/even conditions. Thus, if you were to use the Standard, Alternating Rows template, you would need to move the Odd and Even column templates from positions 1 and 2 to positions 2 and 3, and then use column template 1 for your PL/SQL function template, as shown in Figure 10-32.

Figure 10.32. A column template that includes a PL/SQL expression

In the example in Figure 10-32, we made a slight modification to the first column template: we added the CSS style definition background-color:#f00;, which will render any row that meets the expression in red.

If the data type of the column being evaluated is CHAR, VARCHAR, or VARCHAR2, the column name and associated #s must be enclosed in single quotation marks. For all other types, the column need only be enclosed in #s without the additional single quotes. The name enclosed in #s must match the column name, or if used, the column alias. If COST were the column you were evaluating, the expression would look like this:

#COST# = 1000

When the report is run now, the row of any employee who has a salary of over 2,000 will be highlighted in red, as indicated in Figure 10-33.

Figure 10.33. All high priority, open bugs are highlighted in another color.

Named Column Templates

Named column reports are typically used to display a single row of data in a format other than row/column. They are mapped to a specific table or view, as the column names referenced are placed in the named column template itself. For this reason, none of the APEX built-in report templates are named column. Most of the report attributes, such as those for column-level sorting, column sums, and alignment, are not available in named column templates. All formatting should be done in the template definition itself.

A good example of when to use a named column template is when you need a formatted details view of a single record. You could use a read-only form to achieve the same goal, but using a named column template will give you much more flexibility in the design. In this template, you can use any HTML you like, and you do not need to worry about positioning and sequencing page items.

The structure of a named column report is very similar to that of a generic column report, with a few minor differences. Named column reports combine the Before Each Row, Column Template, and After Each Row attributes into a single attribute called Row Templates. The Row Templates attribute will contain the HTML required to render each specific column. This is in contrast to column templates, which define only a single column that will be used for all columns in a report.

Named column templates also have Column Headings, Before All Rows, and After All Rows attributes. Due to the nature of a named column template, these attributes are rarely used, as most of the HTML required for a named column template is typically found in the row template.

Like generic column templates, named column templates also have logic built in to them. You can define up to four row templates and elect to use them based on a PL/SQL expression or whether the row is an odd-numbered or even-numbered one. For most named column templates, this is not necessary, as only a single row of data is typically used.

When a new named column template is created, by default, APEX will seed Row Template 1, as shown in Figure 10-34.

Figure 10.34. The default Row Template 1 for a new named column template

This template definition is meant only as an example and will not actually work. Replace it with the HTML that you want to use with your report, referencing the specific column names that you have defined.

Using the example in the previous section, let's say that you want to create a nicely formatted view of a record from the BUGLIST table. In any HTML editor, create the layout that you want, using #COLUMN_NAME# substitution strings to represent where the data will go. The following is a quick example:

<table width="500" style="border:1px solid #333;background-color:#ddd;">

<tr>
 <th>Reported:</th>
 <td>#REPORTED#</td>
 <th>Reported By:</th>
 <td>#REPORTED_BY#</td>
</tr>
<tr>
 <th>Status:</th>
 <td>#STATUS#</td>
 <th>Description:</th>
 <td>#DESCRIPTION#</td>
</tr>
<table>

Next, simply cut and paste this HTML into the Row Template 1 of your named column page template, replacing anything that was there, and apply your changes. Run your application, and you should see something similar to Figure 10-35.

Figure 10.35. The results of the sample named column report template

The format mask on the Salary column, which was defined as part of the report attributes, will still be applied to the report.

The possibilities of what you can do with a named column template are almost limitless. Nearly anything that works in HTML will work as part of a named column report template.

Pagination Template

All report templates, regardless of their type, contain a section to define the pagination style. More often than not, this is defined with only generic column templates, as named column templates typically are used for only a single row.

The pagination templates do not allow you to change the type of pagination method used, but rather to add some style to the pagination controls or change the text used when there are more records available.

By default, the pagination scheme Row Ranges X to Y (with next and previous links) will look something like what is shown in Figure 10-36. The corresponding Pagination subtemplate is quite sparse, with only a single element defined, as shown in Figure 10-37.

Figure 10.36. The Employees report with default pagination styles

Figure 10.37. The default Pagination subtemplate

Leaving an attribute of the Pagination subtemplate blank will cause the reporting engine to use the default settings. You do not need values in any of the attributes for pagination to work.

Figure 10-38 shows an example of adding some style to the Pagination subtemplate's first three attributes. When rerun, the report's pagination controls will be smaller, will not contain an image, and will say Next Page and Previous Page (as opposed to Next and Previous), as shown in Figure 10-39.

Figure 10.38. The modified Pagination subtemplate

Figure 10.39. The results of the Pagination Subtemplate modifications

The popup list of values (LOV) template type is definitely the platypus of the bunch, as it contains a little bit of everything: icon definitions; attributes for a search field; button definitions; window attributes; pagination controls; and a header, body, and footer.

It also differs from the rest of the templates in that as a developer, you cannot manually assign this template to any APEX component. Rather, it will be used automatically each time an item type of popup LOV is added to an application. When using the APEX built-in themes, a popup LOV template will be automatically created. If you wish to customize a theme, you will need to alter the existing one, as you can have only one instance of the popup LOV template per theme.

No substitution strings or tokens are available in the popup LOV template. All items that need to be referenced will be done so automatically.

Most attributes of the popup LOV template are either self-explanatory or copies of attributes from other template types.

The calendar component has been greatly enhanced in APEX 3.0, with added support for weekly and daily views. All the calendar templates have attributes for each of the three different views, as the user interface of each will vary. Most built-in APEX themes come with three variations of calendar templates.

It is not advisable to create a calendar template from scratch. If you need a custom calendar template, it is best to copy a built-in one and modify that. Using this method will ensure that the core structure required remains in tact. When modifying a calendar template, you can add any number of styles to almost every facet of the calendar itself.

Calendars have a number of tokens that you can use to denote the day, day of week, and month. They are defined to the right of the calendar template attributes.

When customizing the look and feel of a calendar template, it is best to use CSS class definitions. This will help separate the structure of the calendar template from any of the styling that you add. Refer to any of the built-in APEX CSS files for some examples of how to use CSS definitions to control the look and feel of calendar templates.

You won't find the templates used for rendering APEX trees with the rest of the templates. When a tree is created, the user is given the option to select one of the three templates. That template will be "burned in" to the definition of the tree itself. The tree templates are every bit as configurable as regular templates, but the tree lacks the centralized control of being a shared component.

Changing the structure of a tree template is not recommended, as it requires a number of images that are precisely created to line up with one another. Tree templates are also not scalable. Each time a new tree is created, the altered template will need to be applied by hand.