luca 0.9.2 → 0.9.4

data/src/components/application.coffee

@@ -1,14 +1,52 @@
+# Luca.Application 
+#
+# The Application class is the global state tracking mechanism
+# for your single page application, as well as the entry point.
+#
+# By default it contains a main controller which is a Luca.components.Controller instance. 
+#
+# In a typical Luca application, the router will use the applications @navigate_to() method to switch
+# from page to page on the main controller, or any other controllers nested inside of it.
+#
+# You would control flow when the controller fires activation events on the nested view components inside of it.
+#
+# Decoupling application control flow from the URL Fragment from Backbone.History and preventing
+# your components from directly caring about the URL Fragment, allows you to build applications as
+# isolated components which can run separately or nested inside of other applications.   
+
+startHistory = ()-> Backbone.history.start()
+
 _.def('Luca.Application').extends('Luca.containers.Viewport').with
+  name: "MyApp"
+
+  # The Application uses a Backbone.Model as a state machine, which
+  # allows you to get / set attributes, persist them somewhere, and
+  # most importantly to bind to change events of certain attributes.
+  #
+  # the @defaultState property will be the default attributes
+  defaultState: {}
 
-  # automatically starts the @router
-  # if it exists, once the components
-  # for the application have been created
-  autoStartHistory: true
+  # if autoBoot is set to true, the application will 
+  # attempt to boot on document ready.
+  autoBoot: false
+
+  # automatically starts the @router if it exists, 
+  # once the components for the application have 
+  # been created.  Pass the event name you want to
+  # listen for on this component before you start history
+  autoStartHistory: "before:render"
 
   # we will create a collection manager singleton
-  # by default unless otherwise specified
+  # by default unless otherwise specified. 
   useCollectionManager: true
 
+  # to pass options to the collection manager, set the @collectionManager
+  # hash which will get passed once the collection manager is created
+  collectionManager: {}
+
+  # by default we will use the standard collection manager which ships with
+  # Luca.  If you would like to use your own extension of the collection manager
+  # just pass a reference to the class you would like to use. 
   collectionManagerClass: "Luca.CollectionManager"
 
   # Luca plugin apps are apps which mount onto existing
@@ -22,7 +60,30 @@ _.def('Luca.Application').extends('Luca.containers.Viewport').with
   # with several 'pages' so to speak
   useController: true
 
-  #### Nested Components
+  # Key Handler
+  # 
+  # One responsibility of the application, since it is a viewport which monopolizes the entire screen
+  # is to relay keypress events from the document, to whatever views are interested in responding to them.
+  #
+  # This functionality is disabled by default.
+  useKeyHandler: false
+
+  # You can configure key events by specifying them by their name, as it exists in Luca.keyMap. For example:
+  #
+  keyEvents: {} 
+
+  # keyEvents
+  #   keyup: keyUpHandler
+  #   enter: enterHandler
+  #   meta:
+  #     up: metaUpHandler
+  #   control:
+  #     forwardslash: controlSlashHandler
+  #     keyup: controlUpHandler
+  #   control_meta:
+  #     keydown: metaControlKeyDownHandler
+  #
+  #
 
   # applications have one component, the controller.
   # any components defined on the application class directly
@@ -36,31 +97,36 @@ _.def('Luca.Application').extends('Luca.containers.Viewport').with
   ]
 
   initialize: (@options={})->
-    Luca.containers.Viewport::initialize.apply @, arguments
-
-    if @useController is true
-      definedComponents = @components || []
+    app             = @
+    appName         = @name
+    alreadyRunning  = Luca.getApplication?()
 
-    @components = [
-      ctype: 'controller'
-      name: "main_controller"
-      components: definedComponents
-    ]
+    Luca.Application.instances ||= {}
+    Luca.Application.instances[ appName ] = app
+    
+    Luca.containers.Viewport::initialize.apply @, arguments
 
-    if @useCollectionManager is true
-      @collectionManagerClass = Luca.util.resolve( @collectionManagerClass ) if _.isString( @collectionManagerClass )
+    @state = new Luca.Model( @defaultState )
 
