luca 0.9.8 → 0.9.9

data/app/assets/javascripts/luca/concerns/query_collection_bindings.coffee

@@ -21,6 +21,12 @@ Luca.concerns.QueryCollectionBindings =
           
     Luca.util.readAll(query)
 
+  getRemoteQuery: (options = {}) ->
+    @getQuery(options)
+
+  getLocalQuery: (options = {}) ->
+    @getQuery(options)
+
   # Private: returns the query that is applied to the underlying collection.
   # accepts the same options as Luca.Collection.query's initial query option.
   getQueryOptions: (options={})-> 
@@ -34,7 +40,7 @@ Luca.concerns.QueryCollectionBindings =
   # responds to @query() then it will use that interface. 
   getModels: (query,options)->
     if @collection?.query
-      query ||= @getQuery()
+      query ||= @getLocalQuery()
       options ||= @getQueryOptions()
       options.prepare ||= @prepareQuery
 

data/app/assets/javascripts/luca/concerns/state_model.coffee

@@ -1,44 +1,58 @@
+
+stateModel = Luca.register("Luca.ViewState").extends("Luca.Model")
+
 Luca.concerns.StateModel =
+  __onModelChange: (args...)->
+    statefulView = @
+    state = statefulView.state
+
+    @trigger.call(statefulView, "state:change", args... )
+
+    for changed, value of state.changedAttributes()
+      @trigger.call statefulView, "state:change:#{ changed }", state, value, state.previous(changed)
+
   __initializer: ()->
     @stateful = @stateAttributes if @stateAttributes?
 
     return unless @stateful?
-    return if @state? 
     
+    statefulView = @
+
     if _.isObject(@stateful) and not @defaultState?
       @defaultState = @stateful 
 
-    @state = new Backbone.Model(@defaultState || {})
-    @set = _.bind(@state.set, @state) 
-    @get = _.bind(@state.get, @state) 
+    @state ||= new Luca.ViewState(@defaultState || {})
+
+    view = @
+
+    @get = ()->
+      view.state.get.apply(view.state, arguments)
+
+    @set = ()->
+      view.state.set.apply(view.state, arguments)
 
     for key, value of @state.toJSON()
       hook = "on" + _.str.capitalize(key) + "Change"
       getter = "get" + _.str.capitalize(key) 
       unless _.isFunction(@[getter])
         1
-        #console.log("State Change Getter", getter)
-        # @[getter] = ()=> @state.get(key)
-        # WE COULD CREATE AUTO GETTERS HERE
-
       if _.isFunction(@[hook])
         1
-        #console.log("State Change Hook", hook)
-        # @stateChangeEvents[ key ] = hook
-        # WE COULD AUTO BIND TO STATE CHANGE EVENTS HERE
-
-    unless _.isEmpty(@stateChangeEvents)
-      for attribute, handler of @stateChangeEvents
-        fn = if _.isString(handler) then @[handler] else handler 
-        
-        if attribute is "*"
-          @on "state:change", fn, @
-        else
-          @on "state:change:#{ attribute }", fn, @
-
-    @state.on "change", (state)=>
-      @trigger "state:change", state
-
-      for changed, value of state.changedAttributes()
-        @trigger "state:change:#{ changed }", state, value, state.previous(changed)
 
+    Luca.concerns.StateModel.__setupModelBindings.call(@, "on")
+
+  __setupModelBindings: (direction="on")->
+    statefulView = @
+    for attribute, handler of @stateChangeEvents
+      fn = if _.isString(handler) then statefulView[handler] else handler 
+      
+      if attribute is "*"
+        statefulView[direction]("state:change", fn, statefulView)
+      else
+        statefulView[direction]("state:change:#{ attribute }", fn, statefulView)
+
+    # Any time there is a model change event on the internal state machine
+    # we will trigger a general state:change event on the component as well
+    # as individual state:change:attribute events
+    state = statefulView.state 
+    statefulView.state[direction]("change", Luca.concerns.StateModel.__onModelChange, statefulView)

data/app/assets/javascripts/luca/concerns/templating.coffee

