luca 0.9.8 → 0.9.9

data/app/assets/javascripts/luca/components/collection_view.coffee

@@ -1,9 +1,51 @@
-# The CollectionView handles rendering a set of models from a 
-# collection
-collectionView = Luca.register      "Luca.components.CollectionView"
+# The `Luca.CollectionView` renders models from a `Luca.Collection` into multiple
+# elements, and provides methods for filtering, paginating, sorting the underlying
+# collection and re-rendering the contents of its `@el` accordingly.
+#
+# #### Basic Example
+#     collectionView = Luca.register  "App.views.Books"
+#     collectionView.extends          "Luca.CollectionView"
+#
+#     collectionView.defines
+#       itemProperty: "author"
+#       collection: new Luca.Collection([
+#         author: "George Orwell"
+#         title:  "Animal Farm"
+#       ,
+#         author: "Noam Chomsky"
+#         title: "Manufacturing Consent"
+#       ])
+#
+#     view = new App.views.Books()
+# #### Extending it to make it Filterable and Paginatable
+#     filterable = Luca.register    "App.views.FilterableBooks"
+#     filterable.extends            "App.views.Books"
+#     filterable.defines
+#       collection: "books" 
+#       paginatable: 12
+#       filterable:
+#         query:
+#           author: "George Orwell"
+#    
+#      view = new App.views.FilterableBooks()
+# #### Filterable Collections
+#
+# The `Luca.CollectionView` will attempt to perform a local query against its
+# collection which behaves like a `Backbone.QueryCollection`.  It will do this
+# by default without making a remote request to the API.  
+# 
+# If you do not want this behavior, you can configure the `Luca.CollectionView` to 
+# behave as if the filtering was happen remotely in your REST API.  
+#
+#       filterable:
+#         options:
+#           remote: true
+collectionView = Luca.register      "Luca.CollectionView"
 
 collectionView.extends            "Luca.Panel"
 
+collectionView.replaces           "Luca.components.CollectionView"
+
 collectionView.mixesIn            "QueryCollectionBindings", 
                                   "LoadMaskable", 
                                   "Filterable", 
@@ -15,36 +57,46 @@ collectionView.triggers           "before:refresh",
                                   "refresh",
                                   "empty:results"
 
-# IDEA:
-# 
-# For validation of component configuration,
-# we could define a convention like:
-#
-# collectionView.validatesConfigurationWith
-#   requiresValidCollectionAt: "collection"
-#   requiresPresenceOf: 
-#     either: ["itemTemplate", "itemRenderer", "itemProperty"]
-#
-#
 collectionView.publicConfiguration
+  # Specify which collection will be used to supply the models to be rendered.
+  # Accepts either a string alias for the Collection class, or an instance of
+  # any class which inherits from Backbone.Collection
+  collection: undefined
+
+  # By default the CollectionView will be rendered inside of an OL tag.
   tagName: "ol"
+
+  # The CollectionView behaves as a Luca.Panel which means it has an area for
+  # top and bottom toolbars.  The actual content that gets rendered from the 
+  # collection will be rendered inside an element with the specified class.
   bodyClassName: "collection-ui-panel"
+
+  # Each item from the collection will be rendered inside of an element specified by @itemTagName
   itemTagName: 'li'
+
+  # Each item element will be assigned a CSS class specified by @itemClassName 
   itemClassName: 'collection-item'
+
+  # Specify which template should be used to render each item in the collection.  
+  # Accepts a string which will be passed to Luca.template(@itemTemplate).  Your template
+  # can expect to be passed an object with the `model` and `index` properties on it.
   itemTemplate: undefined
+
+  # Accepts a reference to a function, which will be called with an object with the `model` and `index`
+  # properties on it.  This function should return a String which will be injected into the item DOM element.
   itemRenderer: undefined
+
+  # Plucks the specified property from the model and inserts it into the item DOM element.
   itemProperty: undefined
 
-collectionView.defines
+  # If @observeChanges is set to true, any change in an underlying model will automatically be re-rendered.
+  observeChanges: false
+
+collectionView.publicMethods
   initialize: (@options={})->
     _.extend(@, @options)
     _.bindAll @, "refresh"
 
-    # IDEA:
-    #
-    # This type of code could be moved into a re-usable concern
-    # which higher order components can mixin to make it easier
-    # to extend them, instantiate them, etc.
     unless @collection? or @options.collection
       console.log "Error on initialize of collection view", @
       throw "Collection Views must specify a collection"
