luca 0.9.76 → 0.9.89

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

@@ -0,0 +1,69 @@
+Luca.concerns.Sortable = 
+  __included: (component, module)->
+    _.extend(Luca.Collection::, __sortables:{})
+
+  __initializer:()->
+    if @sortable is false
+      return
+
+    if _.isString(@sortable)
+      @sortable = sortBy: @sortable
+
+    unless Luca.isBackboneCollection(@collection)
+      @debug "Skipping Sortable due to no collection being present on #{ @name || @cid }"
+      @debug "collection", @collection
+      return
+
+    collection = (@getCollection ||= ()-> @collection)()
+
+    sortableState = @getSortableState()
+
+    @optionsSources ||= []
+    @queryOptions ||= {}
+
+    @optionsSources.push -> 
+      _(sortableState.toJSON()).pick('sortBy','order')
+
+    sortableState.on "change", ()=> @trigger "sortable:change"
+
+    @defer ()=>
+      @$(".sortable-toggle").on "click", (e)=>
+        me = my = @$( e.target )
+        me = my = my.closest('.sortable-toggle') 
+        @toggleSortOrderDirection( my.data('sortableSortBy') )
+
+    .until "after:render"
+
+    @on "sortable:change", Luca.concerns.Filterable.classMethods.prepare, @
+
+  isRemote: ()->
+    @getQueryOptions().remote is true    
+
+  getSortableState: ()->
+    options = _( @sortable || {} ).pick 'sortBy', 'order'
+    @collection.__sortables[ @cid ] ||= new SortableState(options)
+
+  sortBy: (field,order)->
+    @setSortBy(field) if field?
+    @setOrder(order) if order?
+    @
+
+  setSortBy: (field, options={})->
+    @getSortableState().set('sortBy', field, options)
+    @
+
+  toggleSortOrderDirection: (sortBy)->
+    current = @getSortableState().get('order') || "ASC"
+    changeTo = if current is "ASC" then "DESC" else "ASC"  
+    sortBy ||= @getSortableState().get('sortBy')
+    @sortBy(sortBy, changeTo)
+
+  setOrder: (order, options={})->
+    @getSortableState().set('order', order, options)
+    @
+
+Luca.util.makeSortableToggleElement = (el, sortBy, order)->
+  $(el).attr('data-sortable-sort-by', sortBy ).attr('data-sortable-order', order)
+  $(el)
+
+SortableState = Backbone.Model.extend()

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

@@ -0,0 +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?
+    
+    statefulView = @
+
+    if _.isObject(@stateful) and not @defaultState?
+      @defaultState = @stateful 
+
+    @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
+      if _.isFunction(@[hook])
+        1
+
+    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/{src → app/assets/javascripts/luca}/concerns/templating.coffee

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

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

@@ -0,0 +1,54 @@
+Luca.config.maintainStyleHierarchy = true
+Luca.config.maintainClassHierarchy = true
+Luca.config.autoApplyClassHierarchyAsCssClasses = true
+
+Luca.config.idAttributeType = "integer"
+
+Luca.config.apiSortByParameter  = 'sortBy'
+Luca.config.apiPageParameter    = 'page'
+Luca.config.apiLimitParameter   = 'limit'
+
+# When using Luca.define() should we automatically register
+# the component with the registry?
+Luca.autoRegister = Luca.config.autoRegister = true
+
+# if developmentMode is true, you have access to some neat development tools
+Luca.developmentMode = Luca.config.developmentMode = false
+
+# The Global Observer is very helpful in development
+# it observes every event triggered on every view, collection, model
+# and allows you to inspect / respond to them.  Use in production
+# may have performance impacts which has not been tested
+Luca.enableGlobalObserver = Luca.config.enableGlobalObserver = false
+
+# let's use the Twitter 2.0 Bootstrap Framework
+# 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
+  KEYLEFT: 37
+  KEYUP: 38
+  KEYRIGHT: 39
+  KEYDOWN: 40
+  SPACEBAR: 32
+  FORWARDSLASH: 191
+  TAB: 9
+
+Luca.config.toolbarContainerClass = "toolbar-container"
+
+# build a reverse map
+Luca.keyMap = Luca.config.keyMap = _( Luca.keys ).inject (memo, value, symbol)->
+  memo[value] = symbol.toLowerCase()
+  memo
+, {}
+
+Luca.config.showWarnings = true
+Luca.config.default_socket_port = 9292

data/{src → app/assets/javascripts/luca}/containers/card_view.coffee

@@ -1,5 +1,7 @@
 component = Luca.define         "Luca.containers.CardView"
-component.extends               "Luca.core.Container"
+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
@@ -23,9 +25,6 @@ component.extends               "Luca.core.Container"
 #   cardView.activeComponent().name # => "two"
 #
 component.defaults
-
-  className: 'luca-ui-card-view-wrapper'
-
   activeCard: 0
 
   components: []
@@ -40,11 +39,19 @@ component.defaults
 
   initialize: (@options)->
     @components ||= @pages ||= @cards 
-    Luca.core.Container::initialize.apply @,arguments
+    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.core.Container::prepareComponents?.apply(@, arguments)
+    Luca.Container::prepareComponents?.apply(@, arguments)
     @componentElements().hide()
     @activeComponentElement().show()
 
@@ -80,7 +87,7 @@ component.defaults
   find: (name)-> Luca(name)
 
   firstActivation: ()->
-    @activeComponent().trigger "first:activation", @, @activeComponent()
+    @activeComponent()?.trigger "first:activation", @, @activeComponent()
 
   activate: (index, silent=false, callback)->
     if _.isFunction(silent)
