luca 0.9.89 → 0.9.91

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

@@ -1,29 +1,70 @@
+# 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)=>
+    @activate page, false, (activator, previous,current)=>
       if current.activatedByController is true
         current.trigger("on:controller:reactivation")
       else
-        current.trigger("on:controller:reactivation")
         current.trigger("on:controller:activation")
         current.activatedByController = true
 
       @state.set(active_section: current.name )
 
-      if app = Luca.getApplication?()
+      if @tracker? and app = @app || Luca.getApplication?()
         app.state.set(@tracker, current.name)
 
       Luca.key?.setScope( current.name )
@@ -31,15 +72,37 @@ controller.publicInterface
       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 = @
     
@@ -57,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 
@@ -98,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"
@@ -7,39 +13,83 @@ field.triggers                "before:validation",
                               "on:change"
 
 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: ()->
-    @getParsedValue(@getInputElement()?.attr('value'))
+    raw = @getInputElement()?.val()
+    @getParsedValue(raw)
 
+  # Sets the value on the input element inside this field control
   setValue: (value)->
-    @getInputElement()?.attr('value', value)
+    @getInputElement()?.val(value)
 
+  # Update the state of this field.  Valid options are defined on
+  # this fields `@statuses` property
   updateState: (state)->
-    _( @statuses ).each (cls)=>
-      @$el.removeClass(cls)
+    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.methods
+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 )
 
@@ -50,10 +100,11 @@ field.methods
       else raw
 
 field.privateConfiguration
+  # A convenience method for identifying field components
   isField: true
   template: 'fields/text_field'
 
-field.defines
+field.privateMethods
   initialize: (@options={})->
     _.extend @, @options
 
@@ -89,3 +140,5 @@ field.defines
 
   getInputElement: ()->
     @input ||= @$('input').eq(0)
+
+field.register()

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

@@ -1,3 +1,9 @@
+# The `Luca.fields.ButtonField` provides an easy way to generate
+# a button element, with an optional icon.  Supports all of the
+# available bootstrap icons, and color states.  
+#
+# The `Luca.fields.ButtonField` component will typically be used as 
+# part of a `Luca.components.FormView` or a `Luca.components.PanelToolbar`.
 buttonField = Luca.register         "Luca.fields.ButtonField"
 
 buttonField.extends                 "Luca.core.Field"
@@ -5,28 +11,62 @@ buttonField.extends                 "Luca.core.Field"
 buttonField.triggers                "button:click"
 
 buttonField.publicConfiguration
+  # Which size should this button be? Valid options are:
+  # - none ( default )
+  # - large
+  # - mini
+  # - small
+  buttonSize: undefined
+
+  # Which bootstrap color class should we apply to this button?
+  # Valid options are any css button class, or the defaults which
+  # ship with bootstrap: 
+  #
+  # - btn-primary
+  # - btn-info
+  # - btn-success
+  # - btn-warning
+  # - btn-danger
+  # - btn-inverse
+  # - btn-link
+  class: undefined 
+
+  # specifies the bootstrap icon class you want to use for this button 
+  # you can use 'icon-ok-sign' or just 'ok-sign'
+  icon_class: undefined
+
+  # specifies the text value of the button
+  label: undefined    
+
+  # an alias for label, or input_value.  controls which text 
+  # displays inside of the button
+  text: undefined
+
+  # should we render the white icon? 
+  white: false
+
+buttonField.privateConfiguration
   readOnly:       true
   input_value:    undefined 
   input_type:     "button" 
   icon_class:     undefined
   input_name:     undefined
-  white:          undefined
   buttonClasses:  "" 
 
 buttonField.privateConfiguration
   isButton: true
+  autoBindEventHandlers: true
   template: "fields/button_field"
   events:
-    "click input" : "click_handler"
+    "click input" : "clickHandler"
 
-buttonField.privateInterface
-  click_handler: (e)->
+buttonField.privateMethods
+  clickHandler: (e)->
     me = my = $( e.currentTarget )
     @trigger "button:click"
 
   initialize: (@options={})->
-    _.extend @options
-    _.bindAll @, "click_handler"
+    _.extend @, @options
 
     Luca.core.Field::initialize.apply @, arguments
 
@@ -37,9 +77,15 @@ buttonField.privateInterface
     @input_name ||= @name ||= @input_id
     @input_value ||= @label ||= @text
     @input_class ||= @class ||= @buttonClasses
+
+    if @buttonSize?.length > 0
+      @input_class += " #{ buttonSize.replace(/btn-/,'') }"
+
     @icon_class ||= ""
     @icon_class = "icon-#{ @icon_class }" if @icon_class.length and !@icon_class.match(/^icon-/)
     @icon_class += " icon-white" if @white
 
-  setValue: ()-> true
+  setValue: ()-> 
+    true
 
+buttonField.register()

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

@@ -1,11 +1,10 @@
-make = Luca.View::make
-
+# The `Luca.fields.CheckboxArray` renders an array of values 
+# into checkbox controls.  This is for fields which can have
+# a list of values associated with them.
 checkboxArray = Luca.register     "Luca.fields.CheckboxArray"
 checkboxArray.extends             "Luca.core.Field"
 
