From e58d789aa45b9650478f18b3ab9160d5c36b52bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Ru=C5=BEevi=C4=87?= Date: Fri, 26 Jan 2024 08:09:18 +0100 Subject: [PATCH] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Goran Alković <77000136+goranalkovic-infinum@users.noreply.github.com> --- .../javascript/events/available-events.mdx | 2 +- website/forms/javascript/state/how-to-use.md | 2 +- .../forms/php/filters/admin/settings-data.md | 2 +- .../block/form/additional-hidden-fields.md | 2 +- .../block/form/pre-response-addon-data.md | 2 +- .../pre-response-success-redirect-data.md | 2 +- .../php/filters/blocks/allowed-blocks.md | 3 ++- .../php/filters/entries/pre-post-params.md | 2 +- website/forms/php/filters/general/locale.md | 2 +- .../php/filters/integrations/clearbit.md | 4 +-- .../php/filters/integrations/hubspot.mdx | 4 +-- .../php/filters/scripts/dependency-admin.md | 4 +-- .../scripts/dependency-blocks-editor.md | 4 +-- .../scripts/dependency-blocks-frontend.md | 4 +-- .../php/filters/scripts/dependency-theme.md | 4 +-- .../php/filters/scripts/routes-private.md | 4 +-- .../php/filters/scripts/routes-public.md | 4 +-- .../validation/force-mimetype-from-fs.md | 10 +++---- website/src/docs/filters.jsx | 26 +++++++++---------- 19 files changed, 42 insertions(+), 45 deletions(-) diff --git a/website/forms/javascript/events/available-events.mdx b/website/forms/javascript/events/available-events.mdx index 3b232c451..2c957151d 100644 --- a/website/forms/javascript/events/available-events.mdx +++ b/website/forms/javascript/events/available-events.mdx @@ -126,7 +126,7 @@ This event is set on the form element. ### esFormsEnrichmentPrefill -Triggered after enrichment profill data from localStorage. +Triggered after enrichment data is pre-filled from `localStorage`. :::tip This event is set on the form element. diff --git a/website/forms/javascript/state/how-to-use.md b/website/forms/javascript/state/how-to-use.md index 6e548cb25..c88c516d6 100644 --- a/website/forms/javascript/state/how-to-use.md +++ b/website/forms/javascript/state/how-to-use.md @@ -16,7 +16,7 @@ window.esForms or you can use built-in events which also contain all the state in the time of the event. :::caution -It's important to be careful when using a state outside of the `esFormsJsFormLoaded` event, as it may not be ready at the time of use. To ensure that the state is available, calling your JavaScript after the `domReady` event and with the `esFormsJsFormLoaded` event you will be safe. +Take caution when using state data outside of the `esFormsJsFormLoaded` event, as it may not be available at the time of use. To be sure the data is available, run code after the DOM is ready (`DOMContentLoaded` event), together with the `esFormsJsFormLoaded` event. If your script is loaded before the main form script, you can use PHP hooks to make forms script dependent on you script to ensure that your script is loaded before the main form script and the events will fire. ::: diff --git a/website/forms/php/filters/admin/settings-data.md b/website/forms/php/filters/admin/settings-data.md index d1b92bafa..8ade13ce7 100644 --- a/website/forms/php/filters/admin/settings-data.md +++ b/website/forms/php/filters/admin/settings-data.md @@ -3,7 +3,7 @@ id: settings-data title: Settings data --- -This filter allows you to add you own custom settings page in the WordPress admin area. Generally, it can be used when creating a custom addon plugin. +This filter allows adding a custom settings page in the WordPress admin area. Useful when creating custom option pages for Forms add-on plugins. ```php add_filter('es_forms_admin_settings_data', 'getSettingsConfig'); diff --git a/website/forms/php/filters/block/form/additional-hidden-fields.md b/website/forms/php/filters/block/form/additional-hidden-fields.md index 13482d99b..470a6681a 100644 --- a/website/forms/php/filters/block/form/additional-hidden-fields.md +++ b/website/forms/php/filters/block/form/additional-hidden-fields.md @@ -3,7 +3,7 @@ id: additional-hidden-fields title: Additional hidden fields --- -This filter allows you to add additional hidden fields to the form block. However this fields will not be visible in the Block Editor. +Allows adding custom hidden fields to the form block. These fields will **not** be visible in the Block Editor. Useful if external data needs to be passed through the form. ```php \add_filter('es_forms_block_form_additional_hidden_fields', [$this, 'getBlockFormAdditionalHiddenFields'], 10, 2); diff --git a/website/forms/php/filters/block/form/pre-response-addon-data.md b/website/forms/php/filters/block/form/pre-response-addon-data.md index 68b7af718..776c1d5a7 100644 --- a/website/forms/php/filters/block/form/pre-response-addon-data.md +++ b/website/forms/php/filters/block/form/pre-response-addon-data.md @@ -3,7 +3,7 @@ id: pre-response-addon-data title: Pre-Response Addon Data --- -This filter allows you to add additional data to the API response when form is submitted. +Allows adding custom data to the API response when the form is submitted. ```php \add_filter('es_forms_block_form_pre_response_addon_data', [$this, 'getPreResponseAddonData'], 10, 2); diff --git a/website/forms/php/filters/block/form/pre-response-success-redirect-data.md b/website/forms/php/filters/block/form/pre-response-success-redirect-data.md index 82a732222..9b16f6da3 100644 --- a/website/forms/php/filters/block/form/pre-response-success-redirect-data.md +++ b/website/forms/php/filters/block/form/pre-response-success-redirect-data.md @@ -3,7 +3,7 @@ id: pre-response-success-redirect-data title: Pre-Response Success Redirect Data --- -This filter allows you to add additional data to the API response key that is used to pass data to the success redirect URL. +Allows adding data to the API response key, which is used when passing data to the success redirect URL. ```php \add_filter('es_forms_block_form_pre_response_success_redirect_data', [$this, 'getPreResponseSuccessRedirectData'], 10, 2); diff --git a/website/forms/php/filters/blocks/allowed-blocks.md b/website/forms/php/filters/blocks/allowed-blocks.md index 2930f6377..f6ed215b0 100644 --- a/website/forms/php/filters/blocks/allowed-blocks.md +++ b/website/forms/php/filters/blocks/allowed-blocks.md @@ -3,7 +3,8 @@ id: allowed-blocks title: Allowed blocks --- -This filter allows you to set the allowed blocks for the form builder as it will override the projects settings. This way you can be sure that the custom addon block is always available for the form builder. +Allows setting a custom list of the allowed blocks within the form editor. It will override the project settings. +Useful if you want to ensure that a custom block (e.g. from an add-on) is visible in the form editor. ```php \add_filter('es_forms_blocks_allowed_blocks', 'getAllowedBlocks'); diff --git a/website/forms/php/filters/entries/pre-post-params.md b/website/forms/php/filters/entries/pre-post-params.md index 3752363c8..609b4e72e 100644 --- a/website/forms/php/filters/entries/pre-post-params.md +++ b/website/forms/php/filters/entries/pre-post-params.md @@ -3,7 +3,7 @@ id: pre-post-params title: Pre-Post Params --- -Change form fields data before it is stored to the WordPress database. This way you can manipulate data and provide additional mapping to the data sent to the WordPress database. +Allows modifying field data before storing it into the database. Useful if, for example, a field value needs to determine a custom output of a different field. ```php add_filter('es_forms_entries_pre_post_params', 'getIntegrationPrePostParams', 10, 3); diff --git a/website/forms/php/filters/general/locale.md b/website/forms/php/filters/general/locale.md index e2b7476b8..b50e7d545 100644 --- a/website/forms/php/filters/general/locale.md +++ b/website/forms/php/filters/general/locale.md @@ -3,7 +3,7 @@ id: locale title: Locale --- -This filter can be used to change the value of current locale. By default, WordPress sets the locale in the admin to `en_US`. With this filter it can be changed to any locale (e.g. when using a multilingual plugin). +Allows changing the current locale. By default, WordPress will use the locale that is set as the Site Language in settings. A plugin like WPML can also set this value. Filter should return an array with two keys: `default` and `current`. Both keys should contain a string value of the locale for your project. diff --git a/website/forms/php/filters/integrations/clearbit.md b/website/forms/php/filters/integrations/clearbit.md index 17e5e1e4f..0556aefa4 100644 --- a/website/forms/php/filters/integrations/clearbit.md +++ b/website/forms/php/filters/integrations/clearbit.md @@ -5,7 +5,7 @@ title: Clearbit ## Map -This filter provides you the ability to change how we map Clearbit fields so you can combine multiple fields in one and add some new ones. +Allows changing how Clearbit fields are mapped. Useful if you want to combine multiple fields, or add new ones. ```php add_filter('es_forms_integrations_clearbit_map', 'getClearbitMap'); @@ -13,7 +13,7 @@ add_filter('es_forms_integrations_clearbit_map', 'getClearbitMap'); /** * Change Clearbit integration fields map. * - * This filter provides you the ability to change how we map Clearbit fields so you can combine multiple fields in one add some new one. + * Allows changing how Clearbit fields are mapped. Useful if you want to combine multiple fields, or add new ones. * * @param array $params Default params provided by the forms. * diff --git a/website/forms/php/filters/integrations/hubspot.mdx b/website/forms/php/filters/integrations/hubspot.mdx index d779ee17f..53663cb1a 100644 --- a/website/forms/php/filters/integrations/hubspot.mdx +++ b/website/forms/php/filters/integrations/hubspot.mdx @@ -6,7 +6,7 @@ title: HubSpot import { IntegrationFilters } from './../../../../src/docs/filters'; ## Files options filter -This filter is used to change default file upload options set by forms and Hubspot. We use this [api](https://legacydocs.hubspot.com/docs/methods/files/v3/upload_new_file), and you can change any of these options. +Allows changing default file upload options set by Forms and Hubspot. For available options check the [HubSpot API reference](https://legacydocs.hubspot.com/docs/methods/files/v3/upload_new_file). ```php add_filter('es_forms_integrations_hubspot_files_options', 'getFileUploadCustomOptions'); @@ -14,7 +14,7 @@ add_filter('es_forms_integrations_hubspot_files_options', 'getFileUploadCustomOp /** * Change Hubspot file upload options. * - * This filter is used to change default file upload options set by forms and Hubspot. We use this [api](https://legacydocs.hubspot.com/docs/methods/files/v3/upload_new_file), and you can change any of these options. + * Allows changing default file upload options set by Forms and Hubspot. For available options check the [HubSpot API reference](https://legacydocs.hubspot.com/docs/methods/files/v3/upload_new_file). * * @return array */ diff --git a/website/forms/php/filters/scripts/dependency-admin.md b/website/forms/php/filters/scripts/dependency-admin.md index 2dd4850c0..4212b8727 100644 --- a/website/forms/php/filters/scripts/dependency-admin.md +++ b/website/forms/php/filters/scripts/dependency-admin.md @@ -3,13 +3,13 @@ id: dependency-admin title: Dependency admin --- -This filter will allow you to change the order of scripts that are loaded in the admin area. Generally used when writing a addon plugin and you want to load you scripts before the main plugin scripts in order to listen to the forms custom event listeners. +Allows changing the order in which the admin area scripts are loaded. Useful when creating a Forms add-on plugin, and your script needs to be loaded before the Forms scripts (e.g. for adding custom event listeners). ```php \add_filter('es_forms_scripts_dependency_admin', 'getScriptsDependency'); /** - * Make addon scripts fired before main plugin scripts. + * Fire add-on scripts before the Forms scripts. * * @return array */ diff --git a/website/forms/php/filters/scripts/dependency-blocks-editor.md b/website/forms/php/filters/scripts/dependency-blocks-editor.md index a9d53f7f0..bcdc4e219 100644 --- a/website/forms/php/filters/scripts/dependency-blocks-editor.md +++ b/website/forms/php/filters/scripts/dependency-blocks-editor.md @@ -3,13 +3,13 @@ id: dependency-blocks-editor title: Dependency blocks editor --- -This filter will allow you to change the order of scripts that are loaded in the blocks editor area. Generally used when writing a addon plugin and you want to load you scripts before the main plugin scripts in order to listen to the forms custom event listeners. +Allows changing the order in which the Block Editor scripts are loaded. Useful when creating a Forms add-on plugin, and your script needs to be loaded before the Forms scripts (e.g. for adding custom event listeners). ```php \add_filter('es_forms_scripts_dependency_blocks_editor', 'getScriptsDependency'); /** - * Make addon scripts fired before main plugin scripts. + * Load add-on scripts before Forms scripts. * * @return array */ diff --git a/website/forms/php/filters/scripts/dependency-blocks-frontend.md b/website/forms/php/filters/scripts/dependency-blocks-frontend.md index 185f468b2..6d6bdb33b 100644 --- a/website/forms/php/filters/scripts/dependency-blocks-frontend.md +++ b/website/forms/php/filters/scripts/dependency-blocks-frontend.md @@ -3,13 +3,13 @@ id: dependency-blocks-frontend title: Dependency blocks frontend --- -This filter will allow you to change the order of scripts that are loaded in the blocks frontend area. Generally used when writing a addon plugin and you want to load you scripts before the main plugin scripts in order to listen to the forms custom event listeners. +Allows changing the order in which the block frontend scripts are loaded. Useful when creating a Forms add-on plugin, and your script needs to be loaded before the Forms scripts (e.g. for adding custom event listeners). ```php \add_filter('es_forms_scripts_dependency_blocks_frontend', 'getScriptsDependency'); /** - * Make addon scripts fired before main plugin scripts. + * Load add-on scripts before the Forms scripts. * * @return array */ diff --git a/website/forms/php/filters/scripts/dependency-theme.md b/website/forms/php/filters/scripts/dependency-theme.md index 3458c3812..9d2d0b676 100644 --- a/website/forms/php/filters/scripts/dependency-theme.md +++ b/website/forms/php/filters/scripts/dependency-theme.md @@ -3,13 +3,13 @@ id: dependency-theme title: Dependency theme --- -This filter will allow you to change the order of scripts that are loaded in the theme area. Generally used when writing a addon plugin and you want to load you scripts before the main plugin scripts in order to listen to the forms custom event listeners. +Allows changing the order in which the theme area scripts are loaded. Useful when creating a Forms add-on plugin, and your script needs to be loaded before the Forms scripts (e.g. for adding custom event listeners). ```php \add_filter('es_forms_scripts_dependency_theme', 'getScriptsDependency'); /** - * Make addon scripts fired before main plugin scripts. + * Load add-on scripts before Forms scripts. * * @return array */ diff --git a/website/forms/php/filters/scripts/routes-private.md b/website/forms/php/filters/scripts/routes-private.md index aabe195b0..33e94ae68 100644 --- a/website/forms/php/filters/scripts/routes-private.md +++ b/website/forms/php/filters/scripts/routes-private.md @@ -3,13 +3,13 @@ id: routes-private title: Routes private --- -This filter allows you to add additional routes to the private routes list passed to the JS via global variable. +Allows adding custom routes to the private routes list, available from the Forms global window object. ```php \add_filter('es_forms_scripts_routes_private', 'getPrivateRoutes'); /** - * Add custom route to the private routes list passed to the JS via global variable. + * Adds custom routes to the private routes list, available from the Forms global window object. * * @return array */ diff --git a/website/forms/php/filters/scripts/routes-public.md b/website/forms/php/filters/scripts/routes-public.md index faa62e7f7..d52de523c 100644 --- a/website/forms/php/filters/scripts/routes-public.md +++ b/website/forms/php/filters/scripts/routes-public.md @@ -3,13 +3,13 @@ id: routes-public title: Routes public --- -This filter allows you to add additional routes to the public routes list passed to the JS via global variable. +Allows adding custom routes to the public routes list, available from the Forms global window object. ```php \add_filter('es_forms_scripts_routes_public', 'getPublicRoutes'); /** - * Add custom route to the public routes list passed to the JS via global variable. + * Adds custom routes to the public routes list, available from the Forms global window object. * * @return array */ diff --git a/website/forms/php/filters/validation/force-mimetype-from-fs.md b/website/forms/php/filters/validation/force-mimetype-from-fs.md index 8ed6124d5..337c1d11f 100644 --- a/website/forms/php/filters/validation/force-mimetype-from-fs.md +++ b/website/forms/php/filters/validation/force-mimetype-from-fs.md @@ -3,19 +3,15 @@ id: force-mimetype-from-fs title: Force mimetype from FS --- -Force mimetype validation from filesystem values. +Forces MIME type validation based on the filesystem values. This is the default behavior. In case the file does not exist, the behavior falls back to validating using the MIME type from the POST object. -By default, mime-types are validated from the filesystem mimetype. - -However, in case the file is not present on the filesystem for any reason, this will fall back to the POST-provided mimetype. - -Using this filter, you can force Eightshift Forms to fail every file upload where it can't validate the mimetype from the filesystem. +If `true` is returned from this filter, the Forms file upload will fail if the MIME type cannot be matched from the filesystem. ```php add_filter('es_forms_validation_force_mimetype_from_fs', 'forceMimetypeFs'); /** - * Force mimetype validation from filesystem values. + * Force MIME type validation based on the filesystem values. * * @return bool */ diff --git a/website/src/docs/filters.jsx b/website/src/docs/filters.jsx index 4dc4652da..8857beff9 100644 --- a/website/src/docs/filters.jsx +++ b/website/src/docs/filters.jsx @@ -35,7 +35,7 @@ export function IntegrationFilters({ export function AdditionalContentFilter({ filter }) { return ( <> -

