set-message macro

Overview

Use the set-message macro to display an on-screen message.

It's great for keeping the user informed during the content production process when a workflow event or change occurs.

• messages are shown between the page title and body content whilst viewing content (it's hidden from the edit screen)

• messages can be configured as different panel displays - info, error, warning, success

• if triggered by stateexpired or taskexpired events, the message won't be shown until the page is refreshed

The set-message macro can be filtered to display the message only to a specific user(s).

A message filtered to display to a specific user includes an option for the user to remove it.

The message is removed and replaced when a new trigger event occurs that includes a new set-message action macro (if the message is for the same audience). The message will be cleared if the empty set-message macro in the trigger is empty.

Where to use it?

Optional.

One or more set-message macros can be added as action macros in a trigger macro.

{trigger:statechanged|state=Rejected}
        {set-message}
        The page content has been rejected. The content must be triaged.
        {set-message}
{trigger}

A filter can be added to display the message to specific audiences - for example to one or more users, one or groups

{trigger:statechanged|state=Draft}
        {set-message:user=@user@}
        The page content has been moved to the Draft state. The content must be triaged before submitting for approval.
        {set-message}
{trigger}

If more than one set-message macro is added to a trigger

• only one message will be displayed on the page if all the messages are for everyone (unfiltered)

• more than one set-message macro in the trigger will be displayed on the page if at least one of them is filtered to be displayed to a user(s), group(s) or the draft/published content

Parameters

{set-message}{set-message}

{set-message:view=draft}{set-message}

Removing a message

An empty set-message macro body in a trigger can be used to remove a previously set message.

{set-message} {set-message}

For example, adding the following message on a state transition

{trigger:statechanged|state=Test}
        {set-message:style=success}
        You transitioned to the "Test" state
        {set-message}
{trigger}

This can be removed in a subsequent transition using an empty set-message macro in the trigger.

{trigger:statechanged|state=Ready}
        {set-message}
        {set-message}
{trigger}

Although the set-message macro included a parameter to define the style of the message, both this set-message macro and the empty set-message macro are unfiltered - they are displayed to the same audience - and the message is removed.

If you have the following two messages displayed - one filtered using view=draft and one unfiltered - they are considered as being for different audiences.

{trigger:statechanged|state=Draft}
        {set-message:view=draft|style=info} This is draft content, an approved version has been published{set-message}
        {set-message:style=warning} This content must be triaged and reviewed{set-message}
{trigger}

Using the following in a trigger will only remove the unfiltered warning message.

{set-message} {set-message}

To remove both messages the trigger will need to include an empty set-message macro for each different audience.

{trigger:statechanged|state=Published}
        {set-message}{set-message}
        {set-message:view=draft}{set-message}
{trigger}

Removing a workflow

If an applied workflow is removed from content

• any displayed set-message macro messages are removed from the document.

If the workflow is removed without clearing the document activity

• previous on-screen messages will be displayed on reapplying the workflow (if the state has not been initialized)

Examples

Adding a filtered set-message macro and an unfiltered set-message macro to the same trigger

{workflow:set message test workflow}
    {state:Test}
    {state}
    {state:Ready}
    {state}
    {trigger:statechanged|state=Test}
        {set-message}
        This message shown to everyone
        {set-message}
        {set-message:user=@user@}
        You transitioned to the "Test" state
        {set-message}
    {trigger}
    {trigger:statechanged|state=Ready}
        {set-message}{set-message}
    {trigger}
{workflow}

A transition to the Test state adds two on-screen notifications to the page.

The message from each set-message macro are both displayed as they are considered to be for different audiences

• at least one of the macros is filtered using an added user parameter value or group parameter value

• unfiltered messages are shown in addition to any messages filtered to users

The second message is specific to the user who actioned the transition and is only displayed to this user. This message can be removed by the user using the X option in the message.

Adding one or more unfiltered set-message macros to the same trigger

If a trigger has two or more set-message macros with no filter (no user, group or view parameter added to any of the macros).

{trigger:statechanged|state=Test}
        {set-message}
        Hey, this page needs some triage work!
        {set-message}
        {set-message:style=success}
        You transitioned to the "Test" state
        {set-message}
    {trigger}

• only the last set-message macro content before the closing trigger will be the message displayed on the page on the transition

The first set-message macro action in the trigger is superseded by the second set-message macro.

All examples

• Page:
  Advanced different-space publishing
• Page:
  Advanced remote-space publishing
• Page:
  Attachment events — Triggering events when attachments are created, updated or removed.
• Page:
  Blog Post Events — Workflow events associated with blog posts
• Page:
  Message notification styles — Test the style parameter of the {set-message} macro
• Page:
  Using set-message and metadata to display different information for the draft and published content — Using the view parameter of the {set-message} macro to display a different metadata when users view the draft or published versions

See also

Workflow Authoring Guide:

• Notifications

• Expiry Dates

• Events

• Triggers

• Actions