From 9c57d299ecd33f2d1f14f2851632514a80e9e858 Mon Sep 17 00:00:00 2001 From: Yuri Salimovskiy Date: Wed, 28 Feb 2024 17:12:07 +0200 Subject: [PATCH 1/2] Inline error handling for forms https://github.com/ExpressionEngine/ExpressionEngine/pull/4093 --- docs/add-ons/email.md | 19 ++++++++++- docs/comment/form.md | 17 ++++++++++ docs/member/edit-profile.md | 37 +++++++++++++++++---- docs/member/forgot-password.md | 10 ++++++ docs/member/forgot-username.md | 11 ++++++ docs/member/login.md | 14 ++++++++ docs/member/registration.md | 33 ++++++++++++++++-- docs/templates/globals/single-variables.md | 29 ++++++++++++++-- docs/toc_sections/_the_fundamentals_toc.yml | 3 +- 9 files changed, 160 insertions(+), 13 deletions(-) diff --git a/docs/add-ons/email.md b/docs/add-ons/email.md index 3afec336c..053f54c4b 100755 --- a/docs/add-ons/email.md +++ b/docs/add-ons/email.md @@ -152,6 +152,17 @@ With this parameter, you can specify the css class you want the form to have, en With this parameter, you can specify the css id you want the form to have. The default value is 'contact_form'. +### `error_handling="inline"` + error_handling="inline" + +This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" + ## Variables [TOC=3] @@ -172,6 +183,12 @@ If a user is logged in, then it will display their email address as recorded in If a user is logged in, then it will display their screen name as recorded in their member profile. +### `{errors}...{error}...{/errors}` + +When inline errors enabled, displays all errors in a loop. Each individual error message is available as `{error}` variable within the loop. + +This variable pair is useful for displaying all errors at once, for example, in a fieldset at the top of the form. It can also be used as a conditional to check if there are any errors at all: `{if errors}`. + ## Form Fields [TOC=3] @@ -237,7 +254,7 @@ Email address to which the email is being sent. Multiple email addresses may be WARN: **Warning:** If you leave this field open to user input, you are potentially giving spammers an easy way to send anonymous emails. If you allow users to access this field, consider using a <select> field to limit the email address to specific choices. Further, you should enable CAPTCHAs to help prevent automated abuse. -### `Preview` +### `preview` Occasionally you'll want to provide a way for users to preview their email message before sending it. You'll start by specifying a [preview=](#preview) parameter in your opening tag: diff --git a/docs/comment/form.md b/docs/comment/form.md index 5fe92dd40..6abd2cc68 100755 --- a/docs/comment/form.md +++ b/docs/comment/form.md @@ -109,6 +109,17 @@ This parameter allows you to define where the user will be returned after submit If this parameter is not defined, they will be returned to the form page. +### `error_handling="inline"` + error_handling="inline" + +This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" + ### Conditionals [TOC=4] @@ -161,6 +172,12 @@ The author's location as entered in their profile or the comment entry form. Name of the author. +### `{errors}...{error}...{/errors}` + +When inline errors enabled, displays all errors in a loop. Each individual error message is available as `{error}` variable within the loop. + +This variable pair is useful for displaying all errors at once, for example, in a fieldset at the top of the form. It can also be used as a conditional to check if there are any errors at all: `{if errors}`. + #### Conditionals The following conditionals are available: diff --git a/docs/member/edit-profile.md b/docs/member/edit-profile.md index 8960a26ae..3be4403cc 100644 --- a/docs/member/edit-profile.md +++ b/docs/member/edit-profile.md @@ -21,6 +21,17 @@ This template tag allows editing a member's profile using the form that is simil {{embed:_tips/form-attributes.md}} +### `error_handling="inline"` + error_handling="inline" + +This parameter allows you to use inline errors in profile edit form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" + ### `datepicker=` Include the datepicker javascript. This should be set to ``yes`` if there is a date type member custom field in order to output the calendar. @@ -86,27 +97,29 @@ Member email address. + {if error:email}

{error:email}

{/if} // when inline error handling is enabled ### Password Member password. This is a **required** field. -
- +
+ + {if error:password}

