luca 0.9.9 → 0.9.42

data/{app/assets/javascripts/luca → src}/core/collection.coffee

@@ -1,18 +1,13 @@
-collection = Luca.register          'Luca.Collection'
-collection.extends                  'Backbone.QueryCollection'
-collection.includes                 'Luca.Events'
+source = 'Backbone.Collection'
+source = 'Backbone.QueryCollection' if Backbone.QueryCollection?
 
-collection.triggers                 "after:initialize",  
-                                    "before:fetch",
-                                    "after:response"
-
-collection.publicConfiguration    
-  model: Luca.Model
+_.def("Luca.Collection").extends( source ).with
+  include: ['Luca.Events']
   # cachedMethods refers to a list of methods on the collection
   # whose value gets cached once it is ran.  the collection then
   # binds to change, add, remove, and reset events and then expires
   # the cached value once these events are fired.
-  #
+
   # cachedMethods expects an array of strings representing the method name
   # or objects containing @method and @resetEvents properties.  by default
   # @resetEvents are 'add','remove',reset' and 'change'.
@@ -22,19 +17,9 @@ collection.publicConfiguration
   # and return the filtered results that way, then set this to true
   remoteFilter: false
 
-  # setting a cache key to a string, or to a function which returns
-  # a string, will determine where the collections' models are pulled
-  # from if they are available on page load.  also known as "bootstrapping"
-  # your collections with data.  The cache key will look in whatever object
-  # is set in Luca.config.modelBootstrap for its models.
-  cache_key: undefined
-
-  # Which CollectionManager should we register with? Expects either a string
-  # which will get resolved into a global variable, or a 
-  manager: undefined
-
   initialize: (models=[], @options)->
     _.extend @, @options
+    @setupMethodCaching()
     @_reset()
 
     # By specifying a @cache_key property or method, you can instruct
@@ -46,7 +31,7 @@ collection.publicConfiguration
       console.log 'The @cached property of Luca.Collection is being deprecated.  Please change to cache_key'
 
     if @cache_key ||= @cached
-      @bootstrap_cache_key = Luca.util.read(@cache_key) 
+      @bootstrap_cache_key = if _.isFunction( @cache_key ) then @cache_key() else @cache_key
 
     if @registerAs or @registerWith
       console.log "This configuration API is deprecated.  use @name and @manager properties instead"
@@ -55,7 +40,7 @@ collection.publicConfiguration
     @name ||= @registerAs
     @manager ||= @registerWith
 
-    @manager = Luca.util.read(@manager) if @manager? 
+    @manager = if _.isFunction(@manager) then @manager() else @manager
 
     # if they specify a
     if @name and not @manager
@@ -67,8 +52,8 @@ collection.publicConfiguration
     # to be scoped with some sort of unique id, as say some sort of belongsTo relationship
     # then you can specify @registerAs as a method()
     if @manager
-      @name ||= Luca.util.read(@cache_key) 
-      @name = Luca.util.read(@name) 
+      @name ||= @cache_key()
+      @name = if _.isFunction( @name ) then @name() else @name
 
       unless @private or @anonymous
         @bind "after:initialize", ()=>
@@ -79,7 +64,7 @@ collection.publicConfiguration
     # locally in localStorage
     if @useLocalStorage is true and window.localStorage?
       table = @bootstrap_cache_key || @name
-      throw "Must specify a cache_key property or method to use localStorage"
+      throw "Must specify either a cached or registerAs property to use localStorage"
       @localStorage = new Luca.LocalStore( table )
 
     # Populating a collection with local data
@@ -100,11 +85,6 @@ collection.publicConfiguration
     if models
       @reset models, silent: true, parse: options?.parse
 
-    Luca.concern.setup.call(@)
-    Luca.util.setupHooks.call(@, @hooks)
-
-    @setupMethodCaching()
-
     @trigger "after:initialize"
 
   # Luca.Collections will append a query string to the URL
