diff --git a/website/forms/features/result-output.md b/website/forms/features/result-output.md new file mode 100644 index 000000000..f3c736220 --- /dev/null +++ b/website/forms/features/result-output.md @@ -0,0 +1,54 @@ +--- +id: result-output +title: Result output +--- + +_Result output_ allows displaying user-defined blocks after the form is submitted successfully. + +![Result output](/img/forms/result-output-1.webp) + +## Configuration + +Follow these steps: +1. Add a _Result output item_ and keep its name in mind. Result outputs are found in the WordPress admin sidebar. +2. Create a form +3. Add the form to the desired page +4. Add the _Result output_ block to the same page +5. In the _Result output_ block options select the form and the Result output block you created in step 1 +6. (Optional) Disable the global messages in the form settings + +Once the form is submitted the select block will be displayed. + +![Result output settings](/img/forms/result-output-2.webp) + +## _Result output item_ block + +Alongside the _Result output_ block you will find the _Result output item_ block. It allows changing parts of the result output or showing things like custom messages, based on user input. + +![Result output item block](/img/forms/result-output-3.webp) + +:::caution +The block will not show anything by default. Some configuration by developers is required. For more details, check the chapter on [custom filters](/forms/php/filters/block/form/result-output-items). +::: + +To configure the block, add it inside a _Result output_ block, and provide a name and a value that will match the data provided by the filter. Once the form is submitted and the condition matches, the selected block will be shown. + +:::tip +Works great with the [Computed Fields Add-on](/forms/addons/premium/computed-fields/intro). +::: + +## _Result output part_ shortcode + +Similar to the _Result output item_ block, the shortcode version allows smaller, inline varations, e.g. simple pieces of text. + +![Result output part shortcode](/img/forms/result-output-4.webp) + +:::caution +The shortcode will not show anything by default. Some configuration by developers is required. For more details, check the chapter on [custom filters](/forms/php/filters/block/form/result-output-items). +::: + +To configure the shortocde, add it somewhere inside the _Result output_ block. Provide a `name` and set the `default text`. The _default text_ will be shown after form submission if the _name_ matches the one in the configuration. + +:::tip +Works great with the [Computed Fields Add-on](/forms/addons/premium/computed-fields/intro). +::: diff --git a/website/forms/features/single-submit.md b/website/forms/features/single-submit.md new file mode 100644 index 000000000..9a3a79fb1 --- /dev/null +++ b/website/forms/features/single-submit.md @@ -0,0 +1,25 @@ +--- +id: single-submit +title: Single submit +--- + +Single submit is a feature that allows dynamic processing of a form when user makes any change on the form. This is useful for forms that require users to perform calculations, such as a mortgage calculator or a loan calculator. + +![Single submit](/img/forms/single-submit.webp) + +You can turn on single submit in the settings of the form. + +Single submit form can work with and without a submit button, but in general it is recommended not to use a submit button with single submit forms. + +Not all form field are supported by single submit. The following fields are supported: +* Input range +* Checkbox +* Radio +* Rating +* Select + +If you add any of the non-supported fields to a single submit form, the form will not submit when the user makes a change to the non-supported field. + +:::caution +This feature may create a large number of request to your server. Use with caution! +::: diff --git a/website/forms/integrations/active-campaign.md b/website/forms/integrations/active-campaign.md index 7b6bdadad..7c7179503 100644 --- a/website/forms/integrations/active-campaign.md +++ b/website/forms/integrations/active-campaign.md @@ -22,14 +22,14 @@ ActiveCampaign is an integrated email marketing, automation, sales software, and * Form builder provided by the service. ### Supported fields: -* Full name -* First name -* Last name -* Hidden -* Textarea -* Email -* Phone -* Checkbox -* Radio -* Dropdown +* firstname +* lastname +* fullname +* hidden +* textarea +* email +* phone +* checkbox +* radio +* dropdown diff --git a/website/forms/integrations/airtable.md b/website/forms/integrations/airtable.md index c986edec2..cf20a568a 100644 --- a/website/forms/integrations/airtable.md +++ b/website/forms/integrations/airtable.md @@ -22,18 +22,19 @@ Airtable is an platform that makes it easy to build powerful, custom application * Form builder provided by the service. ### Supported fields: -* Input -* Email -* Url -* Number -* Date -* Phone number -* Textarea -* Single Select -* Multiple Choices -* Checkbox -* Currency -* MultipleRecordLinks +* singleLineText +* email +* url +* phoneNumber +* dateTime +* date +* number +* currency +* multilineText +* singleSelect +* multipleSelects +* checkbox +* multipleRecordLinks :::caution The Airtable MultipleRecordLinks field relies on the Airtable API to create records in a linked table. diff --git a/website/forms/integrations/calculator.md b/website/forms/integrations/calculator.md new file mode 100644 index 000000000..00956d161 --- /dev/null +++ b/website/forms/integrations/calculator.md @@ -0,0 +1,8 @@ +--- +id: calculator +title: Calculator +--- + +_Calculator_ is a service that allows turning a form into a calculator with custom programmable logic. For example, you can build a mortgage calculator. + +Please not that this is **not** an integration! diff --git a/website/forms/integrations/goodbits.md b/website/forms/integrations/goodbits.md index f0e02b45a..7de43dfd6 100644 --- a/website/forms/integrations/goodbits.md +++ b/website/forms/integrations/goodbits.md @@ -22,6 +22,6 @@ Goodbits is an service that helps you and your business create stellar newslette * Form builder provided by the service. ### Supported fields: -* Email -* First name -* Last name +* email +* first_name +* last_name diff --git a/website/forms/integrations/greenhouse.md b/website/forms/integrations/greenhouse.md index 43993b74e..26c8e8b72 100644 --- a/website/forms/integrations/greenhouse.md +++ b/website/forms/integrations/greenhouse.md @@ -22,10 +22,15 @@ Greenhouse is an sourcing automation tool to help hiring teams find, reach and e * Form builder provided by the service. ### Supported fields: -* Phone -* Text -* Email -* File -* Textarea -* Select -* Checkbox +* input_text + * phone + * email + * text +* input_file +* textarea +* multi_value_single_select + * checkboxes + * select +* mapped_url_token +* longitude +* latitude diff --git a/website/forms/integrations/hubspot.md b/website/forms/integrations/hubspot.md index 6a93f257f..b13582ba0 100644 --- a/website/forms/integrations/hubspot.md +++ b/website/forms/integrations/hubspot.md @@ -27,6 +27,14 @@ Hubspot is an CRM platform that connects everything scaling companies need to de * Form builder provided by the service. -### Not supported fields: -* Heading -* Paragraph +### Supported fields: +* text +* date +* number +* phonenumber +* file +* select +* booleancheckbox +* checkbox +* radio +* consent diff --git a/website/forms/integrations/mailchimp.md b/website/forms/integrations/mailchimp.md index 7d955c640..e1dd37fa0 100644 --- a/website/forms/integrations/mailchimp.md +++ b/website/forms/integrations/mailchimp.md @@ -22,13 +22,15 @@ Mailchimp is an comprehensive email marketing platform that fulfills all your re * Form builder provided by the service. ### Supported fields: -* Text -* Url -* Address - partially -* Zip -* Number -* Birthday -* Date -* Phone -* Radio -* Dropdown +* email_address +* text +* url +* address (partially) +* number +* zip +* phone +* birthday +* date +* birthday +* dropdown +* tags diff --git a/website/forms/integrations/mailerlite.md b/website/forms/integrations/mailerlite.md index bf885460f..dbd6d3f2c 100644 --- a/website/forms/integrations/mailerlite.md +++ b/website/forms/integrations/mailerlite.md @@ -22,8 +22,9 @@ MailerLite is an email service provider that makes it easier to plan email marke * Form builder provided by the service. ### Supported fields: -* Text -* Date -* Number -* Phone -* Date +* text + * phone + * zip + * text +* date +* number diff --git a/website/forms/integrations/moments.md b/website/forms/integrations/moments.md index 9cf14f4ab..5f5121620 100644 --- a/website/forms/integrations/moments.md +++ b/website/forms/integrations/moments.md @@ -21,4 +21,16 @@ Moments is an service that allows you to easily send relevant content derived fr * Form builder provided by the service. ### Supported fields: -* All +* text + * country +* msisdn +* date +* datetime +* email +* number +* textarea +* dropdown + * country +* radiobutton +* checkbox +* checkbox_group diff --git a/website/forms/integrations/pipedrive.md b/website/forms/integrations/pipedrive.md index 19c485367..37c48225f 100644 --- a/website/forms/integrations/pipedrive.md +++ b/website/forms/integrations/pipedrive.md @@ -22,5 +22,3 @@ Pipedrive is a web-based Sales CRM and pipeline management solution that enables * Form builder **not** provided by the service. * The form is created using our forms fields and connected to Pipedrive fields using form settings. -### Supported fields: -* All diff --git a/website/forms/integrations/workable.md b/website/forms/integrations/workable.md index c2fe9bb31..e96137968 100644 --- a/website/forms/integrations/workable.md +++ b/website/forms/integrations/workable.md @@ -21,5 +21,14 @@ Workable is an sourcing automation tool to help hiring teams find, reach and eng * Form builder provided by the service. ### Supported fields: -* All - +* firstname +* lastname +* email +* short_text +* string + * phone +* file +* dropdown +* multiple_choice +* free_text +* boolean diff --git a/website/forms/php/filters/block/form/result-output-items.md b/website/forms/php/filters/block/form/result-output-items.md new file mode 100644 index 000000000..4ed8b284b --- /dev/null +++ b/website/forms/php/filters/block/form/result-output-items.md @@ -0,0 +1,30 @@ +--- +id: result-output-items +title: Result output items +--- + +Allows modifying _Form result output parts_ using an API to change which block is shown on the frontend, based on the user input. + +Used by the `result-output-item` block. + +```php +add_filter('es_forms_integrations_form_result_output_items', 'getIntegrationResultOutputItems', 10, 3); + +/** + * Populate Result output items in the API response data used in 'result-output-item' block. + * + * @param array $output Output data. + * @param array $formDetails Data passed from the 'getFormDetailsApi' function. + * @param string $formId Form ID. + * + * @return array + */ +function getIntegrationResultOutputItems(array $output, array $formDetails, string $formId): array +{ + $output['testKeys'] = 'testValue'; + + return $output; +} +``` + + diff --git a/website/forms/php/filters/block/form/result-output-parts.md b/website/forms/php/filters/block/form/result-output-parts.md new file mode 100644 index 000000000..78d1a4376 --- /dev/null +++ b/website/forms/php/filters/block/form/result-output-parts.md @@ -0,0 +1,30 @@ +--- +id: result-output-parts +title: Result output parts +--- + +Allows modifying _Form result output parts_ using an API to change which shortcode is output on the frontend, based on the user input. + +Used by the `esFormsROIP` shortcode. + +```php +add_filter('es_forms_integrations_form_result_output_parts', 'getIntegrationResultOutputParts', 10, 3); + +/** + * Populate result output parts in the API response data used in the 'esFormsROIP' shortcode. + * + * @param array $output Output data. + * @param array $formDetails Data passed from the 'getFormDetailsApi' function. + * @param string $formId Form ID. + * + * @return array + */ +function getIntegrationResultOutputParts(array $output, array $formDetails, string $formId): array +{ + $output['testKeys'] = 'testValue'; + + return $output; +} +``` + + diff --git a/website/forms/php/filters/integrations/calculator.mdx b/website/forms/php/filters/integrations/calculator.mdx new file mode 100644 index 000000000..25816dd00 --- /dev/null +++ b/website/forms/php/filters/integrations/calculator.mdx @@ -0,0 +1,8 @@ +--- +id: calculator +title: Calculator +--- + +import { IntegrationFilters } from './../../../../src/docs/filters'; + + diff --git a/website/forms/php/shortcodes.md b/website/forms/php/shortcodes.md new file mode 100644 index 000000000..98b14fe9a --- /dev/null +++ b/website/forms/php/shortcodes.md @@ -0,0 +1,24 @@ +--- +id: shortcodes +title: Shortcodes +--- + +## What are shortcodes? + +Shortcodes are small pieces of code that allow adding forms to the site in places blocks can't be easily added. + +## esFormsLink + +This shortcode allows adding links within text labels, e.g. if you need to add a privacy policy link to a form checkbox label. + +```php +[esFormsLink url="https://eightshift.com" label="Eightshift" /] +``` + +## esFormsROIP + +The `esFormsROIP` (_Result output item part_) shortcode allows showing certain content inline, based on the user input. The content is shown if the provided `name` matches the fields defined within filters. + +```php +[esFormsROIP name=""]Default content[/esFormsROIP] +``` diff --git a/website/sidebars-forms.js b/website/sidebars-forms.js index e111cd1ba..158204534 100644 --- a/website/sidebars-forms.js +++ b/website/sidebars-forms.js @@ -31,6 +31,8 @@ module.exports = { 'features/wpml', 'features/entries', 'features/show-as', + 'features/result-output', + 'features/single-submit', ], ], }, @@ -41,6 +43,7 @@ module.exports = { 'integrations/intro', 'integrations/active-campaign', 'integrations/airtable', + 'integrations/calculator', 'integrations/clearbit', 'integrations/goodbits', 'integrations/greenhouse', @@ -90,7 +93,6 @@ module.exports = { ] }, 'php/helpers', - 'php/wp-cli', { 'type': 'category', 'label': 'Filters', @@ -125,6 +127,8 @@ module.exports = { 'php/filters/block/form/pre-response-addon-data', 'php/filters/block/form/pre-response-success-redirect-data', 'php/filters/block/form/additional-hidden-fields', + 'php/filters/block/form/result-output-items', + 'php/filters/block/form/result-output-parts', ], }, { @@ -278,6 +282,7 @@ module.exports = { 'items': [ 'php/filters/integrations/active-campaign', 'php/filters/integrations/airtable', + 'php/filters/integrations/calculator', 'php/filters/integrations/clearbit', 'php/filters/integrations/goodbits', 'php/filters/integrations/greenhouse', @@ -329,6 +334,8 @@ module.exports = { 'php/actions/migrations', ], }, + 'php/shortcodes', + 'php/wp-cli', ], }, { diff --git a/website/src/docs/filters.jsx b/website/src/docs/filters.jsx index 8857beff9..f0e2817f9 100644 --- a/website/src/docs/filters.jsx +++ b/website/src/docs/filters.jsx @@ -173,6 +173,9 @@ function PrePostParamsFilter ({ filter }) { case 'mailer': text = 'mailer system'; break; + case 'calculator': + text = 'calculator'; + break; default: text = 'external integration'; break; diff --git a/website/static/img/forms/result-output-1.webp b/website/static/img/forms/result-output-1.webp new file mode 100644 index 000000000..e8b49a0a7 Binary files /dev/null and b/website/static/img/forms/result-output-1.webp differ diff --git a/website/static/img/forms/result-output-2.webp b/website/static/img/forms/result-output-2.webp new file mode 100644 index 000000000..8b076e246 Binary files /dev/null and b/website/static/img/forms/result-output-2.webp differ diff --git a/website/static/img/forms/result-output-3.webp b/website/static/img/forms/result-output-3.webp new file mode 100644 index 000000000..011e46fa5 Binary files /dev/null and b/website/static/img/forms/result-output-3.webp differ diff --git a/website/static/img/forms/result-output-4.webp b/website/static/img/forms/result-output-4.webp new file mode 100644 index 000000000..118fd173e Binary files /dev/null and b/website/static/img/forms/result-output-4.webp differ diff --git a/website/static/img/forms/single-submit.webp b/website/static/img/forms/single-submit.webp new file mode 100644 index 000000000..2f3499098 Binary files /dev/null and b/website/static/img/forms/single-submit.webp differ