@@ -4,8 +4,10 @@ Luca.concerns.Templating =
 
     if template = @bodyTemplate
       @$el.empty()
+
       try
         templateContent = Luca.template(template, templateVars)      
       catch e
-        console.log "Error Rendering #{ bodyTemplate} in View: #{ @identifier?() || @name || @cid }"
+        console.log "Error Rendering #{ template} in View: #{ @identifier?() || @name || @cid }"
+
       Luca.View::$html.call(@, templateContent)

data/app/assets/javascripts/luca/config.coffee

@@ -25,9 +25,12 @@ Luca.enableGlobalObserver = Luca.config.enableGlobalObserver = false
 # for what it is best at, and not try to solve this
 # problem on our own!
 Luca.config.enableBoostrap = Luca.config.enableBootstrap = true
+Luca.config.fluidWrapperClass = "container-fluid"
+Luca.config.wrapperClass = "container"
 
 Luca.config.enhancedViewProperties = true
 
+# Need to replace this with something like keymaster.js
 Luca.keys = Luca.config.keys =
   ENTER: 13
   ESCAPE: 27
@@ -37,6 +40,7 @@ Luca.keys = Luca.config.keys =
   KEYDOWN: 40
   SPACEBAR: 32
   FORWARDSLASH: 191
+  TAB: 9
 
 Luca.config.toolbarContainerClass = "toolbar-container"
 
@@ -47,3 +51,4 @@ Luca.keyMap = Luca.config.keyMap = _( Luca.keys ).inject (memo, value, symbol)->
 , {}
 
 Luca.config.showWarnings = true
+Luca.config.default_socket_port = 9292

data/app/assets/javascripts/luca/containers/card_view.coffee

@@ -1,8 +1,3 @@
-component = Luca.define         "Luca.containers.CardView"
-component.extends               "Luca.Container"
-
-component.aliases               "Luca.PageView"
-#
 # The CardView is a type of Container which has many sub-views
 # which are only going to be visible one at a time.  A CardView
 # allows you to @activate() its cards, navigate through them using
@@ -23,75 +18,70 @@ component.aliases               "Luca.PageView"
 #   cardView.activeComponent().name # => "one"
 #   cardView.activate('two')
 #   cardView.activeComponent().name # => "two"
-#
-component.defaults
-
-  className: 'luca-ui-card-view-wrapper'
+component = Luca.register       "Luca.containers.CardView"
+component.extends               "Luca.Container"
 
+component.publicConfiguration
   activeCard: 0
-
   components: []
 
+component.classInterface
+  # When the activate method is called and passed a callback
+  # what context should we run that callback in?  Default is
+  # to call the callback in the context of the component that
+  # is currently being activated
+  activationContext: "current"
+
+component.privateConfiguration
+  # Will automatically call beforeCardSwitch and afterCardSwitch
+  # methods if they exist on this view.  These events will be triggered
+  # in response to a call to @activate()
   hooks:[
     'before:card:switch',
     'after:card:switch'
   ]
 
+  # Which css class should we apply to each of the cards
   componentClass: 'luca-ui-card'
-  generateComponentElements: true
-
-  initialize: (@options)->
-    @components ||= @pages ||= @cards 
-    Luca.Container::initialize.apply @,arguments
-    @setupHooks(@hooks)
-
-    @defer( @simulateActivationEvent, @ ).until("after:render")
-
-  simulateActivationEvent: ()->
-    c = @activeComponent()
 
-    if c? and @$el.is(":visible")
-      c?.trigger "activation", @, c, c 
-
-  prepareComponents: ()->
-    Luca.Container::prepareComponents?.apply(@, arguments)
-    @componentElements().hide()
-    @activeComponentElement().show()
-
-  activeComponentElement: ()->
-    @componentElements().eq( @activeCard )
-
-  activeComponent: ()->
-    @getComponent( @activeCard )
-
-  customizeContainerEl: (containerEl, panel, panelIndex)->
-    containerEl.style += if panelIndex is @activeCard then "display:block;" else "display:none;"
-
-    containerEl
+  # Should we generate elements to append each component?
+  generateComponentElements: true
 
