luca 0.9.8 → 0.9.9

data/app/assets/javascripts/luca/components/fields/button_field.coffee

@@ -1,3 +1,9 @@
+# The `Luca.fields.ButtonField` provides an easy way to generate
+# a button element, with an optional icon.  Supports all of the
+# available bootstrap icons, and color states.  
+#
+# The `Luca.fields.ButtonField` component will typically be used as 
+# part of a `Luca.components.FormView` or a `Luca.components.PanelToolbar`.
 buttonField = Luca.register         "Luca.fields.ButtonField"
 
 buttonField.extends                 "Luca.core.Field"
@@ -5,27 +11,62 @@ buttonField.extends                 "Luca.core.Field"
 buttonField.triggers                "button:click"
 
 buttonField.publicConfiguration
-  readOnly:     true
-  input_value:  undefined 
-  input_type:   "button" 
-  icon_class:   undefined
-  input_name:   undefined
-  white:        undefined
+  # Which size should this button be? Valid options are:
+  # - none ( default )
+  # - large
+  # - mini
+  # - small
+  buttonSize: undefined
+
+  # Which bootstrap color class should we apply to this button?
+  # Valid options are any css button class, or the defaults which
+  # ship with bootstrap: 
+  #
+  # - btn-primary
+  # - btn-info
+  # - btn-success
+  # - btn-warning
+  # - btn-danger
+  # - btn-inverse
+  # - btn-link
+  class: undefined 
+
+  # specifies the bootstrap icon class you want to use for this button 
+  # you can use 'icon-ok-sign' or just 'ok-sign'
+  icon_class: undefined
+
+  # specifies the text value of the button
+  label: undefined    
+
+  # an alias for label, or input_value.  controls which text 
+  # displays inside of the button
+  text: undefined
+
+  # should we render the white icon? 
+  white: false
+
+buttonField.privateConfiguration
+  readOnly:       true
+  input_value:    undefined 
+  input_type:     "button" 
+  icon_class:     undefined
+  input_name:     undefined
+  buttonClasses:  "" 
 
 buttonField.privateConfiguration
   isButton: true
+  autoBindEventHandlers: true
   template: "fields/button_field"
   events:
-    "click input" : "click_handler"
+    "click input" : "clickHandler"
 
-buttonField.privateInterface
-  click_handler: (e)->
+buttonField.privateMethods
+  clickHandler: (e)->
     me = my = $( e.currentTarget )
     @trigger "button:click"
 
   initialize: (@options={})->
-    _.extend @options
-    _.bindAll @, "click_handler"
+    _.extend @, @options
 
     Luca.core.Field::initialize.apply @, arguments
 
@@ -35,10 +76,16 @@ buttonField.privateInterface
     @input_id ||= _.uniqueId('button')
     @input_name ||= @name ||= @input_id
     @input_value ||= @label ||= @text
-    @input_class ||= @class
+    @input_class ||= @class ||= @buttonClasses
+
+    if @buttonSize?.length > 0
+      @input_class += " #{ buttonSize.replace(/btn-/,'') }"
+
     @icon_class ||= ""
     @icon_class = "icon-#{ @icon_class }" if @icon_class.length and !@icon_class.match(/^icon-/)
     @icon_class += " icon-white" if @white
 
-  setValue: ()-> true
+  setValue: ()-> 
+    true
 
+buttonField.register()

data/app/assets/javascripts/luca/components/fields/checkbox_array.coffee

@@ -1,11 +1,10 @@
-make = Luca.View::make
-
+# The `Luca.fields.CheckboxArray` renders an array of values 
+# into checkbox controls.  This is for fields which can have
+# a list of values associated with them.
 checkboxArray = Luca.register     "Luca.fields.CheckboxArray"
 checkboxArray.extends             "Luca.core.Field"
 
-checkboxArray.defines
-  version: 2
-
+checkboxArray.privateConfiguration
   template: "fields/checkbox_array"
 
   className: "luca-ui-checkbox-array"
@@ -15,6 +14,7 @@ checkboxArray.defines
 
   selectedItems: []
 
+checkboxArray.privateMethods
   initialize: (@options={})->
     _.extend @, @options
     _.extend @, Luca.concerns.Deferrable
@@ -65,8 +65,8 @@ checkboxArray.defines
       label = model.get(@displayField)
       input_id = _.uniqueId("#{ @cid }_checkbox")
 
-      inputElement = make("input",type:"checkbox",class:"array-checkbox",name:@input_name,value:value,id: input_id)
-      element = make("label", {for:input_id}, inputElement)
+      inputElement = @make("input",type:"checkbox",class:"array-checkbox",name:@input_name,value:value,id: input_id)
+      element = @make("label", {for:input_id}, inputElement)
 
       $( element ).append(" #{ label }")
       @controls().append( element )
