Creating a generic icon-picker

The Case

Oracle APEX comes shipped with a subset of icons from the well known Font Awesome icon library. These can be used in your application in a multitude of ways. But did you realise you could also let your user decide wat icons to use in the application? The CSS classes used by Font Awesome are just pieces of plain text that get interpreted by your browser to show an icon in a certain way. For example, the Font Awesome class “fa-apex” will show you this icon:

As it’s just text you could of course just save the users choice in the database. For example, in a current project we have “work-items” that have to be shown in reports and on maps where the user decides what icon they want to see. Of course the user doesn’t want to be bothered with the Font Awesome class-names but just wants to pick an icon from a list or report.

Creating a solution

In this solution we make a single APEX page that can be called from anywhere in your application to pick an icon. Here’s the steps to create a base page you can change to your liking:

Create a blank page of type modal dialog with a width of 800 pixels and a height 500 pixels.
Add an item where the user can enter a search text (e.g. P43_SEARCH). Set the template to “Optional - Floating” and in the Template options turn on “Stretch Form Item”. We will add a dynamic action later to execute a search.
Next, add a cards region to show the icons, give it a static ID of “region-icons”. This will be based on the APEX-view APEX_DG_BUILTIN_FONTAPEX.

Enter the following query to the region source:
```
 select icon_name
 from   apex_dg_builtin_fontapex 
 where  :P43_SEARCH is null
 or     instr(upper(icon_name||icon_filters), upper(:P43_SEARCH)) > 0
```
Make sure the item you created before and is used in the query is also added to the “Page Items to Submit”!

In the Attributes section of the cards region set the following values:

Option
Value
Appearance - Layout
Grid
Card - Primary Key Column 1
<pick the only column in your query above>
Body - Advanced Formatting
Switch ON

Now set the HTML Expression for the Body to:
```
 <center><span class="fa &ICON_NAME."/></center>
```
Add a hidden page item to your page. This will hold the value of the icon-class the user has picked. Name it for example P43_SELECTED_ICON. Don’t forget to set the “Value Protected” for this item to OFF.
To make the search item we added above actually work add a Dynamic Action of type “Key Release” to P43_SEARCH. Set the execution type to Debounce with a Time of 250 milliseconds.

Add an action of type “Refresh” to the dynamic action to refresh the cards region:

With this done the cards region with the icons will be filtered automatically when a user enters a search-criteria.
Now we are basically done with the layout we need to add some logic to tie it all together. First add a custom Dynamic action to the cards region. Name it “customPickIcon” and set the Selection Type to “Region” and pick the cards-region.

Then add a “Set Value” action that will put the selected icon-name into the hidden item :P43_SELECTED_ICON. Note how I used the Javascript Expression this.data as the value to put into the item. This is basically the input parameter of the custom dynamic action.
The custom Dynamic action now has to be triggered when a user clicks on a icon in the cards region. To achieve this we add an action to the cards region of type “Full Card”:

Set the link type of this action to “Redirect to URL” and enter the below JavaScript code as the URL. Note the parameters in the call to the function. The first one is the Static ID of the region (in jQuery format), the second one is the name of the custom Dynamic action and finally we have the input of the dynamic action.
```
 javascript:apex.event.trigger("#region-icons", "customPickIcon", "&ICON_NAME.");
```
The only thing left to do now is to close the dialog-page an return the icon-class to the calling page. To achieve this we add a Dynamic Action to the hidden item P43_SELECTED_ICON that closes the dialog:

Add an action “Close dialog” and add P43_SELECTED_ICON to the Items to Return:

We have now created a generic icon-picker you can use everywhere you like in your application.

Using your icon-picker

The only thing remaining now is calling your nice and shiny icon picker page from other pages.

Just create a button that redirects to your icon-picker page. Don’t forget to set the Clear Cache, otherwise your previous search will still be visible.

Then add a Dynamic Action to the button for the event “Dialog Closed”. This will fire when the icon picker dialog is closed so we can pick up the Items to Return and do something with it. To achieve this add a “Set Value” action. In the Settings section set the Set Type to “Dialog Return Item” and set the Return Item to the same item you used in the Items to Return on your dialog-page (e.g. P43_SELECTED_ICON):