luca 0.8.599 → 0.9.0

data/src/core/collection.coffee

@@ -1,39 +1,77 @@
-# Luca.Collection
-#
-# Luca.Collection is an extenstion of Backbone.Collection which provides
-# a bunch of commonly used patterns for doing things like:
-#
-#   - setting base parameters used on every request to your REST API
-#
-#   - bootstrapping a collection of objects which are
-#     rendered in your markup on page load
-#
-#   - filtering with query string parameters against your API
-#
-#   - automatic interaction with your Luca.CollectionManager class
-#
-#   - make it easier to parse Rails style responses which include the root
-#     by specifying a @root parameter
-#
-#   - use backbone-query if available
-#
-#   - onceLoaded: run a callback once if there are models present, otherwise wait until
-#     the collection fetches
-#
-#   - ifLoaded: run a callback any time the model gets reset, or if there are already models
-#
-Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
+source = 'Backbone.Collection'
+source = 'Backbone.QueryCollection' if Backbone.QueryCollection?
+
+_.def("Luca.Collection").extends( source ).with
+  # 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'.
+  cachedMethods: []
+
+  restoreMethodCache: ()->
+    for name, config of @_methodCache
+      if config.original?
+        config.args = undefined
+        @[ name ] = config.original
+
+  clearMethodCache: (method)->
+    @_methodCache[method].value = undefined
+
+  clearAllMethodsCache: ()->
+    for name, config of @_methodCache
+      @clearMethodCache(name)
+
+  setupMethodCaching: ()->
+    collection = @
+    membershipEvents = ["reset","add","remove"]
+    cache = @_methodCache = {}
+
+    _( @cachedMethods ).each (method)->
+      # store a reference to the unwrapped version of the method
+      # and a placeholder for the cached value
+      cache[ method ] =
+        name: method
+        original: collection[method]
+        value: undefined
+
+      # wrap the collection method with a basic memoize operation
+      collection[ method ] = ()->
+        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
+      for membershipEvent in membershipEvents
+        collection.bind membershipEvent, ()->
+          collection.clearAllMethodsCache()
+
+      dependencies = method.split(':')[1]
+
+      if dependencies
+        for dependency in dependencies.split(",")
+          collection.bind "change:#{dependency}", ()->
+            collection.clearMethodCache(method: method)
 
   initialize: (models=[], @options)->
     _.extend @, @options
 
+    @setupMethodCaching()
+
     @_reset()
 
-    # By specifying a @cached property or method, you can instruct
+    # By specifying a @cache_key property or method, you can instruct
     # Luca.Collection instances where to pull an array of model attributes
     # usually done with the bootstrap functionality provided.
+
+    # DEPRECATION NOTICE
     if @cached
-      @bootstrap_cache_key = if _.isFunction( @cached ) then @cached() else @cached
+      console.log 'The @cached property of Luca.Collection is being deprecated.  Please change to cache_key'
+
+    if @cache_key ||= @cached
+      @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"
@@ -42,7 +80,6 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
     @name ||= @registerAs
     @manager ||= @registerWith
 
-
     # if they specify a
     if @name and not @manager
       @manager = Luca.CollectionManager.get()
@@ -53,7 +90,7 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
     # 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 ||= @cached()
+      @name ||= @cache_key()
       @name = if _.isFunction( @name ) then @name() else @name
 
       unless @private or @anonymous
@@ -81,15 +118,13 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
 
     @__wrapUrl() unless @useNormalUrl is true
 
-    Backbone.Collection.prototype.initialize.apply @, [models, @options]
+    Backbone.Collection::initialize.apply @, [models, @options]
 
     if models
       @reset models, silent: true, parse: options?.parse
 
     @trigger "after:initialize"
 
-  #### Automatic Query String Generation
-  #
   # Luca.Collections will append a query string to the URL
   # and will automatically do this for you without you having
   # to write a special url handler.  If you want to use a normal
@@ -130,13 +165,16 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
     @base_params = Luca.Collection.baseParams()
     @
 
-  # Applying a filter to a collection, will automatically apply
-  # the filter parameters and then call fetch.  passing an additional
-  # options hash will pass these options to the call to @fetch()
-  # setting refresh to true, forcing a remote call to the REST API
+  # if filtering a collection should handle via a call to a REST API
+  # and return the filtered results that way, then leave this true
+  remoteFilter: true
+
   applyFilter: (filter={}, options={})->
