diff --git a/.github/styles/config/vocabularies/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt index 78822e35..9b4d8fd8 100644 --- a/.github/styles/config/vocabularies/Mautic/accept.txt +++ b/.github/styles/config/vocabularies/Mautic/accept.txt @@ -48,6 +48,8 @@ Firewalls firewalls Focus Item Focus Items +Form +form Forms forms Froala diff --git a/docs/links/mautic_recommended_project.py b/docs/links/mautic_recommended_project.py new file mode 100644 index 00000000..f3b3b07b --- /dev/null +++ b/docs/links/mautic_recommended_project.py @@ -0,0 +1,7 @@ +from . import link + +link_name = "Recommended Project" +link_text = "Recommended Project" +link_url = "https://github.com/mautic/recommended-project" + +link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/themes/getting_started.rst b/docs/themes/getting_started.rst index 3155fb82..57159c40 100644 --- a/docs/themes/getting_started.rst +++ b/docs/themes/getting_started.rst @@ -3,14 +3,20 @@ Getting started with Themes You can use Themes to create default content and layouts for Emails and Landing Pages written in the :xref:`Twig documentation`. -You can use Themes to also customize Forms, for example when visiting /form/ID, or using an iframe to embed a Form into a third party page. You can also customize the Form structure and fields but need to use PHP files, which disqualifies the Theme from being installable through Mautic's Theme manager. It must therefore be manually uploaded to the server. +.. vale off + +You can use Themes to also customize Mautic Forms, for example when visiting ``/form/ID``, or using an iframe to embed a Form into a third party page. You can customize the Form structure and fields but need to use PHP files, which disqualifies the Theme from being installable through Mautic's Theme manager. It must therefore be manually uploaded to the server. + +.. vale on Finally, use a special ``system`` Theme to override system templates to avoid losing core code changes with future upgrades. Directory structure ******************* -A Theme consists of three components: the configuration, Twig files with content, and thumbnails:: +A Theme consists of three components: the configuration, Twig files with content, and thumbnails. + +.. code-block:: json config.json html/ @@ -42,19 +48,26 @@ The configuration file tells Mautic how to utilize the Theme. "builder": ["legacy", "grapesjsbuilder"] } -name +**name** This is the name of the Theme as displayed in Mautic. -author + +**author** This displays in the Theme manager as credit to the author of the Theme. Any Themes added to Mautic Core use 'Mautic Team' as the author. -authorUrl + +**authorUrl** This enables the author to provide a URL displayed in the Theme manager. -features + +**features** An array of strings that tells Mautic which features the Theme supports. Currently recognized values are: ``email`` The Theme is compatible with the Email Builder. See :ref:`themes/getting_started:html/email.html.twig`. +.. vale off + ``form`` The Theme is compatible with the customizing Forms. See :ref:`themes/getting_started:html/form.html.twig`. +.. vale on + ``page`` The Theme is compatible with the Page Builder. See :ref:`themes/getting_started:html/page.html.twig`. A corresponding ``html/[feature].html.twig`` file is required for each feature supported. For example, if the Theme supports ``email``, then there should be a ``html/email.html.twig`` file. See :ref:`themes/getting_started:Twig files` more information on each feature. @@ -64,8 +77,8 @@ builder Twig files ========== -html/message.html.twig ----------------------- +``html/message.html.twig`` +-------------------------- This file is mainly used as the Landing Page for when a Contact unsubscribes or resubscribes to the system's Emails. Other areas use this so all Themes should include it. @@ -73,8 +86,12 @@ It requires echoing two variables: ``message`` and ``content``. ``message`` contains the string message such as "You have been unsubscribed." +.. vale off + ``content`` is empty or contains the HTML of a Form associated with the Email as an unsubscribe Form. +.. vale on + .. code-block:: twig @@ -89,8 +106,8 @@ It requires echoing two variables: ``message`` and ``content``. -html/email.html.twig --------------------- +``html/email.html.twig`` +------------------------ This file defines the base template when creating a new Email and should contain HTML suited for email clients. @@ -133,8 +150,8 @@ The GrapesJS Builder supports the :xref:`MJML email framework`. -html/page.html.twig -------------------- +``html/page.html.twig`` +----------------------- This file defines the base template when creating a new Landing Page and can contain advanced HTML for browsers. @@ -157,8 +174,9 @@ This file defines the base template when creating a new Landing Page and can con -html/form.html.twig -------------------- +``html/form.html.twig`` +----------------------- +.. vale off Mautic uses this file when accessing the form at /form/ID, embedding a Form in a Landing Page, or using the iframe method of embedding a Form into a third party page. @@ -166,6 +184,8 @@ This should output the variables ``message``, ``header``, and ``content``. See :ref:`themes/forms:Customizing forms` on how to customize Form fields. +.. vale on + .. code-block:: twig @@ -189,6 +209,51 @@ See :ref:`themes/forms:Customizing forms` on how to customize Form fields. Thumbnails ========== +.. vale off + The thumbnail should be a screenshot of the Theme with demo content. The dimensions should be 575x600px. Mautic displays thumbnails in the Email edit Form, Landing Page edit Form, and the Theme Manager. +.. vale on + Mautic looks for ``thumbnail.png`` by default, however if you want a specific image for different feature, you can add a ``thumbnail_[feature].png`` with a custom thumbnail. For example, ``thumbnail_email.png``, ``thumbnail_page.png`` or ``thumbnail_form.png``. + +Preparing your Theme for Packagist +********************************** + +Mautic uses Packagist to distribute Themes and Plugins. There are certain steps you must take to ensure readiness of your Theme for distribution. + +1. Ensure there is a ``composer.json`` file in the root of your Theme directory. Ensure it contains the following information, inn particular verifying the minimum supported version of Mautic: + +.. code-block:: json + + { + "name": "mautic/theme-yourthemename", + "description": "A theme for Mautic", + "type": "mautic-theme", + "keywords": ["mautic", "theme"], + "extra": { + "install-directory-name": "yourthemename" + }, + "minimum-stability": "dev", + "require": { + "mautic/core": "^5.0" + } + } + +1. Ensure that you add a ``close_pull_requests.yml`` file in the ``.github/workflows`` directory of your Theme repository. This file automatically close pull requests opened in the Theme repository. Please review other Themes for examples. + +2. Ensure that you add your Theme to, or create, the following files: + + - ``.github/subtree-splitter-config.json`` - this file sets up the connection between the folder in the Mautic GitHub repository and the theme's individual repository. When merging changes into Core which impact this theme or making releases, GitHub pushes into the theme's repository automatically. Add your Theme at the end of the list. + - ``.github/workflows/gitsplit/theme-yourthemename.json`` - GitHub Actions uses this file to sync changes to the theme's repository. Create one for each new theme added to the Mautic repository. + - ``.githu/workflows/split-monorepo-in-multi-repo.yml`` - this file is used by the GitHub Action to create the matrix used when splitting up the repository and pushing changes out to the theme repositories. Update this file with the new theme names. + +3. Make the Pull Request with your Theme and the relevant files from previous steps to the Mautic repository. Once merged, the GitHub Action automatically pushes the changes out to your Theme repository. + +4. Ask the core team to create a new repository in the Mautic GitHub organization for your Theme. They must add the core team to the repository for GitHub Actions to work. The repository naming convention is ``theme-yourthemename``. + +5. Once merged, ask the Core Team to create a Packagist package for your Theme. Once created, make another PR, adding the package to the ``composer.json`` file. Ensure that you also run ``composer require mautic/theme-yourthemename`` which updates the ``composer.lock`` file, adding your new theme. Then, review the ``composer.json`` file and move the package from the 'require' section to the 'replace' section, using ``self.version``. Commit both the ``composer.json`` and ``composer.lock`` files. + +6. Once merged, make your final PR to the :xref:`Recommended Project` repository where you add your Theme to the end of the list in ``composer.json``. + +7. Celebrate, you made it - congratulations 🥳. \ No newline at end of file