@@ -62,9 +114,10 @@ collectionView.defines
       console.log "Missing Collection on #{ @name || @cid }", @, @collection
       throw "Collection Views must have a valid backbone collection"
 
+    # INVESTIGATE THIS BEING DOUBLE WORK
     @on "data:refresh", @refresh, @
-
     @on "collection:reset", @refresh, @
+
     @on "collection:remove", @refresh, @
     @on "collection:add", @refresh, @
     @on "collection:change", @refreshModel, @ if @observeChanges is true
@@ -77,10 +130,46 @@ collectionView.defines
         view.refresh()
         view.unbind "after:render", @
 
+  # Given the id of a model, find the underlying DOM element which was rendered by this collection.
+  # Assumes that the data-model-id attribute is set, which it is by default by @attributesForItem.
+  locateItemElement: (id)->
+    @$(".#{ @itemClassName }[data-model-id='#{ id }']")
+
+  # Refresh is responsible for applying any filtering, pagination, or sorting options that may be set
+  # from the various Luca.concerns mixed in by `Luca.CollectionView` and making a query to the underlying
+  # collection.  It will then take the set of models returned by `@getModels` and pass them through the
+  # item rendering pipeline.
+  refresh: ()->
+    query = @getLocalQuery()
+    options = @getQueryOptions()
+    models  = @getModels(query, options)
+
+    @$bodyEl().empty()
+
+    @trigger("before:refresh", models, query, options)
+
+    if models.length is 0
+      @trigger("empty:results", query, options)
+
+    @renderModels(models, query, options)
+
+    @trigger("after:refresh", models, query, options)
+
+    @
+
 
+collectionView.privateMethods
+  renderModels: (models, query, options)->
+    index = 0
+    for model in models
+      @$append @makeItem(model, index++)
+
+  # Determines which attributes should be set on the item DOM element. 
   attributesForItem: (item, model)->
     _.extend {}, class: @itemClassName, "data-index": item.index, "data-model-id": item.model.get('id')
 
+  # Determines the content for the item DOM element.  Will use the appropriate options
+  # specified by `@itemTemplate`, `@itemRenderer`, or `@itemProperty`
   contentForItem: (item={})->
     if @itemTemplate? and templateFn = Luca.template(@itemTemplate)
       return content = templateFn.call(@, item)
@@ -93,45 +182,23 @@ collectionView.defines
 
     ""
 
+  # Uses the various options passed to the `CollectionView` to assemble a call to `Luca.View::make`.
   makeItem: (model, index)->
     item = if @prepareItem? then @prepareItem.call(@, model, index) else (model:model, index: index)
     attributes = @attributesForItem(item, model) 
     content = @contentForItem(item)
-    # TEMP
-    # Figure out why calls to make are failing with an unexpected string error
+
     try
-      make(@itemTagName, attributes, content)
+      Luca.View::make(@itemTagName, attributes, content)
     catch e
       console.log "Error generating DOM element for CollectionView", @, model, index
-      #no op
-
-  locateItemElement: (id)->
-    @$(".#{ @itemClassName }[data-model-id='#{ id }']")
 
+  # Given a model, attempt to re-render the contents of its item in this view's DOM contents.
   refreshModel: (model)->
     index = @collection.indexOf( model )
     @locateItemElement(model.get('id')).empty().append( @contentForItem({model,index}, model) )
     @trigger("model:refreshed", index, model)
 
-  refresh: (query,options,models)->
-    query   ||= @getQuery()
-    options ||= @getQueryOptions()
-    models  ||= @getModels(query, options)
-
-    @$bodyEl().empty()
-
-    @trigger("before:refresh", models, query, options)
-
-    if models.length is 0
-      @trigger("empty:results")
-
-    index = 0
-    for model in models
-      @$append @makeItem(model, index++)
-
-    @trigger("after:refresh", models, query, options)
-
-    @
 
   registerEvent: (domEvent, selector, handler)->
     if !handler? and _.isFunction(selector)
@@ -141,7 +208,4 @@ collectionView.defines
     eventTrigger = _([domEvent,"#{ @itemTagName }.#{ @itemClassName }", selector]).compact().join(" ")
     Luca.View::registerEvent(eventTrigger,handler)
 
-# Private Helpers
-
-
-make = Luca.View::make
+collectionView.register()