+component.publicMethods
+  # Returns true if at the first 
   atFirst: ()->
     @activeCard is 0
 
+  # Returns true if we're at the last card
   atLast: ()->
     @activeCard is @components.length - 1
 
+  # Activate the next component.  If at the last, do nothing.
   next: ()->
     return if @atLast()
     @activate( @activeCard + 1)
 
+  # Activate the previous component.  If at the first, do nothing.
   previous: ()->   
     return if @atFirst()
     @activate( @activeCard - 1)
 
+  # Activates the next component after the current one.
+  # If at the last component, it will activate the first.
   cycle: ()->
     nextIndex = if @atLast() then 0 else @activeCard + 1
     @activate( nextIndex )
 
-  find: (name)-> Luca(name)
-
-  firstActivation: ()->
-    @activeComponent()?.trigger "first:activation", @, @activeComponent()
+  # Find a direct component on this card by its name.
+  find: (name)-> 
+    _( @components ).detect (c)-> 
+      c.name is name
 
+  # Activates the component at the specified index.  You may optionally specify
+  # the name of the component you wish to activate.  You can pass false as your second
+  # argument, to disable the event handling that occurs when you activate a card on this container.
+  # If you pass a callback function to the activate method, that callback will be executed within
+  # the context of the activated component. 
   activate: (index, silent=false, callback)->
     if _.isFunction(silent)
       silent = false
@@ -100,14 +90,12 @@ component.defaults
     return if index is @activeCard
 
     previous = @activeComponent()
-    current = @getComponent(index)
 
-    if !current
-      index = @indexOf(index)
-      current = @getComponent( index )
+    current = @getComponent(index)
 
-    unless current
-      return
+    if !current?
+      index = @indexOf(index) 
+      return unless current = @getComponent(index)
 
     unless silent is true
       @trigger "before:card:switch", previous, current
@@ -120,10 +108,15 @@ component.defaults
     @componentElements().hide()
 
     unless current.previously_activated is true
-      current.trigger "first:activation"
+      if current.rendered is true
+        current.trigger "first:activation"
+      else
+        current.once "after:render", ()->
+          current.rendered = true
+          current.trigger("first:activation")
       current.previously_activated = true
 
-    @activeCard = index
+    @activeCard = index 
     @activeComponentElement().show()
 
     unless silent is true
@@ -139,5 +132,47 @@ component.defaults
     if _.isFunction(callback)
       callback.apply activationContext, [@,previous,current]
 
+component.privateMethods
+  initialize: (@options)->
+    @components ||= @pages ||= @cards 
+    Luca.Container::initialize.apply @,arguments
+    @setupHooks(@hooks)
+    @defer( @simulateActivationEvent, @ ).until("after:render")
+
+  # Simulates the activation event being triggered on the
+  # active component that gets rendered inside of this card view. 
+  simulateActivationEvent: ()->
+    c = @activeComponent()
+
+    if c? and (@visible || @$el.is(":visible"))
+      c?.trigger "activation", @, c, c 
+      if !c.previously_activated
+        c.trigger "first:activation"
+        c.previously_activated = true
+
+  prepareComponents: ()->
+    Luca.Container::prepareComponents?.apply(@, arguments)
+    @componentElements().hide()
+    @activeComponentElement().show()
+
+  activeComponentElement: ()->
+    @componentElements().eq( @activeCard )
+
+  activeComponent: ()->
+    @getComponent( @activeCard )
+
+  customizeContainerEl: (containerEl, panel, panelIndex)->
+    containerEl.style += if panelIndex is @activeCard then "display:block;" else "display:none;"
+
+    containerEl
+
+
+
+  # The first time activate event is triggered on this component
+  # the @firstActivation hook is responsible for relaying that event
+  # to our @activeComponent() so that it knows it has been activated.
+  firstActivation: ()->
+    if activeComponent = @activeComponent()
+      activeComponent.trigger "first:activation", @, @activeComponent()
 
-Luca.containers.CardView.activationContext = "current"
+component.register()

