Take the 2-minute tour ×
Salesforce Stack Exchange is a question and answer site for Salesforce administrators, implementation experts, developers and anybody in-between. It's 100% free, no registration required.

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 at times 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. - http://www.salesforce.com/us/developer/docs/pages/Content/pages_compref_message.htm


<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. - http://www.salesforce.com/us/developer/docs/pages/Content/pages_compref_messages.htm


<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. - http://www.salesforce.com/us/developer/docs/pages/Content/pages_compref_pageMessage.htm


<apex:pageMessages>

This component displays all messages that were generated for all components on the current page, presented using the Salesforce styling. - http://www.salesforce.com/us/developer/docs/pages/Content/pages_compref_pageMessages.htm


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

share|improve this question

1 Answer 1

up vote 69 down vote accepted

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>

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: I have reposted this question and answer on my website. It can be found here.

share|improve this answer
6  
greased lightning! –  bigassforce Feb 6 '13 at 15:36
3  
awesome... great explanation.. i always wondered what was the difference –  Prady Feb 7 '13 at 6:23
2  
Just a correction to Jesse's answer. In the &lt;apex:message/&gt; example, the message is being displayed because an &lt;apex:inputField/&gt; tag is being used. You could delete the &lt;apex:message/&gt; tag from the example Visualforce page and the message will still display. Change the &lt;apex:inputField/&gt; tag to be an &lt;apex:inputText/&gt; tag in the example Visualforce page and watch as the message never displays with the input component. –  beamso Apr 8 '13 at 7:54
1  
I never knew that a stackexchange post could be epic. Thank you! –  Shane McLaughlin Apr 9 '13 at 2:17

protected by Jesse Altman Oct 21 '13 at 13:28

Thank you for your interest in this question. Because it has attracted low-quality answers, posting an answer now requires 10 reputation on this site.

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.