diff --git a/docs/developers/form.md b/docs/developers/form.md index fc8cc3c35..92a6f6bb4 100644 --- a/docs/developers/form.md +++ b/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. diff --git a/docs/template-guides/rendering-forms.md b/docs/template-guides/rendering-forms.md index bb70aa3c6..e358f18ec 100644 --- a/docs/template-guides/rendering-forms.md +++ b/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 `
` 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 + + ... +``` + +## 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) diff --git a/docs/template-guides/rendering-options.md b/docs/template-guides/rendering-options.md index 61a73a895..9023c348a 100644 --- a/docs/template-guides/rendering-options.md +++ b/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 `` element. +`formDataAttributes` | Provide an object of data attributes to be merged on the `` element. +`formAttributes` | Provide an object of attributes to be merged on the `` element. ## Buttons Options diff --git a/src/elements/Form.php b/src/elements/Form.php index b8a3e9a37..07b94e41d 100644 --- a/src/elements/Form.php +++ b/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 // ========================================================================= diff --git a/src/templates/_special/form-template/form.html b/src/templates/_special/form-template/form.html index 4bb1539b3..297fff478 100644 --- a/src/templates/_special/form-template/form.html +++ b/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 ?? {}) %}
{% set submitted = craft.formie.plugin.service.getFlash(form.id, 'submitted') %}