# APEX Dynamic Inline Help

# Introduction

Inline help can be a good way of providing users with some additional guidance directly below the field that the advice is related to.

![Oracle APEX Inline Help Example](https://cdn.hashnode.com/res/hashnode/image/upload/v1680008286005/08f078c0-be6a-4851-ad0e-6a7d5944b4a2.png align="center")

In this post, I will describe how you can dynamically change the inline help text based on what the user enters on the page. This can help to guide/comfort the user that they are doing the right thing.

## Demonstration

%[https://youtu.be/x2Ji7IS5duU] 

## Inline Help HTML Elements

Before we can dynamically change inline help text, let's look at how it works out of the box. Simply adding text to the `Inline Help Text` property of a page item will cause that text to appear underneath that page item.

![Oracle APEX Inline Help Standard Setup](https://cdn.hashnode.com/res/hashnode/image/upload/v1680009057301/50e01ba7-fed1-4e89-b5fd-facb5bef0e80.png align="center")

After running the page, we can look at the HTML elements that APEX generated:

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680009309983/05a81dc3-59c4-4b7b-9236-4cea627ad823.png align="center")

* The page item for the above example is called `P3_BONUS_AMOUNT`.
    
* APEX has generated a container with the ID `P3_BONUS_AMOUNT_CONTAINER`. This contains all of the elements for the item.
    
* The Inline help text is in a `div` with the class `t-Form-inlineHelp` that sits within the container.
    
* APEX has generated a unique ID for the inline help text called `P3_BONUS_AMOUNT_inline_help`.
    
* **Note**: If you do not add any inline help to the `Inline Help Text` item property, then APEX will not include the `div` with the class `t-Form-inlineHelp` to the container.
    

To dynamically add/edit the inline help text, we need to be able to either add the below `div` (if it does not already exist), or edit the text in the span with the `ID` `P3_BONUS_AMOUNT_inline_help` (if the `div` does exist).

```xml
<div class="t-Form-inlineHelp">
  <span id="P3_BONUS_AMOUNT_inline_help">Enter the bonus amount</span>
</div>
```

# Helper JS Functions

I have created two helper functions to simplify the task of dynamically adding, replacing, or clearing inline help text. The `setInlineHelp` function checks to see if the `ID` of the inline help `span` exists on the page. If it does not exist, then it adds the `div` containing the `ID` and the inline help text; if it does not, it replaces the existing text with the new one. The function `clearInlineHelp` removes the inline help `span`.

I added the code to a static application file called `cnUtil.js`, and then reference it in the pages where I want to use it as follows:

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680017369637/eaff3bdb-36c3-46d5-bb22-65bd57721409.png align="center")

I have included comments in the code to describe what it is doing.

%[https://gist.github.com/jon-dixon/87bdcd0713a1fc65af7642f81bb2e6b8] 

# Putting it All Together

Now that we understand how APEX assembles the inLine help within the item container and have code to manipulate the inline help elements, we can incorporate this into an APEX page.

## Example

In my example, I want to display inline help text to the user in the Justification field `P3_JUSTIFICATION` if the user enters a bonus amount `P3_BONUS_AMOUNT` that is above average.

I also have a hidden field `P3_AVERAGE_BONUS`, which contains the average bonus amount. This is calculated on page load by a SQL statement. You could have any code you want here. You could even add a step to the dynamic action mentioned below to perform a more complex calculation based on the bonus value entered by the user.

![Oracle APEX Inline Help Example Average Bonus](https://cdn.hashnode.com/res/hashnode/image/upload/v1680015079117/7bfd20b7-6775-49bb-ac5f-a9ed3dfba761.png align="center")

### Dynamic Action

I have created a Dynamic Action on P3\_BONUS\_AMOUNT, which fires when the user tabs out of the field. If the Bomus Amount entered is greater than the average, then the TRUE action fires; otherwise, the FALSE action fires.

![Oracle APEX Inline Help Example Bonus Amount 1](https://cdn.hashnode.com/res/hashnode/image/upload/v1680015310914/dd2699b7-7c22-4cd1-b96c-40d3d786372f.png align="center")

* `apex.item( "P3_BONUS_AMOUNT" ).getNativeValue()` in the `JavaScript Expression` property. This returns the current value of the item as a JavaScript number. This allows us to compare it with the value in the hidden average bonus field. `getNativeValue` can only be used on items of the type `Number Field`. Click [here](https://docs.oracle.com/en/database/oracle/apex/22.2/aexjs/numberFieldItem.html#getNativeValue) to read more.
    
* `apex.locale.toNumber($v("P3_AVERAGE_BONUS"), "999,990.00")` converts the hidden item `P3_AVERAGE_BONUS` to a JavaScript number. We can't use `getNativeValue` on hidden fields, but we can use `apex.locale.toNumber`. Click [here](https://docs.oracle.com/en/database/oracle/apex/22.2/aexjs/apex.locale.html#.toNumber) to read more.
    

**TRUE Action Code**

The following code is run for the **true** action of the DA.

```javascript
// Get the bonus amount entered in the current field.
let bonusEntered = this.triggeringElement.value;
// Get the average bonus from the item P3_AVERAGE_BONUS.
let averageBonus = apex.locale.formatNumber($v("P3_AVERAGE_BONUS"), "fm999,990.00" );
// Build the In-Line Help Message.
let itemMsg = apex.lang.formatMessage("IH_BONUS_ABOVE_AVERAGE", bonusEntered, averageBonus);
// Call function to add/replace the InLine help text for the justification field.
cnUtil.setInlineHelp ('P3_JUSTIFICATION', itemMsg);
```

* `apex.locale.formatNumber` is a valuable function that formats a number using the standard Oracle format string syntax. Click [here](https://docs.oracle.com/en/database/oracle/apex/22.2/aexjs/apex.locale.html#.formatNumber) to read more.
    
* `apex.lang.formatMessage` fetches a Text Message (created under shared components) and replaces the substitution values %0, %1, etc. Click [here](https://docs.oracle.com/en/database/oracle/apex/22.2/aexjs/apex.lang.html#.formatMessage) to read more.
    
* **Note**: When referencing Text Messages from JavaScript, you must set the `Used in JavaScript` attribute to Yes. This ensures the messages are loaded with the APEX Page.
    

![Oracle APEX Inline Help Example Bonus Text Messages](https://cdn.hashnode.com/res/hashnode/image/upload/v1680016740246/bba83cde-3227-4595-a4f8-2d9c197d08a4.png align="center")

**FALSE Action Code**

The following code is run for the **false** action of the DA.

```javascript
// Get the default in-line help message.
let itemMsg = apex.lang.formatMessage("IH_BONUS_JUSTIFACTION");
// Call function to add/replace the InLine help text.
cnUtil.setInlineHelp ('P3_JUSTIFICATION', itemMsg);
```

Here we are simply calling the setInlineHelp function to set the inline help to the default value, which is in the text message `IH_BONUS_JUSTIFACTION`.

# Conclusion

Even if you don't need to generate dynamic inline help, I hope that you can make use of some of the techniques described in the post.

⚠️ In future releases of APEX, the APEX development team could change the CSS classes and HTML elements that make up a page item. This could break the code used in this post. By encapsulating the code in a single shared function, we minimize the impact of any potential upgrade remediations. If such a breaking change happens, we only need to change the code in the function and not all of the places that call it.

## Read More

* 🩳 [APEX Shorts](https://blog.cloudnueva.com/series/apex-shorts)
    
* 📖 [APEX Posts](https://blog.cloudnueva.com/tag/orclapex)