Move lost grapesjs documentation to docs, small improves #43

adiux · 2022-06-08T08:59:36Z

Gitpod link: https://gitpod.io/#https://github.com/mautic/developer-documentation-new/pull/43

RCheesley · 2022-06-08T09:12:14Z

Hey @adiux thanks for doing this! You have some Vale spelling / grammar / style errors that will need to be corrected (see the linter) - and there are some RST issues I can notice (headings are too long etc). If you are using VS Code you should get the highlights automatically to tell you where there are problems if you've got Vale installed.

Alternatively you could work in Gitpod: https://gitpod.io/#https://github.com/mautic/developer-documentation-new/pull/43 which has everything configured and will flag up issues with the PR in the Problems tab (ignore the ones relating to other pages, we will fix those in a separate PR!)

Happy to walk through it if you get stuck with anything!

RCheesley

Thanks for making the PR to bring across some of the details @adiux - much appreciated!

I have left some comments on the PR, I think we need to be a lot more detailed on the information we are provided so that we can support developers in learning how to extend and work with the builder and the preset - let me know if anything is unclear!

RCheesley · 2022-06-24T10:37:23Z

docs/components/grapesjs.rst

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


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.

RCheesley · 2022-06-24T10:38:31Z

docs/components/grapesjs.rst

+
+.. vale on
+
+Use the template files provided. For example .eslintrc.temp


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.

RCheesley · 2022-06-24T10:39:23Z

docs/components/grapesjs.rst

+
+Use the template files provided. For example .eslintrc.temp
+
+How to test standalone


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?

RCheesley · 2022-06-24T10:40:21Z

docs/components/grapesjs.rst

+
+.. code-block:: BASH
+
+    npm run start-helloWorld


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?

RCheesley · 2022-06-24T10:40:48Z

docs/components/grapesjs.rst

+
+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``.


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

RCheesley · 2022-06-24T10:41:40Z

docs/components/grapesjs.rst

+
+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`. 


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.

RCheesley · 2022-06-24T10:43:20Z

docs/components/grapesjs.rst

+
+In addition to the code in this repository, there is also the :xref:`GrapesJS Preset`. 
+
+This repository handles the basic Mautic specific code. The general idea is that this preset repository is a base for various Mautic builder Plugins. 


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.

RCheesley · 2022-06-24T10:44:04Z

docs/components/grapesjs.rst

+
+This repository handles the basic Mautic specific code. The general idea is that this 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.


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.

RCheesley · 2022-06-24T10:46:27Z

docs/components/grapesjs.rst

+- Opens the Block Manager at launch
+- Add Dynamic Content Block for HTML used in Mautic
+```
+


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.

RCheesley · 2022-06-24T10:46:48Z

docs/components/grapesjs.rst

+PRs
+***
+
+Contributions to improve the GrapesJS Plugin happen in the main Mautic repository as :xref:`Github PRs`


I think we should also include a section on how to contribute and test PRs for the preset? That used to be in the readme I think.

RCheesley · 2022-10-06T15:23:14Z

@adiux @volha-pivavarchyk please could you take a look at the feedback/suggestions? It would be great to improve this documentation for our developers and get the PR merged but we are missing some key pieces of information I feel.

RCheesley · 2024-01-16T21:11:34Z

Hey folks @adiux @volha-pivavarchyk could we please get this info into the docs? It will need rebasing to 5.x and the feedback addressing. What do you think?

RCheesley requested changes Jun 24, 2022

View reviewed changes

adiux and others added 4 commits November 28, 2022 13:31

move lost grapesjs documentation to docs, small improves

26be57b

Fix vale errors and warnings

8de94d8

Fix incorrect link ref

6703c1c

Fix case-sensitive link

f9a3dc2

dennisameling force-pushed the init-grapesjs branch from e426ed5 to f9a3dc2 Compare November 28, 2022 17:31

Merge branch 'main' into init-grapesjs

7005f92

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move lost grapesjs documentation to docs, small improves #43

Move lost grapesjs documentation to docs, small improves #43

adiux commented Jun 8, 2022 •

edited by gitpod-io bot

RCheesley commented Jun 8, 2022

RCheesley left a comment

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley Jun 24, 2022

RCheesley commented Oct 6, 2022

RCheesley commented Jan 16, 2024


		.. vale on

		Use the template files provided. For example .eslintrc.temp


		Use the template files provided. For example .eslintrc.temp

		How to test standalone


		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``.


		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`.

	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`.


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

		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 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.


		This repository handles the basic Mautic specific code. The general idea is that this 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.

	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.

Move lost grapesjs documentation to docs, small improves #43

Are you sure you want to change the base?

Move lost grapesjs documentation to docs, small improves #43

Conversation

adiux commented Jun 8, 2022 • edited by gitpod-io bot

RCheesley commented Jun 8, 2022

RCheesley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RCheesley commented Oct 6, 2022

RCheesley commented Jan 16, 2024

adiux commented Jun 8, 2022 •

edited by gitpod-io bot