luca 0.9.76 → 0.9.89

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

@@ -0,0 +1,207 @@
+# The `Luca.CollectionView` renders models from a `Luca.Collection` into multiple
+# elements, and provides methods for filtering, paginating, sorting the underlying
+# collection and re-rendering the contents of its `@el` accordingly.
+#
+# #### Basic Example
+#     collectionView = Luca.register  "App.views.Books"
+#     collectionView.extends          "Luca.CollectionView"
+#
+#     collectionView.defines
+#       itemProperty: "author"
+#       collection: new Luca.Collection([
+#         author: "George Orwell"
+#         title:  "Animal Farm"
+#       ,
+#         author: "Noam Chomsky"
+#         title: "Manufacturing Consent"
+#       ])
+#
+#     view = new App.views.Books()
+# #### Extending it to make it Filterable and Paginatable
+#     filterable = Luca.register    "App.views.FilterableBooks"
+#     filterable.extends            "App.views.Books"
+#     filterable.defines
+#       collection: "books" 
+#       paginatable: 12
+#       filterable:
+#         query:
+#           author: "George Orwell"
+#    
+#      view = new App.views.FilterableBooks()
+# #### Filterable Collections
+#
+# The `Luca.CollectionView` will attempt to perform a local query against its
+# collection which behaves like a `Backbone.QueryCollection`.  It will do this
+# by default without making a remote request to the API.  
+# 
+# If you do not want this behavior, you can configure the `Luca.CollectionView` to 
+# behave as if the filtering was happen remotely in your REST API.  
+#
+#       filterable:
+#         options:
+#           remote: true
+collectionView = Luca.register      "Luca.CollectionView"
+
+collectionView.extends            "Luca.Panel"
+
+collectionView.replaces           "Luca.components.CollectionView"
+
+collectionView.mixesIn            "QueryCollectionBindings", 
+                                  "LoadMaskable", 
+                                  "Filterable", 
+                                  "Paginatable",
+                                  "Sortable"
+
+collectionView.triggers           "before:refresh",
+                                  "after:refresh",
+                                  "refresh",
+                                  "empty:results"
+
+collectionView.publicConfiguration
+  # Specify which collection will be used to supply the models to be rendered.
+  # Accepts either a string alias for the Collection class, or an instance of
+  # any class which inherits from Backbone.Collection
+  collection: undefined
+
+  # By default the CollectionView will be rendered inside of an OL tag.
+  tagName: "ol"
+
+  # The CollectionView behaves as a Luca.Panel which means it has an area for
+  # top and bottom toolbars.  The actual content that gets rendered from the 
+  # collection will be rendered inside an element with the specified class.
+  bodyClassName: "collection-ui-panel"
+
+  # Each item from the collection will be rendered inside of an element specified by @itemTagName
+  itemTagName: 'li'
+
+  # Each item element will be assigned a CSS class specified by @itemClassName 
+  itemClassName: 'collection-item'
+
+  # Specify which template should be used to render each item in the collection.  
+  # Accepts a string which will be passed to Luca.template(@itemTemplate).  Your template
+  # can expect to be passed an object with the `model` and `index` properties on it.
+  itemTemplate: undefined
+
+  # Accepts a reference to a function, which will be called with an object with the `model` and `index`
+  # properties on it.  This function should return a String which will be injected into the item DOM element.
+  itemRenderer: undefined
+
+  # Plucks the specified property from the model and inserts it into the item DOM element.
+  itemProperty: undefined
+
+  # If @observeChanges is set to true, any change in an underlying model will automatically be re-rendered.
+  observeChanges: false
+
+collectionView.publicMethods
+  initialize: (@options={})->
+    _.extend(@, @options)
+    _.bindAll @, "refresh"
+
+    unless @collection? or @options.collection
+      console.log "Error on initialize of collection view", @
+      throw "Collection Views must specify a collection"
+
+    unless @itemTemplate? || @itemRenderer? || @itemProperty?
+      throw "Collection Views must specify an item template or item renderer function"
+
+    if _.isString(@collection) 
+      if Luca.CollectionManager.get()
+        @collection = Luca.CollectionManager.get().getOrCreate(@collection)
+      else
+        console.log "String Collection but no collection manager"
+
+    unless Luca.isBackboneCollection(@collection)
+      console.log "Missing Collection on #{ @name || @cid }", @, @collection
+      throw "Collection Views must have a valid backbone collection"
+
+    # INVESTIGATE THIS BEING DOUBLE WORK
+    @on "data:refresh", @refresh, @
+    @on "collection:reset", @refresh, @
+
+    @on "collection:remove", @refresh, @
+    @on "collection:add", @refresh, @
+    @on "collection:change", @refreshModel, @ if @observeChanges is true
+
+    Luca.Panel::initialize.apply(@, arguments)
+
+    view = @
+    if @getCollection()?.length > 0
+      @on "after:render", ()->
+        view.refresh()
+        view.unbind "after:render", @
+
+  # Given the id of a model, find the underlying DOM element which was rendered by this collection.
+  # Assumes that the data-model-id attribute is set, which it is by default by @attributesForItem.
+  locateItemElement: (id)->
+    @$(".#{ @itemClassName }[data-model-id='#{ id }']")
+
+  # Refresh is responsible for applying any filtering, pagination, or sorting options that may be set
+  # from the various Luca.concerns mixed in by `Luca.CollectionView` and making a query to the underlying
+  # collection.  It will then take the set of models returned by `@getModels` and pass them through the
+  # item rendering pipeline.
+  refresh: ()->
+    query = @getLocalQuery()
+    options = @getQueryOptions()
+    models  = @getModels(query, options)
+
+    @$bodyEl().empty()
+
+    @trigger("before:refresh", models, query, options)
+
+    if models.length is 0
+      @trigger("empty:results", query, options)
+
+    index = 0
+    for model in models
+      @$append @makeItem(model, index++)
+
+    @trigger("after:refresh", models, query, options)
+
+    @
+
+collectionView.privateMethods
+  # Determines which attributes should be set on the item DOM element. 
+  attributesForItem: (item, model)->
+    _.extend {}, class: @itemClassName, "data-index": item.index, "data-model-id": item.model.get('id')
+
+  # Determines the content for the item DOM element.  Will use the appropriate options
+  # specified by `@itemTemplate`, `@itemRenderer`, or `@itemProperty`
+  contentForItem: (item={})->
+    if @itemTemplate? and templateFn = Luca.template(@itemTemplate)
+      return content = templateFn.call(@, item)
+
+    if @itemRenderer? and _.isFunction( @itemRenderer )
+      return content = @itemRenderer.call(@, item, item.model, item.index)
+
+    if @itemProperty and item.model?
+      return content = item.model.read( @itemProperty )
+
+    ""
+
+  # Uses the various options passed to the `CollectionView` to assemble a call to `Backbone.View::make`.
+  makeItem: (model, index)->
+    item = if @prepareItem? then @prepareItem.call(@, model, index) else (model:model, index: index)
+    attributes = @attributesForItem(item, model) 
+    content = @contentForItem(item)
+
+    try
+      Backbone.View::make(@itemTagName, attributes, content)
+    catch e
+      console.log "Error generating DOM element for CollectionView", @, model, index
+
+  # Given a model, attempt to re-render the contents of its item in this view's DOM contents.
+  refreshModel: (model)->
+    index = @collection.indexOf( model )
+    @locateItemElement(model.get('id')).empty().append( @contentForItem({model,index}, model) )
+    @trigger("model:refreshed", index, model)
+
+
+  registerEvent: (domEvent, selector, handler)->
+    if !handler? and _.isFunction(selector)
+      handler = selector
+      selector = undefined
+
+    eventTrigger = _([domEvent,"#{ @itemTagName }.#{ @itemClassName }", selector]).compact().join(" ")
+    Luca.View::registerEvent(eventTrigger,handler)
+
+collectionView.register()

