Difference between the multiple messaging options in Visualforce?

I have always been curious what are the exact differences between all of the messaging options Visualforce provides, such as <apex:message>, <apex:messages>, <apex:pageMessage>, and <apex:pageMessages>. The description the Salesforce documentation provides can be rather cryptic.

<apex:message>

A message for a specific component, such as a warning or error. If an or component is not included in a page, most warning and error messages are only shown in the debug log.

<apex:messages>

All messages that were generated for all components on the current page. If an or component is not included in a page, most warning and error messages are only shown in the debug log.

<apex:pageMessage>

This component should be used for presenting custom messages in the page using the Salesforce pattern for errors, warnings and other types of messages for a given severity. See also the pageMessages component.

<apex:pageMessages>

This component displays all messages that were generated for all components on the current page, presented using the Salesforce styling.

So, most of that sounds relatively similar. What are the differences and what are the use cases for each?


Let me start off by explaining each of these in more detail.

<apex:pageMessage> is used to display a single custom message using the Salesforce formatting. You can specify the severity (which will control the display of the message box) and the strength (which will control the size of the box). Take the following code for example:

<apex:page>
	<apex:pageMessage summary="This is a pageMessage" severity="info" strength="3"/>
</apex:page>

Renders as:

pageMessage

Now let’s tweak that code slightly:

<apex:page>
	<apex:pageMessage summary="This is a pageMessage" severity="error" strength="1"/>
</apex:page>

Notice how I changed the severity and the strength. This controls the size and the display of the message. This renders as:

apex:pageMessage error

This can be used to display any custom message that you always want to appear on the screen. There may be a case that whenever a user is on a form you may want a warning to appear to display important information to them.

<apex:pageMessages> is used to display all of the messages on a page. It will display Salesforce generated messages as well as custom messages added to the ApexPages class. Let’s take a look at it in use:

<apex:page controller="TestMessageController">
	<apex:pageMessages />
</apex:page>

public class TestMessageController{
    public TestMessageController(){
         ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, 'This is apex:pageMessages'));
    }
}

This renders as:

apex:pageMessages

Let’s add some more messages and see how it reacts:

<apex:page controller="TestMessageController">
	<apex:pageMessages />
</apex:page>

public class TestMessageController{
    public TestMessageController(){
         ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, 'This is apex:pageMessages'));
         ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, 'This is apex:pageMessages still'));
         ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.INFO, 'This is apex:pageMessages info'));
         ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.INFO, 'This is apex:pageMessages warning'));
    }
}

This renders as:

apex:pageMessages more messages

Notice how that single instance of the <apex:pageMessages> handles all of the errors on the page. The use case for this object is to capture all errors on the page. It should be used on most custom Visualforce page as a catch all to let users know what errors occur (if no other messaging is used).

<apex:message> is used to display an error on only a very specific field. It is used to allow the developer to place field specific errors in a specific location. Take the following code for example:

<apex:page controller="TestMessageController">
	<apex:form >
		<apex:outputLabel value="Test String" /><apex:inputText value="{!test.Name}" id="test"/>
		<br/><apex:message for="test"/>
	</apex:form>
</apex:page>

public class TestMessageController{
    public Account test{get;set;}
    public TestMessageController(){

    }
}

renders as:

enter image description here

Notice how this currently doesn’t have a message displayed. Also notice how this particular element is specified specifically for one field. The error will only occur on that one field. Let’s change the code a bit and take a look at this with an error on the Name field:

<apex:page controller="TestMessageController">
	<apex:form >
		<apex:outputLabel value="Test String" /><apex:inputField value="{!test.Name}" id="test"/>
		<br/><apex:message for="test"/>
	</apex:form>
</apex:page>

public class TestMessageController{
    public Account test{get;set;}
    public TestMessageController(){
        test = new Account();
        test.Id.addError('Correct');
        test.Name.addError('Wrong');
    }
}

This renders as:

apex:message

Notice how only the Name error is shown because that is the only field that has an <apex:message> associated to it. Also notice that although this does have some styling, the styling is minimalistic and Salesforce expects the developer to handle the styling as necessary in this situation.

The final thing to look at is <apex:messages>. <apex:messages> is similar to <apex:message>, but it displays all of the errors. These errors are displayed as a list with no styling. Let’s take the last example we used in the <apex:message> and simply add the <apex:messages> tag to the Visualforce. The code:

<apex:page controller="TestMessageController">
    <apex:messages />
    <apex:form >
      <apex:outputLabel value="Test String" /><apex:inputField value="{!test.Name}" id="test"/>
      <br/><apex:message for="test"/>
    </apex:form>
</apex:page>

public class TestMessageController{
    public Account test{get;set;}
    public TestMessageController(){
        test = new Account();
        test.Id.addError('Correct');
        test.Name.addError('Wrong');
    }
}

