Add documentation for form validation in templates

Author: bryannielsen

docs/_tips/form-validation.md

@@ -0,0 +1 @@
+TIP: **Tip:** This form utilizes template [form validation and error handling](/templates/form-validation.md).  Refer to the documentation for additional parameters and variables that are available to this tag.

docs/add-ons/email.md

@@ -52,6 +52,8 @@ The contact form is created similar to a standard web form, only you **do not**
         </p>
     {/exp:email:contact_form}
 
+{{embed:_tips/form-validation.md}}
+
 ## Parameters
 
 [TOC=3]
@@ -330,7 +332,7 @@ In the above example, the Template "friend" contains the Tell-a-Friend form.
 [TOC=3]
 
 ### `allow_attachments=`
-     
+
      allow_attachments="yes"
 
 This allows you to add a file input field to your form, make sure to give your file input field the name of `attachment`. Adding this parameter automatically gives the form the `enctype='multipart/form-data'` attribute.

docs/comment/form.md

@@ -35,7 +35,7 @@ The comment submission form is created very similar to a standard web form, only
 
       <input type="submit" name="submit" value="Submit" />
       <input type="submit" name="preview" value="Preview" />
-      
+
       {!-- required to prevent EE from outputting form if commenting is disabled or expired --}
 	  {if comments_disabled}Comments on this entry are currently disabled.{/if}
       {if comments_expired}Commenting on this entry has expired.{/if}
@@ -46,6 +46,8 @@ This form should be placed on a "single-entry" type page such as a comments page
 
 TIP: **Tip:** Notice the variables in the "value" form fields? These allow us to show the user's information in the form automatically if they click the "remember personal info" option.
 
+{{embed:_tips/form-validation.md}}
+
 ## Comment Form Tag
 
 ### Parameters
@@ -227,11 +229,11 @@ A request for an edit will return a response array. In the case of an error, an
 
 ### Editing Permissions
 
