luca 0.9.89 → 0.9.91

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

@@ -128,6 +128,10 @@
 #           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"
@@ -153,33 +157,94 @@ container.triggers                "before:components",
 container.replaces                "Luca.Container"
 
 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:[]
 
-container.privateConfiguration
-  emptyContainerElements: false
-  className: 'luca-ui-container'
-  componentTag: 'div'
-  componentClass: 'luca-ui-panel'
-  isContainer: true
-  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: {}
+
+  # 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
 
@@ -199,6 +264,7 @@ container.privateConfiguration
 
     Luca.View::initialize.apply @, arguments
 
+  # Removing a container will call remove on all of the nested components as well.
   remove: ()->
     Luca.View::remove.apply(@, arguments)
     @eachComponent (component)->
@@ -344,8 +410,7 @@ container.privateConfiguration
 
     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"
 
@@ -383,8 +448,6 @@ container.privateConfiguration
 
         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
@@ -401,27 +464,6 @@ container.privateConfiguration
         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, direction="on")->
     container = @
 
@@ -443,13 +485,41 @@ container.privateConfiguration
 
         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
@@ -459,6 +529,11 @@ container.privateConfiguration
 
     _([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 )
 
@@ -506,10 +581,17 @@ container.privateConfiguration
       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 ]
@@ -617,8 +699,6 @@ doComponents = ()->
 validateContainerConfiguration = ()->
   true
 
-# Private Helpers
-#
 # indexComponent( component ).at( index ).in( componentsInternalIndexMap )
 indexComponent = (component)->
   at: (index)->

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

@@ -1,13 +1,13 @@
-_.def("Luca.ModalView").extends("Luca.Container").with
+view = Luca.register      "Luca.containers.ModalView"
+view.extends              "Luca.Container"
 
+view.publicConfiguration
   closeOnEscape: true
-
   showOnInitialize: false
-
   backdrop: false
+  className: "modal"
 
-  className: "luca-ui-container modal"
-
+view.publicMethods
   container: ()->
     $('body')
 
@@ -27,10 +27,10 @@ _.def("Luca.ModalView").extends("Luca.Container").with
     $('body').append( @$el )
     
     @$el.modal
-      backdrop: @backdrop is true
-      keyboard: @closeOnEscape is true
-      show: @showOnInitialize is true
+      backdrop: !!(@backdrop is true)
+      keyboard: !!(@closeOnEscape is true)
+      show: !!(@showOnInitialize is true)
 
     @
 
-_.def("Luca.containers.ModalView").extends("Luca.ModalView").with()
+view.register()

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

@@ -0,0 +1,25 @@
+# The PageController container is a special type of container whose components or pages
+# will always monopolize the entire element's display and where only one page or component
+# will be visible at a time.  The PageController is typically going to be at the very root
+# of every application, and will be directly integrated with the application's router. 
+# A typical application hierarchy will be an abstract `Viewport` with a single top level
+# `PageController` named 'main_controller'. 
+#
+#       - Viewport / Application
+#         - Router. ( maps urls to named pages on the controller )
+#         - Main Page Controller
+#           - Pages
+#             - Named views / containers
+view = Luca.register    "Luca.containers.PageController"
+view.extends            "Luca.Container"
+
+view.privateMethods
+  initialize: (@options={})->
+    @components ||= @pages || @options.pages
+    for component in @components
+      component.components ||= component.pages
+
+    Luca.Container::initialize.apply(@, arguments)
+
+view.register()  
+

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

@@ -75,7 +75,7 @@ panelToolbar.defines
     @
 
 
-make = Backbone.View::make
+make = Luca.View::make
 
 buildButton = (config, wrap=true)->
   if config.ctype? or config.type?

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

@@ -39,10 +39,7 @@ viewport.defines
     @$el.removeClass('fullscreen-enabled')
 
   beforeRender: ()->
-    Luca.containers.CardView::beforeRender?.apply(@, arguments)
-
-    #if Luca.config.enableBoostrap and @topNav and @fullscreen
-    #  $('body').css('padding','40px')
+    Luca.Container::beforeRender?.apply(@, arguments)
 
     @renderTopNavigation() if @topNav?
     @renderBottomNavigation() if @bottomNav?
@@ -54,7 +51,7 @@ viewport.defines
     @$el.width()
 
   afterRender: ()->
-    Luca.containers.CardView::after?.apply(@, arguments)
+    Luca.Container::afterRender?.apply(@, arguments)
 
     if Luca.config.enableBoostrap is true and @containerClassName
       @$el.children().wrap('<div class="#{ containerClassName }" />')

data/app/assets/javascripts/luca/core/collection.coffee

@@ -1,4 +1,4 @@
-collection = Luca.define            'Luca.Collection'
+collection = Luca.register          'Luca.Collection'
 collection.extends                  'Backbone.QueryCollection'
 collection.includes                 'Luca.Events'
 
@@ -6,13 +6,13 @@ collection.triggers                 "after:initialize",
                                     "before:fetch",
                                     "after:response"
 