-      @collectionManager ||= Luca.CollectionManager.get?()
-      @collectionManager ||= new @collectionManagerClass( @collectionManagerOptions||={} )
+    # The Controller is the piece of the application that handles showing
+    # and hiding 'pages' of the app.  The Application has a navigate_to
+    # method which delegates to the controller, and allows you to navigate
+    # to a given page, or component, by its name.  The controller integrates
+    # with the state machine of the application
+    @setupMainController()
 
-    @state = new Luca.Model( @defaultState )
+    # The Collection Manager is responsible 
+    @setupCollectionManager()
 
     # we will render when all of the various components
     # which handle our data dependencies determine that
     # we are ready
-    @defer(()=>@render()).until("ready")
+    @defer(()-> app.render()).until(@, "ready")
+
+    # Set up the Backbone Router
+    @setupRouter()
 
-    # the keyRouter allows us to specify
+    # the keyHandler allows us to specify
     # keyEvents on our application with an API very similar
     # to the DOM events API for Backbone.View
     #
@@ -69,52 +135,51 @@ _.def('Luca.Application').extends('Luca.containers.Viewport').with
     # keyEvents:
     #   meta:
     #     forwardslash: "altSlashHandler"
-    @setupKeyRouter() if @useKeyRouter is true and @keyEvents?
+    if @useKeyRouter is true
+      console.log "The useKeyRouter property is being deprecated. switch to useKeyHandler instead"
+    
+    @setupKeyHandler() if (@useKeyHandler is true or @useKeyRouter is true) and @keyEvents?
 
     # if the application is a plugin designed to modify the behavior
     # of another app, then don't claim ownership.  otherwise the most common
     # use-case is that there will be one application instance
-    unless @plugin is true
-      Luca.getApplication = ()=> @
+    unless @plugin is true or alreadyRunning
+      Luca.getApplication = (name)=> 
+        return app unless name?
+        Luca.Application.instances[ name ] 
+
+    if @autoBoot
+      if Luca.util.resolve(@name)
+        throw "Attempting to override window.#{ @name } when it already exists"
 
+      $ ->
+        window[ appName ] = app 
+        app.boot()
+
+  # @activeView() returns a reference to the instance of the view
+  # which is currently monopolizing the viewport.
+  #
+  # this will be whicever component is active on the controllers
+  # nested within the main controller, if there are any, or the view
+  # itself which is active on the main controller. 
   activeView: ()->
     if active = @activeSubSection()
       @view( active )
     else
       @view( @activeSection() )
 
-  activeSubSection: ()->
-    @get("active_sub_section")
-
+  # Returns the name of the active component on the main controller 
   activeSection: ()->
     @get("active_section")
 
-  beforeRender: ()->
-    Luca.containers.Viewport::beforeRender?.apply(@, arguments)
-
-    if @router? and @autoStartHistory is true
-      routerStartEvent = @startRouterOn || "after:render"
-
-      if routerStartEvent is "before:render"
-        Backbone.history.start()
-      else
-        @bind routerStartEvent, ()-> Backbone.history.start()
-
-  afterComponents: ()->
-    Luca.containers.Viewport::afterComponents?.apply @, arguments
-
-    # any time the main controller card switches we should track
-    # the active card on the global state chart
-    @getMainController()?.bind "after:card:switch", (previous,current)=>
-      @state.set(active_section:current.name)
-
-    # any time the card switches on one of the sub controllers
-    # then we should track the active sub section on the global state chart
-    @getMainController()?.each (component)=>
-      if component.ctype.match(/controller$/)
-        component.bind "after:card:switch", (previous,current)=>
-          @state.set(active_sub_section:current.name)
+  # Returns the name of the active component on the nested controllers
+  # on the main controller, if there is one.  These get set on the
+  # state machine in response to card switch events on the controller component
+  activeSubSection: ()->
+    @get("active_sub_section")
 
+  activePages: ()->
+    @$('.luca-ui-controller').map (index,element)=> $(element).data('active-section')
 
   # boot should trigger the ready event, which will call the initial call
   # to render() your application, which will have a cascading effect on every
@@ -135,12 +200,8 @@ _.def('Luca.Application').extends('Luca.containers.Viewport').with
   get: (attribute)->
     @state.get(attribute)
 
-  getMainController: ()->
-    return @components[0] if @useController is true
-    Luca.cache('main_controller')
-
-  set: (attributes)->
-    @state.set(attributes)
+  set: (attribute, value, options)->
+    @state.set.apply(@state, arguments)
 
   view: (name)->
     Luca.cache(name)
