Skip to content

Entries: document the ability to define a global normalizer #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 25, 2017
Merged

Entries: document the ability to define a global normalizer #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 60 additions & 8 deletions entries/normalizer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,13 @@
</signature>
<desc>Prepares/transforms the elements value for validation.</desc>
<longdesc>
Note that this method:
<p>Doesn't change the elements' value, it only changes the value used for validation.</p>
<p>Gets the value passed as argument, and "this" within it references the corresponding DOMElement.</p>
<p>Needs to return a String value, otherwise it will throw a TypeError exception.</p>
<p>Transform the value of an element and the result for validation instead of the initial value. The normalizer can be defined global to all elements or local to only one element. With that said, the local normalizer will only run for the element for which it was defined. The global normalizer will run for all validated elements. This normalizer can be then overrided for each element, as needed, by attaching one to it. This way only the local one will run for that element, and the global one will run for others.</p>
<p>Note that this method:</p>
<ul>
<li><p>Doesn't change the elements' value, it only changes the value used for validation.</p></li>
<li><p>Gets the value passed as argument, and "this" within it references the corresponding <code>DOMElement</code>.</p></li>
<li><p>Needs to return a String value, otherwise it will throw a <code>TypeError</code> exception.</p></li>
</ul>
</longdesc>
<example>
<desc>Makes "field" required and use a normalizer to trim its value before validating</desc>
Expand All @@ -38,21 +41,67 @@ $( "#myform" ).validate( {
<input type="submit" value="Validate!">
]]></html>
</example>
<example>
<desc>Makes "url" required and use a normalizer to append 'http://', if not present, to the value of the "url" element before validating</desc>
<example>
<desc>Makes "url" required and use a normalizer to append 'http://', if not present, to the value of the "url" element before validating</desc>
<code><![CDATA[
$( "#myform" ).validate( {
rules: {
url_input: {
required: true,
url: true,
normalizer: function( value ) {
var url = value;

// Check if it doesn't start with http:// or https:// or ftp://
if ( url && url.substr( 0, 7 ) !== "http://"
&& url.substr( 0, 8 ) !== "https://"
&& url.substr( 0, 6 ) !== "ftp://" ) {
// then prefix with http://
url = "http://" + url;
}

// Return the new url
return url;
}
}
}
} );
]]></code>
<html><![CDATA[
<label for="url_input">url: </label>
<input class="left" id="url_input" name="url_input">
<br/>
<input type="submit" value="Validate!">
]]></html>
</example>

<example>
<desc>Using a global normalizer in conjunction with a local one</desc>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we note the version in which this new api was added? (Not sure we do it in other places)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK, we never added the version to any of the available API, nor it was added before.
If you want I can add it, but that will be inconsistent with the rest of the documentation.

<code><![CDATA[
$( "#myform" ).validate( {
// This global normalizer will trim the value of all elements
// before validatng them.
normalizer: function( value ) {
return $.trim( value );
},
rules: {
username: {
required: true
},
url_input: {
required: true,
url: true,

// We don't need to trim the value of this element, so we overrided
// the global normalizer in order to append 'http://' to the url value
// if doesn't already.
normalizer: function( value ) {
var url = value;

// Check if it doesn't start with http:// or https:// or ftp://
if ( url && url.substr( 0, 7 ) !== "http://"
&& url.substr( 0, 8 ) !== "https://"
&& url.substr( 0, 6 ) !== "ftp://" ) {
&& url.substr( 0, 8 ) !== "https://"
&& url.substr( 0, 6 ) !== "ftp://" ) {
// then prefix with http://
url = "http://" + url;
}
Expand All @@ -65,6 +114,9 @@ $( "#myform" ).validate( {
} );
]]></code>
<html><![CDATA[
<label for="username">Required: </label>
<input class="left" id="username" name="username">
<br/>
<label for="url_input">url: </label>
<input class="left" id="url_input" name="url_input">
<br/>
Expand Down
7 changes: 7 additions & 0 deletions entries/validate.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,13 @@
</desc>
<type name="Object"/>
</property>
<property name="normalizer">
<desc>
Prepares/transforms the elements value for validation.
See <a href="/normalizer/">normalizer docs</a> for more details.
</desc>
<type name="Function"/>
</property>
<property name="onsubmit" default="true">
<desc>
Validate the form on submit. Set to false to use only other events for validation.
Expand Down