Text Messages are a powerful feature that can be used to build translatable text strings with substitution variables which in turn can be called from PL/SQL packages, procedures, and functions. Using Text Messages in an APEX app has various benefits. Some are:

  • Dynamic Translations for Multi-Language Applications
  • Centralized Management of Text
  • Dynamic UI Text and Prompts
  • Seamless Updates for Content Changes
  • Localization of Emails and Notifications
  • Improved Maintainability in Large Applications

In Oracle APEX 24.2, Text Messages has received further enhancements. Now, you can:

  • Add meaningful placeholders
  • Write a shorter substitution syntax 
  • Omit prefixes
  • Directly specify parameter values
  • Use Text Messages Picker in Page Designer

Let’s dive deeper and understand how to use Text Messages in an APEX application.

Creating a Text Message with Meaningful Placeholders

Now, you can use meaningful placeholders like %name and %quantity instead of positional parameters such as %0 and %1. This not only makes the code easier to read, but also helps to solve common issues where the addition of content could change the position of the variables. The naming convention helps debug and understand the output better.

To create a Text Message, go to Shared Components → Globalization → Text Messages and click Create Text Message or click an existing Text Message to edit.

On the Create/Edit Text Message dialog, enter the following attributes:

  • Name: TEXT_MESSAGE
  • Language: English (en)
  • Text: <The text message that will be displayed >
Figure 1. Creating a Text Message
Figure 1. Creating a Text Message

 

How to Apply Text Messages in APEX 24.2?

After creating a Text Message, it is ready to be used in your application. You can utilize and access the Text Messages from both server-side and client-side code by incorporating them as:

  • Static Content
  • PL/SQL Code
  • JavaScript Code

Using Text Messages with Static Content

Let’s consider a scenario where you are building an online shopping application and you would like to display the order confirmation using Text Messages. A simple option is to create a page item of type Static Value with translatable messages that can be easily displayed on the screen.

Steps:

  1. Create a Display Only Page Item.
  2. Under Source, 
    1. For Type, select Static Value
    2. For Static Value, enter the following code:
      &{SALES_CONFIRMATION user="John" quantity="1" product="Laptop"}.
Figure 2. Adding a Text Message to a Page Item's Source
Figure 2. Adding a Text Message to a Page Item’s Source

This simple implementation will provide the following output:

Figure 2.1 - A sample output from the Text Message
Figure 2.1 – A sample output from the Text Message

 

Using Text Messages with PL/SQL

You can use Text Messages with your PL/SQL code to create easily customizable message outputs by applying the apex_lang.get_message function from Oracle APEX’s API to increase both readability and security. In order to show this, let’s create a computation.

Steps:

  1. On your APEX page, navigate to the Rendering Tree.
  2. Right-click on Before Header and select Create Computation.
  3. In the Property Editor, enter/select the following:
    1. For Type, select Expression 
    2. For Language, select PL/SQL.
    3. For PL/SQL expression, enter the code below:
apex_lang.get_message( 'SALES_CONFIRMATION'
                     , apex_t_varchar2( 'user', :P6_CUSTOMER
                                      , 'quantity', 1
                                      , 'product', 'Laptop'
                                        )
                                     )
Figure 3. Adding Text Message to PL/SQL code
Figure 3. Adding a Text Message to PL/SQL code

Note: This is the same text message created previously using the Static Content. Observe that the result remains the same.

Figure 3.1 - A sample output from the Text Message
Figure 3.1 – A sample output from the Text Message

 

Using Text Messages with JavaScript

For some applications, there might be a need to execute messages with the client-side code. This can be achieved by applying Text Messages within JavaScript.

Note: For this feature to work, you should have enabled Used in JavaScript option in the Create Text Message dialog.

Figure 4. Enabling the Text Message to be used in JS
Figure 4. Enabling the Text Message to be used in JS

Steps:

  1. Create an APEX button
  2. Right-click on the button and select Create a Click Dynamic Action
  3. The action Show will appear by default, change it to Execute JavaScript Code action.
  4. Note that in your JavaScript code, you will use the apex.lang.formatMessage function.
  5. When the JavaScript code is executed, the Text Message is displayed as an APEX Alert dialog box.
// Text Message Data 
const textMessage = 'SALES_CONFIRMATION' 
const textMessageParameters = { user: 'John', quantity: 1, product: 'Laptop' } 

// Calling the formatted text message from the JS API 
const message = apex.lang.formatMessage(textMessage, textMessageParameters); 

// Showing the text with in a alert 
apex.message.alert(message, null, {style: "success", iconClasses: "fa fa-check fa-2x"});
Figure 5. Adding a Text Message to JS code
Figure 5. Adding a Text Message to JS code
Figure 6. Showing the Text Message on an Alert
Figure 6. Showing the Text Message on an Alert

Conclusion

Text Messages are versatile components that can be utilized and accessed from server-side and client-side code. From maintaining large applications to localizing emails and notifications, Text Messages help maintain a single source of truth and centralized text management. In this blog post, you saw examples of using Text Messages with Static Content, PL/SQL expressions, and JavaScript code.

Try this and other new features of Oracle APEX 24.2 on apex.oracle.com!