@@ -80,6 +80,9 @@ checkboxArray.defines
   allFields: ()->
     @controls().find("input[type='checkbox']")
 
+checkboxArray.publicMethods
+  # Check the selected items.  Expects an array of values 
+  # for boxes you would like to see checked.
   checkSelected: (items)->
     @selectedItems = items if items?
 
@@ -91,6 +94,8 @@ checkboxArray.defines
 
     @selectedItems
 
+  # Gets an array of values for the checkboxes in this array
+  # which are checked.
   getValue: ()->
     @$(field).val() for field in @allFields() when @$(field).prop('checked')
 

data/app/assets/javascripts/luca/components/fields/select_field.coffee

@@ -2,40 +2,86 @@ selectField = Luca.register   "Luca.fields.SelectField"
 
 selectField.extends           "Luca.core.Field"
 
-selectField.triggers          "after:select"
+selectField.triggers          "after:select",
+                              "on:change"
 
-selectField.defines
-  events:
-    "change select" : "change_handler"
-
-  template: "fields/select_field"
+selectField.publicConfiguration
+  # Enables multi-select UI element.
+  allowMultiple: false
 
+  # Includes a blank option in addition to all of the items
+  # in the underlying collection.  Defaults to `true` 
   includeBlank: true
 
+  # determines which value is sent when 
+  # the blank option is selected?
   blankValue: ''
 
+  # Determines the text displayed when 
+  # the blank option is selected 
   blankText: 'Select One'
 
+  # Specifying a value for maxDisplayLength will truncate
+  # values displayed in the select field when they reach 
+  # past a certain point, using the _.str truncate method.
+  # Leave at 0 if you want to keep this feature disabled.
+  maxDisplayLength: 0 
+
+  # When the underlying collection is reset and we re-render
+  # the options elements, should we keep the value that was set
+  # on this field prior to that? Defaults to `true` unless otherwise
+  # specified.
+  retainValue: undefined
+
+  # Determines which value is rendered in the label element that gets
+  # rendered along with this control group. 
+  label: undefined
+
+selectField.privateConfiguration
+  template: "fields/select_field"
+  events:
+    "change select" : "change_handler"
+
+selectField.publicMethods
+  # sets the value of this select field.
+  setValue: (value)->
+    @currentValue = value
+    Luca.core.Field::setValue.apply @, arguments
+
+  # returns the value of the select field.  runs
+  # the value through the getParsedValue method which
+  # enforces the valueType type conversion.
+  getValue: ()->
+    raw = @getInputElement()?.val()
+
+    if @allowMultiple
+      _.map raw, (value)=>
+        @getParsedValue(value)
+    else
+      @getParsedValue(raw)
+
+selectField.privateMethods
   initialize: (@options={})->
     _.extend @, @options
     _.extend @, Luca.concerns.Deferrable
-    _.bindAll @, "change_handler", "populateOptions", "beforeFetch"
+    _.bindAll @, "change_handler"
 
     if _.isArray(@collection)
       @collection = data: @collection
-      
+
     Luca.core.Field::initialize.apply @, arguments
 
     @input_id ||= _.uniqueId('field')
     @input_name ||= @name
     @valueType ||= Luca.config.idAttributeType if @valueField is "id"
     @label ||= @name
-    @retainValue = true if _.isUndefined @retainValue
+    @retainValue = true unless @retainValue? 
 
   afterInitialize: ()->
     if @collection?.data
       @valueField ||= "id"
       @displayField ||= "name"
+      @sortOptionsBy ||= @displayField
       @parseData()
 
     try
@@ -43,8 +89,8 @@ selectField.defines
     catch e
       console.log "Error Configuring Collection", @, e.message
 
-    @collection?.bind "before:fetch", @beforeFetch
-    @collection?.bind "reset", @populateOptions
+    @collection?.bind "before:fetch", @beforeFetch, @
+    @collection?.bind "reset", @populateOptions, @
 
   # if the select field is configured with a data property
   # then parse that data into the proper format.  either
@@ -69,10 +115,6 @@ selectField.defines
     else
       @collection?.trigger("reset")
 
-  setValue: (value)->
-    @currentValue = value
-    Luca.core.Field::setValue.apply @, arguments
-
   beforeFetch: ()->
     @resetOptions()
 
@@ -82,19 +124,36 @@ selectField.defines
   resetOptions: ()->
     @getInputElement().html('')
 
