From 1020afc0c26f400a62275b52c60a9e566f0e4555 Mon Sep 17 00:00:00 2001 From: "Anderson J. Eccel" <116097999+andersonjeccel@users.noreply.github.com> Date: Wed, 18 Jun 2025 15:08:41 -0300 Subject: [PATCH 1/3] First version of this document --- docs/design/navigating_resources.rst | 108 +++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/design/navigating_resources.rst diff --git a/docs/design/navigating_resources.rst b/docs/design/navigating_resources.rst new file mode 100644 index 00000000..1473b082 --- /dev/null +++ b/docs/design/navigating_resources.rst @@ -0,0 +1,108 @@ +Views +===== + +Views in Mautic follow a common naming pattern. + +- list: This is the table view, where the list of objects is displayed. These are high level pages (for example, Contacts, Campaigns, etc) +- details: This is the view for a single object (for example, a Contact profile) +- form: This is the form view, where the form for creating or editing a single object is displayed (for example, the New Contact page) + +These templates might have parts splitted into different files, for example, the list template might have a ``_list.html.twig`` file for the table and a ``_list_actions.html.twig`` file for the actions. +Details templates might have an associated Details folder with files for each tab contents to help with organization and maintainability. + +Platform templates +------------------ + +There are several Twig templates available on the platform code to help developers streamline developemnt. + +These templates are organized in folders depending on their purpose and functionality. + +The main folders are: + +- ``@MauticCore/Helper``: Templates that help with common tasks (rendering buttons for page actions, for example) +- ``@MauticCore/Components``: Templates that implement design patterns coming from the design system, suitable for any kind of content +- ``@MauticCore/Modules``: Templates that can be reused across several bundles for specific types of contents, built on top of Components (for example, to render a stats panel by using tile components) + +Module folders can also be found within specific bundles. These folders contain templates that are specific to the bundle they are in, and are not reusable across other bundles. + +.. note:: + + Always use platform templates for existing components to avoid code duplication and to ensure consistency across the platform. + +Modifying templates +^^^^^^^^^^^^^^^^^^^ + +Using attributes +"""""""""""""""" + +Before considering adding, removing or changing variables from a template, check if your needs could be addressed by allowing custom attributes if the template doesn't support it yet. + +For example: + +.. code-block:: twig + + {% if attributes is defined and attributes is not empty %}{% for attr_key, attr_value in attributes %}{{ attr_key }}="{{ attr_value }}" {% endfor %}{% endif %} + +This snippet allows you to pass custom attributes to the template, which can be used to modify the behavior or appearance of the component. It's a common pattern in Mautic templates and is used in several platform templates, becoming useful for integrating with JS libraries such as Bootstrap. + +When including your template, you could pass the attributes as follows: + +.. code-block:: twig + + {% include '@MauticCore/Components/clickable-component.html.twig' with { + 'content': 'Open Modal', + 'icon': 'fa fa-external-link', + 'attributes': { + 'data-toggle': 'ajaxmodal', + 'data-target': '#HelpModal', + 'data-header': 'Modal Title' + } + } %} + +Changing existing structure from templates +"""""""""""""""""""""""""""""""""""""" + +Templates were created to power functionalities across the entire platform. You might find that a template is being applied more than 60 times in different scenarios across the UI. If you change a variable being used by a template, it will affect all the places where it is being used. + +Your options are: +1. Refactor or update all the places where it is being used to ensure they work with the new structure. +2. Create a new template if you have a really good reason to do so and use it instead of the old one, adding a deprecation notice to the old template. +3. Check if adding a custom attribute to the template would be enough to address your needs. + +.. note:: + + Avoid creating custom HTML when a template is available. If a pull request is adding a button using raw HTML, reviewers must request changes to use a platform template instead. + +Naming and organization of templates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When naming templates, it's important to follow the same naming pattern used by the platform. This makes it easier for other developers to understand the purpose of the template and to find it when needed. + +Names must indicate the part of the UI they're responsible for. + +Before, the naming standard worked this way (example): + +The folder ``@MauticPage/Page/`` had these files: +- list.html.twig +- form.html.twig +- details.html.twig +- _list.html.twig + +_list.html.twig was a partial template included in list.html.twig at the same folder level, used to render a table for the list of pages in the list view. +Names usually started with an underscore to indicate it was a partial template. + +Now, the folder ``@MauticPage/Page/`` would have this structure: +- list.html.twig +- form.html.twig +- details.html.twig +- List/list--table.html.twig + +_list.html.twig was renamed to list--table.html.twig and moved to the List subfolder. The new organization standard involves creating a subfolder to group partial elements from different views. This makes it easier to find and understand the purpose of each template when searching files in IDEs, mainly when a single view has dozens of partial templates. + +Other examples: +- For tabs, you can use names such as ``Details/details--tab-overview.html.twig`` +- For modules, create a folder named ``@MauticBundle/Modules/`` (considering full path app/bundles/[Name]Bundle/Resources/views/Modules/) and use names such as ``module--preview.html.twig`` + +.. note:: + + You'll find that the new organization standard is not yet applied to all templates. This is a work in progress and will be completed in the future. From 8d402da9abce3c69e9089b19480dc903f96915be Mon Sep 17 00:00:00 2001 From: "Anderson J. Eccel" <116097999+andersonjeccel@users.noreply.github.com> Date: Wed, 18 Jun 2025 15:19:50 -0300 Subject: [PATCH 2/3] Improving vale --- docs/design/navigating_resources.rst | 57 ++++++++++++++-------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/design/navigating_resources.rst b/docs/design/navigating_resources.rst index 1473b082..fa75bd83 100644 --- a/docs/design/navigating_resources.rst +++ b/docs/design/navigating_resources.rst @@ -1,7 +1,7 @@ Views ===== -Views in Mautic follow a common naming pattern. +Views in Mautic use a consistent naming pattern to help you organize and locate templates efficiently. - list: This is the table view, where the list of objects is displayed. These are high level pages (for example, Contacts, Campaigns, etc) - details: This is the view for a single object (for example, a Contact profile) @@ -13,39 +13,39 @@ Details templates might have an associated Details folder with files for each ta Platform templates ------------------ -There are several Twig templates available on the platform code to help developers streamline developemnt. +Mautic provides several Twig templates to help you streamline development and maintain consistency. Templates are organized by their purpose and functionality. -These templates are organized in folders depending on their purpose and functionality. +You will find these main folders: -The main folders are: +- ``@MauticCore/Helper`` contains templates for common tasks, such as rendering buttons for page actions. +- ``@MauticCore/Components`` includes templates that implement design patterns from the design system for a wide variety of content. +- ``@MauticCore/Modules`` provides templates that combine Components for specific content types, such as using tile components to display statistics. -- ``@MauticCore/Helper``: Templates that help with common tasks (rendering buttons for page actions, for example) -- ``@MauticCore/Components``: Templates that implement design patterns coming from the design system, suitable for any kind of content -- ``@MauticCore/Modules``: Templates that can be reused across several bundles for specific types of contents, built on top of Components (for example, to render a stats panel by using tile components) - -Module folders can also be found within specific bundles. These folders contain templates that are specific to the bundle they are in, and are not reusable across other bundles. +You will also find module folders inside specific bundles for templates unique to that bundle. These templates are not intended for reuse across other bundles. .. note:: - Always use platform templates for existing components to avoid code duplication and to ensure consistency across the platform. + Use existing platform templates to maintain consistency and reduce code duplication. Modifying templates ^^^^^^^^^^^^^^^^^^^ -Using attributes -"""""""""""""""" +Allowing custom attributes +"""""""""""""""""""""""""" -Before considering adding, removing or changing variables from a template, check if your needs could be addressed by allowing custom attributes if the template doesn't support it yet. +Before you add, remove, or change variables in a template, first check whether you can accomplish your goal by supporting custom attributes. Many Mautic templates already allow you to pass custom attributes, which lets you adapt behavior or appearance without changing the template’s structure. This approach works well when you need to integrate with JavaScript libraries such as Bootstrap. -For example: +You can allow custom attributes by adding this snippet to your template: .. code-block:: twig - {% if attributes is defined and attributes is not empty %}{% for attr_key, attr_value in attributes %}{{ attr_key }}="{{ attr_value }}" {% endfor %}{% endif %} - -This snippet allows you to pass custom attributes to the template, which can be used to modify the behavior or appearance of the component. It's a common pattern in Mautic templates and is used in several platform templates, becoming useful for integrating with JS libraries such as Bootstrap. + {% if attributes is defined and attributes is not empty %} + {% for attr_key, attr_value in attributes %} + {{ attr_key }}="{{ attr_value }}" + {% endfor %} + {% endif %} -When including your template, you could pass the attributes as follows: +When you include your template, pass the attributes as follows: .. code-block:: twig @@ -58,20 +58,21 @@ When including your template, you could pass the attributes as follows: 'data-header': 'Modal Title' } } %} - -Changing existing structure from templates -"""""""""""""""""""""""""""""""""""""" -Templates were created to power functionalities across the entire platform. You might find that a template is being applied more than 60 times in different scenarios across the UI. If you change a variable being used by a template, it will affect all the places where it is being used. +Changing template structure +""""""""""""""""""""""""""" + +Templates power features throughout the platform. When you change a variable or structure in a template, you affect every place that uses it. Consider the impact before making changes. + +You have several options: -Your options are: -1. Refactor or update all the places where it is being used to ensure they work with the new structure. -2. Create a new template if you have a really good reason to do so and use it instead of the old one, adding a deprecation notice to the old template. -3. Check if adding a custom attribute to the template would be enough to address your needs. +1. Update all usages to work with the new structure. +2. Create a new template with your changes, and add a deprecation notice to the old template. Use the new template instead of the original. +3. Add support for custom attributes if that satisfies your needs. .. note:: - Avoid creating custom HTML when a template is available. If a pull request is adding a button using raw HTML, reviewers must request changes to use a platform template instead. + Use a platform template instead of custom HTML whenever possible. If a pull request adds a button with raw HTML, reviewers require you to switch to a platform template. Naming and organization of templates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -105,4 +106,4 @@ Other examples: .. note:: - You'll find that the new organization standard is not yet applied to all templates. This is a work in progress and will be completed in the future. + Mautic is actively updating templates to follow this organization standard. Some templates still use the older structure, and the transition will continue over time. From d1d5522e048441f918a1fb6c6ed44e1a25f39dfc Mon Sep 17 00:00:00 2001 From: "Anderson J. Eccel" <116097999+andersonjeccel@users.noreply.github.com> Date: Wed, 18 Jun 2025 15:24:08 -0300 Subject: [PATCH 3/3] v2 Vale --- docs/design/navigating_resources.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/design/navigating_resources.rst b/docs/design/navigating_resources.rst index fa75bd83..bf09c4dc 100644 --- a/docs/design/navigating_resources.rst +++ b/docs/design/navigating_resources.rst @@ -3,11 +3,11 @@ Views Views in Mautic use a consistent naming pattern to help you organize and locate templates efficiently. -- list: This is the table view, where the list of objects is displayed. These are high level pages (for example, Contacts, Campaigns, etc) -- details: This is the view for a single object (for example, a Contact profile) -- form: This is the form view, where the form for creating or editing a single object is displayed (for example, the New Contact page) +- list: View and manage all objects in a table format, such as contacts or campaigns. This page provides an overview and allows you to take actions on multiple items. +- details: Access detailed information about a single object, such as a contact profile. You see all available data and related actions for the specific item. +- form: Enter or update information for a single object, such as creating or editing a contact. You fill in required fields and submit your changes. -These templates might have parts splitted into different files, for example, the list template might have a ``_list.html.twig`` file for the table and a ``_list_actions.html.twig`` file for the actions. +These templates might have parts splitted into different files, for example, the list template might have a ``_list.html.twig`` file for the table and a ``_list_actions.html.twig`` file for actions. Details templates might have an associated Details folder with files for each tab contents to help with organization and maintainability. Platform templates @@ -81,28 +81,30 @@ When naming templates, it's important to follow the same naming pattern used by Names must indicate the part of the UI they're responsible for. -Before, the naming standard worked this way (example): +Template naming and organization best practices +""""""""""""""""""""""""""""""""""""""""""""""" -The folder ``@MauticPage/Page/`` had these files: +Use consistent and descriptive naming for your templates to make them easy to locate and understand. Organize related partial templates into subfolders to improve clarity, especially when a single view includes multiple partials. + +Previous template organizations often placed partial templates in the same folder as their parent view, using a leading underscore to identify partials. For example, the ``@MauticPage/Page/`` folder included: - list.html.twig - form.html.twig - details.html.twig - _list.html.twig -_list.html.twig was a partial template included in list.html.twig at the same folder level, used to render a table for the list of pages in the list view. -Names usually started with an underscore to indicate it was a partial template. +The file ``_list.html.twig`` served as a partial for rendering tables within the list view. -Now, the folder ``@MauticPage/Page/`` would have this structure: +With the current standard, group all partials for a specific view inside a subfolder named after the parent template. Rename partials to follow a clear pattern, and remove the leading underscore. For instance, in ``@MauticPage/Page/``, organize files as follows: - list.html.twig - form.html.twig - details.html.twig - List/list--table.html.twig -_list.html.twig was renamed to list--table.html.twig and moved to the List subfolder. The new organization standard involves creating a subfolder to group partial elements from different views. This makes it easier to find and understand the purpose of each template when searching files in IDEs, mainly when a single view has dozens of partial templates. +Move the partial ``_list.html.twig`` to ``List/list--table.html.twig``. This approach organizes partials for the list view under the ``List`` subfolder, making it easier to locate and understand their context. + +Apply similar patterns to other UI elements. For example, organize tab partials as ``Details/details--tab-overview.html.twig`` within a ``Details`` subfolder. For module templates, create a ``Modules`` folder under the appropriate bundle, such as ``app/bundles/[Name]Bundle/Resources/views/Modules/``, and use descriptive names like ``module--preview.html.twig``. -Other examples: -- For tabs, you can use names such as ``Details/details--tab-overview.html.twig`` -- For modules, create a folder named ``@MauticBundle/Modules/`` (considering full path app/bundles/[Name]Bundle/Resources/views/Modules/) and use names such as ``module--preview.html.twig`` +Consistent and descriptive naming conventions help you and your team quickly find and identify templates, improving maintainability and collaboration. .. note::