Oracle APEX - Centralize your App Messages with Text Messages and Shortcuts

It's very common to see softwares with buttons, labels and messages without a clear pattern and visual identity. For example, a simple submit button may be called add, save, apply changes, insert, commit, confirm, etc. The same thing happens with the messages, but in this case the situation is worse because messages that would be equals may have differences or grammar, syntax errors. How do I solve it?

It's the best practice to centralize all application messages in one place. This ensures that all messages with the same purpose are consistent across all system and Oracle APEX has appropriate features and APIs to solve this issue. This approach also facilitates import and export messages among applications.

Text Messages

Oracle APEX provides a feature called Text Messages, which serves to manage, centralize, and translate application text for globalized applications. Many developers ignore this functionality, but it's very useful and saves a lot of time when you need to make changes in very common messages, which appear on many application pages.

An interesting thing about this resource is a text message created may be accessed by JavaScript, on client-side, and by PL/SQL blocks, on server-side. Let's create a new message by following the steps below:

1. Go to App Builder -> Your Application -> Shared Components -> Globalization -> Text Messages.
2. Click on the button Create Text Message.
3. Fill Name (suggestion: create your message names like a namespace, such as APP.INFO.WELCOME, APP.ERROR.INTERNAL_ERROR, APP.CONFIRM.YOU_AGREE).
4. Choose the language.
5. If you use your message in JavaScript, turn on Used in JavaScript.
6. Fill Text with the message (obs.: you may create a template message using %0-%9 parameters, like "Mr. %0, your registration number is %1.").
7. Click on Create Text Message.

Note that you can choose a language when creating a Text Message. If you require translations, one tip is to define and create all necessary text messages in each language. Oracle APEX will then automatically select the correct messages for each user based on their configured language.

Now, to access your messages, you need to learn about some APIs, which will be mentioned in the following sections.

APEX_LANG Package API

If you need to use a text message inside your PL/SQL code, you need to learn about this package. It provides a comprehensive API for managing text messages, allowing you to access, configure, and retrieve all registered messages in your application.

Considering this article context, APEX_LANG API offers these interesting functions:

• MESSAGE - is a function used to recovers a registered message.

/* 
Syntax
------------------------------
APEX_LANG.MESSAGE (
    p_name       IN VARCHAR2 DEFAULT NULL,
    p0                IN VARCHAR2 DEFAULT NULL,
    p1                IN VARCHAR2 DEFAULT NULL,
    p2                IN VARCHAR2 DEFAULT NULL,
    ...
    p9                IN VARCHAR2 DEFAULT NULL,
    p_lang          IN VARCHAR2 DEFAULT NULL,
    p_application_id  IN NUMBER   DEFAULT NULL )
RETURN VARCHAR2;

The example below recover a text message registered after an exception.
*/

begin
	... -- some code
exception
	when my_exeption then
		-- APP.WARN.INVALID_NUMBER is the registered text message
		l_message = apex_lang.message('APP.WARN.INVALID_NUMBER', 'my_field');
		...
end;        

• CREATE_MESSAGE, UPDATE_MESSAGE and DELETE_MESSAGE - are procedures that allows you to manage your text messages by command line.

/*
Syntax
------------------------------

APEX_LANG.CREATE_MESSAGE (
    p_application_id         IN NUMBER,
    p_name                      IN VARCHAR2,
    p_language                IN VARCHAR2,
    p_message_text         IN VARCHAR2,
    p_used_in_javascript  IN BOOLEAN  DEFAULT FALSE )

The example below reads a table with many messages and register any messages as APEX Text Messages
*/

begin
	...
	for c_message in (select name
	                                      ,language
					      ,message_text
					      ,used_in_javascript
	                              from my_legacy_message_table)
	loop
		apex_lang.create_message(name
                                                          ,language
                                                          ,message_text
                                                          ,my_message_table);
	end loop;
end;        

To know more about this package, see API Reference -> APEX_LANG.

The JavaScript Namespace apex.lang