-    if @includeBlank
+    if @allowMultiple
+      @getInputElement().attr(multiple: true)
+    else if @includeBlank
       @getInputElement().append("<option value='#{ @blankValue }'>#{ @blankText }</option>")
 
   populateOptions: ()->
     @resetOptions()
 
-    if @collection?.each?
-      @collection.each (model) =>
-        value = model.get( @valueField )
-        display = model.get( @displayField )
-        selected = "selected" if @selected and value is @selected
-        option = "<option #{ selected } value='#{ value }'>#{ display }</option>"
+    if @collection?.length > 0
+      if @sortOptionsBy?
+        models = @collection.sortBy (model)=>
+          if model.read?
+            model.read( @sortOptionsBy )
+          else
+            model.get( @sortOptionsBy )
+      else
+        models = @collection.models
+
+      for model in models
+        v = model.read?( @valueField ) || model.get(@valueField)
+        d = model.read?( @displayField ) || model.get(@displayField)
+
+        if @maxDisplayLength and @maxDisplayLength > 0
+          d = _.str.truncate(d, @maxDisplayLength)
+
+        selected = "selected" if @selected and v is @selected
+        option = "<option #{ selected } value='#{ v }'>#{ d }</option>"
         @getInputElement().append( option )
 
     @trigger "after:populate:options", @
-    @setValue( @currentValue )
+    @setValue( @currentValue )
+
+selectField.register()

data/app/assets/javascripts/luca/components/fields/text_area_field.coffee

@@ -1,17 +1,19 @@
-_.def('Luca.fields.TextAreaField').extends('Luca.core.Field').with
+textArea = Luca.register          "Luca.fields.TextAreaField"
+textArea.extends                  "Luca.core.Field"
+textArea.defines
+  autoBindEventHandlers: true
 
   events:
-    "keydown input" : "keydown_handler"
-    "blur input" : "blur_handler"
-    "focus input" : "focus_handler"
+    "blur textarea" : "blur_handler"
+    "focus textarea" : "focus_handler"
 
   template: 'fields/text_area_field'
 
   height: "200px"
   width: "90%"
+  keyEventThrottle: 300
 
   initialize: (@options={})->
-    _.bindAll @, "keydown_handler"
 
     @input_id ||= _.uniqueId('field')
     @input_name ||= @name
@@ -23,6 +25,13 @@ _.def('Luca.fields.TextAreaField').extends('Luca.core.Field').with
 
     Luca.core.Field::initialize.apply @, arguments
 
+    if @enableKeyEvents is true
+      @keyup_handler = _.debounce(@keyup_handler, @keyEventThrottle || 10)
+
+      console.log "Registering Key Events"
+      @registerEvent("keyup textarea","keyup_handler")     
+      @registerEvent("keydown textarea","keyup_handler")     
+
   setValue: (value)->
     $( @field() ).val(value)
 
@@ -30,13 +39,19 @@ _.def('Luca.fields.TextAreaField').extends('Luca.core.Field').with
     $( @field() ).val()
 
   field: ()->
-    @input = $("textarea##{ @input_id }", @el)
+    @input = @$("textarea")
 
-  keydown_handler: (e)->
-    me = my = $( e.currentTarget )
+  keyup_handler: (e)->
+    # TODO: Should ignore certain keyup events
+    # which would not indicate a change
+    @trigger "on:change", @, e
+    @trigger "on:keyup", @, e
 
   blur_handler: (e)->
-    me = my = $( e.currentTarget )
+    @trigger "on:blur", @, e
 
   focus_handler: (e)->
-    me = my = $( e.currentTarget )
+    @trigger "on:focus", @, e
+
+  change_handler: (e)-> 
+    @trigger "on:change", @, e

data/app/assets/javascripts/luca/components/fields/text_field.coffee

@@ -2,7 +2,7 @@ textField = Luca.register     'Luca.fields.TextField'
 textField.extends             'Luca.core.Field'
 
 textField.defines
-  events:
+  _inheritEvents:
     "blur input" : "blur_handler"
     "focus input" : "focus_handler"
     "change input" : "change_handler"
@@ -17,6 +17,9 @@ textField.defines
 
   initialize: (@options={})->
     if @enableKeyEvents
+      if @keyEventThrottle
+        @keyup_handler = _.debounce(@keyup_handler, @keyEventThrottle)
+        
       @registerEvent("keyup input","keyup_handler")     
 
     @input_id ||= _.uniqueId('field')
@@ -26,11 +29,11 @@ textField.defines
     @input_value ||= @value || "" 
     
     if @prepend