{error:password}

{/if} // when inline error handling is enabled ### Password Confirmation Password confirmation. If a new password is submitted, the password confirmation field is **required** and must match the entered password. -
- +
+ ### Current Password If the password or the email address is submitted, the current password field is **required**. -
- +
+ ### Screen name @@ -114,6 +127,7 @@ Member Screen name. This is a **required** field: + {if error:screen_name}

{error:screen_name}

{/if} // when inline error handling is enabled ### Username @@ -121,6 +135,7 @@ Member username. This is a **required** field and must be unique across the site + {if error:username}

{error:username}

{/if} // when inline error handling is enabled ### Custom field @@ -128,6 +143,10 @@ The custom profile fields can be displayed individually by addressing them using {field:birthday} +If inline error handling is enabled, you can use the `{error:field_name}` tag to display the error message for the field. + + {error:birthday} + ## Custom Profile Field Variable Pair All custom fields are output inside the ``{custom_profile_fields}`` variable tag pair. @@ -139,6 +158,8 @@ All custom fields are output inside the ``{custom_profile_fields}`` variable tag {form:custom_profile_field} + {if error}{error}{/if} +

{/custom_profile_fields} @@ -189,6 +210,10 @@ Maximum length set for text fields Short name of the fieldtype used for field +#### `{error}` + +Error message for the field, if inline error handling is enabled. + ## Example {exp:member:edit_profile diff --git a/docs/member/forgot-password.md b/docs/member/forgot-password.md index be0bfe65e..2c6e817e2 100644 --- a/docs/member/forgot-password.md +++ b/docs/member/forgot-password.md @@ -55,6 +55,16 @@ This parameter allows you to define where the user will be returned after succes 1. Use the standard Template_Group/Template syntax to specify where to return the user. For instance, if you want the user to be returned to the "local" Template in the "news" Template Group, you would use: return="member/forgot-password/sent" 2. Use a full URL. For example: return="" +### `error_handling="inline"` + error_handling="inline" + +This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" ## Form Inputs NOTE: Be sure to include the required Javascript and CSS to use the native [Password Validation](member/password-validation.md). diff --git a/docs/member/forgot-username.md b/docs/member/forgot-username.md index 7da35a676..645c871cd 100644 --- a/docs/member/forgot-username.md +++ b/docs/member/forgot-username.md @@ -50,6 +50,17 @@ This parameter allows you to define where the user will be returned after succes 1. Use the standard Template_Group/Template syntax to specify where to return the user. For instance, if you want the user to be returned to the "local" Template in the "news" Template Group, you would use: return="member/login/forgot-username" 2. Use a full URL. For example: return="" +### `error_handling="inline"` + error_handling="inline" + +This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" + ## Form Inputs ### Email diff --git a/docs/member/login.md b/docs/member/login.md index 6d99cde80..861b02a1a 100644 --- a/docs/member/login.md +++ b/docs/member/login.md @@ -63,7 +63,16 @@ This parameter allows you to define where the user will be returned after succes 1. Use the standard Template_Group/Template syntax to specify where to return the user. For instance, if you want the user to be returned to the "local" Template in the "news" Template Group, you would use: return="news/local" 2. Use a full URL. For example: return="" +### `error_handling="inline"` + error_handling="inline" +This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" ## Form Inputs @@ -110,6 +119,11 @@ It is recommended that you use this variable as indicated in the example code at

Auto-login on future visits