-checkboxArray.defines
-  version: 2
-
+checkboxArray.privateConfiguration
   template: "fields/checkbox_array"
 
   className: "luca-ui-checkbox-array"
@@ -15,6 +14,7 @@ checkboxArray.defines
 
   selectedItems: []
 
+checkboxArray.privateMethods
   initialize: (@options={})->
     _.extend @, @options
     _.extend @, Luca.concerns.Deferrable
@@ -65,8 +65,8 @@ checkboxArray.defines
       label = model.get(@displayField)
       input_id = _.uniqueId("#{ @cid }_checkbox")
 
-      inputElement = make("input",type:"checkbox",class:"array-checkbox",name:@input_name,value:value,id: input_id)
-      element = make("label", {for:input_id}, inputElement)
+      inputElement = @make("input",type:"checkbox",class:"array-checkbox",name:@input_name,value:value,id: input_id)
+      element = @make("label", {for:input_id}, inputElement)
 
       $( element ).append(" #{ label }")
       @controls().append( element )
@@ -80,6 +80,9 @@ checkboxArray.defines
   allFields: ()->
     @controls().find("input[type='checkbox']")
 
+checkboxArray.publicMethods
+  # Check the selected items.  Expects an array of values 
+  # for boxes you would like to see checked.
   checkSelected: (items)->
     @selectedItems = items if items?
 
@@ -91,6 +94,8 @@ checkboxArray.defines
 
     @selectedItems
 
+  # Gets an array of values for the checkboxes in this array
+  # which are checked.
   getValue: ()->
     @$(field).val() for field in @allFields() when @$(field).prop('checked')
 

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

@@ -2,7 +2,7 @@ textField = Luca.register     'Luca.fields.TextField'
 textField.extends             'Luca.core.Field'
 
 textField.defines
-  _events:
+  _inheritEvents:
     "blur input" : "blur_handler"
     "focus input" : "focus_handler"
     "change input" : "change_handler"

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

@@ -96,7 +96,7 @@ formView.privateConfiguration
   # These events will get registered on the component
   # but still leave the @events property open to extend
   # for any component which inherits from us.
-  _events:
+  _inheritEvents:
     "click .submit-button" : "submitHandler"
     "click .reset-button" : "resetHandler"
 
@@ -120,7 +120,7 @@ formView.privateMethods
 
     # have our events be internal to the view, and not
     # part of the normal @events chain, so they can be inherited
-    for eventId, handler of @_events
+    for eventId, handler of @_inheritEvents
       @registerEvent(eventId, handler)
 
     if @trackDirtyState is true

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

@@ -36,7 +36,6 @@ gridView.privateMethods
       rowIndex = 0 if index > 0 and index % @itemsPerRow is 0
       row
 
-    console.log "Appending rows", rows
     for row in rows
       @$append(row) 
 

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

@@ -26,6 +26,7 @@ page.privateMethods
   initialize: (@options={})->
     @assignComponentsToRegions()
     @bodyTemplate = @options.layout || @layout
+    @bodyTemplate ||= @options.template || @template
     Luca.Container::initialize.apply(@, arguments)
 
   # Takes the configuration specified in @regions

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

@@ -67,7 +67,7 @@ tableView.classMethods
       content = column.header 
       content = "<a class='link'>#{ column.header }</a>" if column.sortable
 
-      @$(targetElement).find('tr').append( Backbone.View::make "th", attrs, content )
+      @$(targetElement).find('tr').append( Luca.View::make "th", attrs, content )
 
 
     index = 0
@@ -88,6 +88,6 @@ tableView.classMethods
     if _.isFunction( column.renderer )
       cellValue = column.renderer.call @, cellValue, model, column 
 
-    Backbone.View::make("td", {"data-col-index":index}, cellValue)
+    Luca.View::make("td", {"data-col-index":index}, cellValue)
 
 tableView.register()

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

@@ -46,10 +46,10 @@ Luca.concerns.DomHelpers =
       console.log "Error in $template: #{ template } #{ @identifier?() ? @name || @cid }"
 
   $html: (content)->
-    @$el.html( content )
+    if content? then @$el.html(content) else @$el.html()
 
   $append: (content)->
-    @$el.append( content )
+    @$el.append(content)
 
   $attach: ()->
     @$container().append( @el )

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,72 +18,70 @@ component.aliases               "Luca.PageView"
 #   cardView.activeComponent().name # => "one"
 #   cardView.activate('two')
 #   cardView.activeComponent().name # => "two"
-#
-component.defaults
-  activeCard: 0
+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
@@ -97,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,21 +111,18 @@ component.defaults
       if current.rendered is true
         current.trigger "first:activation"
       else
-        current.defer ()-> 
+        current.once "after:render", ()->
+          current.rendered = true
           current.trigger("first:activation")
-        .until current, "after:render"
-
       current.previously_activated = true
 
-    @activeCard = index
+    @activeCard = index 
     @activeComponentElement().show()
 
     unless silent is true
       @trigger "after:card:switch", previous, current
       previous?.trigger "deactivation", @, previous, current
-      current?.trigger "on:deactivation", @, previous, current
       current?.trigger "activation", @, previous, current
-      current?.trigger "on:activation", @, previous, current
 
     activationContext = @
 
@@ -144,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()