data/app/assets/javascripts/luca/containers/container.coffee

@@ -1,3 +1,148 @@
+# The Luca.Container is the heart and soul of the Luca framework 
+# and the component driven design philosophy.  The central idea
+# is that every component should be designed as an isolated unit
+# which completely encapsulates its features.  It should not know about
+# other components outside of it.
+# 
+# It is the responsibility of a `Luca.Container` to define its 
+# child `@components`, render them, and broker communication between them
+# in response to events which occur in the user interface.  
+#
+# A common use case for this would be a page which has a filter form, and
+# a grid of search results.  The fields in the filter form are used to 
+# filter the table.  Neither the form or the table know about each other, 
+# since both can be used in other contexts.  A `Luca.Container` would be used
+# to relay events from the form to the table, and in doing so create a higher
+# level component which can be extended and re-used. 
+#
+# #### Using a container to combine a Filter View and Results Table 
+#
+#         form = Luca.register    "App.views.FilterForm"
+#         form.extends            "Luca.components.FormView"
+#
+#         form.contains
+#           type:   "text"
+#           label:  "Filter by"
+#           name:   "filter_text"
+#         ,
+#           type:   "button"
+#           className: "filter"
+#           value:  "Filter"          
+#
+#
+#         form.defines
+#           toolbar: false 
+# 
+# Elsewhere, we have a table that lists records in a collection:
+#         
+#         table = Luca.register     "App.views.ResultsTable"
+#         table.extends             "Luca.components.TableView"
+#         table.defines 
+#           striped: true
+#           collection: "components"
+#           columns:[
+#             header: "Component Class"
+#             reader: "class_name"
+#           ,
+#             header: "Component Type Alias"
+#             reader: "type_alias"
+#           ]
+#
+# We can join these two components together by declaring their relationship
+# in a `Luca.Container`.  Remember the components we defined above are just
+# prototypes.  We can override specific instance configuration and properties 
+# in our container.
+#
+# #### Container Example
+#
+#         container = Luca.register     "App.views.ComponentFinder"
+#         container.extends             "Luca.Container"
+#       
+#       # This is the same as defining a components property on the component.
+#       # The type alias is derived from the name of the component.  It is 
+#       # a short hand way of referencing a component you might reuse a lot.
+#       container.contains
+#         type: "filter_form"
+#         role: "filter"
+#       ,
+#         type: "results_table"
+#         # change the prototype's default 
+#         striped: false
+#         role: "results"
+#         filterable: true
+#
+#       # A Container will generally define some component event bindings
+#       # and handler methods to handle the communication between its sub
+#       # components.  By default a container is able to access events
+#       # from all of its descendants in the hierarchy. 
+#       container.defines
+#         # These will be applied to each of our components.
+#         defaults:
+#           attributes:
+#             "data-attribute": "whatever"
+#
+#         componentEvents:
+#           # Any time any of our child components emit
+#           # the on:change event, pass it to the filterTable method
+#           "* on:change" : "filterTable"
+#
+#         # Communicates between the filter and the table's
+#         # underlying collection.  NOtice the use of the @role
+#         # property.  It automatically creates getter helpers for us.
+#         filterTable: ()->
+#           filter = @getFilter()
+#           results = @getResults()
+#           # filter.getValues() is a hash of each field and its value
+#           results.applyFilter( filter.getValues() )
+#         
+# ### DOM Layout Configuration
+#
+# Another responsibility of the container is to structurally layout its
+# child components in the DOM.  There are a number of different 
+# options available depending on how you need to do this.  By default,
+# a `Luca.Container` will simply append the @$el of all of its views
+# to its own.
+#
+# The `Luca.components.Controller` is a container which hides every page
+# but the active page.  Similarly, there is the `Luca.containers.TabView`
+# which does the same thing, but renders a tab selector menu for you.  You
+# can create any type of interface you want using containers. 
+#
+# To make this easy for you, you can do a few different things:
+#
+# #### Use the Twitter Bootstrap Fluid Grid
+#
+#         container = Luca.register "App.views.ColumnLayout" 
+#         container.extends         "App.views.ComponentFinder"
+#
+#         container.contains
+#           span: 4
+#           type: "filter_form"
+#           role: "filter"
+#         ,
+#           span: 8
+#           type: "results_table"
+#           role: "results"
+#
+#         container.defines
+#           rowFluid: true
+#
+# #### Using a layout template with CSS Selectors
+# If you find yourself needing a container view with a complicated
+# visual layout, you can provide your own DOM template as a `@bodyTemplate`
+# and assign each child view in `@components` to its own specific CSS selector.
+#
+#         ... 
+#         container.contains
+#           role: "filter"
+#           container: "#filter-wrapper-dom-selector"
+#         ,
+#           role: "results"
+#           container: "#results-wrapper-dom-selector"
+#         ...
+#         container.defines
+#           # assumes the template will provide the CSS selectors used above 
+#           bodyTemplate: "layouts/custom_template"
 container = Luca.register         "Luca.Container"
 
 container.extends                 "Luca.Panel"