{/if} +### `{errors}...{error}...{/errors}` + +When inline errors enabled, displays all errors in a loop. Each individual error message is available as `{error}` variable within the loop. + +This variable pair is useful for displaying all errors at once, for example, in a fieldset at the top of the form. It can also be used as a conditional to check if there are any errors at all: `{if errors}`. ## Example diff --git a/docs/member/registration.md b/docs/member/registration.md index 4ce434879..c2df332d8 100644 --- a/docs/member/registration.md +++ b/docs/member/registration.md @@ -38,7 +38,13 @@ This parameter allows you to specify the primary role to assign the new member, ### `error_handling="inline"` error_handling="inline" -This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error, as used to compose the form. +This parameter allows you to use inline errors in your registration form. The errors can be displayed using the `{error:field_name}` tag where `field_name` would need to be replaced with the name of the field that has an error or using [`{errors}` variable pair](templates/globals/single-variables.md#error-variables). + +### `return_error=` + +When inline errors are enabled, this parameter allows you to specify the template to return to if there are errors in the form. The default is the same template that the form is on. + + return_error="member/error" ### `include_assets=` @@ -160,6 +166,10 @@ Shows the fully parsed custom member form field. Indicates whether the field is marked as required +#### `{error}` + +Error message for the field, if inline error handling is enabled. + ## Variables ### `{accept_terms}` @@ -207,6 +217,16 @@ This will show errors with the submitted password as well as password confirm. Displays the custom field input form for the given field (substitute `field_name` with the actual field name). Note that the field must be set as "visible on registration" in order to show up. +### `{error:field_name}` + +When inline errors enabled, displays the error message for the given field (substitute `field_name` with the actual field name). + +### `{errors}...{error}...{/errors}` + +When inline errors enabled, displays all errors in a loop. Each individual error message is available as `{error}` variable within the loop. + +This variable pair is useful for displaying all errors at once, for example, in a fieldset at the top of the form. It can also be used as a conditional to check if there are any errors at all: `{if errors}`. + ## Example {exp:member:registration_form @@ -214,7 +234,16 @@ Displays the custom field input form for the given field (substitute `field_name error_handling="inline" } -

* Required fields

+ {if errors} +
+ Errors + {errors} +

{error}

+ {/errors} +
+ {/if} + +

* Required fields

Login details

diff --git a/docs/templates/globals/single-variables.md b/docs/templates/globals/single-variables.md index f7dce70b1..62e7247a7 100755 --- a/docs/templates/globals/single-variables.md +++ b/docs/templates/globals/single-variables.md @@ -7,13 +7,13 @@ @license https://expressionengine.com/license Licensed under Apache License, Version 2.0 --> -# Single Global Variables +# Global Variables [TOC] These Global Variables can be used anywhere within your Templates. Note that they are subject to ExpressionEngine's [parsing order](templates/engine.md), which can affect their availability when used inside other tags. -## Variables +## Single Variables [TOC=3 hide] @@ -330,3 +330,28 @@ The total number of forum topics made by the currently logged-in user. ### `{logged_in_username}` The username for the currently logged-in user. + +## Error Variables + +When submitting a form that has `error_handling="inline"` set, the error messages will be displayed in the template. + +By default, they will be rendered on same page that contains the form, however it is also possible to specify different page using `return_error=` parameter. + +### `{if errors}` + +Conditional check if error messages are present. + +### `{errors}...{error}...{/errors}` + +This variable pair is useful for displaying all errors at once, for example, in a fieldset at the top of the form. Inside the pair, each individual error message is available as `{error}` variable. + + {if errors} +

Please correct the following errors:

+
    + {errors} +
  • {error}
    • + {/errors} +
