backbone-validation.backbone.txt

                         
   BACKBONE-VALIDATION   
                         


VERSION ==>                       #0.11.5
Backbone.Validation               #VLD, client-side
require("backbone-validation")    #VLD, server-side (Node)

IN SHORT ==>                      #Use MODEL.validation.VARR RULE (e.g. { required: true }), then VLD.bind(VIEW) in 
                                  #VIEW.initialize(), which will:
                                  #  - if invalid, stop MODEL.save() and (if OBJ.validate true) MODEL.set|fetch()
                                  #  - does DOM manipulation on [in]valid, by def turns <any name="VARR"> into
                                  #    <any name="VARR" class="invalid" data-error="ERROR">
                                  #  - fire events 
                                  #  - can check MODEL.isValid()

MODEL.validation                  #{ VARR: RULE }[()], where RULE can be:
                                  #  - OBJ[_ARR]:
                                  #     - VFUNC VF_VAL, which validates MODEL.VARR
                                  #     - msg "ERROR"[()] (def: VLD.messages.VFUNC), which can contain 
                                  #       (only in VLD.messages.VFUNC):
                                  #        - "{0}": "VARR", after formatting according to CONF.labelFormatter STR:
                                  #           - "none": does nothing
                                  #           - "sentenceCase" (def): aaBB|aa_bb -> "Aa bb"
                                  #           - "label": use MODEL.labels.VARR (if undefined, same as "sentenceCase")
                                  #        - "{NUM}": VF_VAL[NUM] (use 1 for VF_VAL if no ARR)
                                  #  - FUNC: same as { fn FUNC }
                                  #VFUNC VF_VAL can be:
                                  #  - fn "FUNC"|FUNC(VAL, "VARR", ATTR_OBJ)[->"ERROR"]:
                                  #     - this: MODEL
                                  #     - "FUNC", i.e. MODEL.FUNC
                                  #  - required BOOL: null|undefined|""(trimmed)|[]
                                  #  - acceptance BOOL: === true|'true'
                                  #  - min|max NUM: for a NUM
                                  #  - range [ MIN, MAX ]: for a NUM
                                  #  - length|minLength|maxLength NUM: for a STR
                                  #  - rangeLength [ MIN, MAX ]: for a STR
                                  #  - oneOf VAL_ARR: does not work with OBJ_ARR
                                  #  - equalTo "VARR": === MODEL.VARR
                                  #  - pattern REGEXP|STR:
                                  #     - STR is "email", "url", "digits" /^\d+$/ or "numbers"
                                  #       (can have leading -, decimals and commas)
                                  #     - registered as VLD.patterns.STR REGEXP and VLD.messages.STR "ERROR"
                                  #VFUNC are registered as:
                                  #  VLD.validators.VFUNC(VAL, "VARR", VF_VAL, MODEL, ATTR_OBJ)[->"ERROR"]
ERRORS                            #{ "VARR": "ERROR" }

VLD.[un]bind(VIEW[, CONF])        #Sets/overrides MODEL.validate|isValid|preValidate()
                                  #MODEL:
                                  #  - is VIEW|CONF.model
                                  #  - if VIEW|CONF.collection COLL (and no VIEW|CONF.model), do it on each child MODEL, 
                                  #    including new ones (by listening to COLL event)
                                  #     - note than the def. CONF.[in]valid() does not work well with MCOLLVIEW: 
                                  #       each MITEMVIEW will update all others. So prefer using VIEW|CONF.model only.
                                  #Must be called:
                                  #  - bind(): once after MODEL initialized, e.g. VIEW.initialize()
                                  #  - unbind(): in VIEW.destroy()
_.extend(MODL.prototype,VLD.mixin)#Same as VLD.bind() but with MODEL only and no VIEW (for server-side or tests)

MODEL.isValid([VAL])->BOOL        #VAL can be:
                                  #  - "VARR"[_ARR]: checks ATTR_OBJ.VARR
                                  #  - true: checks all, triggering MODEL.validate()
                                  #  - optional: same validity as last MODEL.validate(). Does not fire anything.
                                  #Can restrict to checking MODEL.VARR with CONF.attributes "VARR"_ARR[(VIEW)]|"FUNC":
                                  #  - "FUNC" use VLD.attributeLoaders.FUNC(VIEW)->"VARR"_ARR. Only def "FUNC" is:
                                  #     - "inputNames": VIEW input|select|textarea (with a form ancestor) name HTML attributes
                                  #Fires:
                                  #  - event invalid(MODEL, ERRORS, OBJ), with OBJ.validationError ERRORS
                                  #  - CONF.invalid(VIEW, "VARR", "ERROR", SELECTOR), which by def:
                                  #      VIEW.$('[ATTR~="VARR"]').addClass("invalid").attr("data-error", "ERROR")
                                  #    ATTR being CONF.selector (def: "name")
                                  #  - CONF.valid(VIEW, "VARR", SELECTOR), which by def:
                                  #      VIEW.$('[ATTR~="VARR"]').removeClass("invalid").removeAttr("data-error")
MODEL.preValidate({ VARR: VAL })  #Same but 
MODEL.preValidate("VARR", VAL)    #  - after running an hypothetical MODEL.set(...)
                                  #  - returns ERRORS|undefined (first form) or "ERROR"|"" (second form)
MODEL.validate([ATTR_OBJ[, OBJ2])]#Based on Backbone:
                                  #  - called by MODEL.save() and (if OBJ.validate true) by MODEL.set|fetch()
                                  #  - if invalid (unless CONF|OBJ2.forceUpdate true):
                                  #     - returns ERRORS
                                  #     - stops MODEL.set|save|fetch(), which will return false
                                  #  - pass OBJ2 to MODEL.save|set|fetch() OBJ2
                                  #Also:
                                  #  - can use CONF.attributes like MODEL.isValid()
                                  #  - fires events:
                                  #     - validated(BOOL, MODEL, ERRORS)
                                  #     - validated:[in]valid(MODEL, ERRORS)
                                  #  - fire CONF.[in]valid() like MODEL.isValid()

DEFAULT VALUES & EXTENSIONS ==>   #Must _.extend(OBJ2, OBJ), where OBJ2 is:
                                  #  - VLD.defaultOptions: for CONF
                                  #     - can also do VLD.configure(OBJ)
                                  #  - VLD.callbacks: for CONF.[in]valid
                                  #  - VLD.attributeLoaders|validators|patterns|messages