messages.md

Updating Community Messages:

Community messages are stored in a Google Spreadsheet. Changes to that sheet are deployed automatically. If a site meets all the criteria for a given message, it will be shown on the CiviCRM dashboard. If more than one message matches the criteria for a given site, users will be randomly shown a different message each time they visit their dashboard.

Note: the order of the columns in the spreadsheet does not matter, but the names do. Do not rename any column header without also updating the code which depends on it.

Columns

Criteria:

live

("yes" "no" or "test"). Warning when this column is "yes" the message will automatically be published (generally in about an hour).

type

("offers", "events", "asks", "releases" or leave blank). Allows sites to opt-out of certain types of messages.

reg

Has this site registered? ("yes"/"no" or leave blank for no filtering). This is currently difficult to determine and there are many registered sites this system doesn't know about.

mem

Are they a member? ("never", "yes", "new", "expiring", "grace", "past", or leave blank for no filtering). Note: "yes" encompasses "expiring" "new" and "grace".

age

How old is this site? Requires an operator (< or >) + relative date. Examples: "< 2 months", "> 1 year"

ver

Version of CiviCRM. Optional operator (<, <=, >, >=, != or omit operator to assume ==) + version number. Examples: "< 4.7", ">= 4.6.5". Specifying a major version like "4.6" will include all point releases (4.6.1, 4.6.2 etc.).

cms

Drupal, Wordpress, Joomla, or Backdrop.

components

(comma-separated e.g. "CiviMail,CiviMember") - if supplied, message will be hidden if any listed components are disabled.

perms

(comma-separated e.g. "access CiviCRM") - if supplied, only users with this permission will see the message. If left blank, defaults to "administer CiviCRM".

country

(comma-separated e.g. "US, Europe, Australia") - if supplied, limits the audience to sites in the specified countries or regions. Country names (United States), 2-letter ISO codes (US) or world regions (Americas) can all be used. See full list of countries, codes and regions.

Content:

url

Any part of the message surrounded by double-square brackets [[like this]] will become a link to this url.

en

e.g. "**Message title** Message body with [[link to something]]." This is the only required field in the spreadsheet.

fr, es, etc.

To translate to another language add a new column to the spreadsheet with that language code as the header and it will be auto-detected by the messages app. If a language is missing, the messages app will default to English.

Tokens

The following tokens can be used in constructing the url or the message. Tokens like %%this%% will be output normally, and tokens like {{this}} will be encoded for use as a url argument.

Token	Description
resourceUrl	Url to the local CiviCRM root (w/o trailing slash)
baseUrl	Base url of the website
ver	Local CiviCRM version #
uf	CMS used (Drupal, WordPress, etc.)
php	Local PHP version
sid	Unique site identifier hash
lang	Full language code e.g. en_US
co	Country id (e.g. 1228 for USA)

The following will only work if we can identify the org and look them up in our own db. Since pingbacks are anonymous, we can only identify them if they have already registered or signed up for a membership through this app.

Token	Description
contact_id	Organization id in civicrm.org/civicrm db
display_name	Organization name
membership_start_date	Start date (members only)
membership_end_date	End date (members only)
membership_status_id	Id of membership status (members only)
membership_status	Name of membership status (members only)

Testing

Any CiviCRM site can be used for testing messages. By setting the site_id to "test_mode" (CRM.api3('Setting', 'create', {site_id: "test_mode"}) from the javascript console) the site will show messages where "live" is set to "yes" or "test". This setting also bypasses caching so that changes to the google spreadsheet will be visible in about 30 seconds instead of an hour.