Cavemanon/piratepoet
7
Fork 0
Code Pull Requests Actions Releases 16 Activity

Update Readme documentation

Browse Source 
MAILPOET-6256
This commit is contained in:
Oluwaseun Olorunsola
2024-11-26 16:08:33 +01:00
committed by Rostislav Wolný
parent 98bc96b1b8
commit 8c2ede4ff9
3 changed files with 139 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
mailpoet/lib/EmailEditor/README.md Normal file
View File

@ -0,0 +1,10 @@
# MailPoet plugin Email Editor Integration
This folder contains the code for the MailPoet plugin Email Editor integration.
**MailPoet** specific code and features should be placed here.
Documentation for the core email editor packages can be located here:
- Email editor PHP package: [docs](../../../packages/php/email-editor/README.md)
- Email editor JS package: [docs](../../../packages/js/email-editor/README.md)

85
packages/js/email-editor/README.md Normal file
View File

@ -0,0 +1,85 @@
# MailPoet Email Editor
This folder contains the code for the MailPoet Email Editor JS Package.
We aim to extract the package as an independent library, so it can be used in other projects.
As we are still in an exploration phase, we keep it together with the MailPoet codebase.
You can locate the PHP package here `packages/php/email-editor`
## Workflow Commands
We use `pnpm` run scripts to run the commands. You can run them using `pnpm run <command>`.
Please start with `pnpm install`.
```bash
pnpm run build # runs the build command
pnpm run start # starts the webpack development server
pnpm run lint:css # runs stylelint on all .scss files
pnpm run lint:css-fix # fixes errors reported by `pnpm run lint:css`
pnpm run lint:js # runs eslint on all js and ts files (including the .jsx and .tsx versions)
pnpm run lint:js-fix # fixes errors reported by `pnpm run lint:js`
pnpm run check-types # runs type check on all typescript files
pnpm run format # runs prettier on files. This uses WordPress coding standards.
```
## Development
### Main parts
**Email Editor** – JS application. Custom editor built with WordPress (`@wordpress`) JS packages. Most important ones are `@wordpress/block-editor`, `@wordpress/editor`, `@wordpress/data` and `@wordpress/components`. There is also some PHP code to bootstrap the editor.
**Storage** – we store email content as custom post-type + we use templates (a couple of dummy hardcoded templates) to carry shared parts of the content (header, footer) and style settings. Currently, we store complete style settings per template.
**Renderer** – responsible for converting saved HTML from Gutenberg editor to HTML for email clients.
**Theme Controller** – The theme controller is used to generate settings and styles for the editor. We can define which features for working with content are available in settings. The styles are also used in the Render.
### Email Editor
* Bootstrapped in the plugin in the [email editor controller](https://github.com/mailpoet/mailpoet/blob/13bf305aeb29bbadd0695ee02a3735e62cc4f21f/mailpoet/lib/EmailEditor/Integrations/MailPoet/EmailEditor.php)
* **Components folder** - basically the whole UI of the editor. Most of Gutenberg’s blocks magic happens in block-editor folder.
* **Hooks folder** – several custom hooks mostly to help us pass around data and process data from the store or combine them from multiple stores.
* **Store folder** – classic `wordpress/data` store. We try to use stores from packages we build on as much as possible, but sometimes we need to add an action etc.
* **Layouts folder** – contains one layout. Gutenberg support flex, grid but these can’t be used because email clients don’t support them. Flex-email is restricted layout that supports some features from flex. It is used for buttons.
* **Blocks folder** – when we add support for block, we usually need to do some adjustments and hide some styling options. This is done via Blocks API and save in this folder.
* **Lock-unlock** – key to open the Pandora box with private components from WP packages
* **.sccs files** – we don’t write much CSS. We load styles for the post editor (this is done in page controller) but sometimes we need some adjustments of have a custom ui
* **Custom blocks** - MailPoet custom blocks should be built in [mailpoet-custom-email-editor-blocks folder](https://github.com/mailpoet/mailpoet/tree/13bf305aeb29bbadd0695ee02a3735e62cc4f21f/mailpoet/assets/js/src/mailpoet-custom-email-editor-blocks)
### Theme
Basically theme.json and ThemeController. We don’t use theme.json from the site’s theme. Not every site is using a block theme.
Our current approach is that for email, we have our own theme and we want to handpick settings from the site’s theme to achieve a similar design as the site. Currently, we pick only the color palette.
### Templates
There is no official API for plugins to add templates (there will be in WP6.7). For now, we use low level hooks to add email templates, so they can be available for consumption in the email editor (via Rest API) and for the renderer.
This is done in Templates.php.
### Patterns
Similar to templates but for patterns. Currently, we have one email pattern with initial email content.
## Email clients
### WEB CLIENTS
| Client | Platform | Versions to Support | Rendering Engine | Percentage (Litmus) | Litmus Check | Note |
|-------------------------|----------|------------------------------------------------|------------------|---------------------|--------------|---------------------------------------------------------------------------------|
| Gmail.com | Browser | Latest: Chrome, Firefox, Edge, Safari + mobile | WebKit/Gecko | -/- | Yes | Combined with apps it is around 30%. Mobile Web is not covered by Litmus tests. |
| Yahoo! Mail | Browser | Latest: Chrome, Firefox, Edge, Safari | WebKit/Gecko | 3.37/2.89 | Yes | |
| Outlook.com + Office365 | Browser | Latest: Chrome, Firefox, Edge, Safari | WebKit/Gecko | -/0.67 | Yes | |
| Web.de | Browser | Latest: Chrome, Firefox, Edge, Safari | WebKit/Gecko | -/- | Yes | Combined usage 0.07% App + web |
| Orange.fr | Browser | Latest: Chrome, Firefox, Edge, Safari | WebKit/Gecko | -/- | No | Combined usage 0.07% App + web |
| Windows Live Mail | Browser | Latest: Chrome, Firefox, Edge, Safari | WebKit/Gecko | -/0.06 | No | |
### APPLICATION CLIENTS
| Client | Platform | Versions to Support | Rendering Engine | Percentage (Litmus) | Litmus Check | Note |
|----------------|-----------------------|----------------------|------------------|---------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Gmail App | iOS | Latest | Proprietary | -/- | Yes | |
| Gmail App | Android | Android 7.0 - Latest | Proprietary | -/- | Partially (up to 8.1) | Android 6 market share is 1.7%. Android 7 starts 4.4% |
| Apple Mail | iOS | Latest | WebKit | -/- | Yes | No exact data about usage but combined iOS and desktop has almost 60% on Litmus |
| Apple Mail | macOS | Latest | WebKit | -/- | Yes | |
| Outlook | Windows | 2021, 2019, 2016 | Word | 2.2/4.21 | Yes | 2006 still has 0.04% opens but 2013 officially lost support in April 2023. Not sure what user agents are used in 2021 and 2019. Maybe they report as 2016. They both still use Word as rendering engine. |
| Outlook | macOS | Latest | WebKit | -/- | Yes (2016) | |
| Google Android | Android | Android 7.0 - Latest | ? | -/1.48 | Yes (only 6) | Android 6 market share is 1.7%. Android 7 starts 4.4% |
| Samsung Mail | Android | Android 7.0 - Latest | ? | 0.014/0.17 | Yes (Android 7) | Android 6 market share is 1.7%. Android 7 starts 4.4% |
| Web.de | iOS/Android | Latest | ? | -/0.07 | No | Combined usage 0.07% App + web |
| Orange.fr | iOS/Android | Latest | ? | -/0.07 | No | |
| Thunderbird | Windows, macOS, Linux | Latest | Gecko | -/0.61 | Yes | It uses bundled rendering engine so it should be enough to test on one platform |
| Windows Mail | Windows | 10, 11 | Word | -/- | Yes | Default Client in Windows. Market share should be over 6% in desktop clients |

54
packages/php/email-editor/README.md
View File

@ -1,15 +1,10 @@
# MailPoet Email Editor
This folder contains the code for the MailPoet Email Editor.
This folder contains the code for the MailPoet Email Editor PHP Package.
We aim to extract the engine as an independent library, so it can be used in other projects.
As we are still in an exploration phase we keep it together with the MailPoet codebase.
As we are still in an exploration phase, we keep it together with the MailPoet codebase.
## Development
Both **PHP** **and** JS codes are divided into `engine` and `integrations` subdirectories.
Anything **MailPoet** specific is in the `integrations/MailPoet` folder.
For the core stuff that goes to the engine folder, avoid using other MailPoet-specific services and modules. The code in the Engine folder should work only with WP code or other stuff from the engine.
You can locate the JS package here `packages/js/email-editor`
## Workflow Commands
We use `composer` run scripts to run the commands. You can run them using `composer run <command>`.
@ -28,16 +23,43 @@ Example:
composer run integration-test -- tests/integration/Engine/Theme_Controller_Test.php
```
## Development
Both **PHP** **and** JS codes are divided into `engine` and `integrations` subdirectories.
Engine consist of code for the editor core and integrations are for extending the functionality.
Anything **MailPoet** specific should be in the `mailpoet/lib/EmailEditor/Integrations` folder.
Please avoid using MailPoet-specific services and modules in the Email editor package.
### Renderer
#### Content Renderer
* Responsible for rendering saved template + email content to HTML or email clients
* Flow is Preprocessors > BlocksRenderer > Postprocessors
#### Root Renderer.php
* Takes the rendered content html and places it into email HTML template template-canvas.php (We have too many items we call “template” I know 🙁)
### Integrations
Please locate integrations [here](https://github.com/mailpoet/mailpoet/tree/13bf305aeb29bbadd0695ee02a3735e62cc4f21f/mailpoet/lib/EmailEditor/Integrations/MailPoet)
## Known rendering issues
- In some (not all) Outlook versions the width of columns is not respected. The columns will be rendered with the full width.
- The editor may not start if the URL starts with `wp-admin/post-new.php?post_type=mailpoet_email`.
- Most of the email editor logic heavily depends on the `mailpoet_email` post-type. This is a known issue and we are working to fix it.
- We use `mailpoet_data` in some section of the codebase. This will be updated.
- Native email editor implementation for `preview_url`
- Fix the use of MailPoet vendor packages in the Email editor. We currently use `Emogrifier` and `Html2Text`.
- Fix the Send button (button to send email) or redirect it elsewhere. It is currently pointing to the `mailpoet-newsletter` page.
- We currently support post editing context (a post has to be created before we can use the editor). We need to add support for creation context.
## Actions and Filters
These actions and filters are currently Work-in-progress.
These actions and filters are currently **Work-in-progress**.
We may add, update and delete any of them.
Please use with caution.
**Please use with caution**.
### Actions
@ -57,3 +79,15 @@ Please use with caution.
| `mailpoet_email_content_renderer_styles` | `string` $contentStyles, `WP_Post` $post | `string` $contentStyles | Applied to the inline content styles prior to use by the CSS Inliner. |
| `mailpoet_is_email_editor_page` | `boolean` $isEditorPage | `boolean` | Check current page is the email editor page |
| `mailpoet_email_editor_send_preview_email` | `Array` $postData | `boolean` Result of processing. Was email sent successfully? | Allows override of the send preview mail function. Folks may choose to use custom implementation |
## FAQ
1. How can I activate the new email editor?
* You need to active it as an experimental feature on the URL {your-website}/wp-admin/admin.php?page=mailpoet-experimental
* After that, you can see a dropdown button when you want to create a new email.
2. Are emails from the old editor compatible?
* No. Unfortunately, email editors are not compatible at this moment, and there is no tool which would allow you to migrate old emails yet.
3. Which WP versions are supported?
* The new email editor supports only the latest WP version. The last supported version was 6.6.
4. Can I use the latest Gutenberg version?
* You can use the latest version by installing the Gutenberg plugin, but there is a high chance that the editor will not work properly.