-      @$el.addClass('input-prepend')
+      @$el.addClass 'input-prepend'
       @addOn = @prepend
 
     if @append
-      @$el.addClass('input-append')
+      @$el.addClass 'input-append'
       @addOn = @append
 
     @placeHolder ||= ""
@@ -38,6 +41,9 @@ textField.defines
     Luca.core.Field::initialize.apply @, arguments
 
   keyup_handler: (e)->
+    # TODO: Should ignore certain keyup events
+    # which would not indicate a change
+    @trigger "on:change", @, e
     @trigger "on:keyup", @, e
 
   blur_handler: (e)->

data/app/assets/javascripts/luca/components/form_view.coffee

@@ -3,12 +3,13 @@
 #
 # The FormView component integrates well with Luca.Models and can control
 # the attributes on that model, respond to validations, and submit changes
-# to an API. 
+# to an API.
 formView = Luca.register        "Luca.components.FormView"
 
 formView.extends                "Luca.Container"
 
-formView.mixesIn                "LoadMaskable"
+formView.mixesIn                "LoadMaskable",
+                                "FormModelBindings"
 
 formView.triggers               "before:submit",
                                 "before:reset",
@@ -22,11 +23,20 @@ formView.triggers               "before:submit",
                                 "after:load:existing",
                                 "after:submit:success",
                                 "after:submit:fatal_error",
-                                "after:submit:error"
+                                "after:submit:error",
+                                "state:change:dirty"
 
 
 
 formView.publicConfiguration
+  # track dirty state will bind to change events
+  # on all of the underlying fields, and set a
+  # flag whenever one of them changes
+  trackDirtyState: false
+
+  # don't setup two way binding to the model
+  trackModelChanges: false
+
   # should the label display above, or to the
   # side of the fields
   labelAlign: undefined
@@ -62,7 +72,7 @@ formView.publicConfiguration
 
   # Applies the twitter bootstrap well class to this form.
   # @$el.addClass('well') if @well
-  well: false 
+  well: false
 
   # Applies the twitter bootstrap form-search class to this form.
   # @$el.addClass('form-search') if @searchForm
@@ -82,15 +92,24 @@ formView.publicConfiguration
 
 formView.privateConfiguration
   tagName: 'form'
-  stateful: true
-  events:
+
+  # These events will get registered on the component
+  # but still leave the @events property open to extend
+  # for any component which inherits from us.
+  _inheritEvents:
     "click .submit-button" : "submitHandler"
     "click .reset-button" : "resetHandler"
 
   bodyClassName: "form-view-body"
 
+  stateful:
+    dirty: false
+    currentModel: undefined
+
 formView.privateMethods
   initialize: (@options={})->
+    form = @
+
     @loadMask = Luca.config.enableBoostrap unless @loadMask?
 
     Luca.Container::initialize.apply @, arguments
@@ -99,12 +118,26 @@ formView.privateMethods
 
     _.bindAll @, "submitHandler", "resetHandler", "renderToolbars"
 
+    # have our events be internal to the view, and not
+    # part of the normal @events chain, so they can be inherited
+    for eventId, handler of @_inheritEvents
+      @registerEvent(eventId, handler)
+
+    if @trackDirtyState is true
+      @on "after:components", ()->
+        for field in @getFields()
+          field.on "on:change", @onFieldChange, form
+      , form
+
     @setupHooks( @hooks )
 
     @applyStyleClasses()
 
     Luca.components.FormView.setupToolbar.call(@)
 
+  onFieldChange: (field, e)->
+    @trigger "field:change", field, e
+    @state.set('dirty', true)
 
   getDefaultToolbar: ()->
     config = @toolbarConfig || @defaultToolbar
@@ -127,13 +160,20 @@ formView.privateMethods
 
   resetHandler: (e)->
     me = my = $( e?.target )
-    @trigger "before:reset", @
+    if @beforeReset?
+      result = @beforeReset()
+      return if result is false
+
     @reset()
     @trigger "after:reset", @
 
   submitHandler: (e)->
-    me = my = $( e?.target )
-    @trigger "before:submit", @
+    if @beforeSubmit?
+      result = @beforeSubmit()
+      return if result is false
+    else
+      @trigger "before:submit", @
+
     @trigger "enable:loadmask", @ if @loadMask is true
     @submit() if @hasModel()
 
@@ -142,7 +182,7 @@ formView.privateMethods
 
     form = @
     @eachField (field)->
-      field.getForm = ()=> form 
+      field.getForm = ()=> form
       field.getModel = ()=> form.currentModel()
 
   eachField: (iterator)->
