[title sub="Written by Patrick Schmalstig"]Composr Tutorial: Pinning messages at the top of pages[/title]

{!site_messaging:DOC_SITE_MESSAGING}

[contents]decimal,lower-alpha[/contents]

[title="2"]Managing site messages[/title]
Clicking Admin Zone > Setup > Site messaging will take you to a simple do-next screen to assist you with setting up your site messages.
[media_set]
[media width="150" description="The site messaging item is under Admin Zone > Setup > Site messaging."]data_custom/images/docs/tut_site_messaging/menu_location.png[/media]
[media width="150" description="The simple do-next screen will assist you with managing your messages."]data_custom/images/docs/tut_site_messaging/donext.png[/media]
[media width="150" description="This is an example of the display of a site message."]data_custom/images/docs/tut_site_messaging/example.png[/media]
[/media_set]

[title="3"]Adding a site message[/title]
[media width="150" description="There are several criteria you can define for a site message" float="right"]data_custom/images/docs/tut_site_messaging/add.png[/media]
The screen for adding a site message gives you several options from which to choose. We will cover those in this section. Here are the basic options:
 - [b]Title[/b]: This is just a label and is only used on the "Edit a site message" screen and the action log. It allows you to easily identify different site messages.
 - [b]Message[/b]: This is the actual contents of the message to be displayed. The field allows Comcode, so you could for example specify a URL tag to create a link.
 - [b]Type[/b]: This defines the level of importance for the message and thus how it is displayed on the site. Warnings show up in red.
 - [b]Start[/b]: You can optionally specify a start date and time for the message. If left blank, it will start showing immediately.
 - [b]Expiry date[/b]: You can optionally specify an expiry date and time for the message. If left blank, the message will continue showing until you manually edit or delete it.
 - [b]Validated[/b]: If the validation addon is installed, you can hide certain messages while preserving all their settings by turning this to 'Off'.

[title="3"]Advanced filtering[/title]
There are two advanced criteria that can optionally be used to further filter who sees the message and where: usergroups and match-keys.

[title="4"]Advanced filtering: Usergroups[/title]
If the "Usergroups" multi-list field is left blank, then the message will show for members of all usergroups. Otherwise, the member must be in one or more of the defined usergroups to see the message.

[title="4"]Advanced filtering: Match-keys[/title]
[media width="150" description="If you need help getting the page-link of a current page, they are typically visible in the footer when viewing as an administrator." float="right"]data_custom/images/docs/tut_site_messaging/page_link_footer.png[/media]
Match-key filtering is a very powerful tool which allows you to show specific messages on specific pages. For example, you may want to show a reminder message to staff to do something if they are on a specific page in the Admin Zone. Or you may want to indicate there is a known bug on a particular screen. The possibilities are endless.

If the "Match-keys" multi-line field is left blank, then the message will show everywhere. Otherwise, the message will only show if one or more of the specified match-keys match the current page.

At minimum, every match-key specified must contain a [tt]zone:page[/tt], and any that do not will be skipped automatically. You can use [tt]_WILD[/tt] in any portion of the match-key as a catch-all.

You can also specify additional bits to further filter the message. You can specify [tt]zone:page:type[/tt] (to also filter by type) or even [tt]zone:page:type:id[/tt] (to also filter by type and ID). If you just want to filter by ID but not type, you will need to do [tt]zone:page:id=the_id[/tt], or you can do [tt]zone:page:_WILD:id[/tt]. Other parameters are also supported, just add them in as [tt]:param=value[/tt].

Here are some examples:
 - [b]_WILD:_WILD[/b]: This will show everywhere; this has the same behaviour as not defining any match-keys.
 - [b]adminzone:_WILD[/b]: This will show on all pages in the Admin Zone.
 - [b]:home[/b]: This will show on the home page of the welcome (unnamed) zone.
 - [b]_WILD:home[/b]: This will show on the home pages of every zone (assuming every zone has defined "home" as its home page).
 - [b]site:tickets[/b]: This will show on every screen in Support Tickets, but only if the Support Tickets module is in the site zone.
 - [b]_WILD:tickets[/b] or [b]_SEARCH:tickets[/b]: You should use this syntax instead when dealing with modules; this will show on Support Tickets regardless what zone it is in.
 - [b]_WILD:cms_news:add[/b]: This will show when adding a new news article.
 - [b]_WILD:cms_news:_edit[/b]: This will show when editing any news article.
 - [b]_WILD:cms_news:_edit:1[/b] or [b]_WILD:cms_news:_edit:id=1[/b]: This will show when editing the news article with an ID of 1.
 - [b]_WILD:cms_news:_WILD:1[/b] or [b]_WILD:cms_news:id=1[/b]: This will show when dealing with any CMS action involving news article ID 1 (such as editing or deleting).
 - [b]_WILD:news:view:1[/b]: This will show when viewing news article ID 1.
 - [b]_WILD:members:view:test[/b]: This will show on test's member profile (you can also use a member ID instead of the username).
 - [b]_WILD:report_content:content_type=member[/b]: This will show when reporting specifically a member profile via the "Report this" link.

[title="2"]Use cases[/title]

Here are some of the many ways you can use site messages:
 - Inform users of scheduled maintenance which may impact portions of the site (using match-key filtering on the specific locations) or the site as a whole
 - Inform users of bugs or problems in certain areas of the site that have not yet been fixed
 - Announce the future removal / change of a site section, feature, or page
 - Inform that a user is looking at old content and provide a link to the updated content
 - Make critical announcements that need higher visibility than what news alone can offer
 - Make collaboration notices (e.g. if you use git for your site, you could put a message on the Comcode edit screen informing staff not to edit pages through the UI but to edit the txt files manually)
 - Announce exclusive content to specific usergroups
 - Make an announcement that only appears to guests but disappears when they log in (e.g. selecting all usergroups except guests)
 - Make disclaimers of liability of content in user-centric locations, such as the forums

[concepts
 1_key="Site messaging"  1_value="The system / interface for setting up site messages."
 2_key="Site message"    2_value="A small pinned / global message that shows at the top of a page."
]Concepts[/concepts]

[title="2"]See also[/title]

 - [page="_SEARCH:tut_news"]Releasing news & running a Blog[/page]
 - [page="_SEARCH:tut_adv_news"]Advanced news[/page]
 - [page="_SEARCH:tut_configuration"]Basic configuration and getting started[/page]

{$SET,tutorial_tags,news_shared,news,site_messaging,syndication,syndication_blocks,Collaboration,Maintenance,News,novice}{$SET,tutorial_add_date,May 2024}{$SET,tutorial_summary,How to pin messages at the top of site pages for critical information communication.}[block]main_tutorial_rating[/block]