data/{src → app/assets/javascripts/luca}/components/controller.coffee

@@ -2,36 +2,44 @@ controller = Luca.register        "Luca.components.Controller"
 controller.extends                "Luca.containers.CardView"
 
 controller.publicInterface
+  tracker: "page"
+
   default: (callback)->
     @navigate_to(@defaultPage || @defaultCard, callback)
 
   activePage: ()-> 
     @activeSection()
 
-  # switch the active card of this controller
-  # optionally passing an onActivation callback
-  # will fire this callback in the context of
-  # the currently active card
   navigate_to: (section, callback)->
     section ||= @defaultCard
 
-    # activate is a method on Luca.containers.CardView which
-    # selects a component and makes it visible, hiding any
-    # other component which may be monopolizing the view at that time.
-
-    # after activation it triggers a after:card:switch event
-    # and if it is the first time that view is being activated,
-    # it triggers a first:activation event which gets relayed to all
-    # child components in that view
     @activate section, false, (activator, previous,current)=>
+      if current.activatedByController is true
+        current.trigger("on:controller:reactivation")
+      else
+        current.trigger("on:controller:reactivation")
+        current.trigger("on:controller:activation")
+        current.activatedByController = true
+
       @state.set(active_section: current.name )
+
+      if app = Luca.getApplication?()
+        app.state.set(@tracker, current.name)
+
+      Luca.key?.setScope( current.name )
+
       if _.isFunction( callback )
-        callback.apply(current)
+        callback.call(current)
 
     # return the section we are navigating to
     @find(section)
 
 controller.classMethods
+  setupComponentKeyEvents: ()->
+    @_().each (component)->    
+      if _.isObject(component.keyEvents) and component.name?
+        Luca.util.setupKeymaster(component.keyEvents, component.name).on(component)    
+
   controllerPath: ()->
     component = @
     
