Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move lost grapesjs documentation to docs, small improves #43

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions docs/components/grapesjs.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
GrapesJS Builder
################

Currently, Mautic uses the GrapesJS Builder for Emails and Landing pages.

Setup
*****
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to be a bit more verbose here. Where exactly do they run npm install? Do they have to have Mautic installed first?

We need to assume that people reading this are completely new to using the builder and may not know where to start.


.. code-block:: BASH

npm install

.. vale off

Configure Babel, ESLint, Prettier
=================================

.. vale on

Use the template files provided. For example .eslintrc.temp
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And do what with them? Can we be a bit more helpful here? Even if we point people out to documentation on external sites, it would be helpful to folks who might not know what to do with the template files.


How to test standalone
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean to test standalone? This isn't very clear. Perhaps we could explain why you would do this and what it would allow you to do?

**********************

.. code-block:: BASH

npm run start-helloWorld
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above I think we need to be clear - are we in Mautic's root? In the plugin folder? What is the difference between the two commands and why might you use one rather than the other?

or
npm run start-mautic

In order for ``start-mautic`` to work, a running DDEV container has to be present.

If you are using another development environment you need to update some paths in ``Demo/mautic/index.html``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's be kind and give some examples here? You can use code blocks to include code samples.


How to build for production
***************************

.. code-block:: BASH

npm run build
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above, state where to run this.


Code architecture
*****************

There is PHP and the JavaScript code.

All the JavaScript code lives in the Assets/library folder. This handles the UI of the builder.

In addition to the code in this repository, there is also the :xref:`GrapesJS Preset`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In addition to the code in this repository, there is also the :xref:`GrapesJS Preset`.
In addition to the code in this `plugins/GrapesJsBuilderBundle` folder, there is also the :xref:`GrapesJS Preset`.

We aren't referring to a separate repo at this time.


This repository handles the basic Mautic specific code. The general idea is that this preset repository is a base for various Mautic builder Plugins.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This repository handles the basic Mautic specific code. The general idea is that this preset repository is a base for various Mautic builder Plugins.
This code in the `plugins/GrapesJsBuilderBundle` folder handles the basic Mautic specific code. The general idea is that the GrapesJS Preset repository is a base for various Mautic builder Plugins.


E.g one where the Rich Text Editor is CKEditor, or where there is some very customer or industry specific features.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
E.g one where the Rich Text Editor is CKEditor, or where there is some very customer or industry specific features.
Examples might include if you wanted to have the Rich Text Editor is CKEditor, or where there is some very customer or industry specific features. These can be done with a custom preset.


```
- It's a pack of configurable feautures:
- Adds the function to edit source code
- Extends the original image and add a confirm dialog before removing it
- Add the option to hide/show the Layers Manager
- Add the option to enable/disable the import code button
- Moves the Settings panel inside Style Manager panel
- Opens the Block Manager at launch
- Add Dynamic Content Block for HTML used in Mautic
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that we need to add here some instructions on how to roll your own custom preset. For example how to create a fork of the Mautic preset, and how to ship it with your own Mautic instance. I think that a few people do that already so hopefully we can get that documented.

I would also like to see some basic examples of:

How to create a new block
How to create a new section

These could link out to external documentation or be included here as our own docs.

Issues
******

Report issues in the main Mautic repository, labelled as :xref:`GrapesJS issue queue`

PRs
***

Contributions to improve the GrapesJS Plugin happen in the main Mautic repository as :xref:`GitHub PRs`
7 changes: 7 additions & 0 deletions docs/links/github_mautic_prs.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
from . import link

link_name = "GitHub PRs"
link_text = "GitHub PRs"
link_url = "https://github.com/mautic/mautic/pulls"

link.xref_links.update({link_name: (link_text, link_url)})
7 changes: 7 additions & 0 deletions docs/links/grapesjs_issues.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
from . import link

link_name = "GrapesJS issue queue"
link_text = "GrapesJS builder issues"
link_url = "https://github.com/mautic/mautic/issues?q=is%3Aopen+is%3Aissue+label%3Abuilder-grapesjs"

link.xref_links.update({link_name: (link_text, link_url)})
7 changes: 7 additions & 0 deletions docs/links/grapesjs_preset.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
from . import link

link_name = "GrapesJS Preset"
link_text = "GrapesJS Preset"
link_url = "https://github.com/mautic/grapesjs-preset-mautic"

link.xref_links.update({link_name: (link_text, link_url)})