@@ -153,43 +133,43 @@ collection.publicConfiguration
     @
 
   applyFilter: (filter={}, options={})->
-    options = _( options ).clone()
-
     if options.remote? is true or @remoteFilter is true
       @applyParams(filter)
-      @fetch _.extend(options,refresh:true,remote:true)
+      @fetch _.extend(options,refresh:true)
     else
-      @reset @query(filter, options)
+      @reset @query filter
 
   # You can apply params to a collection, so that any upcoming requests
   # made to the REST API are made with the key values specified
   applyParams: (params)->
-    @base_params = _( Luca.Collection.baseParams() ).clone() || {}
+    @base_params = _( Luca.Collection.baseParams() ).clone()
     _.extend @base_params, params
 
     @
 
-  register: (collectionManager, key="", collection)->
-    collectionManager ||= Luca.CollectionManager.get()
-
-    unless key.length >= 1
-      throw "Attempt to register a collection without specifying a key." 
-
+  # If this collection is to be registered with some global collection
+  # tracker such as new Luca.CollectionManager() then we will register
+  # ourselves automatically
+  #
+  # To automatically register a collection with the registry, instantiate
+  # it with the registerWith property, which can either be a reference to
+  # the manager itself, or a string in case the manager isn't available
+  # at compile time
+  register: (collectionManager=Luca.CollectionManager.get(), key="", collection)->
+    throw "Can not register with a collection manager without a key" unless key.length >= 1
+    throw "Can not register with a collection manager without a valid collection manager" unless collectionManager?
 
     # by passing a string instead of a reference to an object, we can look up
     # that object only when necessary.  this prevents us from having to create
     # the manager instance before we can define our collections
     if _.isString( collectionManager )
-      collectionManager = Luca.util.resolve( collectionManager )
+      collectionManager = Luca.util.nestedValue( collectionManager, (window || global) )
 
-    unless collectionManager?
-      throw "Attempt to register with a non existent collection manager." 
+    throw "Could not register with collection manager" unless collectionManager
 
     if _.isFunction( collectionManager.add )
       return collectionManager.add(key, collection)
 
-    # If we don't want to use the CollectionManager class, and just want
-    # to cache collection instances on an object, we can do that too.
     if _.isObject( collectionManager )
       collectionManager[ key ] = collection
 
@@ -225,7 +205,7 @@ collection.publicConfiguration
     # fetch will try to pull from the bootstrap if it is setup to do so
     # you can actually make the roundtrip to the server anyway if you pass
     # refresh = true in the options hash
-    return @bootstrap() if @cached_models().length and not (options.refresh is true or options.remote is true)
+    return @bootstrap() if @cached_models().length and not options.refresh
 
     url = if _.isFunction(@url) then @url() else @url
 
@@ -244,11 +224,10 @@ collection.publicConfiguration
   # reset trigger with a function wrapped in _.once
   # so that it only gets run...ahem...once.
   #
+  # that being said, if the collection already has models
   # it won't even bother fetching it it will just run
   # as if reset was already triggered
-  onceLoaded: (fn, options={})->
-    _.defaults(options, autoFetch: true)
-
+  onceLoaded: (fn, options={autoFetch:true})->
     if @length > 0 and not @fetching
       fn.apply @, [@]
       return
@@ -259,7 +238,7 @@ collection.publicConfiguration
       wrapped()
       @unbind "reset", @
 
-    unless @fetching or not !!options.autoFetch
+    unless @fetching or not options.autoFetch
       @fetch()
 
   # ifLoaded is equivalent to binding to the reset trigger with
@@ -277,6 +256,17 @@ collection.publicConfiguration
     unless @fetching is true or !options.autoFetch or @length > 0
       @fetch()
 
