Inline error handling for forms

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:
 

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:

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                                       |

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);

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,48 +97,56 @@ Member email address.
 
     <label for="email">Email</label>
     <input type="email" name="email" value="{email}" maxlength="120" size="40" />
+    {if error:email}<p class="error">{error:email}</p>{/if} // when inline error handling is enabled
 
 ### Password
 
 Member password. This is a **required** field.
 
-            <label>Your New Password</label><br />
-            <input type="password" name="password" value="" maxlength="50" size="40" />
+    <label>Your New Password</label><br />
+    <input type="password" name="password" value="" maxlength="50" size="40" />
+    {if error:password}<p class="error">{error:password}</p>{/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.
 
-            <label>Confirm New Password</label><br />
-            <input type="password" name="password_confirm" value="" maxlength="50" size="40" />
+    <label>Confirm New Password</label><br />
+    <input type="password" name="password_confirm" value="" maxlength="50" size="40" />
 
 ### Current Password
 
 If the password or the email address is submitted, the current password field is **required**.
 
-            <label>Confirm New Password</label><br />
-            <input type="password" name="current_password" value="" maxlength="50" size="40" />
+    <label>Confirm New Password</label><br />
+    <input type="password" name="current_password" value="" maxlength="50" size="40" />
 
 ### Screen name
 
 Member Screen name. This is a **required** field:
 
     <label for="screen_name">Screen Name</label>
     <input type="text" name="screen_name" value="{screen_name}" maxlength="120" size="40" />
+    {if error:screen_name}<p class="error">{error:screen_name}</p>{/if} // when inline error handling is enabled
 
 ### Username
 
 Member username. This is a **required** field and must be unique across the site:
 
     <label for="username">Username</label>
     <input type="text" name="username" value="{username}" maxlength="120" size="40" />
+    {if error:username}<p class="error">{error:username}</p>{/if} // when inline error handling is enabled
 
 ### Custom field
 
 The custom profile fields can be displayed individually by addressing them using the field's short name prefixed with `field:`:
 
     {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}<span class="error">{error}</span>{/if}
+
             </p>
          {/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

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="<https://example.com/member/forgot-password/sent.html>"
 
+### `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).

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="<https://example.com/member/login/forgot-username.html>"
 
+### `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

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="<https://example.com/return.html>"
 
+### `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
       <p><input class="checkbox" type="checkbox" name="auto_login" value="1"> Auto-login on future visits</p>
     {/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
 

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,14 +217,33 @@ 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
         return="member/registration/success"
         error_handling="inline"
     }
 
-        <p>* Required fields</p>
+    {if errors}
+        <fieldset class="error">
+            <legend>Errors</legend>
+            {errors}
+                <p>{error}</p>
+            {/errors}
+        </fieldset>
+    {/if}
+
+    <p>* Required fields</p>
     <fieldset>
         <h4>Login details</h4>