@@ -151,23 +212,12 @@ _.def('Luca.Application').extends('Luca.containers.Viewport').with
   navigate_to: (component_name, callback)->
     @getMainController().navigate_to(component_name, callback)
 
-  setupKeyRouter: ()->
-    return unless @keyEvents
-
-    @keyEvents.control_meta ||= {}
-
-    # allow for both meta_control, control_meta for the combo
-    _.extend(@keyEvents.control_meta, @keyEvents.meta_control) if @keyEvents.meta_control
-
-    router = _.bind(@keyRouter, @)
-
-    $( document ).keydown( router )
+  getMainController: ()->
+    return @components[0] if @useController is true
+    Luca.cache('main_controller')
 
-  #### Key Router
-  #
-  # TODO: Define a syntax for mapping combinations of meta, control, and keycodes
-  # to some sort of method delegation system that the application handles.
-  keyRouter: (e)->
+  # 
+  keyHandler: (e)->
     return unless e and @keyEvents
 
     isInputEvent = $(e.target).is('input') || $(e.target).is('textarea')
@@ -187,7 +237,82 @@ _.def('Luca.Application').extends('Luca.containers.Viewport').with
     source = if meta and control then @keyEvents.meta_control else source
 
     if keyEvent = source?[keyname]
-      if @[keyEvent]?
+      if @[keyEvent]? and _.isFunction(@[keyEvent])
         @[keyEvent]?.call(@)
       else
-        @trigger(keyEvent)
+        @trigger(keyEvent, e, keyname)
+
+  setupControllerBindings: ()->
+    app = @
+    # any time the main controller card switches we should track
+    # the active card on the global state chart
+    @getMainController()?.bind "after:card:switch", (previous,current)=>
+      @state.set(active_section:current.name)
+      app.trigger "page:change"
+
+    # any time the card switches on one of the sub controllers
+    # then we should track the active sub section on the global state chart
+    @getMainController()?.each (component)=>
+      if component.ctype.match(/controller$/)
+        component.bind "after:card:switch", (previous,current)=>
+          @state.set(active_sub_section:current.name)       
+          app.trigger "sub:page:change"
+
+  setupMainController: ()->
+    if @useController is true
+      definedComponents = @components || []
+
+      @components = [
+        ctype: 'controller'
+        name: "main_controller"
+        components: definedComponents
+      ]
+
+      @defer( @setupControllerBindings, false ).until("after:components")
+
+  setupCollectionManager: ()->
+    if @useCollectionManager is true
+      @collectionManagerClass = Luca.util.resolve( @collectionManagerClass ) if _.isString( @collectionManagerClass )
+
+      collectionManagerOptions = @collectionManagerOptions
+
+      if _.isObject(@collectionManager) and not _.isFunction( @collectionManager?.get )
+        collectionManagerOptions = @collectionManager
+        @collectionManager = undefined
+
+      if _.isString(@collectionManager)
+        collectionManagerOptions = 
+          name: @collectionManager
+
+      @collectionManager = Luca.CollectionManager.get?( collectionManagerOptions.name )
+
+      unless _.isFunction(@collectionManager?.get)
+        @collectionManager = new @collectionManagerClass( collectionManagerOptions )    
+
+  setupRouter: ()->
+    app = @
+
+    if _.isString( @router )
+      routerClass = Luca.util.resolve(@router)
+      @router = new routerClass({app})
+
+    # if this application has a router associated with it
+    # then we need to start backbone history on a certain event.
+    # you can control which by setting the @startHistoryOn property
+    if @router and @autoStartHistory
+      @autoStartHistory = "before:render" if @autoStartHistory is true
+      @defer(startHistory, false).until(@, @autoStartHistory)   
+
+  setupKeyHandler: ()->
+    return unless @keyEvents
+
+    @keyEvents.control_meta ||= {}
+
+    # allow for both meta_control, control_meta for the combo
+    _.extend(@keyEvents.control_meta, @keyEvents.meta_control) if @keyEvents.meta_control
+
+    handler = _.bind(@keyHandler, @)
+
+    for keyEvent in (@keypressEvents || ["keydown"])
+      $( document ).on( keyEvent, handler )
+

data/src/components/base_toolbar.coffee