@@ -11,36 +156,95 @@ container.triggers                "before:components",
 
 container.replaces                "Luca.Container"
 
-container.defines
-  className: 'luca-ui-container'
-
-  componentTag: 'div'
-
-  componentClass: 'luca-ui-panel'
-
-  isContainer: true
+container.publicConfiguration
+  # @components should contain a list of object configurations for child view(s)
+  # of this container.  The values specified in the configuration object will override the 
+  # values defined as properties and methods on your view prototypes.
+  #
+  # There are special properties you can define in your components configuration items 
+  # that will effect the container:
+  #
+  # - role:       will create a camelized getter for you on the container.  e.g. when role is `my_custom_role`, 
+  #               the container will have a method `getMyCustomRole()` that returns that child view.
+  #
+  # - name:       a name for the child view.  this allows you to access the component by name using 
+  #               the find() method on the container.
+  #
+  # - type:       a type alias from the component registry.  type alias are underscore'd strings 
+  #               matching the component class name.  e.g. App.views.MyCustomView type alias is `my_custom_view`
+  #
+  # - component:  a convenience property for setting type, role, and name to be equal. 
+  components:[]
 
-  rendered: false
+  # The `@defaults` property is an object of configuration parameters which will be set
+  # on each child component.  Values explicitly defines in the components config will 
+  # take precedence over the default.
+  defaults: {}
 
-  components: []
+  # The `@extensions` property is useful when you are subclassing a container view
+  # which already defines an array of components, and you want to specifically override
+  # properties and settings on the children. The `@extensions` property expects either: 
+  #
+  # An object whose keys match the names of the `@role` property defined on the child components.
+  # The value should be an object which will override any values defined on the parent class.
+  #
+  # or:
+  # 
+  # An array of objects in the same array position / index as the target child view you wish to extend.
+  extensions: {}
 
   # @componentEvents provides declarative syntax for responding to events on
   # the components in this container.  the format of the syntax is very similar
   # to the other event binding helpers:
   #
-  #   component_accessor component:trigger
-  #
-  # where component_accessor is either the name of the role, or a method on the container
-  # which will find the component in question.
-  #
-  # myContainer = new Luca.Container
-  #   componentEvents:
-  #     "name component:trigger"    : "handler"
-  #     "role component:trigger"    : "handler"
-  #     "getter component:trigger"  : "handler"
+  # `component_accessor component:trigger`
   #
+  # where component_accessor is either the name of the component, or a the role 
+  # property on the component, component:trigger is the event that component fires.
+  # handler is a method on the container which will respond to the child component event.
+  # <pre>
+  #       myContainer = new Luca.Container
+  #         componentEvents:
+  #           "name component:trigger"    : "handler"
+  #           "role component:trigger"    : "handler"
+  #           "getter component:trigger"  : "handler"
+  #         components:[
+  #           name: "name"
+  #         ]
+  # </pre>
   componentEvents: {}
 