+  # parse is very close to the stock Backbone.Collection parse, which
+  # just returns the response.  However, it also triggers a callback
+  # after:response, and automatically parses responses which contain
+  # a JSON root like you would see in rails, if you specify the @root
+  # property.
+  #
+  # it will also update the Luca.Collection.cache with the models from
+  # the response, so that any subsequent calls to fetch() on a bootstrapped
+  # collection, will have updated models from the server.  Really only
+  # useful if you call fetch(refresh:true) manually on any bootstrapped
+  # collection
   parse: (response)->
     @fetching = false
     @trigger "after:response", response
@@ -306,8 +296,6 @@ collection.publicConfiguration
       @clearMethodCache(name)
 
   setupMethodCaching: ()->
-    return unless @cachedMethods?.length > 0 
-
     collection = @
     membershipEvents = ["reset","add","remove"]
     cache = @_methodCache = {}
@@ -322,7 +310,7 @@ collection.publicConfiguration
 
       # wrap the collection method with a basic memoize operation
       collection[ method ] = ()->
-        cache[method].value ||= cache[method].original.apply(collection, arguments)
+        cache[method].value ||= cache[method].original.apply collection, arguments
 
       # bind to events on the collection, which once triggered, will
       # invalidate the cached value.  causing us to have to restore it
@@ -333,33 +321,19 @@ collection.publicConfiguration
       dependencies = method.split(':')[1]
 
       if dependencies
-        watchForChangesOn = dependencies.split(",")
-
-        _( watchForChangesOn ).each (dependency)->
+        for dependency in dependencies.split(",")
           collection.bind "change:#{dependency}", ()->
             collection.clearMethodCache(method: method)
 
-
   # make sure the querying interface from backbone.query is present
   # in the case backbone-query isn't loaded.  without it, it will
   # just return the models
-  #
-  # TODO:
-  # 
-  # Currently the View mixins: Filterable, Sortable, and Paginatable
-  # implement a lot of logic that belongs in this interface.
   query: (filter={},options={})->
     if Backbone.QueryCollection?
-      if _.isFunction(prepare = options.prepare || @prepareQuery)
-        filter = prepare(filter) 
-
-      return Backbone.QueryCollection::query.call(@, filter, options)
+      return Backbone.QueryCollection::query.apply(@, arguments)
     else
       @models
 
-collection.register()
-
-
 # Global Collection Observer
 _.extend Luca.Collection.prototype,
   trigger: ()->
@@ -369,38 +343,18 @@ _.extend Luca.Collection.prototype,
 
     Backbone.View.prototype.trigger.apply @, arguments
 
-Luca.Collection._originalExtend = Backbone.Collection.extend
-
-Luca.Collection.extend = (definition={})->
-  # for backward compatibility
-  definition.concerns ||= definition.concerns if definition.concerns?
-
-  componentClass = Luca.Collection._originalExtend.call(@, definition)
-
-  if definition.concerns? and _.isArray( definition.concerns )
-    for module in definition.concerns
-      Luca.decorate( componentClass ).with( module )
-
-  componentClass
-
-Luca.Collection.namespace = (namespace)->
-  namespace = Luca.util.resolve(namespace) if _.isString(namespace)
-  Luca.Collection.__defaultNamespace = namespace if namespace?
-  Luca.Collection.__defaultNamespace ||= (window || global)
-  Luca.util.read( Luca.Collection.__defaultNamespace )
-  
 # Always include these parameters in every request to your REST API.
 #
 # either specify a function which returns a hash, or just a normal hash
 Luca.Collection.baseParams = (obj)->
-  obj = Luca.util.resolve(obj) if _.isString(obj)
-  Luca.Collection._baseParams = obj if obj
+  return Luca.Collection._baseParams = obj if obj
+
+  if _.isFunction( Luca.Collection._baseParams )
+    return Luca.Collection._baseParams()
 
-  Luca.util.read( Luca.Collection._baseParams )
+  if _.isObject( Luca.Collection._baseParams )
+    Luca.Collection._baseParams
 
