Add ability to override form settings, classes and attributes in temp…

…lates

docs/developers/form.md

@@ -45,3 +45,30 @@ Method | Description
 `getRedirectUrl()` | Returns the URL for the redirection upon final submission of the form.
 `getRedirectEntry()` | Returns the [Entry](https://docs.craftcms.com/api/v3/craft-elements-entry.html) used for redirection, if applicable.
 `getCaptchas()` | Returns all enabled [Captcha](docs:integration/captchas) objects for this form.
+
+## Form Settings
+Each form has a collection of settings associated with it.
+
+### Attributes
+
+Attribute | Description
+--- | ---
+`displayFormTitle` | Whether to show the form’s title.
+`displayPageTabs` | Whether to show the form’s page tabs.
+`displayCurrentPageTitle` | Whether to show the form’s current page title.
+`displayPageProgress` | Whether to show the form’s page progress.
+`submitMethod` | The form’s submit method. `ajax` or `page-reload`.
+`submitAction` | Set the submission action. `message`, `entry`, `url`, `reload`.
+`submitActionTab` | Whether to the redirect URL should open in a new tab.
+`submitActionUrl` | The URL to redirect to on success.
+`submitActionFormHide` | Whether the form should be hidden on success.
+`submitActionMessage` | The success message as HTML shown on validation success.
+`submitActionMessageTimeout` | Whether the success message should hide after the provided number of milliseconds.
+`errorMessage` | The error message as HTML shown on validation failure.
+`loadingIndicator` | The type of loading indicator to use. `none`, `spinner` or `text`.
+`loadingIndicatorText` | The text for the loading indicator.
+`validationOnSubmit` | Whether to validate the form fields on-submit.
+`validationOnFocus` | Whether to validate the form fields on-focus.
+`submissionTitleFormat` | The submission title format.
+`collectIp` | Whether to collect the IP address of the user.
+`collectUser` | Whether to collect a logged-in user against the form.

docs/template-guides/rendering-forms.md

@@ -25,4 +25,45 @@ If you are using custom templates, you can also pass in a number of options to t
 {{ craft.formie.renderForm('contactForm', options) }}
 ```
 
+## Override Form Attributes and Classes
+You can use the rendering options to override any HTML attributes, data attributes and classes on the `<form>` element.
+
+```twig
+{% set options = {
+    formClasses: [
+        'my-custom-class',
+    ],
+    formDataAttributes: {
+        'new-attribute': 'some-value',
+    },
+    formAttributes: {
+        'title': 'Some Title',
+    },
+} %}
+
+{{ craft.formie.renderForm('contactForm', options) }}
+```
+
+The above would produce:
+
+```twig
+<form class="fui-form fui-labels-above-input my-custom-class" data-new-attribute="some-value" title="Some Title">
+    ...
+```
+
+## Override Form Settings
+You can also dynamically override any settings for the form
+
+```twig
+{% set form = craft.formie.forms.handle('contactForm').one() %}
+
+{% do form.setSettings({
+    submitActionUrl: 'https://google.com',
+}) %}
+
+{{ craft.formie.renderForm(form, options) }}
+```
+
+The above would override the redirect URL for the form, regardless of what is defined in the form's settings. See the [Form Settings](docs:developers/form) docs for a full list of available settings to override.
+
 For more fine-grained control over rendering of a form, see [Rendering Pages](docs:template-guides/rendering-pages) and [Rendering Fields](docs:template-guides/rendering-fields)

docs/template-guides/rendering-options.md

@@ -12,6 +12,9 @@ Option | Description
 `buttons` | Affect the attributes of the submit/next page and previous page buttons. Accepts a [Buttons Options](#buttons-options) object as the value.
 `fieldTag` | Set the tag for the outer-most field container. This is `div` by default.
 `fieldNamespace` | Set the namespace used by all fields. This is `fields` by default.
+`formClasses` | Provide an array of classes to be merged on the `<form>` element.
+`formDataAttributes` | Provide an object of data attributes to be merged on the `<form>` element.
+`formAttributes` | Provide an object of attributes to be merged on the `<form>` element.
 
 
 ## Buttons Options

src/elements/Form.php

@@ -1000,6 +1000,14 @@ public function getFrontEndTemplateLocation($location)
         return $output;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function setSettings($settings)
+    {
+        $this->settings->setAttributes($settings, false);
+    }
+
 
     // Events
     // =========================================================================

src/templates/_special/form-template/form.html

@@ -23,7 +23,7 @@
             "fui-labels-#{defaultLabelPosition}",
             form.settings.displayPageProgress ? "fui-progress-#{form.settings.progressPosition}",
             form.settings.validationOnFocus ? 'fui-validate-on-focus',
-        ],
+        ] | merge(options.formClasses ?? []),
         method: 'post',
         enctype: 'multipart/form-data',
         'accept-charset': 'utf-8',
@@ -35,8 +35,8 @@
             'loading-text': form.settings.loadingIndicatorText ?: false,
             'redirect': form.getRedirectUrl() ?: false,
             'config': form.configJson,
-        },
-    } %}
+        } | merge(options.formDataAttributes ?? {}),
+    } | merge(options.formAttributes ?? {}) %}
 
     <div class="fui-i">
         {% set submitted = craft.formie.plugin.service.getFlash(form.id, 'submitted') %}