diff --git a/ciform/trunk/src/ciform.js b/ciform/trunk/src/ciform.js index d9750f8..e74b364 100644 --- a/ciform/trunk/src/ciform.js +++ b/ciform/trunk/src/ciform.js @@ -19,19 +19,19 @@

-

Most functions work with {@link ciform.Options} : it's just an object with limited properties - (also named 'fields' here), and a few utility functions.
- In general, a function uses somes of the options it was provided, - and then passes them on to the next layer / function.
- When default values are set or when there is a special usage of an option, - it is specified in the function's documentation.
+

Most functions work with {@link ciform.Options}. + Options are just an object with limited properties (also named 'fields' here), and a few utility functions.
+ Usually, a first set of options is given to the constructor and acts as the base context of the object. + Another set of options can be passed to its methods, as a one-time context.
+ In general, a function uses only some of the options it was provided, and then passes them on to the next layer / function.
+ When default values are set or when there is a special usage of an option, it is specified in the function's documentation.
Boolean properties default to false, except if stated otherwise.

- @requires base64.js (http://www.hanewin.net/encrypt/rsa/base64.js) - @requires hex.js (http://www.hanewin.net/encrypt/rsa/hex.js) - @requires sha1.js (http://pajhome.org.uk/crypt/md5/sha1.js) - @requires rsa.js (http://www.hanewin.net/encrypt/rsa/rsa.js) + @requires http://www.hanewin.net/encrypt/rsa/base64.js + @requires http://www.hanewin.net/encrypt/rsa/hex.js + @requires http://pajhome.org.uk/crypt/md5/sha1.js + @requires http://www.hanewin.net/encrypt/rsa/rsa.js @author cbonar at users dot sf dot net */ @@ -89,47 +89,44 @@ ciform.protocol = function() so they refer to this class to define the fields they use.
It should be seen as a flat view of most options used by the classes in this library.

+ @param options {Object} properties to add to this object @constructor */ -ciform.Options = function() +ciform.Options = function( options ) { - // adds fields specific to this class - for ( var a=0 ; a + Fields will be searched in this form if not fully specified. + @type HTMLFormElement + */ + this.form = options['form']; - /** - The presence of this field limits encryption operations to the form element it represents - (except of course if it's overridden with further options).
- Fields will be searched in this form if not fully specified. - @type HTMLFormElement - */ - this.form = arguments[a]['form']; + /** + This array contains ciform.Options.Field objects : it defines which form control may be encrypted. + NOTE : this field is replaced, not merged with the current one (if any) + @type Array + */ + this.fields = options['fields']; - /** - This array contains ciform.Options.Field objects : it defines which form control may be encrypted. - NOTE : this field is replaced, not merged with the current one (if any) - @type Array - */ - this.fields = arguments[a]['fields']; + /** If true, Ciform will show an indication of the progress of the encryption (because it can take some time) */ + this.showWait = options['showWait']; - /** If true, Ciform will show an indication of the progress of the encryption (because it can take some time) */ - this.showWait = arguments[a]['showWait']; + /** + A custom error handler that will be called with the error as an argument + @type ciform + */ + this.onerror = options['onerror']; - /** - A custom error handler that will be called with the error as an argument - @type ciform - */ - this.onerror = arguments[a]['onerror']; + /** The {@link ciform.encoders.Encoder encoder} to use */ + this.encoder = options['encoder']; - /** The {@link ciform.encoders.Encoder encoder} to use */ - this.encoder = arguments[a]['encoder']; - - /** If set, this array lists the only tag types allowed to be encrypted. + /** + If set, this array lists the only tag types allowed to be encrypted. It can be either a tag name or the value of the 'type' attribute of an <input> tag. - @type Array */ - this.allowedTags = arguments[a]['allowedTags']; - } + @type Array + */ + this.allowedTags = options['allowedTags']; }; ciform.Options.prototype = new Object(); @@ -152,14 +149,29 @@ ciform.Options.prototype._isCiformInput = function( object ) /** This is the preferred way to access the form element carried by this object. + Tries :
    +
  1. $(this[key]) +
  2. $(key) +
  3. $(this.form) +
+ @param key (optional) the key of the form in this object @return the form element or null if the argument doesn't match a form @type HTMLFormElement */ ciform.Options.prototype.getForm = function( key ) { - var k = $defined(key) ? key : 'form'; - var form = $(this[k]); + var form = null; + + if ( $defined(key) ) + { + form = $(this[key]) ? $(this[key]) : $(key); + } + else if ( $defined(this.form) ) + { + form = $(this.form); + } + return form instanceof HTMLFormElement ? form : null; } @@ -179,7 +191,7 @@ ciform.Options.prototype.getForm = function( key ) */ ciform.Options.prototype.getField = function( key, index ) { - var fieldName = $defined(this.fields) && $defined(index) ? this.fields[key][index] : this[key]; + var fieldName = $defined(this.fields) && this.fields[key] && $defined(index) ? this.fields[key][index] : this[key]; var form = $(this.form); if ( form && form[fieldName] ) @@ -195,40 +207,6 @@ ciform.Options.prototype.getField = function( key, index ) -/** - @class - This class gathers all options that can be applied to a field. - - @constructor -*/ -ciform.Options.Field = function( options ) -{ - // calls the constructor of the superclass - ciform.encoders.Options.apply(this,arguments); - - // adds fields specific to this class - for ( var a=0 ; a -
  • If == 1, this field will be SHA1-encoded before encryption. -
  • If == 2, meta-data will be prepended to the result. - - @type number - */ - this.sha1 = arguments[a]['sha1']; - } -}; -ciform.Options.Field.prototype = new ciform.encoders.Options(); - - - // // NAMESPACE : ciform.encoders.* // @@ -270,6 +248,8 @@ ciform.encoders.Encoder.prototype.encode = function( message ) /** @class This class presents options specific to encoders. See each encoders' definition to know which subset of these options they support. + + @param options {Object} properties to add to this object @constructor */ ciform.encoders.Options = function( options ) @@ -277,34 +257,63 @@ ciform.encoders.Options = function( options ) // calls the constructor of the superclass ciform.Options.apply(this,arguments); - for ( var a=0 ; a - E.g. "1234:my message" : "1234:" is the salt - @type boolean - */ - this.salt = options['salt']; + /** + If true, a random string will be prepended to the text before encryption, + in order to make the ciphertext different every time, even with the same original text.
    + E.g. "1234:my message" : "1234:" is the salt + @type boolean + */ + this.salt = options['salt']; - /** - If true, does not check that the padding scheme is correct (does not apply if salt is added). - @type boolean - */ - this.noPadding = options['noPadding']; - } + /** + If true, does not check that the padding scheme is correct (does not apply if salt is added). + @type boolean + */ + this.noPadding = options['noPadding']; } -ciform.encoders.Options.prototype = new ciform.Options(); +ciform.encoders.Options.prototype = new ciform.Options({}); + + + +/** + @class This class gathers all options that can be applied to a field. + + @param options {Object} properties to add to this object + @constructor +*/ +ciform.Options.Field = function( options ) +{ + // calls the constructor of the superclass + ciform.encoders.Options.apply(this,arguments); + + /** Input field : where to read the text to encode */ + this.name = options['in']; + + /** Output field : the name / id of the field where to write the encoded text */ + this.out = options['out']; + + /** +
      +
    • If == 1, this field will be SHA1-encoded before encryption. +
    • If == 2, meta-data will be prepended to the result. +
    + @type number + */ + this.sha1 = options['sha1']; +}; +ciform.Options.Field.prototype = new ciform.encoders.Options({}); @@ -602,21 +611,26 @@ ciform.encoders.CiformEncoder.prototype.encode = function( message )
  • {@link ciform.Options#encoder encoder} = a {@link ciform.encoders.RSAEncoder}
  • {@link ciform.Options#showWait showWait} = false - @throws Error if the arguments are not correct (a required field is missing, ...) + @throws TypeError if the arguments are not correct (a required field is missing, ...) */ ciform.Ciform = function( options ) { + console.debug("new ciform.Ciform(",options,")"); + // copies the options into this object for ( var a=0 ; a -

    It can be called in three ways :

      -
    • 2 arguments : target is the first argument, options the second -
    • 1 argument : can be either the target or options (determined from its type) -
    • 0 argument : target and options will be guessed from the current object -
    -

    - - @param arg1 (optional) Either a form, a form field or an list of fields to encrypt / or options - @param arg2 (optional) Options to pass to the encoding method + @param target + Either a form, a form field or an array of fields to encrypt + @param arg2 (optional) + Options to pass to the encoding method @see ciform.Ciform#encryptForm @see ciform.Ciform#encryptField @see ciform.Ciform#encryptFields - @return The returned valued depends on the target (see the definition of the corresponding function) + @see ciform.Ciform#encryptText + @return The returned value depends on the target (see the definition of the corresponding function) @throws SyntaxError if a target could not be determined */ -ciform.Ciform.prototype.encrypt = function( arg1, arg2 ) +ciform.Ciform.prototype.encrypt = function( target, options ) { - var targetForm = false; - var targetField = false; - var targetFields = false; + console.debug(this,".encrypt(",target,options,")"); - var options = arg2 ? arg2 : {}; - - // 1. determines if the first argument is the target - if ( arg1 ) - { - targetForm = this._getForm($(arg1)); - targetField = this._getField($(arg1)); - targetFields = this._getFields(arg1); + if ( !$defined(target) && !$defined(options) ) { + console.debug("No target : trying with an internal form"); + return this.encryptForm( new ciform.Options(this).getForm(), this ); } - - // 2. target couldn't be determined from the first argument : try with the current context - if ( !targetForm && !targetField && !targetFields ) - { - options = arg1 ? arg1 : {}; - targetFields = $defined(this['fields']) && this['fields'] instanceof Array ? this['fields'] : false; - targetField = targetFields && targetFields.length == 1 ? targetFields[0] : false; - targetForm = $defined(this['form']) && this['form'] instanceof HTMLFormElement ? this['form'] : false; + if ( target instanceof HTMLFormElement ) { + console.debug("Target is a form"); + return this.encryptForm(target,options); } - - // 3. executes the correct encryption method - if ( targetForm ) { - return this.encryptForm($(targetForm),options); + else if ( ciform.Options.prototype._isCiformInput(target) ) { + console.debug("Target is an input field"); + return this.encryptField(target,options); } - else if ( targetField ) { - return this.encryptField($(targetField),options); + else if ( target instanceof Array ) { + console.debug("Target is a field array"); + return this.encryptFields(target,options); } - else if ( targetFields ) { - return this.encryptFields(targetFields,options); + else if ( target instanceof String ) { + console.debug("Target is a text"); + return this.encryptText(target,options); } throw new SyntaxError("A target couldn't be determined for encryption from the current context and arguments !"); }; + +// +// GLOBAL FUNCTIONS +// + + + +function $ciform( target, options ) +{ + console.debug("$ciform(",target,options,")"); + + if ( target ) + { + var $target = $(target); + var targetOptions = {}; + + if ( $target instanceof HTMLFormElement ) { + console.debug("Target is a form"); + targetOptions = {'form':$target}; + } + else if ( ciform.Options.prototype._isCiformInput($target) ) { + console.debug("Target is an input field"); + targetOptions = {'fields':[$target]}; + } + else if ( $target instanceof Array ) { + console.debug("Target is a field array"); + targetOptions = {'fields':$target}; + } + + return new ciform.Ciform(merge(options,targetOptions)); + } + + // return null ? +} + + + +