-By using the [{if editable}](/comment/entries.html#if-editable) conditional in the Comment Entries tag, you can output a link, instructions or a form if the viewing member has permission to edit the comment, and by using the {if can_moderate_comment} you can display whatever is appropriate if the viewing member has permission to moderate (close) the comment.
+By using the [{if editable}](/comment/entries.md#if-editable) conditional in the Comment Entries tag, you can output a link, instructions or a form if the viewing member has permission to edit the comment, and by using the {if can_moderate_comment} you can display whatever is appropriate if the viewing member has permission to moderate (close) the comment.
 
 For members without administrative access, in order to edit a comment they must be logged in, the author of the comment, and the editing time limit must not have expired. If a member has a role with permission to edit the comments of any entry, that member will have edit permissions regardless of the editing time limit.
 
-Comment moderators may close the comment. The edit time limit does not apply to moderators. 
+Comment moderators may close the comment. The edit time limit does not apply to moderators.
 
 Superadmins will always have {editable} and {can_moderate_comment} permissions on any comment.
 

docs/development/legacy/libraries/output.md

@@ -195,3 +195,78 @@ $output = array(
     'message' => 'not allowed',
 );
 ee()->output->send_ajax_response($output, true);
+
+### `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` | Specialty 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 `general` or `off`                    |
+| \$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);
+
+### `show_form_error($errors, $type = 'general')`
+
+| Parameter       | Type     | Description                                                                                |
+| --------------- | -------- | ------------------------------------------------------------------------------------------ |
+| \$errors        | `Mixed`  | Array of error messages or instance of \ExpressionEngine\Service\Validation\Result         |
+| \$type          | `String` | Type of error. Defaults to `general`, can also be `submission` or `off`                    |
+| Returns         | `Void`   | void                                                                                       |
+
+Handle displaying errors for a form either passed as a Validation Result or an array of errors.  If the form is using
+inline error handling the errors and old input will be flashed to the session otherwise they will be displayed with the
+appropriate template.
+
+### `show_form_error_aliases($errors = '', $aliases = [], $type = 'general')`
+
+| Parameter       | Type     | Description                                                                                   |
+| --------------- | -------- | --------------------------------------------------------------------------------------------- |
+| \$errors        | `Mixed`  | Array of error messages or instance of \ExpressionEngine\Service\Validation\Result            |
+| \$aliases       | `Array`  | Array of aliases to use, i.e. ['input_id_1' => ['field' => 'input_name', 'label' => 'Input']] |
+| \$type          | `String` | Type of error. Defaults to `general`, can also be `submission` or `off`                       |
+| Returns         | `Void`   | void                                                                                          |
+
+This function builds upon `show_form_error()` with the additional ability to provide aliases for input names so
+that variable names used in inline error handling can be more meaningful i.e. `field_name` instead of `field_id_1`.

docs/member/edit-profile.md

@@ -17,6 +17,8 @@
 
 This template tag allows editing a member's profile using the form that is similar to [Channel Form](channels/channel-form/overview.md). Please note however that not all Channel Form parameters and template tags are available in the Member Profile form, so make sure to consult the documentation below. The form can only be used to update profile of the member that is currently logged in.
 
+{{embed:_tips/form-validation.md}}
+
 ## Parameters
 
 {{embed:_tips/form-attributes.md}}
@@ -194,6 +196,7 @@ Short name of the fieldtype used for field
     {exp:member:edit_profile
         return="member/registration/success"
 		include_assets="yes"
+        inline_errors="yes"
 		datepicker="yes"
         }
 
@@ -204,27 +207,42 @@ Short name of the fieldtype used for field
             <p>
                 <label for="username">Username*:</label><br />
                 <input type="text" name="username" id="username" value="{username}"/><br />
+                {if error:username}
+                    <span class="error">{error:username}</span>
+                {/if}
             </p>
 
             <p>
                 <label for="email">Email:</label><br />
                 <input type="text" name="email" id="email" value="{email}"/><br />
+                {if error:email}
+                    <span class="error">{error:email}</span>
+                {/if}
             </p>
 
             <p>
                 <label for="password">Password:</label><br />
                 <input type="password" name="password" id="password" value=""/>
+                {if error:password}
+                    <span class="error">{error:password}</span>
+                {/if}
             </p>
 
             <p>
                 <label for="password_confirm">Confirm password*:</label><br />
                 <input type="password" name="password_confirm" id="password_confirm" value=""/>
+                {if error:password_confirm}
+                    <span class="error">{error:password_confirm}</span>
+                {/if}
             </p>
 
             <p>
                 <label for="current_password">Current password*:</label><br />
 					<em>You <b>must</b> enter your current password to change your password, username or email.</em>
                  <input type="password" name="current_password" id="current_password" value=""/>
+                 {if error:current_password}
+                    <span class="error">{error:current_password}</span>
+                {/if}
             </p>
 
 
@@ -235,6 +253,9 @@ Short name of the fieldtype used for field
 
                 {form:custom_profile_field}
 
+                {if has_error}
+                    <span class="error">{error}</span>
+                {/if}
             </p>
          {/custom_profile_fields}
 

docs/member/forgot-password.md

@@ -24,16 +24,18 @@ Output a forgotten password form that sends an email with instructions for reset
 
     {/exp:member:forgot_password_form}
 
-    
+
 NOTE: **Note:** This form will only email the user if the user requesting the password reset is not currently logged in.
 
+{{embed:_tips/form-validation.md}}
+
 ## Parameters
 
 ### `email_template=`
 
     email_template="member/email-password-reset"
 
-Template to use for email which is sent to user. 
+Template to use for email which is sent to user.
 
 NOTE: **Note:** If no template is defined, the default [Member Profile Template](control-panel/template-manager.md#member-profile-templates) for a forgotten password will be used.
 
@@ -66,47 +68,27 @@ Member email address. This is a **required** field:
     <label for="email">Email</label>
     <input type="email" name="email" value="" maxlength="120" size="40" />
 
-
-
-## Variable Pairs
-
-### `{errors}`
-
-Form submission errors are displayed using a "looping pair" as there can be more than 1 error in a form submission.
-
-    {errors}
-        <p>{error}</p>
-    {/errors}
-
-#### Error Tag Pair Parameters
-
-##### `backspace=`
-
-    backspace="3"
-
-The `backspace=` parameter will remove characters, including spaces and line breaks, from the last iteration of the tag pair.
-
-#### Error Tag Pair Variables
-
-##### `{error}`
-
-    {error}
-
-The error text.
-
-
-
 ## Example
 
     {exp:member:forgot_password_form
         return="member/forgot-password/sent"
+        inline_errors="yes"
         password_reset_url="member/reset-password"
         email_template="member/email-password-reset"
         }
 
+        {if errors}
+            <fieldset class="error">
+                <legend>Errors</legend>
+                {errors}
+                    <p>{error}</p>
+                {/errors}
+            </fieldset>
+        {/if}
+
         <p>
             <label>Your Email Address</label><br />
-            <input type="email" name="email" value="" maxlength="120" size="40" />
+            <input type="email" name="email" value="{if old:email}{old:email}{/if}" maxlength="120" size="40" />
         </p>
 
         <p><input type="submit" name="submit" value="Submit" /></p>

docs/member/forgot-username.md

@@ -24,6 +24,8 @@ Output a forgotten username form that sends an email with instructions for addre
 
     {/exp:member:forgot_username_form}
 
+{{embed:_tips/form-validation.md}}
+
 ## Parameters
 
 ### `email_subject=`
@@ -37,7 +39,7 @@ Subject of email sent to user.
 
     email_template="member/email-forgot-username"
 
-Template to use for email which is sent to user. 
+Template to use for email which is sent to user.
 
 If no template is defined or if the template defined does not exist, the default [Member Profile Template](control-panel/template-manager.md#member-profile-templates) for a forgotten username will be used.
 
@@ -59,46 +61,27 @@ Member email address. This is a **required** field:
     <label for="email">Email</label>
     <input type="email" name="email" value="" maxlength="120" size="40" />
 
-
-
-## Variable Pairs
-
-### `{errors}`
-
-Form submission errors are displayed using a "looping pair" as there can be more than 1 error in a form submission.
-
-    {errors}
-        <p>{error}</p>
-    {/errors}
-
-#### Error Tag Pair Parameters
-
-##### `backspace=`
-
-    backspace="3"
-
-The `backspace=` parameter will remove characters, including spaces and line breaks, from the last iteration of the tag pair.
-
-#### Error Tag Pair Variables
-
-##### `{error}`
-
-    {error}
-
-The error text.
-
-
 ## Example
 
     {exp:member:forgot_username_form
         return="member/login/forgot-username"
+        inline_errors="yes"
         email_subject="Your Username"
         email_template="member/email-forgot-username"
         }
 
+        {if errors}
+            <fieldset class="error">
+                <legend>Errors</legend>
+                {errors}
+                    <p>{error}</p>
+                {/errors}
+            </fieldset>
+        {/if}
+
         <p>
             <label>Your Email Address</label><br />
-            <input type="email" name="email" value="" maxlength="120" size="40" />
+            <input type="email" name="email" value="{if old:email}{old:email}{/if}" maxlength="120" size="40" />
         </p>
 
         <p><input type="submit" name="submit" value="Submit" /></p>