data/app/assets/javascripts/luca/components/controller.coffee

@@ -1,30 +1,108 @@
+# The Controller is a special type of CardView that is used to provide structure to a Luca.Application.  Each
+# component in the controller is expected to have a unique `@name` property.  The Application's router configuration
+# will map URL / Hashbangs to the `@name`s of components that belong to the Application controller.  
+#
+# Applications which structure their 'pages' in controllers, or sections, will have the names of which
+# section or page is active inside of its state model.  One example / common application structure we see:
+#
+#       application:
+#         main_controller:
+#           controller / section_one:
+#             page_one
+#             page_two
+#             page_three
+#           controller / section_two
+#             page_alpha
+#             page_bravo
+#
+# In the above example, the Application would attempt to route to page_one, and the state 
+# of the application may look like:
+#
+#       application.activeSection() #=> 'section_one'
+#       application.activeSubSection() # => 'page_one'
+#       application.activePage() # => page_one
+#
 controller = Luca.register        "Luca.components.Controller"
 controller.extends                "Luca.containers.CardView"
 
-controller.publicInterface
+controller.publicConfiguration
+  # If there is an active application, we will attempt to 
+  # set the name of our currently activated page on the application's
+  # state machine.  The attribute we will set can be configured by setting this value.
+  tracker: "page"
+
+  # We will set the name of the active page / section on our DOM element
+  # The attribute we will set can be configured by setting this.
+  activeAttribute: "active-section"
+  stateful: true
+  defaultPage: undefined
+  defaultCard: 0
+
+controller.publicMethods  
+  # Navigate to the default ( or first ) component on this controller.
+  # This will automatically get called upon rendering, so that it sets up
+  # the proper state tracking, event binding, etc.
   default: (callback)->
     @navigate_to(@defaultPage || @defaultCard, callback)
 
+  # Returns the name of the component which is currently active
+  # on this controller.
   activePage: ()-> 
     @activeSection()
 
-  navigate_to: (section, callback)->
-    section ||= @defaultCard
+  # Navigate to a page on this controller by name.  If passed an optional
+  # callback, the callback will be called within the context of the activated page.
+  navigate_to: (page, callback)->
+    page ||= @defaultCard
 
-    @activate section, false, (activator, previous,current)=>
-      unless current.activatedByController is true
+    @activate page, false, (activator, previous,current)=>
+      if current.activatedByController is true
+        current.trigger("on:controller:reactivation")
+      else
         current.trigger("on:controller:activation")
         current.activatedByController = true
 
       @state.set(active_section: current.name )
 
+      if @tracker? and app = @app || Luca.getApplication?()
+        app.state.set(@tracker, current.name)
+
+      Luca.key?.setScope( current.name )
+
       if _.isFunction( callback )
         callback.call(current)
 
-    # return the section we are navigating to
-    @find(section)
+    # return the component we are navigating to
+    @find(page)
 
 controller.classMethods
+  # For each component we control, if there is a keyEvents property defined
+  # then we will define a keymaster scope for that component's name, and setup
+  # bindings as directed.  This is important because each time a controller 
+  # activates a component, that component will attempt to change the scope of
+  # the keymaster so that components becomes responsible for handling detected key events.
+  setupComponentKeyEvents: ()->
+    @_().each (component)->    
+      if _.isObject(component.keyEvents) and component.name?
+        Luca.util.setupKeymaster(component.keyEvents, component.name).on(component)    
+
+  # The Controller Path is an array of the names of the controllers
+  # a given component belongs to.  This method will get patched on to each
+  # component that belongs to a controller.  It will always be bound to the instance
+  # of the component itself.  Example:
+  # 
+  #       application.contains
+  #         name: "main_controller"
+  #         components: [
+  #           name: "sub_controller"
+  #           components:[
+  #             name: "page"
+  #           ]
+  #         ]
+  #
+  # The @controllerPath() method for the component named page would be ['sub_controller','page'].
+  # This will be used internally by the Application route builder, so that each of page's parent
+  # controllers are activated in the proper order needed to make page visible.
   controllerPath: ()->
     component = @
     
@@ -42,9 +120,6 @@ controller.afterDefinition ()->
   Luca.View::hooks.push "on:controller:activation"
 
 controller.defines
-  additionalClassNames: 'luca-ui-controller'
-  activeAttribute: "active-section"
-  stateful: true
 
   initialize: (@options)->
     # let's phase out the 'card' terminology 