-collection.defines    
+collection.publicConfiguration    
   model: Luca.Model
   # cachedMethods refers to a list of methods on the collection
   # whose value gets cached once it is ran.  the collection then
   # binds to change, add, remove, and reset events and then expires
   # the cached value once these events are fired.
-
+  #
   # cachedMethods expects an array of strings representing the method name
   # or objects containing @method and @resetEvents properties.  by default
   # @resetEvents are 'add','remove',reset' and 'change'.
@@ -22,6 +22,17 @@ collection.defines
   # and return the filtered results that way, then set this to true
   remoteFilter: false
 
+  # setting a cache key to a string, or to a function which returns
+  # a string, will determine where the collections' models are pulled
+  # from if they are available on page load.  also known as "bootstrapping"
+  # your collections with data.  The cache key will look in whatever object
+  # is set in Luca.config.modelBootstrap for its models.
+  cache_key: undefined
+
+  # Which CollectionManager should we register with? Expects either a string
+  # which will get resolved into a global variable, or a 
+  manager: undefined
+
   initialize: (models=[], @options)->
     _.extend @, @options
     @_reset()
@@ -44,7 +55,7 @@ collection.defines
     @name ||= @registerAs
     @manager ||= @registerWith
 
-    @manager = if _.isFunction(@manager) then @manager() else @manager
+    @manager = Luca.util.read(@manager) if @manager? 
 
     # if they specify a
     if @name and not @manager
@@ -346,6 +357,9 @@ collection.defines
     else
       @models
 
+collection.register()
+
+
 # Global Collection Observer
 _.extend Luca.Collection.prototype,
   trigger: ()->

data/app/assets/javascripts/luca/core/model.coffee

@@ -1,4 +1,4 @@
-model = Luca.define       'Luca.Model'
+model = Luca.register     'Luca.Model'
 
 model.extends             'Backbone.Model'
 

data/app/assets/javascripts/luca/core/panel.coffee

@@ -54,7 +54,7 @@ panel.publicMethods
     @$bodyEl().empty()
     
   $html: (content)->
-    @$bodyEl().html( content )
+    if content? then @$bodyEl().html( content ) else @$bodyEl().html()
 
   $append: (content)->
     @$bodyEl().append(content)

data/app/assets/javascripts/luca/core/view.coffee

@@ -136,11 +136,11 @@ view.publicConfiguration
   #
   autoBindEventHandlers: false
 
-  # Supplying configuration to `@_events` will ensure that this configuration
+  # Supplying configuration to `@_inheritEvents` will ensure that this configuration
   # is present on views which extend from this view.  In normal Backbone behavior
   # the `@events` property can be overridden by views which extend, and this isn't
   # always what you want from your component.   
-  _events: undefined
+  _inheritEvents: undefined
 
 
 
@@ -174,14 +174,14 @@ view.publicMethods
 
     Luca.concern.setup.call(@)
 
-    @delegateEvents()
+    @delegateEvents() unless _.isEmpty(@events)
 
     @trigger "after:initialize", @
 
     _.bindAll(@, @bindMethods...) if @bindMethods?.legth > 0
 
-    unless _.isEmpty(@_events)
-      for eventId, handler of @_events
+    unless _.isEmpty(@_inheritEvents)
+      for eventId, handler of @_inheritEvents
         @registerEvent(eventId, handler)
 
 
@@ -198,7 +198,17 @@ view.publicMethods
 
     Backbone.View::trigger.apply @, arguments
 
- 
+  # Backbone.View.prototype.make is removed in 0.9.10.
+  # As we happen to rely on this little utility heavily,
+  # we add it to Luca.View
+  make: (tagName, attributes, content)->
+    el = document.createElement(tagName);
+    if (attributes) 
+      Backbone.$(el).attr(attributes)
+    if (content != null) 
+      Backbone.$(el).html(content)
+      
+    el    
 
   registerEvent: (selector, handler)->
     @events ||= {}
@@ -206,7 +216,8 @@ view.publicMethods
     if _.isObject(selector)
       @events = _.extend(@events, selector)
     else
-      @events[selector] = handler
+      if _.isFunction(handler) || (_.isString(handler) && @[handler]?)
+        @events[selector] = handler 
 
     @delegateEvents()
 
@@ -240,6 +251,14 @@ view.privateMethods
   # - first:activation  : firstActivation()
   setupHooks: Luca.util.setupHooks
 
+# In order to support some Luca apps which rely
+# on Backbone.View.make.  
+view.afterDefinition ()->
+  if not Backbone.View::make?
+    Backbone.View::make = ()->
+      console.log "Backbone.View::make has been removed from backbone.  You should use Luca.View::make instead."
+      Luca.View::make
+
 view.register()
 
 Luca.View._originalExtend = Backbone.View.extend

data/app/assets/javascripts/luca/development/code_sync_manager.coffee