+container.privateConfiguration
+  className: 'luca-ui-container'
+
+  # This is a convenience attribute for identifying
+  # views which are luca containers
+  isContainer: true
+
+  # if set to true, we will generate DOM elements
+  # to wrap each of our components in.  This should 
+  # generally be avoided IMO as it pollutes the DOM, 
+  # but is currently necessary for some container implementations
+  generateComponentElements: false
+
+  # if set to true, the DOM elements which wrap
+  # our components will be emptied prior to rendering
+  # the component inside this container.
+  emptyContainerElements: false
+
+  # if @generateComponentElements is true, which tag should this 
+  # container wrap our components in?
+  componentTag: 'div'
+
+  # if @generateComponentElements is true, which class should we 
+  # apply to the container elements which wrap our components?
+  componentClass: 'luca-ui-panel'
+
+  rendered: false
+
+
+
+container.privateMethods
   initialize: (@options={})->
     _.extend @, @options
 
@@ -60,52 +264,12 @@ container.defines
 
     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()
-  #
+  # Removing a container will call remove on all of the nested components as well.
+  remove: ()->
+    Luca.View::remove.apply(@, arguments)
+    @eachComponent (component)->
+      component.remove?()
+      
   beforeRender: ()->
     doLayout.call(@)
     doComponents.call(@)
@@ -144,7 +308,6 @@ container.defines
   prepareComponents: ()->
     container = @
 
-
     _( @components ).each (component, index)=>
       ce = componentContainerElement = @componentContainers?[index]
 
@@ -205,8 +368,17 @@ container.defines
       component = if Luca.isComponent( object )
         object
       else
+        # if a component is tagged with a @component property
+        # we assume this is the kind of singleton component
+        # and set the type, role and name to the same value (if they're blank)
+        if object.component? and not (object.type || object.ctype)
+          object.type = object.component
+          object.name ||= object.component
+          object.role ||= object.component
+
         object.type ||= object.ctype
 
+        # guess the type based on the properties
         if !object.type?
           # TODO
           # Add support for all of the various components property aliases
@@ -238,8 +410,7 @@ container.defines
 
     map
 
-  # Trigger the Rendering Pipeline process on all of the nested
-  # components
+  # Trigger the Rendering Pipeline process on all of the nested components
   renderComponents: (@debugMode="")->
     @debug "container render components"
 
@@ -260,10 +431,14 @@ container.defines
           # so look into wtf is going on and which components are problematic
           containerElement = @$( component.container ).eq(0) if containerElement.length is 0
 
+        if @emptyContainerElements is true
+          containerElement.empty()
+
         containerElement.append( component.el )
 
         component.trigger "after:attach"
         component.render()
+        component.rendered = true
       catch e
         console.log "Error Rendering Component #{ component.name || component.cid }", component
 
@@ -273,8 +448,6 @@ container.defines
 
         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
@@ -291,28 +464,7 @@ container.defines
         component?.trigger?.call component, "first:activation", component, activator
         component.previously_activated = true
 
-  #### Underscore Methods For Working with Components
-  _: ()-> _( @components )
-
-  pluck: (attribute)->
-    @_().pluck(attribute)
-
-  invoke: (method)->
-    @_().invoke(method)
-
-  select: (fn)->
-    @_().select(fn)
-
-  detect: (fn)->
-    @_().detect(attribute)
-
-  reject: (fn)->
-    @_().reject(fn)
-
-  map: (fn)->
-    @_().map(fn)
-
-  registerComponentEvents: (eventList)->
+  registerComponentEvents: (eventList, direction="on")->
     container = @
 
     for listener, handler of (eventList || @componentEvents||{})
@@ -331,31 +483,71 @@ container.defines
           console.log "Error registering component event", listener, componentNameOrRole, eventId
           throw "Invalid component event definition: #{ componentNameOrRole }"
 
-        component?.bind eventId, @[handler], container
+        component[direction](eventId, @[handler], container)
+
+container.publicMethods
+  # Returns an underscore.js object that wraps the components array
+  _: ()-> _( @components )
+
+  # Return the value of attribute of each component 
+  pluck: (attribute)->
+    @_().pluck(attribute)
+
+  # Invoke the passed method name on each component
+  invoke: (method)->
+    @_().invoke(method)
+
+  # Select any component for which the passed iterator returns true
+  select: (iterator)->
+    @_().select(iterator)
 