@@ -1,6 +1,6 @@
 _.def('Luca.components.Toolbar').extends('Luca.core.Container').with
 
-  className: 'luca-ui-toolbar'
+  className: 'luca-ui-toolbar toolbar'
 
   position: 'bottom'
 

data/src/components/collection_view.coffee

@@ -1,4 +1,12 @@
-make = Luca.View::make
+# Public: The CollectionView renders a collection of models into a list of items.
+# 
+# Examples
+#
+#   _.def('App.ListView').extends('Luca.components.CollectionView').with
+#     collection: new App.SampleCollection()
+#     itemTemplate: "list_view_item"
+#     loadMask: true
+#
 
 _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
   tagName: "div"
@@ -17,6 +25,10 @@ _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
 
   itemClassName: 'collection-item'
 
+  hooks:[
+    "empty:results"
+  ]
+  
   initialize: (@options={})->
     _.extend(@, @options)
 
@@ -31,12 +43,23 @@ _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
     Luca.components.Panel::initialize.apply(@, arguments)
 
     if _.isString(@collection) and Luca.CollectionManager.get()
-      @collection = Luca.CollectionManager.get().get(@collection)
+      @collection = Luca.CollectionManager.get().getOrCreate(@collection)
 
     if Luca.isBackboneCollection(@collection)
-      @collection.bind "reset", @refresh
+      @collection.on "before:fetch", ()=>
+        @trigger "enable:loadmask" if @loadMask is true
+        
+      @collection.bind "reset", ()=>
+        @trigger "disable:loadmask" if @loadMask is true
+        @refresh()
+
       @collection.bind "add", @refresh
       @collection.bind "remove", @refresh
+    else
+      throw "Collection Views must have a valid backbone collection"
+
+    if @collection.length > 0
+      @refresh()
 
   attributesForItem: (item)->
     _.extend {}, class: @itemClassName, "data-index": item.index
@@ -46,7 +69,7 @@ _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
       content = templateFn.call(@, item)
 
     if @itemRenderer? and _.isFunction( @itemRenderer )
-      content = @itemRenderer.call(@, item)
+      content = @itemRenderer.call(@, item, item.model, item.index)
 
     if @itemProperty
       content = item.model.get(@itemProperty) || item.model[ @itemProperty ]
@@ -56,7 +79,6 @@ _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
 
   makeItem: (model, index)->
     item = if @prepareItem? then @prepareItem.call(@, model, index) else (model:model, index: index)
-
     make(@itemTagName, @attributesForItem(item), @contentForItem(item))
 
   getModels: ()->
@@ -66,12 +88,13 @@ _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
       @collection.models
 
   refresh: ()->
-    panel = @
-
     @$bodyEl().empty()
 
-    _( @getModels() ).each (model, index)->
-      panel.$append( panel.makeItem(model, index) )
+    if @getModels().length is 0
+      @trigger("empty:results")
+
+    _( @getModels() ).each (model, index)=>
+      @$append( @makeItem(model, index) )
 
   registerEvent: (domEvent, selector, handler)->
     if !handler? and _.isFunction(selector)
@@ -83,4 +106,9 @@ _.def("Luca.components.CollectionView").extends("Luca.components.Panel").with
 
   render: ()->
     @refresh()
-    @$attach() if @$el.parent().length > 0 and @container?
+    @$attach() if @$el.parent().length > 0 and @container?
+    @
+
+# Private Helpers
+
+make = Luca.View::make

data/src/components/controller.coffee

@@ -1,4 +1,9 @@
 _.def('Luca.components.Controller').extends('Luca.containers.CardView').with
+
+  additionalClassNames:['luca-ui-controller']
+
+  activeAttribute: "active-section"
+
   initialize: (@options)->
     Luca.containers.CardView::initialize.apply @, arguments
 
@@ -6,13 +11,31 @@ _.def('Luca.components.Controller').extends('Luca.containers.CardView').with
 
     throw "Controllers must specify a defaultCard property and/or the first component must have a name" unless @defaultCard
 
-    @state = new Backbone.Model
+    @state = new Backbone.Model 
       active_section: @defaultCard
 
   each: (fn)->
     _( @components ).each (component)=>
       fn.apply @, [component]
 