@@ -165,30 +205,33 @@ formView.privateMethods
 
     fields
 
-  loadModel: (@current_model)->
+  loadModel: (model)->
     form = @
     fields = @getFields()
 
-    @trigger "before:load", @, @current_model
+    @state.set('dirty', false)
+
+    @trigger "before:load", @, model
 
-    if @current_model
-      @current_model.beforeFormLoad?.apply(@current_model, @)
+    if model
+      model.beforeFormLoad?.apply(model, @)
+      event = "before:load:#{ (if model.isNew() then "new" else "existing")}"
+      @trigger event, @, model
 
-      event = "before:load:#{ (if @current_model.isNew() then "new" else "existing")}"
-      @trigger event, @, @current_model
+    @state.set('currentModel', model)
 
-    @setValues(@current_model)
+    @setValues(model || {}, silent: true)
 
-    @trigger "after:load", @, @current_model
+    @trigger "after:load", @, model
 
-    if @current_model
-      @trigger "after:load:#{ (if @current_model.isNew() then "new" else "existing")}", @, @current_model
+    if model
+      @trigger "after:load:#{ (if model.isNew() then "new" else "existing")}", @, model
 
   reset: ()->
-    @loadModel( @current_model ) if @current_model?
+    @loadModel( @state.get('currentModel') )
 
   clear: ()->
-    @current_model = if @defaultModel? then @defaultModel() else undefined
+    @state.set('currentModel', @defaultModel?() )
 
     _( @getFields() ).each (field)=>
       try
@@ -196,6 +239,9 @@ formView.privateMethods
       catch e
         console.log "Error Clearing", @, field
 
+  isDirty: ()->
+    !!@state.get('dirty')
+
   # set the values on the form
   # without syncing
   setValues: (source, options={})->
@@ -205,16 +251,15 @@ formView.privateMethods
     _( fields ).each (field) =>
       field_name = field.input_name || field.name
 
-      if value = source[field_name]
-        if _.isFunction(value)
-          value = value.apply(@)
+      if source?[field_name]
+        value = Luca.util.read( source[field_name] )
 
       if !value and Luca.isBackboneModel(source)
         value = source.get(field_name)
 
       field?.setValue( value ) unless field.readOnly is true
 
-    @syncFormWithModel() unless options.silent? is true
+    @applyFormValuesToModel() unless options.silent? is true
 
   # Public: returns a hash of values for the form fields in this view.
   #
@@ -261,6 +306,26 @@ formView.privateMethods
 
     values
 
+  removeErrors: ()->
+    @$('.alert.alert-error').remove()
+    @$el.removeClass('error')
+
+    for field in @getFields()
+      field.clearErrors()
+
+  displayErrors: (errors)->
+    has_errors = false
+    for field in @getFields()
+      for field_name, field_errors of errors when field_name is field.input_name
+        field.displayErrors(field_errors)
+        has_errors = true
+
+    if has_errors
+      @$el.addClass('error')
+
+  displayValidationErrorsMessage: ()->
+    @errorMessage('Please fix the fields with errors')
+
   submit_success_handler: (model, response, xhr)->
     @trigger "after:submit", @, model, response
     @trigger "disable:loadmask", @ if @loadMask is true
@@ -274,27 +339,34 @@ formView.privateMethods
     @trigger "after:submit", @, model, response
     @trigger "after:submit:fatal_error", @, model, response
 
+    try
+      json = $.parseJSON(response.responseText)
+      if !json.success && json.errors?
+        @displayValidationErrorsMessage()
+        @displayErrors(json.errors)
+
   submit: (save=true, saveOptions={})->
     _.bindAll @, "submit_success_handler", "submit_fatal_error_handler"
 
     saveOptions.success ||= @submit_success_handler
     saveOptions.error ||= @submit_fatal_error_handler
 
-    @syncFormWithModel()
+    @removeErrors()
+    @applyFormValuesToModel()
     return unless save
-    @current_model.save( @current_model.toJSON(), saveOptions )
+    @currentModel()?.save( @currentModel().toJSON(), saveOptions )
 
   hasModel: ()->
-    @current_model?
+    @currentModel()?
 
   currentModel: (options={})->
     if options is true or options?.refresh is true
-      @syncFormWithModel()
+      @applyFormValuesToModel()
 
-    @current_model
+    @state.get('currentModel')
 
-  syncFormWithModel: (options)->
-    @current_model?.set( @getValues(), options )
+  applyFormValuesToModel: (options)->
+    @currentModel()?.set( @getValues(), options )
 
   setLegend: (@legend)->
     $('fieldset legend', @el).first().html(@legend)