+ {if:else} + + {/if} \ No newline at end of file diff --git a/docs/toc_sections/_the_fundamentals_toc.yml b/docs/toc_sections/_the_fundamentals_toc.yml index a74b7f465..ee7b44d00 100644 --- a/docs/toc_sections/_the_fundamentals_toc.yml +++ b/docs/toc_sections/_the_fundamentals_toc.yml @@ -142,7 +142,7 @@ href: templates/variable.md - name: Global Template Variables items: - - name: Single Global Variables + - name: Global Variables href: templates/globals/single-variables.md - name: Linking to Stylesheets href: templates/globals/stylesheet.md @@ -315,4 +315,3 @@ href: comment/subscriptions.md - name: Control Panel href: comment/control-panel.md - From 974b0466cc7d08b815d6c12c0381a29ffd7ff4b9 Mon Sep 17 00:00:00 2001 From: Yuri Salimovskiy Date: Thu, 29 Feb 2024 09:33:50 +0200 Subject: [PATCH 2/2] developer docs (add missing functions) --- .../development/legacy/libraries/functions.md | 18 +++++++ docs/development/legacy/libraries/output.md | 51 +++++++++++++++++++ 2 files changed, 69 insertions(+) diff --git a/docs/development/legacy/libraries/functions.md b/docs/development/legacy/libraries/functions.md index bcc9b7821..6060489ec 100755 --- a/docs/development/legacy/libraries/functions.md +++ b/docs/development/legacy/libraries/functions.md @@ -103,6 +103,24 @@ Redirect to location. Random number/password generator. +### `determine_return($go_to_index = false)` + +| Parameter | Type | Description | +| ------------- | -------- | ------------------------------------------------- | +| \$go_to_index | `Bool` | When `true`, redirect to homepage | +| Returns | `String` | URL to redirect to | + +Discover the redirect link to return to upon form submission. + + $return_link = ee()->functions->determine_return(); + +### `determine_error_return()` + +Discover the redirect link to return to upon form submission, if there have been validation errors and inline error handling was enabled in the form. + + $return_error_link = ee()->functions->determine_error_return(); + ee()->output->show_user_error('submission', $errors, '', $return_error_link); + ### `form_declaration($data)` | Parameter | Type | Description | diff --git a/docs/development/legacy/libraries/output.md b/docs/development/legacy/libraries/output.md index 3df10bf30..925620f71 100755 --- a/docs/development/legacy/libraries/output.md +++ b/docs/development/legacy/libraries/output.md @@ -176,3 +176,54 @@ Example: 'foo' => 'bar' ); ee()->output->send_ajax_response($output); + +### `show_message($data, $xhtml = true, $redirect_url = false, $template_name = 'generic')` + +| Parameter | Type | Description | +| --------------- | -------- | ------------------------------------------------------------------------------------------ | +| \$data | `Array` | Data to be sent to the view. Explained below | +| \$xhtml | `Bool` | Parse the content as HTML | +| \$redirect_url | `String` | URL to redirect to instead of showing the message | +| \$template_name | `String` | Speciatly template to use. Defaults to `generic` which is equivalent of `message_template` | +| Returns | `Void` | void | + +Show user message using [system message template](control-panel/template-manager.md#system-message-templates) or [custom template](control-panel/template-manager.md#custom-system-messages). This is used on front-end, for instance, when we need to inform the user about successful form submission. + +When `$redirect_url` is provided, the user will be redirected to that URL instead of showing the message. + +The `$data` parameter is an associative array with the following keys: + - `title` - HTML titles of message page + - `heading` - heading text + - `content` - main content + - `redirect` - URL to automatically redirect to after showing message + - `rate` - time in seconds after which the redirect happens + - `link` - the link to include in the message. Should be in the format of `array($link_url, $link_text)` + +Example: + + $data = array( + 'title' => 'Title', + 'heading' => 'Heading', + 'content' => 'Content', + 'redirect' => 'http://example.com', + 'rate' => 5, + 'link' => array('http://example.com', 'Link Text') + ); + ee()->output->show_message($data); + +### `show_user_error($type = 'submission', $errors = '', $heading = '', $redirect_url = '')` + +| Parameter | Type | Description | +| --------------- | -------- | ------------------------------------------------------------------------------------------ | +| \$type | `String` | Type of error. Defaults to `submission`, can also be `generic` | +| \$errors | `Mixed` | Error message or array of messages to display. | +| \$heading | `String` | Heading text. Legacy, not used, set automatically based on type. | +| \$redirect_url | `String` | URL to redirect to instead of showing the message | +| Returns | `Void` | void | + +Show user an error message using [system message template](control-panel/template-manager.md#system-message-templates) or [custom template](control-panel/template-manager.md#custom-system-messages). This is used on front-end, for instance, when a form is submitted without the required info. + +When `$redirect_url` is provided, the user will be redirected to that URL instead of showing the message. Useful when the form is set to [handle errors inline](templates/globals/single-variables.md#error-variables). + + $return_error_link = ee()->functions->determine_error_return(); + ee()->output->show_user_error('submission', $errors, '', $return_error_link); \ No newline at end of file