+  # Find the first matching component for which the passed iterator returns true
+  detect: (iterator)->
+    @_().detect(iterator)
 
+  # Return a list of components without the components for which the passed iterator returns true 
+  reject: (iterator)->
+    @_().reject(iterator)
+
+  # Run the passed iterator over each component and return the result in an array
+  map: (fn)->
+    @_().map(fn)
+
+  # Returns a list of nested components which are also containers
   subContainers: ()->
     @select (component)->
       component.isContainer is true
 
   roles: ()->
-    _( @allChildren() ).pluck('role')
+    _( @allChildren() ).chain().pluck('role').compact().value()
 
   allChildren: ()->
     children = @components
-    grandchildren = _( @subContainers() ).invoke('allChildren')
+
+    grandchildren = _( @subContainers() ).map (component)->
+      component?.allChildren?()
+
     _([children,grandchildren]).chain().compact().flatten().value()
 
+  # Find a direct component on this card by its name.
+  find: (name)-> 
+    _( @components ).detect (c)-> 
+      c.name is name    
+
   findComponentForEventBinding: (nameRoleOrGetter, deep=true)->
     @findComponentByName(nameRoleOrGetter, deep) || @findComponentByGetter( nameRoleOrGetter, deep ) || @findComponentByRole( nameRoleOrGetter, deep )
 
   findComponentByGetter: (getter, deep=false)->
     _( @allChildren() ).detect (component)->
-      component.getter is getter
+      component?.getter is getter
 
   findComponentByRole: (role,deep=false)->
     _( @allChildren() ).detect (component)->
-      component.role is role or component.type is role or component.ctype is role
+      component?.role is role or component?.type is role or component?.ctype is role
+
+  findComponentByType: (desired,deep=false)->
+    _( @allChildren() ).detect (component)->
+      desired is (component.type || component.ctype)
 
   findComponentByName: (name, deep=false)->
     _( @allChildren() ).detect (component)->
@@ -389,10 +581,17 @@ container.defines
       fn.call component, component, index
       component?.eachComponent?.apply component, [fn,deep] if deep
 
-  indexOf: (name)->
+  indexOfComponentName: (name)->
     names = _( @components ).pluck('name')
     _( names ).indexOf(name)
 
+  indexOf: (nameOrComponent)->
+    if _.isString(nameOrComponent)
+      return @indexOfComponentName(nameOrComponent)
+
+    if _.isObject(nameOrComponent)
+      _( @components ).indexOf( nameOrComponent )
+
   activeComponent: ()->
     return @ unless @activeItem
     return @components[ @activeItem ]
@@ -425,6 +624,8 @@ container.defines
     _.flatten( components )
 
 
+container.register()
+
 # 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.
@@ -464,22 +665,21 @@ createGetterMethods = ()->
   container = @
 
   childrenWithGetter = _( @allChildren() ).select (component)->
-    component.getter?
+    component?.getter?
 
   _( childrenWithGetter ).each (component)->
-    container[ component.getter ] ||= ()->
-      component
+    container[ component.getter ] ||= ()-> component
 
 createMethodsToGetComponentsByRole = ()->
   container = @
 
   childrenWithRole = _( @allChildren() ).select (component)->
-    component.role?
+    component?.role?
 
   _( childrenWithRole ).each (component)->
     getter = _.str.camelize( "get_" + component.role )
-    container[ getter ] ||= ()->
-      component
+    getterFn = ()-> component
+    container[ getter ] ||= _.bind(getterFn, container) 
 
 doComponents = ()->
   @trigger "before:components", @, @components
@@ -499,9 +699,6 @@ doComponents = ()->
 validateContainerConfiguration = ()->
   true
 
-
-# Private Helpers
-#
 # indexComponent( component ).at( index ).in( componentsInternalIndexMap )
 indexComponent = (component)->
   at: (index)->