luca 0.9.9 → 0.9.42

data/src/components/application.coffee

@@ -0,0 +1,318 @@
+# 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: {}
+
+  # 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. 
+  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
+  # luca apps, and will not have the behavior of a main
+  # app which acts as a singleton
+  plugin: false
+
+  # by default, the application will use a controller
+  # component, which is a card view container which shows
+  # one view at a time.  this is useful for having an application
+  # with several 'pages' so to speak
+  useController: true
+
+  # 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
+  # will get wrapped by the main controller unless you
+  # set useController = false
+  components:[
+    ctype: 'template'
+    name: 'welcome'
+    template: 'sample/welcome'
+    templateContainer: "Luca.templates"
+  ]
+
+  initialize: (@options={})->
+    app             = @
+    appName         = @name
+    alreadyRunning  = Luca.getApplication?()
+
+    Luca.Application.instances ||= {}
+    Luca.Application.instances[ appName ] = app
+    
+    Luca.containers.Viewport::initialize.apply @, arguments
+
+    @state = new Luca.Model( @defaultState )
+
+    # 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()
+
+    # 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(()-> app.render()).until(@, "ready")
+
+    # Set up the Backbone Router
+    @setupRouter()
+
+    # the keyHandler allows us to specify
+    # keyEvents on our application with an API very similar
+    # to the DOM events API for Backbone.View
+    #
+    # Example:
+    #
+    # keyEvents:
+    #   meta:
+    #     forwardslash: "altSlashHandler"
+    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 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() )
+
+  # Returns the name of the active component on the main controller 
+  activeSection: ()->
+    @get("active_section")
+
+  # 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
+  # subcomponent in the view, recursively rendering everything which is set
+  # to automatically render (i.e. any non-deferrable components ).
+  #
+  # you should use boot to fire up any dependent collections, manager, any
+  # sort of data processing, whatever your application requires to run outside
+  # of the views
+  boot: ()->
+    @trigger "ready"
+
+  # delegate to the collection manager's get or create function.
+  # use App.collection() to create or access existing collections
+  collection: ()->
+    @collectionManager.getOrCreate.apply(@collectionManager, arguments)
+
+  get: (attribute)->
+    @state.get(attribute)
+
+  set: (attribute, value, options)->
+    @state.set.apply(@state, arguments)
+
+  view: (name)->
+    Luca.cache(name)
+
+  #### Navigation Hooks
+  #
+  # delegate to the main controller so that we can switch the active section
+  navigate_to: (component_name, callback)->
+    @getMainController().navigate_to(component_name, callback)
+
+  getMainController: ()->
+    return @components[0] if @useController is true
+    Luca.cache('main_controller')
+
+  # 
+  keyHandler: (e)->
+    return unless e and @keyEvents
+
+    isInputEvent = $(e.target).is('input') || $(e.target).is('textarea')
+
+    return if isInputEvent
+
+    keyname = Luca.keyMap[ e.keyCode ]
+
+    return unless keyname
+
+    meta = e?.metaKey is true
+    control = e?.ctrlKey is true
+
+    source = @keyEvents
+    source = if meta then @keyEvents.meta else source
+    source = if control then @keyEvents.control else source
+    source = if meta and control then @keyEvents.meta_control else source
+
+    if keyEvent = source?[keyname]
+      if @[keyEvent]? and _.isFunction(@[keyEvent])
+        @[keyEvent]?.call(@)
+      else
+        @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

@@ -0,0 +1,15 @@
+_.def('Luca.components.Toolbar').extends('Luca.core.Container').with
+
+  className: 'luca-ui-toolbar toolbar'
+
+  position: 'bottom'
+
+  initialize: (@options={})->
+    Luca.core.Container::initialize.apply @, arguments
+
+  prepareComponents: ()->
+    _( @components ).each (component)=>
+      component.container = @$el
+
+  render: ()->
+    $(@container).append(@el)

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

@@ -3,10 +3,8 @@
 # if you want to. Default implementation uses twitter bootstrap modal and
 # progress bar (http://twitter.github.com/bootstrap/). You template
 # should contain `progress`, `bar` and `message` classes