@@ -110,7 +117,13 @@ 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.defer ()-> 
+          current.trigger("first:activation")
+        .until current, "after:render"
+
       current.previously_activated = true
 
     @activeCard = index
@@ -119,7 +132,9 @@ component.defaults
     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 = @
 

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

@@ -1,6 +1,147 @@
-container = Luca.register         "Luca.core.Container"
-
-container.extends                 "Luca.components.Panel"
+# 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
+#         ... 
+#         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"
 
 container.triggers                "before:components",
                                   "before:render:components",
@@ -9,19 +150,19 @@ container.triggers                "before:components",
                                   "after:layout",
                                   "first:activation"
 
-container.defines
-  className: 'luca-ui-container'
+container.replaces                "Luca.Container"
 
-  componentTag: 'div'
+container.publicConfiguration
+  components:[]
 
+container.privateConfiguration
+  emptyContainerElements: false
+  className: 'luca-ui-container'
+  componentTag: 'div'
   componentClass: 'luca-ui-panel'
-
   isContainer: true
-
   rendered: false
 
-  components: []
-
   # @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:
@@ -31,7 +172,7 @@ container.defines
   # 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.core.Container
+  # myContainer = new Luca.Container
   #   componentEvents:
   #     "name component:trigger"    : "handler"
   #     "role component:trigger"    : "handler"
@@ -52,65 +193,23 @@ container.defines
 
     _.bindAll(@, "beforeRender")
 
-    @setupHooks( Luca.core.Container::hooks )
-
+    @setupHooks( Luca.Container::hooks )
 
     validateContainerConfiguration(@)
 
     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()
-  #
+  remove: ()->
+    Luca.View::remove.apply(@, arguments)
+    @eachComponent (component)->
+      component.remove?()
+      
   beforeRender: ()->
     doLayout.call(@)
     doComponents.call(@)
-    Luca.components.Panel::beforeRender?.apply(@, arguments)
+    Luca.Panel::beforeRender?.apply(@, arguments)
 
-  # Components which inherit from Luca.core.Container can implement
+  # Components which inherit from Luca.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.
@@ -122,10 +221,27 @@ container.defines
     @componentContainers = _( @components ).map (component, index)->
       applyDOMConfig.call(container, component, index)
 
+    componentsWithClassBasedAssignment = @_().select (component)->
+      _.isString(component.container) and component.container?.match(/^\./) and container.$( component.container ).length > 0
+
+    # TEMP / HACK / Workaround
+    #
+    # Containers with components assigned to .class-based-containers
+    # seem to get double rendered in the renderComponents() method.
+    #
+    # So here I am uniquely identifying the containers in a way that is not possible
+    # in the templates ( since we want to be able to inherit templates and component assignments )
+    if componentsWithClassBasedAssignment.length > 0
+      for specialComponent in componentsWithClassBasedAssignment
+        containerAssignment = _.uniqueId('container')
+        targetEl = container.$( specialComponent.container )
+        if targetEl.length > 0
+          $(targetEl).attr('data-container-assignment', containerAssignment)
+          specialComponent.container += "[data-container-assignment='#{ containerAssignment }']"
+
   prepareComponents: ()->
     container = @
 
-
     _( @components ).each (component, index)=>
       ce = componentContainerElement = @componentContainers?[index]
 
@@ -186,8 +302,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
@@ -228,8 +353,27 @@ container.defines
 
     _(@components).each (component)->
       try
-        @$( component.container ).eq(0).append( component.el )
+        component.trigger "before:attach"
+
+        containerElement = container.$(component.container)
+
+        if containerElement.length is 0
+          if _.isString( component.container )
+            # the container trying to assign this component to is not in the dom
+            1
+
+          # try in the window context.  this is almost always certainly a bug
+          # 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
 
@@ -278,7 +422,7 @@ container.defines
   map: (fn)->
     @_().map(fn)
 
-  registerComponentEvents: (eventList)->
+  registerComponentEvents: (eventList, direction="on")->
     container = @
 
     for listener, handler of (eventList || @componentEvents||{})
@@ -297,7 +441,7 @@ 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)
 
 
   subContainers: ()->
@@ -309,7 +453,10 @@ container.defines
 
   allChildren: ()->
     children = @components
-    grandchildren = _( @subContainers() ).invoke('allChildren')
+
+    grandchildren = _( @subContainers() ).map (component)->
+      component?.allChildren?()
+
     _([children,grandchildren]).chain().compact().flatten().value()
 
   findComponentForEventBinding: (nameRoleOrGetter, deep=true)->
@@ -317,11 +464,15 @@ container.defines
 
   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)->
@@ -391,10 +542,12 @@ 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.
-Luca.core.Container.componentRenderer = (container, component)->
+Luca.Container.componentRenderer = (container, component)->
   attachMethod = $( component.container )[ component.attachWith || "append" ]
   attachMethod( component.render().el )
 
@@ -430,27 +583,26 @@ createGetterMethods = ()->
   container = @
 
   childrenWithGetter = _( @allChildren() ).select (component)->
-    component.getter?
+    component?.getter?
 
   _( childrenWithGetter ).each (component)->
-    container[ component.getter ] ||= ()->
-      console.log component.getter, component, container
-      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
   @prepareComponents()
+  @trigger "before:create:components", @, @components
   @createComponents()
   @trigger "before:render:components", @, @components
   @renderComponents()
@@ -465,7 +617,6 @@ doComponents = ()->
 validateContainerConfiguration = ()->
   true
 
-
 # Private Helpers
 #
 # indexComponent( component ).at( index ).in( componentsInternalIndexMap )