-Luca.Collection.resetBaseParams = ()->
-  Luca.Collection._baseParams = {}
-  
 # In order to make our Backbone Apps super fast it is a good practice
 # to pre-populate your collections by what is referred to as bootstrapping
 #

data/src/core/container.coffee

@@ -0,0 +1,374 @@
+# The Component Container
+#
+# The Component Container is a nestable component
+# which are responsible for handling communication between multiple
+# nested views.
+#
+# One: Layout
+#
+# a container is responsible for laying out the nested views
+# and rendering them in a special DOM element
+doLayout = ()->
+  @trigger "before:layout", @
+  @prepareLayout()
+  @trigger "after:layout", @
+
+# and displaying those elements in a way that is
+# optimal for the desired user experience of that view
+# ( i.e seeing only one of them at a time, seeing them side by side )
+applyDOMConfig = (panel, panelIndex)->
+  style_declarations = []
+
+  style_declarations.push "height: #{ (if _.isNumber(panel.height) then panel.height + 'px' else panel.height ) }" if panel.height?
+  style_declarations.push "width: #{ (if _.isNumber(panel.width) then panel.width + 'px' else panel.width ) }" if panel.width?
+  style_declarations.push "float: #{ panel.float }" if panel.float
+
+  config =
+    class: panel?.classes || @componentClass
+    id: "#{ @cid }-#{ panelIndex }"
+    style: style_declarations.join(';')
+    "data-luca-owner" : @name || @cid
+
+  if @customizeContainerEl?
+   config = @customizeContainerEl( config, panel, panelIndex )
+
+  config
+
+# Two: Component Creation
+#
+# A container is responsible for creating and storing references to the nested
+# views that are required for its functioning.
+doComponents = ()->
+
+  @trigger "before:components", @, @components
+  @prepareComponents()
+  @createComponents()
+  @trigger "before:render:components", @, @components
+  @renderComponents()
+  @trigger "after:components", @, @components
+
+
+# Containers are central to Luca.  They are what make it easy to structure
+# your application in a logical way and to specify much of the behavior of
+# complex / composite views at define time using JSON syntax combined with
+# the meta data contained in the Luca component registry.
+_.def('Luca.core.Container').extends('Luca.components.Panel').with
+
+  className: 'luca-ui-container'
+
+  componentTag: 'div'
+  componentClass: 'luca-ui-panel'
+
+  isContainer: true
+
+  hooks:[
+    "before:components"
+    "before:render:components"
+    "before:layout"
+    "after:components"
+    "after:layout"
+    "first:activation"
+  ]
+
+  rendered: false
+
+  components: []
+
+  initialize: (@options={})->
+    _.extend @, @options
+
+    @setupHooks [
+      "before:components"
+      "before:render:components"
+      "before:layout"
+      "after:components"
+      "after:layout"
+      "first:activation"
+    ]
+
+    Luca.View::initialize.apply @, arguments
+
+  # Rendering Pipeline
+  #
+  # A container has nested components.  these components
+  # are automatically rendered inside their own DOM element
+  # and then CSS configuration is generally applied to these
+  # DOM elements.  Each component is assigned to this DOM
+  # element by specifying a @container property on the component.
+  #
+  # Each component is instantiated by looking up its @ctype propery
+  # in the Luca Component Registry.  Then the components are rendered
+  # by having their @render() method called on them.
+  #
+  # Any class which extends Luca.View will have its defined render method
+  # wrapped in a method which triggers "before:render", and "after:render"
+  # before and after the defined render method.
+  #
+  # so you can expect the following, for any container or nested container
+  #
+  # DOM Element Manipulation:
+  #
+  # beforeRender()
+  # beforeLayout()
+  # prepareLayout()
+  # afterLayout()
+  #
+  # Luca / Backbone Component Manipulation
+  #
+  # beforeComponents()
+  # prepareComponents()
+  #   createComponents()
+  #   beforeRenderComponents()
+  #   renderComponents() ->
+  #     calls render() on each component, starting this whole cycle
+  #
+  # afterComponents()
+  #
+  # DOM Injection
+  #
+  # render()
+  # afterRender()
+  #
+  # For Components which are originally hidden
+  # ( card view, tab view, etc )
+  #
+  # firstActivation()
+  #
+  beforeRender: ()->
+    doLayout.call(@)
+    doComponents.call(@)
+    Luca.components.Panel::beforeRender?.apply(@, arguments)
+
+  # Components which inherit from Luca.core.Container can implement
+  # their own versions of this method, if they need to apply any sort
+  # of additional styling / configuration for the DOM elements that
+  # are created to wrap each container.
+  customizeContainerEl: (containerEl, panel, panelIndex)->
+    containerEl
+
+  prepareLayout: ()->
+    container = @
+    @componentContainers = _( @components ).map (component, index)->
+      applyDOMConfig.call(container, component, index)
+
+  prepareComponents: ()->
+    # accept components as an array of strings representing
+    # the luca component type
+    for component in @components when _.isString(component)
+      component = (type: component)
+
+    _( @components ).each (component, index)=>
+      ce = componentContainerElement = @componentContainers?[index]
+
+      # support a variety of the bad naming conventions
+      ce.class = ce.class || ce.className || ce.classes
+
+      if @generateComponentElements
+        panel = @make(@componentTag, componentContainerElement, '')
+        @$append( panel )
+
+      unless component.container?
+        component.container = "##{ componentContainerElement.id }" if @generateComponentElements
+        component.container ||= @$bodyEl()
+
+  # create components is responsible for turning the JSON syntax of the
+  # container's definition into live objects against a given Luca Component
+  # type.
+  #
+  # In addition to this, a container builds an index of the components
+  # which belong to it, so that they can easily be looked up by name
+  createComponents: ()->
+    return if @componentsCreated is true
+
+    map = @componentIndex =
+      name_index: {}
+      cid_index: {}
+
+    @components = _( @components ).map (object, index)=>
+
+      # you can include normal backbone views as components
+      # you will want to make sure your render method handles
+      # adding the views @$el to the appropriate @container.
+
+      # you can also just pass a string representing the component_type
+      component = if Luca.isBackboneView( object )
+        object
+      else
+        object.type ||= object.ctype
+
+        if !object.type?
+          if object.components?
+            object.type = object.ctype = 'container'
+          else
+            object.type = object.ctype = Luca.defaultComponentType
+
+        Luca.util.lazyComponent( object )
+
+      # if you define a @getter property as a string on your component
+      # we will create a function with that name on this container that
+      # allows you to access this component
+      if _.isString( component.getter )
+        @[ component.getter ] = (()-> component) 
+
+      # if we're using base backbone views, then they don't extend themselves
+      # with their passed options, so this is a workaround to get them to
+      # pick up the container config property
+      if !component.container and component.options.container
+        component.container = component.options.container
+
+      if map and component.cid?
+        map.cid_index[ component.cid ] = index
+
+      if map and component.name?
+        map.name_index[ component.name ] = index
+
+      component
+
+    @componentsCreated = true
+
+    @registerComponentEvents() unless _.isEmpty(@componentEvents)
+
+    map
+
+  # Trigger the Rendering Pipeline process on all of the nested
+  # components
+  renderComponents: (@debugMode="")->
+    @debug "container render components"
+
+    container = @ 
+    _(@components).each (component)->
+      component.getParent = ()-> 
+        container 
+
+      try
+        $( component.container ).append( component.el )
+        component.render() 
+      catch e
+        console.log "Error Rendering Component #{ component.name || component.cid }", component
+
+        if _.isObject(e)
+          console.log e.message
+          console.log e.stack
+
+        throw e unless Luca.silenceRenderErrors? is true
+
+  #### Container Activation
+  #
+  # When a container is first activated is a good time to perform
+  # operations which are not needed unless that component becomes
+  # visible.  This first activation event should be relayed to all
+  # of the nested components.  Components which hide / display
+  # other components, such as a CardView or TabContainer
+  # will trigger first:activation on the components as they become
+  # displayed.
+  firstActivation: ()->
+    activator = @
+    @each (component, index)->
+      # apply the first:activation trigger on the component, in the context of the component
+      # passing as arguments the component itself, and the component doing the activation
+      unless component?.previously_activated is true
+        component?.trigger?.call component, "first:activation", component, activator
+        component.previously_activated = true
+
+  #### Underscore Methods For Working with Components
+  pluck: (attribute)-> 
+    _( @components ).pluck attribute
+
+  invoke: (method)->
+    _( @components ).invoke method
+
+  map: (fn)->
+    _( @components ).map(fn)
+    
+  # event binding sugar for nested components
+  #
+  # you can define events like:
+
+  # _.def("MyContainer").extends("Luca.View").with
+  #   componentEvents:
+  #     "component_name before:load" : "mySpecialHandler"
+  componentEvents: {}
+
+  registerComponentEvents: ()->
+    for listener, handler of @componentEvents
+      [componentName,trigger] = listener.split(' ')
+      component = @findComponentByName(componentName)
+      component?.bind trigger, @[handler]
+
+  findComponentByName: (name, deep=false)->
+    @findComponent(name, "name_index", deep)
+
+  findComponentById: (id, deep=false)->
+    @findComponent(id, "cid_index", deep)
+
+  findComponent: (needle, haystack="name", deep=false)->
+    @createComponents() unless @componentsCreated is true
+
+    position = @componentIndex?[ haystack ][ needle ]
+    component = @components?[ position ]
+
+    return component if component
+
+    if deep is true
+      sub_container = _( @components ).detect (component)-> component?.findComponent?(needle, haystack, true)
+      sub_container?.findComponent?(needle, haystack, true)
+
+  each: (fn)->
+    @eachComponent(fn, false)
+
+  # run a function for each component in this container
+  # and any nested containers in those components, recursively
+  # pass false as the second argument to skip the deep recursion
+  eachComponent: (fn, deep=true)->
+    _( @components ).each (component, index)=>
+      fn.call component, component, index
+      component?.eachComponent?.apply component, [fn,deep] if deep
+
+  indexOf: (name)->
+    names = _( @components ).pluck('name')
+    _( names ).indexOf(name)
+
+  activeComponent: ()->
+    return @ unless @activeItem
+    return @components[ @activeItem ]
+
+  componentElements: ()->
+    @$(">.#{ @componentClass }", @$bodyEl())
+
+  getComponent: (needle)->
+    @components[ needle ]
+
+  rootComponent: ()->
+    console.log "Calling rootComponent will be deprecated.  use isRootComponent instead"
+    !@getParent?
+
+  isRootComponent:()->
+    !@getParent?
+
+  getRootComponent: ()->
+    if @rootComponent() then @ else @getParent().getRootComponent()
+    
+  selectByAttribute: (attribute, value, deep=false)->
+    components = _( @components ).map (component)->
+      matches = []
+      test = component[ attribute ]
+
+      matches.push( component ) if test is value
+
+      # recursively traverse our components
+      matches.push component.selectByAttribute?(attribute, value, true) if deep is true
+
+      _.compact matches
+
+    _.flatten( components )
+
+  select: (attribute, value, deep=false)->
+    console.log "Container.select will be replaced by selectByAttribute in 1.0"
+    Luca.core.Container::selectByAttribute.apply(@, arguments)
+
+# This is the method by which a container injects the rendered child views
+# into the DOM.  It will get passed the container object, and the component
+# that is being rendered.  
+Luca.core.Container.componentRenderer = (container, component)->
+  attachMethod = $( component.container )[ component.attachWith || "append" ]
+  attachMethod( component.render().el )