-loaderView = Luca.register        "Luca.components.CollectionLoaderView"
-loaderView.extends                "Luca.View"
+_.def('Luca.components.CollectionLoaderView').extends('Luca.components.Template').with
 
-loaderView.defines
   className: 'luca-ui-collection-loader-view'
 
   template: "components/collection_loader_view"

data/src/components/collection_view.coffee

@@ -0,0 +1,131 @@
+# 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"
+
+  className: "luca-ui-collection-view"
+
+  bodyClassName: "collection-ui-panel"
+
+  # A collection view can pass a model through to a template
+  itemTemplate: undefined
+
+  # A collection view can pass a model through a function which should return a string
+  itemRenderer: undefined
+
+  itemTagName: 'li'
+
+  itemClassName: 'collection-item'
+
+  hooks:[
+    "empty:results"
+  ]
+  
+  initialize: (@options={})->
+    _.extend(@, @options)
+
+    _.bindAll @, "refresh"
+
+    unless @collection? or @options.collection
+      throw "Collection Views must specify a collection"
+
+    unless @itemTemplate? || @itemRenderer? || @itemProperty?
+      throw "Collection Views must specify an item template or item renderer function"
+
+    Luca.components.Panel::initialize.apply(@, arguments)
+
+    if _.isString(@collection) and Luca.CollectionManager.get()
+      @collection = Luca.CollectionManager.get().getOrCreate(@collection)
+
+    if Luca.isBackboneCollection(@collection)
+      @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
+
+      if @observeChanges is true
+        setupChangeObserver.call(@)
+
+    else
+      throw "Collection Views must have a valid backbone collection"
+
+    if @collection.length > 0
+      @refresh()
+
+  attributesForItem: (item, model)->
+    _.extend {}, class: @itemClassName, "data-index": item.index, "data-model-id": item.model.get('id')
+
+  contentForItem: (item={})->
+    if @itemTemplate? and templateFn = Luca.template(@itemTemplate)
+      # this is the model
+      content = templateFn.call(@, item)
+
+    if @itemRenderer? and _.isFunction( @itemRenderer )
+      content = @itemRenderer.call(@, item, item.model, item.index)
+
+    if @itemProperty
+      content = item.model.get(@itemProperty) || item.model[ @itemProperty ]
+      content = content() if _.isFunction(content)
+
+    content
+
+  makeItem: (model, index)->
+    item = if @prepareItem? then @prepareItem.call(@, model, index) else (model:model, index: index)
+    make(@itemTagName, @attributesForItem(item, model), @contentForItem(item))
+
+  getModels: ()->
+    if @collection?.query and (@filter || @filterOptions)
+      @collection.query(@filter, @filterOptions)
+    else
+      @collection.models
+
+
+  locateItemElement: (id)->
+    @$(".#{ @itemClassName }[data-model-id='#{ id }']")
+
+  refreshModel: (model)->
+    index = @collection.indexOf( model )
+    @locateItemElement(model.get('id')).empty().append( @contentForItem({model,index}, model) )
+
+  refresh: ()->
+    @$bodyEl().empty()
+
+    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)
+      handler = selector
+      selector = undefined
+
+    eventTrigger = _([domEvent,"#{ @itemTagName }.#{ @itemClassName }", selector]).compact().join(" ")
+    Luca.View::registerEvent(eventTrigger,handler)
+
+  render: ()->
+    @refresh()
+    @$attach() if @$el.parent().length > 0 and @container?
+    @
+
+# Private Helpers
+
+make = Luca.View::make
+
+setupChangeObserver = ()->
+  @collection.on "change", (model)=> 
+    @refreshModel(model)

data/src/components/controller.coffee

@@ -0,0 +1,63 @@
+_.def('Luca.components.Controller').extends('Luca.containers.CardView').with
+
+  additionalClassNames:['luca-ui-controller']
+
+  activeAttribute: "active-section"
+
+  initialize: (@options)->
+    Luca.containers.CardView::initialize.apply @, arguments
+
+    @defaultCard ||= @components[0]?.name
+
+    throw "Controllers must specify a defaultCard property and/or the first component must have a name" unless @defaultCard
+
+    @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)
+
+  # 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)=>
+      @state.set(active_section: current.name )
+      if _.isFunction( callback )
+        callback.apply(current)
+
+    # return the section we are navigating to
+    @find(section)