renders as:

apex:messages

This provides no formatting for the errors, however, it does display them all. The use case for using <apex:messages> is to display all errors on the page while providing your own styling.

Now, to close it all out, let’s take a look at them all together. The code:

<apex:page controller="TestMessageController">
    <apex:pageMessages />
    <apex:pageMessage summary="This is apex:message" severity="info" strength="2"/>
    <apex:messages />
    <apex:form >
      <apex:outputLabel value="Test String" /><apex:inputField value="{!test.Name}" id="test"/>
      <br/><apex:message for="test"/>
    </apex:form>
</apex:page>

public class TestMessageController{
    public Account test{get;set;}
    public TestMessageController(){
        ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, 'This is apex:pageMessages'));
        test = new Account();
        test.Id.addError('Correct');
        test.Name.addError('Wrong');
    }
}

renders as:

All together now!

As expected, <apex:pageMessages> shows all of the errors with formatting, <apex:pageMessage> only shows the specified message, <apex:messages> shows all of the errors with no formatting, and <apex:message> shows only the error for the specified field.

Note: This is a repost of my original question and answer which can be found on the Salesforce StackExchange.

21 Responses to “Difference between the multiple messaging options in Visualforce?”

  1. Peter Knolle
    August 12, 2013 at 12:05 pm #

    Amazing article!

  2. Ravindra
    September 12, 2013 at 12:03 am #

    Thanks for sharing.. 🙂

    • September 12, 2013 at 8:09 am #

      I’m glad you enjoyed it enough to comment! This was a topic that always interested me, so I really enjoyed writing this article.

  3. Mayank Pant
    September 16, 2013 at 4:43 am #

    It is really a very good article on visual force messaging. Can you also provide us with the limitations of apex/visual force page messaging.

    Thanks!

    • September 16, 2013 at 8:21 am #

      I don’t believe there are limits when working with this type of messaging Mayank. At least, none that I am really aware of. It is just adding messages to the Visualforce page, so it shouldn’t add extra processing that Salesforce would be concerned with.

  4. September 17, 2013 at 8:16 am #

    Hi Jesse,

    Great article, this is one area often considered after the fact in development yet Clear concise messages, error or warning really go a long way in making software user FRIENDLY!!!!!

    Larry

    • September 17, 2013 at 8:27 am #

      I am glad you enjoyed it Larry. I agree, it is crucial to user experience to be able to easily tell them what is going on with the system. Using these methods allow you to do exactly that.

  5. Bhupendra
    November 26, 2013 at 8:22 am #

    Thanks for the Nice Article. I was reading salesforce help and was puzzled with the message behavior. This article corrected my all understanding about apex message.

  6. Arjun
    December 26, 2013 at 12:52 pm #

    Hi , I felt so happy after reading this article . I always wondered about different types of messages in sales force. Now I am crystal clear. Continue sharing your knowledge.
    Thanks Jesse.

    • December 26, 2013 at 12:55 pm #

      I am really glad you enjoyed it! Keep checking every Monday morning at 6:45am EST for new articles!

  7. janakiram
    January 7, 2014 at 7:45 am #

    Very Helpful

  8. Vanita
    January 11, 2014 at 11:17 am #

    Its a good article. Thank you for sharing. Some of my doubts got clear & also learned some different ways to display messages on page, like for a particular field and collectively as well.

  9. Oleksiy
    October 24, 2014 at 5:22 pm #

    I’m wondering why there is no any copyright marks or reference links there http://www.salesforcegeneral.com/salesforce-articles/explore-different-messaging-options-in-visualforce-part-1.html
    Thanks for the great post!

  10. shivkumar
    June 28, 2015 at 12:48 am #

    Very nice article . It clears all the confusions .

  11. Alba Azcona
    November 30, 2015 at 7:57 am #

    Nice and very clear article, thank you!!

  12. December 1, 2015 at 3:01 am #

    This is very informative, concise and crisp.
    Thanks for sharing 🙂

  13. Drew Chaplin
    July 29, 2016 at 11:43 am #

    Thanks, this helps. One question I haven’t found answered yet.

    I’m using field level Add.Error for specific errors, but I also have apex:pageMessages to capture remaining.

    So in your example, the “Wrong” error would also show up under the inputfield but NOT in the pagesMessages. Is that possible?

Trackbacks/Pingbacks

  1. Apex pageMessage revealed | TechNext - March 11, 2014

    […] http://jessealtman.com/2013/08/difference-between-the-multiple-messaging-options-in-visualforce/ […]

  2. PageMessages & Testing | My Salesforce adventure - December 21, 2015

    […] to know more about the different options for showing messages in a Visualforce page, take a look at this great post from Jesse […]

Leave a Comment