When you create a Text Message and check the Use JavaScript option, Oracle APEX loads all of these messages into a JavaScript file returned by wwv_flow.js_messages (look at the HTML code and search for it within the <head> tag). This approach avoids unnecessary requests and significantly improves the speed at which the messages are used.

You can acess your text messages inside the JavaScript code using the namespace apex.lang, which provides similar API to APEX_LANG package. This API offers these interesting functions:

• getMessage - return a registered message without parameter replacement.

/*
Syntax
--------------------------
apex.lang.getMessage(pKey);
*/

let label = apex.lang.getMessage('APP.LABEL.EMPLOYEE.NAME');        

• formatMessage - is equivalent to APEX_LANG.MESSAGE.

/*
Syntax
--------------------------
apex.lang.getMessage(pKey, pValues);
*/

-- Msg: Your %0 has been successfully registered with the number %1.
-- Return: Your order has been successfully registered with the number 8699201.
let success = apex.lang.formatMessage('APP.SUCCESS.SAVE', pEntityName, pNumber);        

• loadMessagesIfNeeded - There are some messages that you may not need most of the time. In such cases, instead of checking the option to use them in JavaScript, you can load these messages on demand as needed and decrease the size of your message file, returned by wwv_flow.js_messages.

/*
Syntax
--------------------------
apex.lang.loadMessagesIfNeeded(pMessageKeys, pCallback);
*/

apex.lang.loadMessageIfNeeded( ['APP.HELP.FILLING_INSTRUCTIONS'], function() {
    $('#message_container')
          .text(apex.lang.getMessage('APP.HELP.FILLING_INSTRUCTIONS');
} );        

To know more about apex.lang, see JavaScript API -> Namespaces -> apex.lang.

Substitution Strings

A substitution string is an identifier that Oracle APEX replaces by a predefined text. This feature is very useful to utilize the same string a lot. In many places inside your application, it's possible to use substitution strings like templates, labels and many page attributes.

The interestest functionality here is call an existent text message as substitution string. You can make it as follow:

/*
Syntax
-------------------------------
Bind variable
:APP_TEXT$Message_Name or :APP_TEXT$Message_Name$Lang

PL/SQL
V('APP_TEXT$Message_Name') or V('APP_TEXT$Message_Name$Lang')

Substitution String
&APP_TEXT$Message_Name. or &APP_TEXT$Message_Name$Lang.
*/        

Shortcuts

Shortcuts are an overlooked yet powerful feature that enables the storage of repeatable code, reducing redundancy. They can be used within the following locations:

• The Region Source attribute of regions defined as HTML Text (with shortcuts).
• Region Header and Footer Text attribute.
• Item Label attributes, Pre Element Text, Post Element Text, and Default Value attribute.
• Region Templates attributes.

To create a shortcut, follow the steps below:

• Access App Builder -> Your Application -> Shared Components -> Other Components -> Shortcuts.
• Click on Create.
• Fill Name with the name of your shortcut.
• Choose one shortcut type in Type.
• Fill Shortcut with your shortcut content.
• Fill Error Text with an error message (used with PL/SQL).
• Click on Create.

One interesting tip is that you can call a text message within a Shortcut, unifying both resources as needed. For example, you need to create HTML code with instructions to display in some pages. You can recover the instruction text from a text message and creates a shortcut for it. This is beneficial because you won't repeat your code across many pages, with the risk of display inconsistent messages. Besides standardizing your messages, this approach will make it easy to create translations if you need to export your app. You can make it as follow:

You can also use shortcuts within your JavaScript code. Every time a page is created, Oracle APEX provides an example of usage within the Function and Global Variable Declaration property:

var htmldb_delete_message='"DELETE_CONFIRM_MSG"';        

Conclusion

Now, you know a little bit about message standards. Explore the power of Text Messages and Shortcuts within your Oracle APEX applications using your creativity. By implementing these techniques, you can unlock greater efficiency, improve code quality, and deliver a more streamlined and user-friendly experience for your end-users.

Thank you for reading!

Follow me to the next articles. See you soon!