Dave Rolsky - Form.Serializer-0.14

NAME

Form.Serializer - Serialize form values into various forms

SYNOPSIS

  var serializer = new Form.Serialize("name_of_form");
  // or var serializer = new Form.Serialize("id_of_form");

  var qs = serializer.queryString();

  var pairs = serializer.pairsArray();
  for ( var i in pairs ) {
      document.write( pairs[i][0] + " = " + pairs[i][1] );
  }

  var named = serializer.keyValues();
  for ( var key in named ) {
      document.write( key + " = " );
      if ( typeof named[key] == 'object' ) {
          document.write( named[key].join(", ") );
      }
      else {
          document.write( named[key] );
      }
  }

  var named = serializer.keyValues('force array for all keys');
  for ( var key in named ) {
      document.write( key + " = " + named[key].join(", ") );
  }

DESCRIPTION

A form serializing class that can return various serialized versions of the form.

Note that when serializing a form it does not include the names or values of any button, submit, or image elements.

METHODS

new Form.Serializer(name)

new Form.Serializer(id)

new Form.Serializer(form_element)

The constructor can be given either the name or id of a form, or a form element object. It checks for an object first, then id, and finally name.

If no matching form is found an exception is thrown.

Returns a new object.

pairsArray()

Returns an array of pairs (two-element arrays). The first element of each pair is a form element's name, and the second is the value. The same name may recur multiple times.

queryString()

queryString(separator)

This method returns a properly encoded query string representing the serialized form. By default, key-value pairs are separated with a semi-colon (;). If you pass a string to this method, that string will be used as the separator.

keyValues()

keyValues(forceArray)

Returns an object. The properties of the object are the form element names and the values of each property is the value(s) for that element. When the same name occurs multiple times or for multi-select elements, the value will be an array. To force all values to be made into array, pass a true value into this method.

AUTHOR

Dave Rolsky, <autarch@urth.org>.

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as the Perl programming language (your choice of GPL or the Perl Artistic license).

if ( typeof Form == "undefined" ) {
    Form = {};
}

Form.Serializer = function (name) {
    return this._initialize(name);
};

Form.Serializer.VERSION = "0.14";

Form.Serializer.ElementTypes = [ "input", "textarea", "select" ];

Form.Serializer.prototype._initialize = function (form) {
    if ( typeof form == "object" ) {
        this.form = form;
        return;
    }

    this.form = document.getElementById(form);

    if ( ! this.form ) {
        for ( var i = 0; i < document.forms.length; i++ ) {
            if ( document.forms[i].name == form ) {
                this.form = document.forms[i];
                break;
            }
        }
    } 

    if ( ! this.form ) {
        throw new Error( "Cannot find a form with the name or id '" + name + "'" );
    }
};

Form.Serializer.prototype.pairsArray = function () {
    var pairs = new Array;

    for ( var i = 0; i < Form.Serializer.ElementTypes.length; i++ ) {
        var type = Form.Serializer.ElementTypes[i];
        var elements = this.form.getElementsByTagName(type);

        for ( var j = 0; j < elements.length; j++ ) {

            var p = eval( "this._serialize_" + type + "(elements[j])" );

            if (p) {
                for ( var k = 0; k < p.length; k++ ) {
                    pairs.push( p[k] );
                }
            }
        }
    }

    return pairs;
}

Form.Serializer.prototype._serialize_input = function (elt) {
    switch (elt.type.toLowerCase()) {
      case "hidden":
      case "password":
      case "text":
          return this._simple(elt);

      case "checkbox":  
      case "radio":
          return this._simple_if_checked(elt);

      default:
          return false;
    }
}

Form.Serializer.prototype._simple = function (elt) {
    return [ [ elt.name, elt.value ] ];
}

Form.Serializer.prototype._simple_if_checked = function (elt) {
    if ( ! elt.checked ) {
        return;
    }

    return this._simple(elt);
}

Form.Serializer.prototype._serialize_textarea = function (elt) {
    return this._simple(elt);
}

Form.Serializer.prototype._serialize_select = function (elt) {
    var options = elt.options;

    var serialized = new Array;
    for ( var i = 0; i < options.length; i++ ) {
        if ( options[i].selected ) {
            serialized.push( [ elt.name, options[i].value ] );
        }
    }
        
    return serialized;
}

Form.Serializer.prototype.queryString = function () {
    var pairs = this.pairsArray();

    var queryPairs = new Array;
    for ( var i = 0; i < pairs.length; i++ ) {
        queryPairs.push(   encodeURIComponent( pairs[i][0] )
                         + "=" 
                         + encodeURIComponent( pairs[i][1] ) );
    }

    var sep = arguments.length ? arguments[0] : ";";
    return queryPairs.join(sep);
}

Form.Serializer.prototype.keyValues = function (forceArray) {
    var pairs = this.pairsArray();

    var named = {};
    for ( var i = 0; i < pairs.length; i++ ) {
        var k = pairs[i][0];
        var v = pairs[i][1];

        if ( named[k] ) {
            if ( typeof named[k] == 'object' ) {
                named[k].push(v);
            }
            else {
                named[k] = [ named[k], v ];
            }
        }
        else {
            if (forceArray) {
                named[k] = [v];
            }
            else {
                named[k] = v;
            }
        }
    }

    return named;
}

/*

*/