+  activeSection: ()->
+    @get("activeSection")
+
+  controllers:(deep=false)->
+    @select 'ctype', 'controller', deep
+
+  availableSections: ()->
+    base = {}
+    base[ @name ] = @sectionNames()
+
+    _( @controllers() ).reduce (memo,controller)=>
+      memo[ controller.name ] = controller.sectionNames()  
+      memo
+    , base 
+
+  sectionNames: (deep=false)->
+    @pluck('name')
+
   default: (callback)->
     @navigate_to(@defaultCard, callback)
 

data/src/components/fields/checkbox_field.coffee

@@ -3,23 +3,20 @@ _.def('Luca.fields.CheckboxField').extends('Luca.core.Field').with
   events:
     "change input" : "change_handler"
 
-  change_handler: (e)->
-    me = my = $(e.currentTarget)
+  className: 'luca-ui-checkbox-field luca-ui-field'
+  template: 'fields/checkbox_field'
+  hooks: ["checked","unchecked"]
+  send_blanks: true
 
-    @trigger "on:change", @, e
+  change_handler: (e)->
+    me = my = $(e.target)
 
-    if me.checked is true
+    if me.is(":checked")
       @trigger "checked"
     else
       @trigger "unchecked"
 
-  className: 'luca-ui-checkbox-field luca-ui-field'
-
-  template: 'fields/checkbox_field'
-
-  hooks: ["checked","unchecked"]
-
-  send_blanks: true
+    @trigger "on:change", @, e, me.is(":checked")
 
   initialize: (@options={})->
     _.extend @, @options
@@ -37,4 +34,4 @@ _.def('Luca.fields.CheckboxField').extends('Luca.core.Field').with
     @input.attr('checked', checked)
 
   getValue:()->
-    @input.attr('checked') is true
+    @input.is(":checked")

data/src/components/fields/label_field.coffee

@@ -0,0 +1,14 @@
+_.def("Luca.components.LabelField").extends("Luca.core.Field").with
+  className: "luca-ui-field luca-ui-label-field"
+    
+  getValue: ()->
+    @$('input').attr('value')
+
+  formatter: (value)->
+    value ||= @getValue()
+    _.str.titleize( value )
+
+  setValue: (value)->
+    @trigger("change", value, @getValue())
+    @$('input').attr('value', value)
+    @$('.value').html( @formatter(value) )

data/src/components/fields/select_field.coffee

@@ -50,13 +50,13 @@ _.def('Luca.fields.SelectField').extends('Luca.core.Field').with
   parseData: ()->
     @collection.data = _( @collection.data ).map (record)=>
       return record if not _.isArray( record )
+
       hash = {}
       hash[ @valueField ] = record[0]
-      hash[ @displayField ] = record[1]
+      hash[ @displayField ] = record[1] || record[0]
 
       hash
 
-
   afterRender: ()->
     @input = $('select', @el)
 

data/src/components/fields/text_field.coffee

@@ -1,4 +1,3 @@
-change_handler = (e)-> @trigger "on:change", @, e
 
 _.def('Luca.fields.TextField').extends('Luca.core.Field').with
   events:
@@ -12,8 +11,11 @@ _.def('Luca.fields.TextField').extends('Luca.core.Field').with
 
   send_blanks: true
 
+  keyEventThrottle: 300
+
   initialize: (@options={})->
-    Luca.core.Field::initialize.apply @, arguments
+    if @enableKeyEvents
+      @registerEvent("keyup input","keyup_handler")     
 
     @input_id ||= _.uniqueId('field')
     @input_name ||= @name
@@ -28,13 +30,16 @@ _.def('Luca.fields.TextField').extends('Luca.core.Field').with
       @$el.addClass('input-append')
       @addOn = @append
 
-    @registerEvent("keydown input","keydown_handler") if @enableKeyEvents
+    Luca.core.Field::initialize.apply @, arguments
+
+  keyup_handler: (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: change_handler
-  keydown_handler: _.throttle ((e)-> change_handler.apply @, arguments), 300
+  change_handler: (e)-> 
+    @trigger "on:change", @, e

data/src/components/fields/type_ahead_field.coffee

@@ -2,6 +2,7 @@ _.def('Luca.fields.TypeAheadField').extends('Luca.fields.TextField').with
   className: 'luca-ui-field'
 
   getSource: ()->
+    return @source.call(@) if _.isFunction(@source)
     @source || []
 
   matcher: (item)->