-    @applyParams(filter)
-    @fetch _.extend(options,refresh:true)
+    if options.remote? is true
+      @applyParams(filter)
+      @fetch _.extend(options,refresh:true)
+    else
+      @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
@@ -144,8 +182,6 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
     @base_params ||= _( Luca.Collection.baseParams() ).clone()
     _.extend @base_params, params
 
-  # Collection Manager Registry
-  #
   # If this collection is to be registered with some global collection
   # tracker such as new Luca.CollectionManager() then we will register
   # ourselves automatically
@@ -174,7 +210,7 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
 
   # A Luca.Collection will load models from the in memory model store
   # returned from Luca.Collection.cache, where the key returned from
-  # the @cached attribute or method matches the key of the model cache
+  # the @cache_keyattribute or method matches the key of the model cache
   loadFromBootstrap: ()->
     return unless @bootstrap_cache_key
     @reset @cached_models()
@@ -186,7 +222,7 @@ Luca.Collection = (Backbone.QueryCollection || Backbone.Collection).extend
 
   # cached_models is a reference to the Luca.Collection.cache object
   # key'd on whatever this collection's bootstrap_cache_key is set to be
-  # via the @cached() interface
+  # via the @cache_key() interface
   cached_models: ()->
     Luca.Collection.cache( @bootstrap_cache_key )
 
@@ -286,8 +322,6 @@ _.extend Luca.Collection.prototype,
 
     Backbone.View.prototype.trigger.apply @, arguments
 
-#### Base Parameters
-#
 # Always include these parameters in every request to your REST API.
 #
 # either specify a function which returns a hash, or just a normal hash
@@ -300,14 +334,12 @@ Luca.Collection.baseParams = (obj)->
   if _.isObject( Luca.Collection._baseParams )
     Luca.Collection._baseParams
 
-#### Bootstrapped Models ( stuff loaded on page load )
-#
 # 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
 #
 # Luca.Collections make it easier for you to do this cleanly and automatically
 #
-# by specifying a @cached property or method in your collection definition
+# by specifying a @cache_keyproperty or method in your collection definition
 # Luca.Collections will automatically look in this space to find models
 # and avoid a roundtrip to your API unless explicitly told to.
 Luca.Collection._bootstrapped_models = {}
@@ -321,4 +353,4 @@ Luca.Collection.bootstrap = (obj)->
 # roundtrips to the API
 Luca.Collection.cache = (key, models)->
   return Luca.Collection._bootstrapped_models[ key ] = models if models
-  Luca.Collection._bootstrapped_models[ key ] || []
+  Luca.Collection._bootstrapped_models[ key ] || []

data/src/core/container.coffee

@@ -1,14 +1,62 @@
-#### The Component Container
+# The Component Container
 #
 # The Component Container is a nestable component
-# which is responsible for laying out the many components
-# it contains, assigning them to a DOM container, and
-# automatically instantiating and rendering the components
-# in their proper place.
-_.component('Luca.core.Container').extends('Luca.View').with
+# 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
@@ -29,11 +77,18 @@ _.component('Luca.core.Container').extends('Luca.View').with
   initialize: (@options={})->
     _.extend @, @options
 
-    @setupHooks( Luca.core.Container::hooks )
+    @setupHooks [
+      "before:components"
+      "before:render:components"
+      "before:layout"
+      "after:components"
+      "after:layout"
+      "first:activation"
+    ]
 
     Luca.View::initialize.apply @, arguments
 
-  #### Rendering Pipeline
+  # Rendering Pipeline
   #
   # A container has nested components.  these components
   # are automatically rendered inside their own DOM element
@@ -80,62 +135,52 @@ _.component('Luca.core.Container').extends('Luca.View').with
   # firstActivation()
   #
   beforeRender: ()->