@@ -63,6 +138,7 @@ controller.defines
       component.controllerPath = Luca.components.Controller.controllerPath
 
     @on "after:render", @default, @
+    @on "before:render", Luca.components.Controller.setupComponentKeyEvents, @
 
   each: (fn)->
     _( @components ).each (component)=> fn.call(@,component)
@@ -82,6 +158,7 @@ controller.defines
     @availableSections.apply(@, arguments)    
 
   availableSections: ()->
+    console.log "The availableSections()/availablePages() method will be removed in 1.0"
     base = {}
     base[ @name ] = @sectionNames()
 

data/app/assets/javascripts/luca/components/fields/base.coffee

@@ -1,3 +1,9 @@
+# The `Luca.core.Field` is an abstract base class for field components
+# which are used in the `Luca.components.FormView`.  They provide common
+# functionality like getValue, setValue, change and validation event bindings. 
+#
+# Additionally, the field component provides common Twitter Bootstrap styling
+# hooks, such as error, warning, and success status flagging.
 field = Luca.register         "Luca.core.Field"
 
 field.extends                 "Luca.View"
@@ -6,25 +12,85 @@ field.triggers                "before:validation",
                               "after:validation",
                               "on:change"
 
-field.publicConfiguration   
+field.publicConfiguration
+  className: 'luca-ui-field'
+
+  # Controls whether or not this field is rendered in a disabled state
+  disabled: undefined
+
+  # Controls the bootstrap helperText value for this field control
+  helperText: undefined
+
+  # Text value for the label element that goes along with this field control
+  label: undefined
+
+  # Controls the positioning of the label element.  Valid options are
+  # 'top', 'left'.  For any other custom display you can control this
+  # on your own by specifying a template
   labelAlign: 'top'
-  className: 'luca-ui-text-field luca-ui-field'
+
+  # Controls the value displayed in this field when it is in an untouched state
+  # by the user.  Uses the html5 placeholder attribute
+  placeHolder: undefined
+
+  # Controls whether or not we want to display visual indicator
+  # that this field is required. 
+  required: undefined
+
+  # Which statuses can be applied to this field? Valid options are taken
+  # from bootstrap state styling.
   statuses: [
     "warning"
     "error"
     "success"
   ]
 
-field.publicInterface
+  # What is the type of value that this field
+  # should have? You can use this to coerce the `getValue()` type
+  # into an integer, string, or float.
+  valueType: "string"
+
+
+
+field.publicMethods
+  # Disable this field
   disable: ()->
     @getInputElement().attr('disabled', true)
 
+  # Enable this field
   enable: ()->
     @getInputElement().attr('disabled', false)
 
+  # Gets the value from the input element in this field control
   getValue: ()->
-    raw = @getInputElement()?.attr('value')
+    raw = @getInputElement()?.val()
+    @getParsedValue(raw)
+
+  # Sets the value on the input element inside this field control
+  setValue: (value)->
+    @getInputElement()?.val(value)
+
+  # Update the state of this field.  Valid options are defined on
+  # this fields `@statuses` property
+  updateState: (state)->
+    for cssClass in @statuses
+      @$el.removeClass(cssClass)
+
+    @$el.addClass(state)
+
+  # Remove any visual error indications from this field control
+  clearErrors: ()->
+    @$el.removeClass('error')
+
+  # Display a visual error state on this field
+  displayErrors: (errors)->
+    @updateState('error')
 
+field.privateMethods
+  # Runs the value from the underlying input element
+  # through a type conversion process configured by
+  # the `@valueType` field
+  getParsedValue: (raw)->
     return raw if _.str.isBlank( raw )
 
     switch @valueType
@@ -33,19 +99,12 @@ field.publicInterface
       when "float" then parseFloat(raw)
       else raw
 
-  setValue: (value)->
-    @getInputElement()?.attr('value', value)
-
-  updateState: (state)->
-    _( @statuses ).each (cls)=>
-      @$el.removeClass(cls)
-      @$el.addClass(state)
-
 field.privateConfiguration
+  # A convenience method for identifying field components
   isField: true
   template: 'fields/text_field'
 
-field.defines
+field.privateMethods
   initialize: (@options={})->
     _.extend @, @options
 
@@ -81,3 +140,5 @@ field.defines
 
   getInputElement: ()->
     @input ||= @$('input').eq(0)
+
+field.register()