Mosaico Extension v2.0-beta3, etal

During the month of November, we made a concerted effort to stabilize the CiviCRM-Mosaico extension -- addressing several bugs, installation issues, missing features, and testing processes. I'm happy to announce a new beta releases of the Mosaico and FlexMailer extensions for CiviCRM. The updates include ~160 commits from ~15 contributors.

Credits

v2.0-beta3 has been made possible through the work of over a dozen people. Multiple contributions were provided by the maintainers (Deepak Srivastava of Veda and Tim Otten of CiviCRM) as well as the Compucorp theming team (Maged Adel, Mihael Mladenov, Mukesh Ram), Matthew Wire (MJW), and Samuel Vanhove (SymbioTIC). Additional contributions were provided by Anne Dru, David Snopek, Francesc Bassas, Jitendra Purohit, John Kingsnorth, Matthew Roberts, and Philipp Batroff. And, of course, all of this is built on the great upstream project, Void Labs' Mosaico.

(And I apologize if I've missed anyone -- it's hard to keep track with all the ways people contribute.)

Install or upgrade

To install the latest beta, consult the README.

Please note:

• If you are upgrading from a previous beta, please download the updates for FlexMailer, Shoreditch, and Mosaico.
• v2.0-beta3 has been mostly tested on the pre-release version of CiviCRM v4.7.29, but it's also been lightly tested on v4.7.27.

Changes

Overall, the general aim of beta3 was to resolve open PRs and common issues. Many of the changes are bugfixes aimed at "doing what you expect", e.g.

• Positioning the Mosaico box with respect to navbars, dialogs, etc (esp. on different CMS contexts)
• Fixing image URLs and broken links in emails
• Improving compatibility with recent CiviMail changes

Additionally, some improvements have a more conscious impact on users, administrators, or developers. Let's explore those a bit further.

Status checks

Deploying the Mosaico extension requires several steps, such as installing ImageMagick, FlexMailer, Shoreditch, and the upstream Mosaico codebase. Each step is an opportunity for something to go wrong -- to omit a step or use an old version, thus leading to an esoteric error and support request.

v2.0-beta3 improves the built-in diagnostics for common problems, so that they're identified more quickly and easily.

Data migration (v1.0 => v2.0)

The data-storage for templates changed from v1.0 to v2.0. v2.0-beta3 introduces the "Mosaico Migration Assistant". If your system has any templates in the old data-store, the "System Status" will display a link to the migration assistant. Use the assistant to import templates from v1.0.

Settings page

In the CiviCRM menu, you'll find a new item "Administer => CiviMail => Mosaico Settings". This exposes options, such as "Layout" and "Custom Template Directory", which would otherwise remain hidden.

Base templates

A base template defines the HTML blocks that are available for drag/drop in the Mosaico palette. Several designers have asked, "How do I customize the HTML for Mosaico mailings?"

The upstream Mosaico project provides a tutorial on writing templates. The steps are great for the template author... but how do you distribute and install these templates?

v2.0-beta3 allows site administrators to install templates in the "Custom Template Directory", and it allows developers to bundle templates into CiviCRM extensions. See also: API.md.

"Message Template" integration (experimental, unsupported)

v1.0 and v2.0 represent different approaches to embedding Mosaico within CiviCRM:

• In v1.0, Mosaico is embedded into the Message Templates system. This design is flexible but has usability issues.
• In v2.0, Mosaico is embedded directly into CiviMail. This design is less flexible but more user-friendly.

If you want both the user-friendly CiviMail support and the flexibility of Message Templates, you can also install the Mosaico Message Template (mosaicomsgtpl) extension. This reproduces the functionality of v1.0.

mosaicomsgtpl is experimental and unsupported. Why? Well, Message Templates are often copied into CKEditor for additional editing, but this doesn't work well with Mosaico content. Unsophisticated users find the experience difficult -- meaning that it's hard to support or train users. On the other hand, the technique is powerful and flexible, and we don't want to completely remove functionality that was available in v1.0. For sophisticated folks -- or folks who already conquered the learning curve in v1.0 -- the unsupported extension should provide feature-parity.

Testing

Although it's not visible to a user, the test processes are important -- they improve long-term viability for these extensions. Changes this month include:

• Setting up a daily testbot for FlexMailer and Mosaico. This feeds into a matrix that can help assess the CiviCRM release-candidates.
• Setting up a testbot for FlexMailer PRs.
• Improving the manual test procedures for Mosaico.

Developer Documentation

The FlexMailer developer docs have been revamped. See https://docs.civicrm.org/flexmailer/en/latest/

The Mosaico docs have been slightly expanded with the addition of the developer-oriented API.md.

Known issues

• Social media icons - In some deployments, mailings with social media icons do not correctly display the icons. The circumstances of the bug are currently unclear, and we don't have solid steps to reproduce, but it's been reported multiple times. (See also: #160 and #183)
• Images appear as malformed text - In some deployments, the editor UI does not show image blocks correctly. As with social media icons, the circumstances of the bug are currently unclear, and we don't have solid steps to reproduce, but it's been reported multiple times. (See also: #186)
• Token validation fix requires v4.7.30 - There has been a bug in validating unsubscribe tokens. A patch has been merged, but it won't become fully functional until CiviCRM v4.7.30 is released. In the mean time, it is easy to work-around. (See also: #143)
• Testbot fix requires v4.7.30 - The test suite for FlexMailer cannot run fully on v4.7.28. This is not due to an issue in the runtime code -- rather, it's an issue with certain test classes. The issue is resolved in v4.7.30.

Additionally, you can browse the list of open issues, unconfirmed issues, and suggested enhancements in the issue queue.

What next?

Before releasing v2.0-final, I'd like to:

• Get more clarity on the social media icons (#160) and malformed image blocks (#186). Although those problems aren't universal, they do appear to be common enough.
• Provide some time for v2.0-beta3 to propagate and simmer -- and for people to feedback on November's comments/discussions.

Of course, there's a lot more that we would like to do -- such as addressing proposed enhancements and unreproduced issues. Some examples that would be great developments:

• Publish documentation on https://docs.civicrm.org/
• Provide better defaults for pre-header (#218)
• Integrate direct support for A/B testing and conditional blocks
• Embed RSS feeds in mailings
• Make Shoreditch optional
• And more....

These would make the project better.

If you're in a position to investigate the known issues, to develop enhancements, or to fund enhancements, please get in touch on the issue tracker or on https://chat.civicrm.org under "dev-mosaico".