Phil Grinham's Blog
Re-purposing Inline Help in Oracle APEX

Photo by Breana Panaguiton on Unsplash

Re-purposing Inline Help in Oracle APEX

Quick tip on an alternative way to show warnings in APEX.

Phil Grinham's photo
Phil Grinham
·

3 min read

Oracle APEX offers developers the ability to add inline help underneath any input or display field to improve the end-user experience and clarify what the user is being asked for when it isn't immediately clear.

However, this same field can be used for another purpose - as a nice way to display a warning message as the user completes the field.

Consider this use case; a form requires a user to fill out the location of an item, its global region, sub-region, country and city. The country and city fields are pop-up lists of values that allow manual entry so new countries and cities can be added to the geographical meta-data by the end user if they aren't already present.

Now there are perfectly valid cases where a city name appears in multiple different countries so it isn't a validation error we need, just an advisory to the user in case it is an error on their part. This is where the inline help text can be a nice home for this warning message to live.

In the inline help text for the city field, we put a span placeholder that we can use later, by default it will be empty. Here you can see we have just added a span tag and provided an ID and a class.

The class is just to change the colour to orange and the ID will be used in a dynamic action.

On change of the city field, we will set the value of the span to be a warning if one is warranted.

  • Create a Set Value action under the true branch.

  • Using a SQL statement we can set the value to be a warning message if it is applicable or to be NULL if it's not.

  • Set the Affected Elements to be a Javascript Expression of $("#cityWarn"). This is where the ID comes in.

  • Set it to Fire on Initialization so it applies to existing records when the form loads.

The SQL can be something similar to this (as the message has html in it, remember to turn off the escaping of special characters) :

SELECT '<span class="fa fa-warning" aria-hidden="true"></span>&nbsp;This city is already used under sub region ' ||
       L.SUB_REGION || ' and country ' || L.COUNTRY AS MSG
FROM   LOCATION L
WHERE  (UPPER(L.COUNTRY) <> UPPER(:P20_LOCATION_COUNTRY) OR L.SUB_REGION <> :P20_LOCATION_SUB_REGION)
AND    UPPER(L.CITY) = UPPER(:P20_LOCATION_CITY)
FETCH  FIRST 1 ROWS ONLY;

Once we set the Items to Submit to match the page item bind variables in the SQL we are good to go. Note, limiting the SQL to return just a single row prevents the TOO_MANY_ROWS exception and keeps the message succinct. If you really need to show all the potential duplicates then this isn't the correct solution for that.

So now the user is warned that this could be a duplicate inline with the field it applies to when a match is found against another country or region. Perhaps in future versions of APEX, much in the same way we create validations with specific tests and conditions, we could get the ability to natively declare warnings that fire on submission and ask the user to confirm if they wish to continue or not.

#oracle-apex