-    @debug "container before render"
-    @doLayout()
-    @doComponents()
-
-  doLayout: ()->
-    @debug "container do layout"
-    @trigger "before:layout", @
-    @prepareLayout()
-    @trigger "after:layout", @
-
-  doComponents: ()->
-    @debug "container do components"
-
-    @trigger "before:components", @, @components
-    @prepareComponents()
-    @createComponents()
-    @trigger "before:render:components", @, @components
-    @renderComponents()
-    @trigger "after:components", @, @components
-
-  applyPanelConfig: (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 =
-      classes: panel?.classes || @componentClass
-      id: "#{ @cid }-#{ panelIndex }"
-      style: style_declarations.join(';')
-
-  # prepare layout is where you would perform the DOM element
-  # creation / manipulation for how your container lays out
-  # its components.  Minimally you will want to set the
-  # container property on each component.
-  prepareLayout: ()->
-    @debug "container prepare layout"
-    @componentContainers = _( @components ).map (component, index) =>
-      @applyPanelConfig.apply @, [ component, index ]
+    doLayout.call(@)
+    doComponents.call(@)
+    Luca.components.Panel::beforeRender?.apply(@, arguments)
 
-    if @appendContainers
-      _( @componentContainers ).each (container)=>
-        @$el.append Luca.templates["containers/basic"](container) unless container.appended?
-        container.appended = true
+  # 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
 
-  # prepare components is where you would set necessary object
-  # attributes on the components themselves.
+  prepareLayout: ()->
+    container = @
+    @componentContainers = _( @components ).map (component, index)->
+      applyDOMConfig.call(container, component, index)
+
+  # prepare components is where each component gets assigned
+  # a container to be rendered into.  if @appendContainers is
+  # set to true, then the view will automatically $append()
+  # elements created via Backbone.View::make() to the body element of the view
   prepareComponents: ()->
-    @debug "container prepare components"
-    @components = _( @components ).map (object, index) =>
-      panel = @componentContainers[ index ]
-      object.container = if @appendContainers then "##{ panel.id }" else @el
+    # 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)=>
+      container = @componentContainers?[index]
+
+      # support a variety of the bad naming conventions
+      container.class = container.class || container.className || container.classes
+
+      if @appendContainers
+        panel = @make(@componentTag, container, '')
+        @$append( panel )
 
-      object
+      unless component.container?
+        component.container = "##{ container.id }" if @appendContainers
+        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
 
@@ -144,17 +189,28 @@ _.component('Luca.core.Container').extends('Luca.View').with
       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
-      component = if _.isObject( object ) and object.render and object.trigger
+      # 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.ctype ||= Luca.defaultComponentType || "template"
+        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 we're using base backbone views, then they don't extend themselves
-      # with their passed options, so this is a workaround
+      # 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
 
@@ -167,6 +223,9 @@ _.component('Luca.core.Container').extends('Luca.View').with
       component
 
     @componentsCreated = true
+
+    @registerComponentEvents() unless _.isEmpty(@componentEvents)
+
     map
 
   # Trigger the Rendering Pipeline process on all of the nested
@@ -181,8 +240,11 @@ _.component('Luca.core.Container').extends('Luca.View').with
         component.render()
       catch e
         console.log "Error Rendering Component #{ component.name || component.cid }", component
-        console.log e.message
-        console.log e.stack
+
+        if _.isObject(e)
+          console.log e.message
+          console.log e.stack
+
         throw e unless Luca.silenceRenderErrors? is true
 
   #### Container Activation
@@ -195,13 +257,12 @@ _.component('Luca.core.Container').extends('Luca.View').with
   # will trigger first:activation on the components as they become
   # displayed.
   firstActivation: ()->
-    _( @components ).each (component)=>
-      activator = @
-
+    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?.apply component, ["first:activation", [component, activator] ]
+        component?.trigger?.call component, "first:activation", component, activator
         component.previously_activated = true
 
   #### Component Finder Methods
@@ -219,6 +280,22 @@ _.component('Luca.core.Container').extends('Luca.View').with
 
     _.flatten( components )
 
+  # 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)
 
@@ -238,12 +315,15 @@ _.component('Luca.core.Container').extends('Luca.View').with
       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)=>
-      fn.apply component, [component]
+    _( @components ).each (component, index)=>
+      fn.call component, component, index
       component?.eachComponent?.apply component, [fn,deep] if deep
 
   indexOf: (name)->
@@ -254,7 +334,8 @@ _.component('Luca.core.Container').extends('Luca.View').with
     return @ unless @activeItem
     return @components[ @activeItem ]
 
-  componentElements: ()-> $(".#{ @componentClass }", @el)
+  componentElements: ()->
+    $(">.#{ @componentClass }", @el)
 
   getComponent: (needle)->
     @components[ needle ]