Unverified Commit dddf05ba authored by Rich Lott's avatar Rich Lott Committed by GitHub
Browse files

Merge pull request #7 from civicrm/issue/6

Fix for issue #6
parents d7634c7b 6cd40bd4
......@@ -16,7 +16,7 @@ The extension is licensed under [AGPL-3.0](LICENSE.txt).
* PHP v5.4+
* CiviCRM 4.7.28+ (recommended)
* CiviCRM-Mosaico v2.0-beta3+ ***Note:** You should ensure you are using the official beta3 from https://github.com/veda-consulting/uk.co.vedaconsulting.mosaico - some of the forked beta3 versions do not work with this extension.*
* CiviCRM-Mosaico v2.0-beta3+ **Note:** *You should ensure you are using the official beta3 from https://github.com/veda-consulting/uk.co.vedaconsulting.mosaico - some of the forked beta3 versions do not work with this extension.*
## Installation
......@@ -40,7 +40,8 @@ cv en mosaicomsgtpl
```
## Normal Usage
Simply enable the module. All ordinary tasks should be handled automatically.
Simply enable the module. All ordinary tasks should be handled automatically,
but see Special Links below.
CiviCRM Message Templates have both a *name* and an email *subject*, but Mosaico templates do not have a subject. By default the name of the Mosaico template will be used for both the message template name and also its subject. This might or might not be appropriate to your use case.
......@@ -52,6 +53,33 @@ As a work-around, you can use the format `title | subject` to specify your Mosai
| Thanks - existing donors \| Well hi there | Thanks - existing donors | Well hi there |
## Special Links (unsubscribe, show online)
CiviMail mailings can include unsubscribe links and "show online" links. Mosaico complicates this a bit further by using its own custom tokens for this, `[unsubscribe_link]` and `[show_link]`.
Most message template use is for *transactional* email not *bulk* email, but there are cases when this boundary is blurred (e.g. "Welcome to our newsletter list" type emails that the recipient should still be able to unsubscribe from, or automated mailings based on message templates, e.g. from the [Chassé extension](https://github.com/artfulrobot/chasse)).
It's your responsibility to check that these links are used properly (or not used). The options are:
### Unsubscribe Links
If you are writing a message template that will be sent via CiviMail you should be covered because this extension will change the Mosaico tokens for CiviMail ones, and CiviMail will then substitute those.
If you are writing a message template that will be sent by some other means, e.g. sending an email as an activity, or using the MessageTemplate.send API method, then you will need to either:
1. Remove all unsubscribe links (e.g. in Mosaico remove the "Pre Header" section, as well as any `{action.unsubscribeUrl}` links). This may be fine for transactional email that does not require the unsubscribe offer.
2. Write your own code to substitute the `{action.unsubscribeUrl}` with an appropriate other link, e.g. maybe you have a WebForm set up that can give users a way to unsubscribe from certain mailings, and you could construct a URL to that including the contact hash. You can do this with [`hook_civicrm_alterMailContent`](https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_alterMailContent/). However please note that as this extension also uses that hook and may get called after your extension, you should look to also substitute `[unsubscribe_link]` in your code.
### Show Online Link
This one is more tricky because there is no way in Mosaico's template to remove the Show Online link if using the preheader. So you can either remove the preheader element for these mailings or write your own code using the hook mentioned above and a regular expression to remove the full link.
### Other CiviMail tokens
There are many [tokens available](https://docs.civicrm.org/user/en/latest/common-workflows/tokens-and-mail-merge/#available-tokens) that may not be appropriate for Message Template use. You should check that any tokens in use still behave properly.
## API Usage
System administrators and developers may wish to use the synchronization API:
......
......@@ -136,6 +136,35 @@ function mosaicomsgtpl_civicrm_alterSettingsFolders(&$metaDataFolders = NULL) {
_mosaicomsgtpl_civix_civicrm_alterSettingsFolders($metaDataFolders);
}
/**
* Implements hook_civicrm_alterMailContent
*
* Replaces Mosaico template custom tokens with proper CiviMail tokens.
*
* Note that this can still result in broken links if the mail is not sent
* using CiviMail, but that's a user-error not a coding one. (Anyone can put
* the {action.unsubscribeUrl} token in a message template but it's not going
* to work since there's nothing to unsubscribe *from*.)
*
* @see https://github.com/civicrm/org.civicrm.mosaicomsgtpl/issues/6
* @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_alterMailContent/
*
* @param Array $content - fields include: html, text, subject, groupName, valueName, messageTemplateID
*
*/
function mosaicomsgtpl_civicrm_alterMailContent(&$content) {
if (!empty($content['messageTemplateID'])) {
// This mailing was created by a Message Template, so it could have the Mosaico-based custom tokens in it.
$replacements = [
'[unsubscribe_link]' => '{action.unsubscribeUrl}',
'[show_link]' => '{mailing.viewUrl}',
];
$content['html'] = strtr($content['html'], $replacements);
$content['text'] = strtr($content['text'], $replacements);
}
}
// --- Functions below this ship commented out. Uncomment as required. ---
/**
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment