diff --git a/docs/components/config.rst b/docs/components/config.rst index 82915872..464f10ea 100644 --- a/docs/components/config.rst +++ b/docs/components/config.rst @@ -1,6 +1,177 @@ Configuration ############# +For basic information about configuring your Plugin, see :ref:`Config file`. This document goes into more detail by explaining how to add User-configurable options to Mautic. Configuration parameters -************************ \ No newline at end of file +************************ + +You can find Mautic's configuration in ``app/config/local.php``. Plugins can leverage custom config parameters to use within its code. + +You can define every configuration option you need. Make sure it has a default set in the :ref:`Plugin's config file`. +This prevents Symfony from throwing errors if the parameter gets used during cache compilation or if accessed directly from the container without checking if it exists first. +Defining the parameters in the Plugin's config file ensures that it always exists. + +To add config options to the Configuration section, you need to add an :ref:`Event Listener`, a config :ref:`form type`, and a specific view (TODO). + +.. note:: To translate the Plugin's tab in the configuration Form, be sure to include ``mautic.config.tab.helloworld_config`` in the Plugin's messages.ini file. Replace helloworld_config with whatever you use as the ``formAlias`` when registering the Form in the event subscriber. You can find more on this below. + +.. vale off + +Config Event Subscriber +======================= + +.. vale on + +The event subscriber should listen to the ``ConfigEvents::CONFIG_ON_GENERATE`` and ``ConfigEvents::CONFIG_PRE_SAVE`` events. + +The ``ConfigEvents::CONFIG_ON_GENERATE`` is dispatched when the configuration form is built giving the plugin an opportunity to inject it's own tab and config options. + +To do this, the Plugin must register it's configuration details through the method assigned to the ``ConfigEvents::CONFIG_ON_GENERATE`` event. +The ``\Mautic\ConfigBundle\Event\ConfigBuilderEvent`` object gets passed into the method and expects the method to call ``addForm()``. ``addForm()`` expects an array with the following elements: + +.. list-table:: + :header-rows: 1 + + * - Key + - Description + * - ``formAlias`` + - Alias of the Form type class that sets the expected Form elements + * - ``formTheme`` + - View to format the configuration Form elements, i.e, ``HelloWorldBundle:FormTheme\Config`` + * - ``parameters`` + - Array of custom config elements. ``$event->getParametersFromConfig('HelloWorldBundle')))`` can be used to glean them from the plugin's config file. + + +The ``ConfigEvents::CONFIG_PRE_SAVE`` is called before the values from the form are rendered and saved to the ``local.php`` file. +This gives the Plugin an opportunity to clean up or manipulate the data before it's written. + +Remember that you must register the subscriber through the Plugin's config in the ``services[events]`` :ref:`section`. + +.. code-block:: php + + ['onConfigGenerate', 0], + ConfigEvents::CONFIG_PRE_SAVE => ['onConfigSave', 0] + ]; + } + + public function onConfigGenerate(ConfigBuilderEvent $event) + { + $event->addForm( + [ + 'formAlias' => 'helloworld_config', + 'formTheme' => 'HelloWorldBundle:FormTheme\Config', + 'parameters' => $event->getParametersFromConfig('HelloWorldBundle') + ] + ); + } + + public function onConfigSave(ConfigEvent $event) + { + $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); + } + } + +.. vale off + +Config Form +=========== + +.. vale on + +.. 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' + ] + ] + ); + } + + public function getName() + { + return 'helloworld_config'; + } + } + +The Form type gets used to generate the Form Fields in the main configuration Form. Refer to :ref:`Forms` for more information on using Form types. + +Remember that you must register the Form type through the Plugin's config in the ``services[forms]`` :ref:`section`. + +.. vale off + +Config Template +=============== + +.. vale on + +.. code-block:: php + + + +
+
+

trans('mautic.config.tab.helloworld_config'); ?>

+
+
+ children as $f): ?> +
+
+ row($f); ?> +
+
+ +
+
+ +Registering a ``formTheme`` as ``HelloWorldBundle:FormTheme\Config`` in the event listener told the ConfigBundle to look in the HelloWorldBundle's Views/FormTheme/Config folder for templates. +Specifically, it will look for a template named ``_config_{formAlias}_widget.html.php`` where ``{formAlias}`` is the same as ``formAlias`` set in the plugin's ``ConfigEvents::CONFIG_ON_GENERATE`` event listener. + +The template should be in a panel format to match the rest of the config UI.