6 * @class mw.htmlform.Checker
10 * A helper class to add validation to non-OOUI HtmlForm fields.
13 * @param {jQuery} $element Form field generated by HTMLForm
14 * @param {Function} validator Validation callback
15 * @param {string} validator.value Value of the form field to be validated
16 * @param {jQuery.Promise} validator.return The promise should be resolved
17 * with an object with two properties: Boolean 'valid' to indicate success
18 * or failure of validation, and an array 'messages' to be passed to
19 * setErrors() on failure.
21 mw
.htmlform
.Checker = function ( $element
, validator
) {
22 this.validator
= validator
;
23 this.$element
= $element
;
25 this.$errorBox
= $element
.next( '.error' );
26 if ( !this.$errorBox
.length
) {
27 this.$errorBox
= $( '<span>' );
28 this.$errorBox
.hide();
29 $element
.after( this.$errorBox
);
32 this.currentValue
= this.$element
.val();
36 * Attach validation events to the form element
38 * @param {jQuery} [$extraElements] Additional elements to listen for change
40 * @return {mw.htmlform.Checker}
43 mw
.htmlform
.Checker
.prototype.attach = function ( $extraElements
) {
45 // We need to hook to all of these events to be sure we are
46 // notified of all changes to the value of an <input type=text>
48 events
= 'keyup keydown change mouseup cut paste focus blur';
51 if ( $extraElements
) {
52 $e
= $e
.add( $extraElements
);
54 $e
.on( events
, $.debounce( 1000, this.validate
.bind( this ) ) );
60 * Validate the form element
61 * @return {jQuery.Promise}
63 mw
.htmlform
.Checker
.prototype.validate = function () {
64 var currentRequestInternal
,
66 value
= this.$element
.val();
68 // Abort any pending requests.
69 if ( this.currentRequest
&& this.currentRequest
.abort
) {
70 this.currentRequest
.abort();
74 this.currentValue
= value
;
79 this.currentRequest
= currentRequestInternal
= this.validator( value
)
80 .done( function ( info
) {
81 var forceReplacement
= value
!== that
.currentValue
;
83 // Another request was fired in the meantime, the result we got here is no longer current.
84 // This shouldn't happen as we abort pending requests, but you never know.
85 if ( that
.currentRequest
!== currentRequestInternal
) {
88 // If we're here, then the current request has finished, avoid calling .abort() needlessly.
89 that
.currentRequest
= undefined;
91 that
.currentValue
= value
;
94 that
.setErrors( [], forceReplacement
);
96 that
.setErrors( info
.messages
, forceReplacement
);
98 } ).fail( function () {
99 that
.currentValue
= null;
100 that
.setErrors( [] );
103 return currentRequestInternal
;
107 * Display errors associated with the form element
108 * @param {Array} errors Error messages. Each error message will be appended to a
109 * `<span>` or `<li>`, as with jQuery.append().
110 * @param {boolean} [forceReplacement] Set true to force a visual replacement even
111 * if the errors are the same. Ignored if errors are empty.
112 * @return {mw.htmlform.Checker}
115 mw
.htmlform
.Checker
.prototype.setErrors = function ( errors
, forceReplacement
) {
116 var $oldErrorBox
, tagName
, showFunc
, text
, replace
,
117 $errorBox
= this.$errorBox
;
119 if ( errors
.length
=== 0 ) {
120 $errorBox
.slideUp( function () {
122 .removeAttr( 'class' )
126 // Match behavior of HTMLFormField::formatErrors(), <span> or <ul>
127 // depending on the count.
128 tagName
= errors
.length
=== 1 ? 'span' : 'ul';
130 // We have to animate the replacement if we're changing the tag. We
131 // also want to if told to by the caller (i.e. to make it visually
132 // obvious that the changed field value gives the same error) or if
133 // the error text changes (because it makes more sense than
134 // changing the text with no animation).
136 forceReplacement
|| $errorBox
.length
> 1 ||
137 $errorBox
[ 0 ].tagName
.toLowerCase() !== tagName
140 text
= $( '<' + tagName
+ '>' )
141 .append( errors
.map( function ( e
) {
142 return errors
.length
=== 1 ? e
: $( '<li>' ).append( e
);
144 if ( text
.text() !== $errorBox
.text() ) {
149 $oldErrorBox
= $errorBox
;
151 this.$errorBox
= $errorBox
= $( '<' + tagName
+ '>' );
153 $oldErrorBox
.after( this.$errorBox
);
156 showFunc = function () {
157 if ( $oldErrorBox
!== $errorBox
) {
159 .removeAttr( 'class' )
163 .attr( 'class', 'error' )
165 .append( errors
.map( function ( e
) {
166 return errors
.length
=== 1 ? e
: $( '<li>' ).append( e
);
170 if ( $oldErrorBox
!== $errorBox
&& $oldErrorBox
.hasClass( 'error' ) ) {
171 $oldErrorBox
.slideUp( showFunc
);
180 }( mediaWiki
, jQuery
) );