@@ -1,15 +1,59 @@
+# The `Luca.CodeSyncManager` works along with the Guard adapter that ships with 
+# the ruby gem.  This is still an experimental option at this point, but I use
+# it regularly on all of my Luca projects and it allows me to develop my applications
+# directly from my editor and rarely have the need to refresth the browser to work with
+# javascript and css changes.
+#
+# #### Similar to LiveReload
+# It is similar to projects like LiveReload, except that it knows a lot about the luca
+# framework and application conventions and uses this knowledge to optimize live reloading
+# behavior, avoiding the need to do full browser reloads.  This typically doesn't work well
+# with state heavy applications, since the browser reloading doesn't always construct application
+# state exactly as you need it when you're making your css changes etc.
+#
+# #### 1) Add an entry to your Guardfile:
+#         guard 'luca' do
+#           watch(%r{^app/assets/stylesheets/(.+)}) do |match|
+#               path = match.last
+#           end 
+  
+#           watch(%r{^app/assets/javascripts/(.+)}) do |match|
+#             path = match.last
+#           end
+#         end
+#
+# #### 2) Add the `CodeSyncManager` to your development mode application. 
+# **Note:** This expect
+# you to have a `Luca.SocketManager` capable backend such as faye or socket.io running. It
+# handles the same configuration options as the `Luca.SocketManager` as well.
+#
+#               app = Luca()
+#               app.codeSyncManager = new Luca.CodeSyncManager
+#                 host: "//localhost:9292/faye"
+#                 channel: "/changes"
+#               app.codeSyncManager.trigger("ready")
+#
+# #### 3) Run guard.  
+# Edit your files, watch your changes appear.
+#
+# ### Using the Syncpad
+#
+# The syncpad is a special naming convention for development scratch paper in your editor.  A file
+# named syncpad.coffee, syncpad.css.scss, syncpad.jst.ejs.haml, etc will be evaluated live when you change
+# them in your editor.  I personally use this to experiment with code / css and get immediate results without
+# needing to refresh the browser.
 codeManager = Luca.register     "Luca.CodeSyncManager"
 codeManager.extends             "Luca.SocketManager"
 
 codeManager.publicConfiguration
-  host:       Luca.config.codeSyncHost || "http://localhost:9292/faye"
+  host:       Luca.config.codeSyncHost || "//localhost:9292/faye"
   namespace:  "luca"
-  channel:    Luca.config.codeSyncChannel || "/changes"
+  channel:    Luca.config.codeSyncChannel || "/luca-code-sync"
 
 codeManager.classMethods
   setup: (options={})->
     @codeSyncManager = new Luca.CodeSyncManager(options) 
-    @codeSyncManager.trigger("ready")
+    @codeSyncManager.trigger "ready"
 
 codeManager.privateMethods
   initialize: (@attributes={})->
@@ -19,6 +63,9 @@ codeManager.privateMethods
     Luca.SocketManager::initialize.call(@, @attributes)
     @bindToChannel()
 
+  start: ()->
+    @trigger "ready"
+
   bindToChannel: ()->
     if @client?
       @client.subscribe @channel, ()=>
@@ -123,4 +170,4 @@ codeManager.privateMethods
       $('head').append( link )
 
 codeManager.defines
-  make: Backbone.View::make
+  make: Luca.View::make

data/app/assets/javascripts/luca/development/console.coffee

@@ -186,7 +186,7 @@ Luca.util.inspectComponent = (component)->
 
 Luca.util.launchers.developmentConsole = (name="luca-development-console")->
   @_lucaDevConsole = Luca name, ()=>
-    @$el.append Backbone.View::make("div", id: "#{ name }-wrapper", class: "modal fade large")
+    @$el.append Luca.View::make("div", id: "#{ name }-wrapper", class: "modal fade large")
 
     dconsole = new Luca.tools.DevelopmentConsole
       name: name

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

@@ -22,7 +22,7 @@ lucaUtilityHelper = (payload, args...)->
 
 (window || global).Luca = ()-> lucaUtilityHelper.apply(@, arguments)
 
-Luca.VERSION = '0.9.9'
+Luca.VERSION = '0.9.91'
 
 _.extend Luca,
   core: {}

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

@@ -1,3 +1,4 @@
+#= require_self
 #= require_tree ./templates
 #= require ./framework
 #= require ./config

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

@@ -112,7 +112,8 @@ Luca.util.loadScript = (url, callback) ->
   script.src = url
   document.body.appendChild(script)
 
-Luca.util.make = Backbone.View::make
+Luca.util.make = (tagName="div", attributes={}, contents="")->
+  Luca.View::make.apply(@, arguments)
 
 Luca.util.list = (list,options={},ordered)->
   container = if ordered then "ol" else "ul"

data/app/assets/stylesheets/luca/components/viewport.scss

@@ -3,10 +3,6 @@ html.luca-ui-fullscreen, body.luca-ui-fullscreen {
 }
 
 .luca-ui-fullscreen {
-  .fluid-viewport-wrapper {
-    padding-top:40px;
-  }
-
   .luca-viewport, .luca-ui-viewport, .fullscreen-container {
     min-height: 100%;
     height: auto !important;

data/bin/luca

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'rubygems'
+require 'faye'
+require 'sass'
+require 'coffee-script'
+require 'redcarpet'
+require 'listen'
+require 'luca'
+require 'luca/cli'
+
+Luca::Cli::Base.start