diff --git a/docs/_static/tablefix.css b/docs/_static/tablefix.css index 8d367b00..68ce4a0c 100644 --- a/docs/_static/tablefix.css +++ b/docs/_static/tablefix.css @@ -7,8 +7,11 @@ margin-bottom: 24px; max-width: 100%; overflow: visible; + white-space: normal !important; + word-break: break-word !important; } .wy-table-responsive th p { margin-bottom: unset; -} \ No newline at end of file +} + diff --git a/docs/conf.py b/docs/conf.py index 91ecfd7f..f968d500 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -74,6 +74,8 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_css_files = ['tablefix.css'] + # Please add links here that do not pass the "make checklinks" check. # A little context on the reason for ignoring is greatly appreciated! diff --git a/docs/plugins/config.rst b/docs/plugins/config.rst index ff151ee5..63d475fc 100644 --- a/docs/plugins/config.rst +++ b/docs/plugins/config.rst @@ -22,6 +22,7 @@ Mautic recognizes the Plugin through the general config options. .. list-table:: :header-rows: 1 + :widths: 15 15 40 * - Key - Type @@ -99,6 +100,7 @@ The following firewalls are available to routes. .. list-table:: :header-rows: 1 + :widths: 15 20 65 * - Key - URL prefix @@ -127,8 +129,11 @@ Route definitions Route definitions define the route's method, path, controller, parameters, and others defined below. + + .. list-table:: :header-rows: 1 + :widths: 28 20 25 60 * - Key - Is required? @@ -170,6 +175,7 @@ Mautic defaults the following route definitions if not declared otherwise by the .. list-table:: :header-rows: 1 + :widths: 15 20 50 * - Parameter - Default value @@ -290,6 +296,7 @@ There are currently four menus built into Mautic. .. list-table:: :header-rows: 1 + :widths: 25 50 * - Key - Description @@ -321,6 +328,7 @@ Key each item with its respective :ref:`language string key` to register the configuration. +- A :doc:`Form type ` that defines the fields. +- A specific view for rendering the form. + +.. note:: + + To translate the Plugin’s tab label in the configuration form, include a translation key like ``mautic.config.tab.helloworld_config`` in the Plugin’s ``messages.ini`` file. Replace ``helloworld_config`` with the ``formAlias`` used when registering the form in the event subscriber. + + +Config event subscriber +======================= + +This allows Plugins to interact with Mautic's configuration events. It listens to two important events: ``ConfigEvents::CONFIG_ON_GENERATE`` and ``ConfigEvents::CONFIG_PRE_SAVE``. + +The following code example shows how a Plugin structures its event subscriber. + +.. code-block:: php + + ['onConfigGenerate', 0], + ConfigEvents::CONFIG_PRE_SAVE => ['onConfigSave', 0] + ]; + } + + public function onConfigGenerate(ConfigBuilderEvent $event): void + { + $event->addForm( + [ + 'formAlias' => 'helloworld_config', + 'formTheme' => 'HelloWorldBundle:FormTheme\Config', + 'parameters' => $event->getParametersFromConfig('HelloWorldBundle') + ] + ); + } + + public function onConfigSave(ConfigEvent $event): void + { + /** @var array $values */ + $values = $event->getConfig(); + // Manipulate the values + if (!empty($values['helloworld_config']['custom_config_option'])) { + $values['helloworld_config']['custom_config_option'] = htmlspecialchars($values['helloworld_config']['custom_config_option']); + } + // Set updated values + $event->setConfig($values); + } + } + + +Subscribed events +----------------- + +The event subscriber listens to the following events: + +- ``ConfigEvents::CONFIG_ON_GENERATE``: + Mautic dispatches this event when it builds the configuration form. This allows the Plugin to inject its own tab and configuration options. + +- ``ConfigEvents::CONFIG_PRE_SAVE``: + Mautic triggers this event before it renders the form values and saves them to the ``local.php`` file. This allows the Plugin to clean up or modify the data before writing it to ``local.php``. + +Generate plugin configuration +----------------------------- +.. vale on +To register Plugin’s configuration details during the ``ConfigEvents::CONFIG_ON_GENERATE event``, call the ``addForm()`` method on the ``ConfigBuilderEvent`` object. The method expects an array with the following elements: + +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Key + - Description + * - ``formAlias`` + - The alias of the form type class that defines the expected form elements. + * - ``formTheme`` + - The view that formats the configuration form elements, for example, ``HelloWorldBundle:FormTheme\Config``. + * - ``parameters`` + - An array of custom configuration elements. ``Use $event->getParametersFromConfig('HelloWorldBundle')`` to retrieve them from the plugin’s configuration file. +.. vale off + +Modify configuration before saving +---------------------------------- + +To modify the form data before saving, use the ``ConfigEvents::CONFIG_PRE_SAVE event``. This event is triggered just before values are saved to the ``local.php`` file, allowing the Plugin to adjust them. + +Register the event subscriber +----------------------------- + +Register the subscriber through the Plugin’s configuration in the ``services[events]`` in :ref:`plugins/config:Service config items`. This ensures that the plugin listens for the events and reacts accordingly. + + +Config form +=========== + +The form type is used to generate the form fields in the main configuration form. See the :doc:`Forms documentation` for more information about using form types. + +Remember that the form type must be registered through the Plugin’s config in the ``services[forms]`` in :ref:`plugins/config:Service config items` +. + +Below is an example of a form type class that adds a custom configuration option to the Plugin's configuration form. + +.. code-block:: php + + add( + 'custom_config_option', + 'text', + [ + 'label' => 'plugin.helloworld.config.custom_config_option', + 'data' => $options['data']['custom_config_option'], + 'attr' => [ + 'tooltip' => 'plugin.helloworld.config.custom_config_option_tooltip' + ] + ] + ); + } + } + +Config template +=============== + +Registering a form theme as ``HelloWorldBundle:FormTheme\Config`` in the event listener tells the ConfigBundle to look in the HelloWorldBundle’s ``Resources/views/FormTheme/Config`` folder for templates. Specifically, it will look for a template named ``_config_{formAlias}_widget.html.twig``, where ``{formAlias}`` is the same as the ``formAlias`` set in the Plugin’s ``ConfigEvents::CONFIG_ON_GENERATE`` event listener. + +The template should be structured in a panel format to match the rest of the configuration UI. + +Below is an example of how the template should be structured: + +.. code-block:: twig + + {# plugins/HelloWorldBundle/Views/FormTheme/Config/_config_helloworld_config_widget.html.twig #} +
+
+

{{ 'mautic.config.tab.helloworld_config'|trans }}

+
+
+ {% for field in form.children %} +
+
+ {{ form_row(field) }} +
+
+ {% endfor %} +
+
\ No newline at end of file