@@ -45,6 +53,9 @@ controller.classMethods
 
     list.reverse()
 
+controller.afterDefinition ()->
+  Luca.View::hooks.push "on:controller:activation"
+
 controller.defines
   additionalClassNames: 'luca-ui-controller'
   activeAttribute: "active-section"
@@ -66,6 +77,9 @@ controller.defines
     @_().each (component)->
       component.controllerPath = Luca.components.Controller.controllerPath
 
+    @on "after:render", @default, @
+    @on "before:render", Luca.components.Controller.setupComponentKeyEvents, @
+
   each: (fn)->
     _( @components ).each (component)=> fn.call(@,component)
 

data/{src/core/field.coffee → app/assets/javascripts/luca/components/fields/base.coffee}

@@ -6,7 +6,7 @@ field.triggers                "before:validation",
                               "after:validation",
                               "on:change"
 
-field.publicConfiguration   
+field.publicConfiguration
   labelAlign: 'top'
   className: 'luca-ui-text-field luca-ui-field'
   statuses: [
@@ -23,8 +23,24 @@ field.publicInterface
     @getInputElement().attr('disabled', false)
 
   getValue: ()->
-    raw = @getInputElement()?.attr('value')
+    @getParsedValue(@getInputElement()?.attr('value'))
 
+  setValue: (value)->
+    @getInputElement()?.attr('value', value)
+
+  updateState: (state)->
+    _( @statuses ).each (cls)=>
+      @$el.removeClass(cls)
+    @$el.addClass(state)
+
+  clearErrors: ()->
+    @$el.removeClass('error')
+
+  displayErrors: (errors)->
+    @updateState('error')
+
+field.methods
+  getParsedValue: (raw)->
     return raw if _.str.isBlank( raw )
 
     switch @valueType
@@ -33,14 +49,6 @@ field.publicInterface
       when "float" then parseFloat(raw)
       else raw
 
-  setValue: (value)->
-    @getInputElement()?.attr('value', value)
-
-  updateState: (state)->
-    _( @statuses ).each (cls)=>
-      @$el.removeClass(cls)
-      @$el.addClass(state)
-
 field.privateConfiguration
   isField: true
   template: 'fields/text_field'

data/{src → app/assets/javascripts/luca}/components/fields/button_field.coffee

@@ -5,12 +5,13 @@ 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
+  readOnly:       true
+  input_value:    undefined 
+  input_type:     "button" 
+  icon_class:     undefined
+  input_name:     undefined
+  white:          undefined
+  buttonClasses:  "" 
 
 buttonField.privateConfiguration
   isButton: true
@@ -35,12 +36,10 @@ buttonField.privateInterface
     @input_id ||= _.uniqueId('button')
     @input_name ||= @name ||= @input_id
     @input_value ||= @label ||= @text
-    @input_class ||= @class
+    @input_class ||= @class ||= @buttonClasses
     @icon_class ||= ""
     @icon_class = "icon-#{ @icon_class }" if @icon_class.length and !@icon_class.match(/^icon-/)
     @icon_class += " icon-white" if @white
 
   setValue: ()-> true
 
-buttonField.defines
-  version: 1

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

@@ -0,0 +1,159 @@
+selectField = Luca.register   "Luca.fields.SelectField"
+
+selectField.extends           "Luca.core.Field"
+
+selectField.triggers          "after:select",
+                              "on:change"
+
+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"
+
+    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 unless @retainValue? 
+
+  afterInitialize: ()->
+    if @collection?.data
+      @valueField ||= "id"
+      @displayField ||= "name"
+      @sortOptionsBy ||= @displayField
+      @parseData()
+
+    try
+      @configure_collection( @setAsDeferrable )
+    catch e
+      console.log "Error Configuring Collection", @, e.message
+
+    @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
+  # an array of objects with the valueField and displayField
+  # properties, or an array of arrays with [valueField, displayField]
+  parseData: ()->
+    @collection.data = _( @collection.data ).map (record)=>
+      return record if not _.isArray( record )
+
+      hash = {}
+      hash[ @valueField ] = record[0]
+      hash[ @displayField ] = record[1] || record[0]
+
+      hash
+
+  getInputElement: ()->
+    @input ||= @$('select').eq(0)
+
+  afterRender: ()->
+    if @collection?.models?.length > 0
+      @populateOptions()
+    else
+      @collection?.trigger("reset")
+
+  beforeFetch: ()->
+    @resetOptions()
+
+  change_handler: (e)->
+    @trigger "on:change", @, e
+
+  resetOptions: ()->
+    @getInputElement().html('')
+
+    if @allowMultiple
+      @getInputElement().attr(multiple: true)
+    else if @includeBlank
+      @getInputElement().append("<option value='#{ @blankValue }'>#{ @blankText }</option>")
+
+  populateOptions: ()->
+    @resetOptions()
+
+    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 )
+
+selectField.register()