This filter allows to add custom content before the closing tag of the field element. Can be useful for additional markup, styles, etc.

+

Allows adding custom content before the field element's closing tag. Useful for adding markup, styles, etc.

{reformatCode(` @@ -52,9 +52,9 @@ function DataFilter ({ filter }) { return ( <>

Data filter

-

This filter is used if you want to change form fields data before output. This way you can change components map before it is parsed inside Block Editor and on the frontend.

-

For example if you want to force set all fields to have 2 columns layout this will be the filter to use.

-

This field will override any Block Editor changes!

+

Allows modifying form field data before it's shown in the Block Editor or output on the frontend.

+

Useful if, for example, you want to ensure that all fields fit into a 2-column layout.

+

Overrides any Block Editor changes!

{reformatCode(` @@ -111,15 +111,15 @@ function OrderFilter ({ filter }) { return ( <>

Order filter

-

Forces a specific form fields order, regardless of one set in the editor. Fields that are not defined here will follow the natural in-editor order.

-

Not all fields need to have an order defined. For example, if you want to make sure firstname, lastname and email are displayed first, this filter can help.

+

Forces a form field order, regardless of how it's set in the Block editor. Fields not modified through the filter will use order in which they're set in the Block editor.

+

Not all fields need to have an order defined. For example, you may want to make sure firstname, lastname and email are displayed first, but other fields follow their Block editor order.

{reformatCode(` add_filter('es_forms_integrations_${filter}_order', 'getIntegrationOrder'); /** - * Manipulate form fields order before it is sent to the Block Editor. + * Forces form field order for the provided fields. For other fields, Block editor order is used. * * @return array */ @@ -140,15 +140,15 @@ function OrderFilter ({ filter }) { function PrePostIdFilter ({ filter }) { return ( <> -

Pre post id filter

-

This filter enables you to update the item ID for the external integration where your form data will be sent.

+

Pre-post ID filter

+

Allows updating item IDs sent to external integrations to which the form data is sent.

{reformatCode(` add_filter('es_forms_integrations_${filter}_pre_post_id', 'getIntegrationPrePostId', 10, 3); /** - * Manipulate form fields order before it is sent to the Block Editor. + * Modifies integration item ID. * * @param string $itemId Integration item ID. * @param array $params Params to be sent to the integration. @@ -179,15 +179,15 @@ function PrePostParamsFilter ({ filter }) { } return ( <> -

Pre post params filter

-

Change form fields data before it is sent to the {text}. This way you can manipulate data and provide additional mapping to the data sent to the {text}.

+

Pre-post parameters filter

+

Allows modifying form field data before it's sent to {text}. Useful if you want to make values derived from the sent data, or add new fields.

{reformatCode(` add_filter('es_forms_integrations_${filter}_pre_post_params', 'getIntegrationPrePostParams', 10, 2); /** - * Change form fields data before we send it to the ${text}. + * Modifies form field data before it's sent to ${text}. * * @param array $params Array of params. * @param string $formId Form ID.