Thursday, 22 December 2016

APEX 5.1 - Client side messaging and apps not using Universal Theme


In APEX 5.1, we are introducing new client side messaging functionality, which aims to provide more modern, faster messaging across APEX, including the capability to display both error and success messages from the client side, without requiring a full page reload (as is the traditional way in APEX). Messaging in APEX is something we have wanted to modernise for a long time, and in 5.1, precipitated by the introduction of the Interactive Grid and its requirement for such messaging, this comes to fruition. 

This new functionality works well with apps already using the Universal Theme, however apps using older, or custom themes may face some consistency issues in how inline item errors are displayed between pages that display messages the old way and the new way. The purpose of this blog post is to highlight when such inconsistencies may occur, and to provide guidance on how you can go about fixing them.

Note: If you have created your own custom theme, please see Method #2 for instructions on how to update your theme to work with client side messaging.

When can these inconsistencies occur?

Client side messaging for inline item errors will be used in the following scenarios:
  1. To display the error messages if an APEX validation error occurs, and the page attribute Reload on Submit is set to Only for Success (which is the default for new pages, irrespective of theme).

  2. Screenshot showing the new Reload on Submit page level attribute in APEX 5.1
    The new Reload on Submit page level attribute in APEX 5.1

  3. To display the error messages if a client side validation error occurs such as Value Required = Yes, and the app Compatibility Mode is set to 5.1 (default for new apps, irrespective of theme), a Submit Page button is used with set to Execute Validations = Yes.
Compatibility Mode, available in Application Attributes

So as soon as you start adding new pages to an existing app for example, you will start to hit these inconsistencies, because existing pages will have Reload on Submit set to Always, and new pages will have this set to Only for Success

In both of the above scenarios, an inline item error will be shown but it may not look exactly the same as on other existing pages. This is because as it is, the client side messaging logic isn't able to use the corresponding template markup from the theme because of some missing information (more on that in a moment), and instead relies on some generic fallback logic to display the error. We can see the inconsistency below. 

Here is an inline item error, rendered using server-side logic due to the page level attribute Reload on Submit being set to Always (default for existing apps).

Screenshot showing Inline item error display for Theme 21, when the page level attribute Reload on Submit is set to Always

And here is the same error, rendered on the client side due to the page level attribute Reload on Submit being set to Only for Success (default for new pages).

Screenshot showing Inline item display for Theme 21 in APEX 5.1 when the page level attribute Reload on Submit is set to Only for Success

The Known Issues page for 5.1 mention this issue, including a few suggestions for working around it.

Screenshot showing excerpt from known issues page detailing this issue. To read the full issue please follow the known issues page for 5.1 link, and search for 'client-side messaging issues in apps using old, or custom themes'

Now let's explore each of the suggestions in a bit more detail.

Method #1 - Disallowing client side validation

The first solution is described in the Known Issues as follows:
These differences can be avoided by setting Reload on Submit to Always, (please note the Interactive Grid feature requires this to be set to Only for Success and not using client side validation by either setting app Compatibility Mode to less than 5.1, or setting Execute Validations = No.
Setting Reload on Submit to Always, or disallowing client side validation as described will of course resolve the inconsistencies, but are somewhat brute-force, with the negative side-effects that you cannot benefit from the new way, you are precluded from upgrading your compatibility mode and also by setting Reload on Submit to Always, this means you cannot use the Interactive Grid on that page.

This is good for a quick-fix, but does place limitations upon your app, which are far from ideal.

Method #2 - Updating your theme

A better way to resolve this, and one that doesn't limit you in the same way as detailed in Method #1, is to update your themes so that they work better with the new client side messaging. Specifically this involves an update to your theme's label templates. 

The reason that the client side messaging functionality is not able to use the markup from the label template, is because it relies on the following:
  1. The error markup being provided in the Error Template attribute of the label template.
  2. The #ERROR_TEMPLATE# substitution string being included in either the Before Item or After Item attribute of the label template.
Now we know what's required, let's look at an example using the standard Theme 21, and the Optional Label with Help label template. In this template, you will see the Error Display information is provided as follows:

Screenshot showing Theme 21 > Optional Label with Help label template before any changes. Shows an empty Error Template and error markup defined in the On Error Before Label and On Error After Label attributes
Theme 21 > Optional Label with Help label template before any changes. Shows an empty Error Template and error markup defined in the On Error Before Label and On Error After Label attributes

Given the aforementioned rules, this clearly won't work, there is no Error Template defined, so the client side will need to resort to its fallback template, causing the possible inconsistencies.

So firstly, we need to move the error related markup into the Error Template attribute. However, this presents a slight problem, because the way it is currently, the On Error Before Label markup will be rendered exactly as described, before the label markup when an error occurs, and the On Error After Label markup similarly will be rendered after the label markup. This means that it will effectively wrap the label markup in the template, which is very difficult to replicate by switching to the Error Template approach (where the markup is defined in its entirety in a single place, and inserted into the template in a single place). Unfortunately this means we will need to compromise, and go with an approach that will be slightly different to how it looked prior to 5.1, however importantly this will be consistent between client side and server-side rendered messages now, and without the downsides of having to resort to Method #1.

So we move the combined error markup into the Error Template, as shown:

Screenshot showing Theme 21 > Optional Label with Help label template after moving the error markup into the Error Template attribute
Theme 21 > Optional Label with Help label template after moving the error markup into the Error Template attribute

Note: We removed the line break because we no longer need to force a new line after the label as was the case before, and because the DIV will automatically start on a new line because it is a block-level element, so the error will appear on a new line after its preceding element.

The next part is to add the #ERROR_TEMPLATE# substitution string to the best place in either of the two attributes where it is supported in a label template, either the Before Item or After Item attributes. Let's go with the more common approach of displaying the error after the item, so simply add #ERROR_TEMPLATE# in the After Item attribute, as shown:

Screenshot showing #ERROR_TEMPLATE# substitution string added to the After Item attribute of the label template

You will need to replicate this in the different label templates in your app, and of course different themes will have slightly different implementations for label templates, but if you follow the rules laid out above, then it should be a fairly straight forward switch over. 

Screenshot showing Updated appearance following template change with the error displayed below the input, now consistent irrespective messaging type
Updated appearance following template change, now consistent irrespective messaging type

Method #3 - Migrate to Universal Theme

This will almost certainly result in the most work, but will provide great benefit in the long run, and all these problems will automatically go away.

Screenshot showing Universal Theme Sample Application, available in your workspace via Packaged Apps > Sample
Universal Theme Sample Application, available in your workspace via Packaged Apps > Sample

This will fix these inconsistency issues, and would be the best thing you can do to also benefit from the huge improvements offered by Universal Theme over our legacy themes, but will most likely take the most time and should be considered as part of a migration project (rather than a simple change), so may of course not be feasible. To see our Migration Guide, specifically the section entitled Migrating from Other Themes for further information.


The new client side messaging of APEX 5.1 offers some great benefits over the server-side approach, but does represent some issues with inline errors and apps not using Universal Theme as detailed here. If you have time, converting to Universal Theme would definitely be the way to go, there are just such massive improvements to benefit from in terms of capability, accessibility, responsiveness, modern look and feel, and more, but this will of course take the most time and investment. If this is not feasible, we would recommend updating your existing themes as detailed here, to be able to provide a consistent look and feel, and still benefit from other new features in 5.1 as described.

No comments: