The kirby-blocks-mjml plugin for Kirby (> 3.9.0) helps you to create responsive emails by the use of custom MJML blocks.
This plugin consits basically of three components:
- a responsive email blueprint,
- two default templates for mjml and html content representation
- a MJML class to generate respomsive html from a mjml document
Install the plugin and its requirements and use it for your needs.
As the plugin is still work in progress it is discouraged to use it in production. Comments, feedback or issues are very welcome.
- TODO: implement the attributes for
snippets/blocks/mj-*.phpwhere not already implemented - add further components, see mjml documentation
- TODO: improve documentation in
README.md, e.g. explain the problem: why is mjml a solution? - TODO: publish plugin on packagist
- TODO: tell people about it
Currently only tested in local environment.
In your README, describe the plugin in every little detail and how to use it:
This plugin requires Kirby >3.9.0 and node installed in your environment.
You have three options to install this plugin.
composer require soerenengels/kirby-blocks-mjmlDownload and copy this repository to /site/plugins/kirby-blocks-mjml.
git submodule add https://github.com/soerenengels/kirby-blocks-mjml.git site/plugins/kirby-blocks-mjmlHow can users use the plugin? Ideally, add step by step instructions, not just a few examples. This is particularly important if using the plugin requires some background knowledge or user code.
Additional instructions on how to configure the plugin (e.g. blueprint setup, config options, etc.)
- install plugin
- install requirement in plugin repository:
npm i - use mjml-Template
As there seems to be any maintained possibility to convert MJML to HMTL in PHP, this plugin requires the installation of the mjml node module.
Document the options and APIs that this plugin offers
You can choose between a couple of handy MJML-Blocks to create a responsive email.
Are there any config settings? If so, what is each config setting good for?
'templates' => [
'mjml' => __DIR__ . '/templates/mjml.php', // default template for email on page
'mjml.mjml' => __DIR__ . '/templates/mjml.mjml.php' // mjml content representation
],This plugin provides two templates: templates/mjml.php and templates/mjml.mjml.php. While the first template creates the default template, if you plan to display the E-Mail on the page (e.g. a newsletter issue), the second template creates a mjml document (content representation) for further processing.
The mjml content representation utilizes the layouts/mjml.php snippet:
$data = [
'language' => $kirby->language() ?? 'en', // TODO: default as option
'direction' => $kirby->language()?->direction() ?? 'ltr', // TODO: default as option
'title' => $page->title(),
'preview' => $page->preview(),
'font' => [
'name' => null,
'href' => null
],
]If you do not want your website to expose the mjml content representation publicly, you have to secure the route.
E.g. in site/config/config.php:
return [
// ...
'routes' => [
[
'pattern' => '(:any).mjml',
'action' => function () {
// TODO: Add example
}
]
]
// ...
]A MJML block consists of a blueprint, two block content representations and preview component.
blueprints/
blocks/
mjml/
mj-custom-block-name.yml
snippets/
blocks/
mj-custom-block-name.php
mj-custom-block-name.mjml.php
src/
components/
Blocks/
MJMLCustomBlockName.vue
The files get registered in the src/index.js and index.php.
The BlockModel MJMLBlock extends the custom MJML blocks, which are based on the Kirby\Cms\Block class. Therefor you can use the ->toMJML() method on MJML blocks to create a MJML content representation. This method is internally used to create a valid MJML document from the mjml-Template.
Example: ...
The MJML class is a simplified version of qferr's qferr/mjml-php class, which unfortunately didn't work out for me. It takes a $mjml_input as parameter and offers the ->toHTMLEmail() method to generate a responsive html email from a valid mjml document.
Example:
$mjml = new MJML('a valid mjml document');
$html_email = $mjml->toHTMLEmail();As alternative you could also use the MJML API.
I have some open questions development wise and would be glad about feedback and help:
- What are ways to improve performance?
- Can I use template language with this plugin?
- Are there ideas to better connect the MJML blocks to Core Kirby blocks? maybe...? or this
- How can I make the code more error prove?
- Where are validations necessary?
- How to make the preview section
src/Sections/MJMLPreview.vueinstantly reflect changes? maybe...? - Are there ideas to programmatically generate attributes from MJML documentation in case of changes?
You can extend this plugin by creating a custom MJML component and adding a MJMLBlock to Kirby.
MIT
- Thanks to the incredible Kirby Documentation and Guides
- MJML
- MJML Class is inspired by qferr's qferr/mjml-php
- Sören Engels
<mj-section>https://documentation.mjml.io/#mj-section --> get settings in snippet<mj-spacer>https://documentation.mjml.io/#mj-spacer<mj-social>https://documentation.mjml.io/#mj-social<mj-social-element>https://documentation.mjml.io/#mj-social-element<mj-raw>https://documentation.mjml.io/#mj-raw<mj-hero>https://documentation.mjml.io/#mj-hero<mj-image>https://documentation.mjml.io/#mj-image<mj-navbar>https://documentation.mjml.io/#mj-navbar<mj-include>https://documentation.mjml.io/#mj-include<mj-table>https://documentation.mjml.io/#mj-include<mj-accordion>https://documentation.mjml.io/#mj-accordion<mj-button>https://documentation.mjml.io/#mj-button
Issue: ... Idea: May be possible by utilizing the kirby-column-settings or kirby-column-blocks Plugin?
<mj-wrapper>https://documentation.mjml.io/#mj-wrapper<mj-column>https://documentation.mjml.io/#mj-column-
<mj-group>https://documentation.mjml.io/#mj-group
<mj-html-attribute>https://documentation.mjml.io/#mj-attributes<mj-carousel>https://documentation.mjml.io/#mj-carousel