data/src/components/fields/button_field.coffee

@@ -0,0 +1,38 @@
+_.def('Luca.fields.ButtonField').extends('Luca.core.Field').with
+
+  readOnly: true
+
+  events:
+    "click input" : "click_handler"
+
+  hooks:[
+    "button:click"
+  ]
+
+  className: 'luca-ui-field luca-ui-button-field'
+
+  template: 'fields/button_field'
+
+  click_handler: (e)->
+    me = my = $( e.currentTarget )
+    @trigger "button:click"
+
+  initialize: (@options={})->
+    _.extend @options
+    _.bindAll @, "click_handler"
+
+    Luca.core.Field::initialize.apply @, arguments
+
+    @template = "fields/button_field_link" if @icon_class?.length
+
+  afterInitialize: ()->
+    @input_id ||= _.uniqueId('button')
+    @input_name ||= @name ||= @input_id
+    @input_value ||= @label ||= @text
+    @input_type ||= "button"
+    @input_class ||= @class
+    @icon_class ||= ""
+    @icon_class = "icon-#{ @icon_class }" if @icon_class.length and !@icon_class.match(/^icon-/)
+    @icon_class += " icon-white" if @white
+
+  setValue: ()-> true

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

@@ -1,10 +1,8 @@
-# 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"
+make = Luca.View::make
+
+_.def('Luca.fields.CheckboxArray').extends('Luca.core.Field').with
+  version: 2
 
-checkboxArray.privateConfiguration
   template: "fields/checkbox_array"
 
   className: "luca-ui-checkbox-array"
@@ -14,10 +12,9 @@ checkboxArray.privateConfiguration
 
   selectedItems: []
 
-checkboxArray.privateMethods
   initialize: (@options={})->
     _.extend @, @options
-    _.extend @, Luca.concerns.Deferrable
+    _.extend @, Luca.modules.Deferrable
     _.bindAll @, "renderCheckboxes", "clickHandler", "checkSelected"
 
     Luca.core.Field::initialize.apply @, arguments
@@ -36,9 +33,6 @@ checkboxArray.privateMethods
 
     cbArray = @
 
-    unless Luca.isBackboneCollection(@collection)
-      throw "Checkbox Array Fields must specify a @collection property"
-      
     if @collection.length > 0
       @renderCheckboxes()
     else
@@ -65,8 +59,8 @@ checkboxArray.privateMethods
       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,9 +74,6 @@ checkboxArray.privateMethods
   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?
 
@@ -94,8 +85,6 @@ checkboxArray.publicMethods
 
     @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 → src}/components/fields/checkbox_field.coffee

@@ -1,20 +1,13 @@
-checkboxField = Luca.register         "Luca.fields.CheckboxField"
+_.def('Luca.fields.CheckboxField').extends('Luca.core.Field').with
 
-checkboxField.extends                 "Luca.core.Field"
-
-checkboxField.triggers                "checked",
-                                      "unchecked"
-
-checkboxField.publicConfiguration
-  send_blanks: true
-  input_value: 1
-
-checkboxField.privateConfiguration
-  template: 'fields/checkbox_field'
   events:
     "change input" : "change_handler"
 
-checkboxField.privateInterface
+  className: 'luca-ui-checkbox-field luca-ui-field'
+  template: 'fields/checkbox_field'
+  hooks: ["checked","unchecked"]
+  send_blanks: true
+
   change_handler: (e)->
     me = my = $(e.target)
 
@@ -31,16 +24,14 @@ checkboxField.privateInterface
 
     Luca.core.Field::initialize.apply @, arguments
 
+  afterInitialize: ()->
     @input_id ||= _.uniqueId('field')
     @input_name ||= @name
+    @input_value ||= 1
     @label ||= @name
 
-checkboxField.publicInterface
   setValue: (checked)->
-    @getInputElement().attr('checked', checked)
+    @input.attr('checked', checked)
 
   getValue:()->
-    @getInputElement().is(":checked")
-
-checkboxField.defines
-  version: 1
+    @input.is(":checked")