ERP 2.50:Developers Guide/Concepts/Messages
Contents |
Introduction
Messages are used to display information to the user, they are typically shown when a process is completed or when an event occurs (for example an error).
Types of messages
The different types of messages that can be shown with Openbravo are:
- Success messages
- Failure messages
- Warning messages
- Information messages
Success messages
These messages will be shown after the execution of a process in case of success. In this case it should be shown the corresponding message in the zone of messages with a green background color.
Failure messages
These messages will be shown after the execution of a process in case of error. In this case it should be shown the corresponding message in the zone of messages with a red background color.
Warning messages
These messages will be shown when certain conditions have to be taken into account by the user, as for example a message indicating that the client selected has surpassed the limit established, etc. In this case the corresponding message should be shown in the messages area with a yellow background color.
The example shows a warning message happened because the user is trying to print labels but he/she has not properly connected the printer.
Information messages
These messages will be shown in order to communicate any information to the user, as for example the functionality of the window, etc. In this case the corresponding message should be shown with a blue background color.
Application Dictionary definition
All messages are maintained in Application Dictionary || Message window (AD_Message table). Basically a message consists in a Search Key or value, a Message Type which sets the color for the box and a Message Text containing the text that will be displayed within the box. Additionally messages can be translated to different languages, to add translations to a message use the Translation tab.
Search Key field is a unique identifier for the message, it is not displayed to the user but it is used internally to identify the message. Thus, for example, when a java class needs to show a message it is the search key value used to select the message.
Message usage
Depending on the object raising the message, some different considerations must be taken into account.
Database
Processes
As explained in the PL/SQL processes section of this guide, the final result as well as the message to be shown to the user from a PL process is stored in the |AD_PInstance record that was used to invoke it.
This message can be a static string which will be displayed as is in UI:
AD_UPDATE_PINSTANCE(p_PInstance_ID, v_User_ID, 'N', 1, 'Show this static text');
This kind of message does not make use of the messages defined in Message window. To use them it is necessary to set the message identifier (Search key Value) surrounded by at symbols (@):
AD_UPDATE_PINSTANCE(p_PInstance_ID, v_User_ID, 'N', 1, '@HR_MyMessage1@');
In the line above when the process is finished the application will try to find a message which value is HR_Message1 and it will display the text it contains. Note that as messages are translatable, if user is logged in the application with one of the languages the message has been translated to, he/she will see the text in that language.
Furthermore, it is possible to combine more than one message and static text. For example:
AD_UPDATE_PINSTANCE(p_PInstance_ID, v_User_ID, 'N', 1, '@Success@, 5 @LinesCreated@');
This message will concatenate the text in message with identifier Success with the static text ', 5 ' and with the text for message LinesCreated.
All exceptions raised by processes should be caught to manage them and insert a proper message in PInstance
Exceptions
Exceptions are specially useful for triggers, when an exception is raised within a trigger the current transaction is rolled back. This allows to do some checks before updating or inserting a row in a table and in case some verifications are not satisfied an exception can be raised provoking the row not to be inserted/updated.
Oracle
Oracle identifies each error by a numeric code, range between -20000 and -20999 belongs to custom errors, and using the RAISE_APPLICATION_ERROR procedure they can be associated to a message.
When Openbravo ERP catches one of these errors it tries to find a message with the same Search Key as the code number, if it exists it will display the text in the same way as explained in the previous version to replace the message between at symbols (@) with the matching message.
It is not recommendable to use these code numbers to manage messages because:
- They cannot be defined within modules. As the only identifier they have is a numeric value there's no way to include them in modules without the risk of two different modules using the same number for different purposes.
- This is Oracle specific and cannot be used in PostgreSQL, thus they will not work in the same way in PostgreSQL.
So it is better to use a number which has no associated message and insert within the text the identifier for the message to be used. With this intention there is not message for value 20000, so when it is used the message will be taken from the second parameter:
RAISE_APPLICATION_ERROR(-20000, '@HR_MyErrorMessage@');
PostgreSQL
PostgreSQL doesn't manage code value for errors, so the only way to identify a message to be displayed is identifying it by its Search Key.
RAISE EXCEPTION '%', '@HR_MyErrorMessage@';
Checks
Check restrictions are defined in database to ensure data integrity, they define some restriction that data must be fulfill. In case when inserting or updating some data in database it does not satisfy a constraint, an error is raised.
When a piece of data is tried to be inserted in a table with a check constraint and that data does not follow the rules defined by that constraint, a database error is raised. By default, if there is no an Application Dictionary Message associated to that constraint a generic error message will be shown in the UI.
It is possible to refine that error by adding a new message with the same Search Key as the constraint's name. In this case instead of appearing that generic message, it will be showed the new one.
Manual windows
HTML template
In order to make HTML capable to show messages, the HTML template must include:
a) These imports in the <HEAD> section
<script language="JavaScript" src="../../../../../web/js/messages.js" type="text/javascript"></script> <script language="JavaScript" src="../utility/DynamicJS.js" type="text/javascript"></script>
b) Into the <BODY> section the following block of code just after
<div class="Main_ContentPane_Client" ...> or <div class="Popup_ContentPane_Client" ...> depending if it is a main or popup window:
<table cellpadding="0" cellspacing="0" id="messageBoxID" class="MessageBoxyy"> <tbody> <tr class="MessageBox_TopMargin"> <td class="MessageBox_LeftMargin"></td> <td></td> <td class="MessageBox_RightMargin"></td> </tr> <tr> <td class="MessageBox_LeftMargin"></td> <td> <table cellpadding="0" cellspacing="0" class="MessageBox_Container"> <tbody> <tr> <td class="MessageBox_LeftTrans"> <table style="width: 100%; height: 100%" cellpadding="0" cellspacing="0"> <tbody> <tr> <td class="MessageBox_TopLeft"></td> </tr> <tr> <td class="MessageBox_Left"></td> </tr> </tbody> </table> </td> <td class="MessageBox_bg"> <table class="MessageBox_Top"> <tbody> <tr> <td> <span> <table cellpadding="0" cellspacing="0" class="MessageBox_Body_ContentCell"> <tbody> <tr> <td class="MessageBox_Icon_ContentCell"> <div class="MessageBox_Icon"></div> </td> <td style="vertical-align: top;" id="messageBoxIDContent"> <span> <div class="MessageBox_TextTitle" id="messageBoxIDTitle"> xxInfo: AccessTableWithNoView </div> <div class="MessageBox_TextDescription" id="messageBoxIDMessage"> xxThe current information is empty. </div> <div class="MessageBox_TextSeparator"></div> </span> </td> </tr> </tbody> </table> </span> </td> </tr> </tbody> </table> </td> <td class="MessageBox_RightTrans"> <table style="width: 100%; height: 100%" cellpadding="0" cellspacing="0"> <tbody> <tr> <td class="MessageBox_TopRight"></td> </tr> <tr> <td class="MessageBox_Right"></td> </tr> </tbody> </table> </td> </tr> <tr> <td rowspan="2" class="MessageBox_BottomLeft"> </td> <td class="MessageBox_BottomTrans MessageBox_bg"> </td> <td rowspan="2" class="MessageBox_BottomRight"> </td> </tr> <tr> <td class="MessageBox_Bottom"> </td> </tr> </tbody> </table> </td> <td class="MessageBox_RightMargin"></td> </tr> <tr class="MessageBox_BottomMargin"> <td class="MessageBox_LeftMargin"></td> <td></td> <td class="MessageBox_RightMargin"></td> </tr> </tbody> </table>
XML
The xml used for that template should include the following parameters:
<PARAMETER id="messageBoxID" name="messageType" attribute="class" replace="yy" default="HIDDEN"/> <PARAMETER id="messageBoxIDTitle" name="messageTitle" default=""/> <PARAMETER id="messageBoxIDMessage" name="messageMessage" default=""/>
Java
XML parameters
When a message is wanted to be displayed it is necessary to fill the xml parameters defined above, the Java code to do so looks like:
xmlDocument.setParameter("messageType", "Warning"); xmlDocument.setParameter("messageTitle", "Message Title"); xmlDocument.setParameter("messageMessage", "Message Body");
The first parameter (messageType) specifies the type of message to be displayed, the possible values are: Error, Info, Success and Warning, depending on this value the box for the message will have a different color and icon.
Second parameter (messageTitle) is the string that will be displayed as title for the message.
And the third one (messageMessage) is the text the message will contain.
OBError class
org.openbravo.erpCommon.utility.OBError class just contains the 3 parameters previously explained (type, title and message), it is useful to store a message in session to use it in another servlet doPost. A typical example is a java that executes a process, this process returns a message which is stored in session and the servlet is redirected. Then the servlet managing the redirection looks if there's an OBError object in session and in this case it displays it.
Example:
- After executing the process:
final OBError message = new OBError(); message.setType("Error"); message.setTitle("Process Failed"); message.setMessage("The process failed because an error occurred"); vars.setMessage("YourServlet|Message", message); try { response.sendRedirect(strDireccion + request.getServletPath() + "?Command=DEFAULT"); } catch (final Exception ex) { log4j.error("error", ex); }
This piece of code creates an OBError instance, stores it in session (with the "YourServlet|Message" name) and redirect the flow to the same servlet passing the "DEFALT" command.
- DEFAULT command in that servlet:
final OBError myMessage = vars.getMessage("YourServlet|Message"); vars.removeMessage("YourServlet|Message"); if (myMessage != null) { xmlDocument.setParameter("messageType", myMessage.getType()); xmlDocument.setParameter("messageTitle", myMessage.getTitle()); xmlDocument.setParameter("messageMessage", myMessage.getMessage()); }
Here we look in session for an OBError named "YourServlet|Message", in case it exists the xml parameters are set using the getters in OBError.
Obtaining message text
In the examples above all the texts (both for titles and message bodies) were set as directly Strings, this means they didn't make use of any error defined in Application dictionary and they could not be translated depending on the user interface's language.
To do this there are two methods in org.openbravo.erpCommon.utility.Utility class that facilitate the messages management, they are:
- public static String messageBD(ConnectionProvider conn, String strCode, String strLanguage)
- This method is the simplest one, it receives a database connection, a String with the code of the application dictionary message (search key) and the user interface's language (which can be obtained with vars.getLanguage() method) and it returns the text for that message in the given language. This method is useful for displaying simple messages.
- public static String parseTranslation(ConnectionProvider conn, VariablesSecureApp vars, String language, String text)
- This method works in a similar way than messageBD, but the identifier for the message is passed in the text parameter surrounded by at symbols (@). The text sections that are not between @ will not be parsed, thus is possible to concatenate more than one message and to include also static (non translatable) text. For example text could be like this: @Success@ 2 @LinesCreated@ and the return would be the concatenation of the text in the user's language for Success message, the static text 2 and the text for LinesCreated message.
- public static OBError getProcessInstanceMessage(ConnectionProvider conn, VariablesSecureApp vars, PInstanceProcessData[] pinstanceData)
- This method is used to obtain the result message after executing a PL/SQL process. In the next example the process has been already executed, and its instance id is stored in pinstance variable, these two lines obtain the in myMessage the result message for that process:
final PInstanceProcessData[] pinstanceData = PInstanceProcessData.select(pool, pinstance); final OBError myMessage = Utility.getProcessInstanceMessage(pool, vars, pinstanceData);
Error pages
In some cases instead of displaying an error in a message box in the same page it is useful to show a complete page just with the error. For this purpose org.openbravo.base.secureApp.HttpSecureAppServlet, which is the class all servlets in the application extend from, has some methods:
- public void bdError(HttpServletRequest request, HttpServletResponse response, String strCode, String strLanguage)
- This will display full page error obtained for the message with if strCode and in the language determined by strLanguage. This is used for full screen pages.
- public void bdErrorGeneral(HttpServletRequest request, HttpServletResponse response, String strTitle, String strText)
- This method is equivalent to bdError but it doesn't look in database for the message, it just displays the title and text passed as parameters.
- public void bdErrorGeneralPopUp(HttpServletRequest request, HttpServletResponse response, String strTitle, String strText)
- This method is equivalent to the previous ones but is used when the servlet is going to be shown in a pop up instead of full screen.
Javascript
Is is also possible to show messages directly from Javascript, to do it invoke showJSMessage function in messages.js.
Its usage is quite simple, it accepts a parameter with the code for the message to be shown. If no language is passed it will take the current language. The execution of this function looks for the message in database and shows it in a message box in the correct language.
| Languages: |
ERP 2.50:Developers Guide/Concepts/Multi-Currency | ERP 2.50:Developers Guide/Concepts/Skins look and feel