all files / src/ form.cjsx

86.57% Statements 116/134
65% Branches 26/40
97.3% Functions 36/37
88.24% Lines 90/102
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349                                                                                                                                                11× 11×         11×       29×             29×   28×   28× 28× 28× 28× 28×         11×                   28× 28×         28×       28× 27×       28×     28× 28×   28× 28×         24× 24× 24×         28×             28×       28×       56×                                                                                                                   10× 10×                                                         120×       29×                   14×                             28× 28× 10×           15× 15×                    
 
React = require('react')
ReactDom = require('react-dom')
Datum = require('./datums/datum')
Backbone = require('backbone')
_ = require('underscore')
 
# see ./form.md 
module.exports = class Form extends React.Component
  @displayName: "react-datum.Form"
 
  # TODO : move this to somewhere reusable. most of the datums accept
  # a model or plain js object
  @modelOrObject: ->
    React.PropTypes.oneOfType([
      React.PropTypes.instanceOf(Backbone.Model)
      React.PropTypes.object
    ])
 
 
  @propTypes:
    # can also accept model instance as context var. prop has precendence 
    model: @modelOrObject()
    
    # you can specify any method on the model to call when save is clicked
    # TODO : add ability to also pass in a func?  would need to accept model, attrs, options
    modelSaveMethod: React.PropTypes.string
    
    #  no formMode like zform, but we have to support programatic readonly
    #  see also ClickToEditForm component.   readonly should always take precendence
    readonly: React.PropTypes.bool
    
    # you can style a buttonPossiton: 'top' to float left or right in css.
    buttonPosition: React.PropTypes.oneOf(['top', 'bottom', 'none'])
    
    # specify className of form element
    className: React.PropTypes.string
    
    # on save success this method, if specified, will be called with the standard
    # Backbone success callback arguments (model, response, options)
    # If you don't specify a saveSuccessCallback, a small success message will be rerendered
    # below the form button after successfully saving the form
    saveSuccessCallback: React.PropTypes.func
    
    # on save error this method, if specified, will be called with the standard
    # Backbone error callback arguments (model, response, options)
    # If you don't specify a saveErrorCallback, an error message will be rerendered
    # below the form button after failing to save the form on user request
    saveErrorCallback: React.PropTypes.func
 
 
  @defaultProps:
    readonly: false
    buttonPosition: 'bottom'
    className: 'form'
    modelSaveMethod: 'save'
 
 
  @contextTypes:
    ### can also accept model instance as a prop.  prop has precendence ###
    model: @modelOrObject()
 
  
  @childContextTypes:
    # we pass along the model (make it contextually available) so you can
    # say `<Rz.Form model={this.ourModel}>` and change the model context
    # for all of the datums in this form
    model: @modelOrObject()
    # this is how we tell the datums in our children to render for input
    inputMode: Datum.contextTypes.inputMode
    # datums will register with us through the addDatum method when they mount
    # and remove themselves when they unmount
    form: React.PropTypes.object
 
  # default input mode for all datums that don't have 'readonly' or 'inputMode props
  datumInputMode:  'edit'
 
 
  constructor: (props) ->
    @datums = [] # see addDatum() and removeDatum()
    @state =
      errorMessage: null
      successMessage: null
 
 
    super
 
 
  getChildContext: ->
    return {
      model: @getModel()
      inputMode: @getDatumInputMode()
      form: @
    }
 
  render: ->
    return null unless @getModel()?
 
    @_saveModelStateAtRender()
 
    <div className={"form #{@datumInputMode} #{@props.className}"}>
      {@renderTopButtons()}
      {@renderChildren()}
      {@renderBottomButtons()}
      {@renderMessages()}
    </div>
 
 
  componentDidMount: ->
    @node = ReactDom.findDOMNode(this)
 
 
  ###
    Gives the first editable datum focus
  ###
  focus: ->
    firstEditable = _.find @datums, (d) -> d.isEditable()
    firstEditable?.focus()
 
 
  renderChildren: ->
    <div className="form-content">
      {@props.children}
    </div>
 
 
  renderTopButtons: ->
    return unless @props.buttonPosition == 'top'
    @renderButtonContainer(addClass: "top")
 
 
  renderBottomButtons: ->
    return unless @props.buttonPosition == 'bottom'
    @renderButtonContainer(addClass: "bottom")
 
 
  renderButtonContainer: (options={}) ->
    options = _.defaults options,
      addClass: null
 
    className = "form-buttons"
    EclassName += " #{options.addClass}" if options.addClass?
 
    <div className={className}>
      {@renderButtons(options)}
    </div>
 
 
  renderButtons: (options) ->
    return [
      <button key="save" ref="saveButton" className='btn btn-success' onClick={@onSaveClick}>Save</button>
      <button key="cancel" ref="cancelButton" className='btn' onClick={@onCancelClick}>Cancel</button>
    ]
 
 
  renderMessages: ->
    return [
      @renderSuccessMessage()
      @renderErrorMessage()
    ]
 
 
  renderErrorMessage: ->
    @renderMessage @state.errorMessage, 'error'
 
 
  renderSuccessMessage: ->
    @renderMessage @state.successMessage, 'success'
 
 
  renderMessage: (message, className) ->
    return null unless message?
    fullClassName = "datum-form-message-#{className} #{className}"
    <div key={className} className={fullClassName}>{message}</div>
 
 
  ###
    Save the changes from datums on the form to the Backbone model. 
    
    Calls model.save after first attempting to validate() the model.  Handles 
    inconsistencies in model.validate() between versions 0.9.2 - 1.2.2 of Backbone.
    
    The user clicking on the save button belonging to the Form will call this Method
    
    The options argument is passed on to Backbone model.save()
  ###
  save: (options={})->
    options = _.defaults options,
      validateDatums: true      # TODO : these should also be @props
      validateModel: true
      
    @setState errorMessage: null, successMessage: null
    model = @getModel()
    
    if options.validateDatums and not @validateDatums(options)
      @onSaveError model, "Correct errors and try again."
      return
 
    Iif options.validateModel and not @validateModel(options)
      @onSaveError model, model.validationError
      return
 
    # saving the model triggers events that will rerender us
    return @saveModel(options)
 
 
  ###
    Validate the datums on the form. 
    
    returns false if any are currently invalid
  ###
  validateDatums: (options={}) ->
    if @getInvalidDatums().length > 0
      @setState errorMessage: "Please correct errors and try again."
      return false
      
    return true
    
  
  ###
    Calls Backbone model.validate and handles inconsistencies in model.validate() 
    between versions 0.9.2 - 1.2.2 of Backbone.
  ###    
  validateModel: (options={}) ->
    model = @getModel()
    Ireturn unless model?
 
    try
      # Note that backbone 0.9.2 would call error callback on save if the model was
      # invalid.  Somewhere around 1.1, that is no more.  Now the model returns false
      # from save and you have to check a new model instance attribute called validationError
      Iunless model.isValid()
        if model.validationError?
          return false
    catch 
      null
      # Backbone 0.9.2 isValid will exception if the model subject doesn't have a
      #   validate() method
      
    # if model was not valid but there is no .validationError, then we are probably
    # dealing with an earlier version of Backbone. Let it fall out through the
    # error handler on save    
    return true;
    
    
  
  # TODO : move this to somewhere utilitarian
  preceedOriginalCallback: (obj, attr, newCallback) ->
    originalCallback = obj[attr]
    obj[attr] = () ->
      newCallback.apply(this, arguments)
      originalCallback?.apply(this, argumentsk)
 
  ###  
    calls Backbone model.save and calls success and error handlers. 
    
    You should probably call Form.save() above instead.  It will also validate the model 
    and datums.  
  ### 
  saveModel: (options={}) ->
    model = @getModel() 
    Ireturn unless model?
    
    @preceedOriginalCallback(options, 'success', @onSaveSuccess)
    @preceedOriginalCallback(options, 'error', @onSaveError)
    saved = model[@props.modelSaveMethod]({}, options)
      
 
  onSaveClick: (evt) =>
    @save()
 
 
  onSaveSuccess: (model, response, options={}) =>
    @_saveModelState()
    Iif @props.saveSuccessCallback? && _.isFunction @props.saveSuccessCallback
      @props.saveSuccessCallback(model, response, options)
    else
      @setState successMessage: "Successfully saved!", successAt: Date.now()
 
 
  onSaveError: (model, response, options={}) =>
    Iif @props.saveErrorCallback? && _.isFunction @props.saveErrorCallback
      @props.saveErrorCallback(model, response, options)
    else
      response = Eif !response? || _.isString(response) then response else JSON.stringify(response)
      @setState errorMessage: "Unable to save. " + response || "Reason unknown."
 
 
  onCancelClick: (evt) =>
    @setState errorMessage: null, successMessage: null
    @_restoreModelState()
    @_resetDatums()
 
 
  getModel: ->
    @props.model || @context.model
 
 
  getDatumInputMode: ->
    if @props.readonly then 'readonly' else @datumInputMode
 
 
  getInvalidDatums: ->
    _.filter @datums, (d) -> !d.validate()
 
 
  ###
    This method is called by the datum children when they mount
  ###
  addDatum: (datumComponent) ->
    E@datums.push datumComponent unless datumComponent in @datums
 
 
  ###
    This method is called by the datum children when they unmount
  ###
  removeDatum: (datumComponent) ->
    index = @datums.indexOf(datumComponent)
    if index < 0
      console.error "form.removeDatum called for datumComponent (#{datumComponent.constructor.displayName}) that we don't know about?"
      return
    @datums = @datums.slice(0, index).concat(@datums.slice(index + 1, @datums.length))
 
 
  _saveModelStateAtRender: ->
    model = @getModel()
    return if model == @_savedModel
    @_saveModelState()
 
 
  # save the attributes at this point in time for later restoreModelState when called
  # on cancel
  _saveModelState: ->
    @_savedModel = @getModel()
    @_savedAttrs = @_savedModel.toJSON()
 
 
  _restoreModelState: ->
    model = @getModel()
    # don't ever get confused and save one model's attributes on another
    Ireturn if model != @_savedModel
    model.set(@_savedAttrs)
    
    
 
 
  _resetDatums: ->
    datum.cancelEdit() for datum in @datums