Introduction
Template Components were a big hit when they were introduced in APEX 23.1. They provide the ability to create reusable components that can add functionality and style to your APEX applications. Although they utilize the Plug-in architecture, I think they are easier to understand and implement than standard Plug-Ins. What I wasn't aware of, however, was that there are six out-of-the-box "Theme Components" that you can use without writing a single line of code. These "Theme Components" are Template Components built into the Universal Theme. Available Theme Components as of APEX 23.1 are:
Badge
Avatar
Comments
Content Row
Media List
Timeline
This post will provide examples of several Theme Components used in different scenarios. Throughout this post, you can think of Theme Components as Template Components (they are consumed the same way); it's just that Oracle built them for you.
The added benefit of using "Theme Components" is that you can see how they work and can more easily move on to creating your own custom "Template Components".
Universal Theme App
Like many other things in APEX, I learned about the six Theme Components from the Universal Theme Application. Here is a screenshot of the documentation for the Badge Component when used in an Interactive Report.
Types of Template Components
There are two fundamental types of Template Components:
Single (Partial)
- Used to render a single instance of a component.
Multiple (Report)
- Use in report regions to render a Template Component for each row of a report.
Where can they be Used?
Template Directives
One of the benefits of Theme Components is that they can be used anywhere that Template Directives can be used. This allows us to use them in many interesting ways.
Here is an example where I use Template Directives to reference the Avatar Theme Component. This will render an Avatar on every line of a Classic Report.
Declaratively
You can also use Theme Components declaratively in both Regions and Interactive Report columns.
Regions
You can create regions as Theme Components:
Interactive Report Columns
You can also use Theme Components in an Interactive Report column:
When writing this post (APEX 23.1), Interactive Report columns seem to be the only reports supporting the declarative use of Template Components (and Theme Components). Fear not; as we have already discussed, you can use Theme Components in many places by using Template Directives.
Examples
In this section, I will illustrate three examples of Theme Components, all using the Badge Theme Component.
Single Badge Declarative
In this example, we will show a badge in the header region of an APEX App that shows the current instance name (e.g., DEV, TEST, PROD).
Create a new Region as follows:
- Note: The position 'Before Navigation Bar' will place the badge in the header region of your page to the left of the navigation bar.
On the Attributes Tab, enter the following:
- Note: the 'Display' value of
Single (Partial) indicates to APEX that we only want to render one badge value.
The result should be a green badge in the header of your page. If you create the region on page 0, this badge will appear on every page of your App.
Badge in Report Column Declarative
In this example, we will create a Badge in an Interactive Report column.
Create a new Interactive Report Region:
Note: The badge_icon column is used to determine the background color for the badge.
Next, identify one of the columns to be the badge column; in this case, I am setting the NUMBER_OF_VEHICLES column to a Type of Badge.
The Settings section shows all of the settings related to the Theme Component. These will be different for each Theme Component. These settings can be free-form entries, values selected from a list of values, or derived from a column in the source SQL. In the above example, Value and State are derived from columns in the source SQL.
Note: I have hidden the BADGE_STATE column as I only need it for the Theme Component, and I do not want to display it in the report.
The End Result looks like the below screenshot:
Note: I have a Control Break on the Year column.
Badge Via Template Directive
In this example, we will display a badge in a Classic Report. We will need to display the badge using Template Directives. This is because Classic Reports do not support Theme Components natively, but they do support Template Directives.
Create a region like the following:
Add a Template Directive to the column in which you want to display the badge:
- APEX uses the
apply clause to look up the appropriate Theme Component to apply.
The variables LABEL, VALUE, STATE, etc., are defined in the Theme Component. I will later show you a trick to find these variable names in the post.
You can assign static values or assign column values from the SQL statement using the #COLUMN_NAME# syntax.
The final report looks something like this:
Badge Report
In the final example, I will show you how to create a report of just badges. This utilizes the 'Multiple (Report)' Template Component Type.
Setup a region like the following:
Under the Attributes tab, ensure the Display value is set to Multiple (Report):
Complete the values in the Settings region just like we did for the declarative Interactive Report column example above. You can reference values from the SQL or provide static values.
The result looks something like this:
We even get full support for pagination!
Customizing a Theme Component
One of the cool things about Theme Components is that you can copy and use them yourself. Making a copy of a Theme Component also allows you to confirm the variable names and possible values when you use them for Template Directives.
Navigate to Shared Components > Plug-ins and Click the 'Create' button:
Select 'As a Copy of an Existing Plug-in' and click Next.
Important: Select '42. Universal Theme' for the Theme and click Next.
Select which Theme Component you want to copy and click Next.
You should now see a copy of the Badge component in your list of Plug-ins. Click on the Plug-in name to see details of the plug-in.
Conclusion
I think Template Components are a fantastic feature of APEX. I strongly encourage you to explore and use them in your APEX applications. Using out-of-the-box Theme Components makes getting started with Template Components easy.
I used the Badge Theme Component in my examples. You can use any of the Theme Components, in the same way, to make your APEX UI more engaging for your users.
