luca 0.9.9 → 0.9.42

data/src/define.coffee

@@ -0,0 +1,110 @@
+# Component Definition Helpers
+#
+#
+# We have customized the core Backbone.extend process to use a slightly
+# different syntax, which allows us to intercept the component definition at
+# various points, and maintain information about classes being defined, and
+# the relationships between inherited classes, etc.
+
+# _.def, or Luca.define returns a chainable object which allows you to define
+# your components with a readable syntax.  For example:
+
+# _.def("Luca.View").extends("Backbone.View").with the_good:"shit"
+# _.def("MyView").extends("Luca.View").with the_custom:"shit"
+
+Luca.define = (componentName)->
+  new DefineProxy(componentName)
+
+Luca.component = Luca.define
+
+# The define proxy chain sets up a call to Luca.extend, which is a wrapper around Luca and Backbone component class' extend function.
+class DefineProxy
+  constructor:(componentName)->
+    @namespace = Luca.util.namespace()
+    @componentId = @componentName = componentName
+
+    if componentName.match(/\./)
+      @namespaced = true
+      parts = componentName.split('.')
+      @componentId = parts.pop()
+      @namespace = parts.join('.')
+
+      # automatically add the namespace to the namespace registry
+      Luca.registry.addNamespace( parts.join('.') )
+
+  # allow for specifying the namespace
+  in: (@namespace)-> @
+
+  # allow for multiple ways of saying the same thing for readability purposes
+  from: (@superClassName)-> @
+  extends: (@superClassName)-> @
+  extend: (@superClassName)-> @
+
+  # an alias for with, or a readability helper in multi-line definitions
+  enhance: (properties)->
+    return @with(properties) if properties?
+    @
+
+  # which properties, methods, etc will you be extending the base class with?
+  with: (properties)->
+    at = if @namespaced
+      Luca.util.resolve(@namespace, (window || global))
+    else
+      (window||global)
+
+    # automatically create the namespace
+    if @namespaced and not at?
+      eval("(window||global).#{ @namespace } = {}")
+      at = Luca.util.resolve(@namespace,(window || global))
+
+    at[@componentId] = Luca.extend(@superClassName,@componentName, properties)
+
+    if Luca.autoRegister is true 
+      componentType = "view" if Luca.isViewPrototype( at[@componentId] )
+
+      if Luca.isCollectionPrototype( at[@componentId] )
+        Luca.Collection.namespaces ||= []
+        Luca.Collection.namespaces.push( @namespace )
+        componentType = "collection" 
+
+      componentType = "model" if Luca.isModelPrototype( at[@componentId] )
+
+      # automatically register this with the component registry
+      Luca.register( _.string.underscored(@componentId), @componentName, componentType)
+
+    at[@componentId]
+
+# The last method of the DefineProxy chain is always going to result in
+# a call to Luca.extend.  Luca.extend wraps the call to Luca.View.extend,
+# or Backbone.Collection.extend, and accepts the names of the extending,
+# and extended classes as strings.  This allows us to maintain information
+# and references to the classes and their prototypes, mainly for the purposes
+# of introspection and development tools
+Luca.extend = (superClassName, childName, properties={})->
+  superClass = Luca.util.resolve( superClassName, (window || global) )
+
+  unless _.isFunction(superClass?.extend)
+    throw "#{ superClassName } is not a valid component to extend from"
+
+  properties.displayName = childName
+
+  properties._superClass = ()->
+    superClass.displayName ||= superClassName
+    superClass
+
+  properties._super = (method, context, args)->
+    @_superClass().prototype[method]?.apply(context, args)
+
+  definition = superClass.extend(properties)
+
+  # _.def("MyView").extends("View").with
+  #   include: ['Luca.Events']
+  if _.isArray( properties?.include )
+    for mixin in properties.include
+      mixin = Luca.util.resolve(mixin) if _.isString(mixin)
+      _.extend(definition::, mixin)
+
+  definition
+
+_.mixin
+  def: Luca.define

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

@@ -1,112 +1,74 @@
-lucaUtilityHelper = (payload, args...)->
-  if arguments.length is 0 
-    return _( Luca.Application.instances ).values()?[0]
-
+# the Luca() browser utility function is meant to be a smart wrapper around various
+# types of input which will return what the developer would expect given the
+# context it is used.
+(window || global).Luca = (payload, args...)->
   if _.isString(payload) and result = Luca.cache(payload)
     return result
 
   if _.isString(payload) and result = Luca.find(payload)
     return result
 
-  if _.isString(payload) and result = Luca.registry.find(payload)
-    return result
-
-  if payload instanceof jQuery and result = Luca.find(payload)
-    return result
-
   if _.isObject(payload) and payload.ctype?
     return Luca.util.lazyComponent( payload )
 
+  if _.isObject(payload) and payload.defines and payload.extends
+    definition = payload.defines
+    inheritsFrom = payload.extends
+
   if _.isFunction( fallback = _(args).last() )
     return fallback()
 
-(window || global).Luca = ()-> lucaUtilityHelper.apply(@, arguments)
-
-Luca.VERSION = '0.9.9'
-
 _.extend Luca,
+  VERSION: "0.9.42"
   core: {}
-  collections: {}
   containers: {}
   components: {}
-  models: {}
-  concerns: {}
+  modules: {}
   util: {}
   fields: {}
   registry:{}
   options: {}
-  config: {}
-  logger: (trackerMessage)->
-    (args...)->
-      args.unshift( trackerMessage )
-      console.log(@, args)
-
-  getHelper: ()->
-    ()-> lucaUtilityHelper.apply(@, arguments)
 
 # for triggering / binding to component definitions
 _.extend Luca, Backbone.Events
 
-Luca.setupCollectionSpace = (options={})->
-  {baseParams, modelBootstrap} = options
-
-  if baseParams? 
-    Luca.Collection.baseParams( baseParams )
-  else
-    Luca.warn('You should remember to set the base params for Luca.Collection class.  You can do this by defining a property or function on Luca.config.baseParams')
-
-  if modelBootstrap?
-    Luca.Collection.bootstrap( modelBootstrap )
-  else
-    Luca.warn("You should remember to set the model bootstrap location for Luca.Collection.  You can do this by defining a property or function on Luca.config.modelBootstrap")
-
-# Creates a basic Namespace for you to begin defining
-# your application and all of its components.
-Luca.initialize = (namespace, options={})->
-  Luca.namespace = namespace.toLowerCase()
-  existing       = Luca.util.resolve(namespace, window || global) || {}
-
-  _.defaults existing,
-    views: {}
-    collections: {}
-    models: {}
-    components: {}
-    lib: {}
-    util: {}
-    concerns: {}
-    register: ()->
-      Luca.register.apply(@, arguments)
-    onReady: ()-> 
-      Luca.onReady.apply(@, arguments)
-    getApplication: ()->
-      Luca.getApplication?.apply(@, arguments)
-    getCollectionManager: ()->
-      Luca.CollectionManager.get?.apply(@, arguments)
-    route: Luca.routeHelper
-
-
-  object = {}
-  object[ namespace ] = _.defaults(Luca.getHelper(), existing)
-
-  _.extend(Luca.config, options)
-  _.extend (window || global), object
-
-  Luca.lastNamespace = namespace
-  Luca.concern.namespace "#{ namespace }.concerns"
-  Luca.registry.namespace "#{ namespace }.views"
-  Luca.Collection.namespace "#{ namespace }.collections"
-
-  Luca.on "ready", ()->
-    Luca.setupCollectionSpace(options)
-
-Luca.onReady = (callback)->
-  Luca.define.close()
-  Luca.trigger("ready")
-
-  $ -> callback.apply(@, arguments)
-
-Luca.find = (el)->
-  Luca( $(el).data('luca-id') )
+# When using Luca.define() should we automatically register
+# the component with the registry?
+Luca.autoRegister = true
+
+# if developmentMode is true, you have access to some neat development tools
+Luca.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 = 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.enableBootstrap = true
+
+Luca.keys =
+  ENTER: 13
+  ESCAPE: 27
+  KEYLEFT: 37
+  KEYUP: 38
+  KEYRIGHT: 39
+  KEYDOWN: 40
+  SPACEBAR: 32
+  FORWARDSLASH: 191
+
+# build a reverse map
+Luca.keyMap = _( Luca.keys ).inject (memo, value, symbol)->
+  memo[value] = symbol.toLowerCase()
+  memo
+, {}
+
+Luca.find = ()->
+  # TODO Implement
+  undefined
 
 Luca.supportsEvents = Luca.supportsBackboneEvents = (obj)->
   Luca.isComponent(obj) or (_.isFunction( obj?.trigger ) or _.isFunction(obj?.bind))
@@ -142,29 +104,75 @@ Luca.isCollectionPrototype = (obj)->
   obj? and obj::? and !Luca.isModelPrototype(obj) and obj::reset? and obj::select? and obj::reject?
 
 Luca.inheritanceChain = (obj)->
-  Luca.parentClasses(obj)
-
+  _( Luca.parentClasses(obj) ).map (className)-> Luca.util.resolve(className)
+    
 Luca.parentClasses = (obj)->
   list = []
 
   if _.isString(obj)
     obj = Luca.util.resolve(obj)
 
-  metaData = obj.componentMetaData?()
-  metaData ||= obj::componentMetaData?()
+  list.push( obj.displayName || obj::?.displayName || Luca.parentClass(obj) )
+
+  classes = until not Luca.parentClass(obj)?
+    obj = Luca.parentClass(obj)
+
+  list = list.concat(classes)
 
-  list = metaData?.classHierarchy() || [obj.displayName || obj::displayName]
+  _.uniq list
+
+Luca.parentClass = (obj)->
+  list = []
 
-Luca.parentClass = (obj, resolve=true)->
   if _.isString( obj )
     obj = Luca.util.resolve(obj)
 
-  parent = obj.componentMetaData?()?.meta["super class name"]
-  parent ||= obj::componentMetaData?()?.meta["super class name"]
+  if Luca.isComponent(obj)
+    obj.displayName
+
+  else if Luca.isComponentPrototype(obj)
+    obj::_superClass?()?.displayName
+
+# This is a convenience method for accessing the templates
+# available to the client side app, either the ones which ship with Luca
+# available in Luca.templates ( these take precedence ) or
+# the app's own templates which are usually available in JST
+
+# optionally, passing in variables will compile the template for you, instead
+# of returning a reference to the function which you would then call yourself
+Luca.template = (template_name, variables)->
+  window.JST ||= {}
+
+  if _.isFunction(template_name)
+    return template_name(variables)
+
+  luca = Luca.templates?[ template_name ]
+  jst = JST?[ template_name ]
+
+  unless luca? or jst?
+    needle = new RegExp("#{ template_name }$")
 
-  parent || obj.displayName || obj.prototype?.displayName
+    luca = _( Luca.templates ).detect (fn,template_id)->
+      needle.exec( template_id )
 
-  if resolve then Luca.util.resolve(parent) else parent
+    jst = _( JST ).detect (fn,template_id)->
+      needle.exec( template_id )
+
+  throw "Could not find template named #{ template_name }" unless luca || jst
+
+  template = luca || jst
+
+  return template(variables) if variables?
+
+  template
+
+Luca.available_templates = (filter="")->
+  available = _( Luca.templates ).keys()
+
+  if filter.length > 0
+    _( available ).select (tmpl)-> tmpl.match(filter)
+  else
+    available
 
 
 UnderscoreExtensions =
@@ -181,9 +189,6 @@ UnderscoreExtensions =
   # this function will ensure a function gets called at least once
   # afrer x delay.  by setting defaults, we can use this on backbone
   # view definitions
-  #
-  # Note:  I am not sure if this is the same as _.debounce or not.  I will need
-  # to look into it
   idle: (code, delay=1000)->
     delay = 0 if window.DISABLE_IDLE
     handle = undefined

data/src/index.coffee

@@ -0,0 +1,23 @@
+#= require ./util
+#= require_tree ./plugins
+#= require ./define
+
+#= require_tree ./modules
+
+#= require ./core/registry
+#= require ./core/observer
+#= require ./core/view
+#= require ./core/model
+#= require ./core/collection
+#= require ./core/panel
+#= require ./core/field
+#= require ./core/container
+
+#= require_tree ./managers
+
+#= require ./containers/split_view
+#= require ./containers/column_view
+#= require_tree ./containers
+
+#= require ./components/template
+#= require_tree ./components

data/{app/assets/javascripts/luca → src}/managers/collection_manager.coffee

@@ -1,9 +1,10 @@
 class Luca.CollectionManager
   name: "primary"
 
+  collectionNamespace: Luca.Collection.namespace
+
   __collections: {}
 
-  autoStart: true
   relayEvents: true 
 
   constructor: (@options={})->
@@ -14,8 +15,6 @@ class Luca.CollectionManager
     if existing = Luca.CollectionManager.get?(@name)
       throw 'Attempt to create a collection manager with a name which already exists'
 
-    @collectionNamespace ||= Luca.util.read( Luca.Collection.namespace )  
-    
     Luca.CollectionManager.instances ||= {}
 
     _.extend @, Backbone.Events
@@ -30,9 +29,7 @@ class Luca.CollectionManager
     @state = new Luca.Model()
 
     if @initialCollections
-      @on "ready", handleInitialCollections, @
-
-    @trigger "ready" if @autoStart is true
+      handleInitialCollections.call(@)
 
   add: (key, collection)->
     @currentScope()[ key ] ||= collection
@@ -48,11 +45,7 @@ class Luca.CollectionManager
     CollectionClass ||= guessCollectionClass.call(@, key)
     collectionOptions.name = "" if collectionOptions.private
 
-    try  
-      collection = new CollectionClass(initialModels,collectionOptions)
-    catch e
-      console.log "Error creating collection", CollectionClass, collectionOptions, key
-      throw(e)
+    collection = new CollectionClass(initialModels,collectionOptions)
 
     @add(key, collection)
 
@@ -88,6 +81,7 @@ class Luca.CollectionManager
 
   collectionCountDidChange: ()->
     if @allCollectionsLoaded() 
+      # for backwards compat
       @trigger "all_collections_loaded" 
       @trigger "initial:load"
 
@@ -103,33 +97,13 @@ class Luca.CollectionManager
   private: (key, collectionOptions={}, initialModels=[])->
     @create(key,collectionOptions,initialModels,true)
 
-#### Helpers
-
-Luca.CollectionManager.isRunning = ()->
-  _.isEmpty( Luca.CollectionManager.instances ) isnt true
-
 Luca.CollectionManager.destroyAll = ()-> 
   Luca.CollectionManager.instances = {} 
 
-Luca.CollectionManager.loadCollectionsByName = (set, callback)->
-  for name in set 
-    if collection = @getOrCreate(name)
-      collection.on "reset", ()->
-        callback(collection)
-        collection.unbind("reset", @)
-
-      collection.fetch()  
-
-#### Private Methods
 guessCollectionClass = (key)->
   classified = Luca.util.classify( key )
-
-  if _.isString( @collectionNamespace )
-    @collectionNamespace = Luca.util.resolve(@collectionNamespace)
-
   # support our naming convention of Books
   guess = (@collectionNamespace || (window || global) )[ classified ]
-
   # support naming covention like BooksCollection
   guess ||= (@collectionNamespace || (window || global) )[ "#{classified}Collection" ]
 
@@ -146,22 +120,24 @@ guessCollectionClass = (key)->
 loadInitialCollections = ()->
   collectionDidLoad = (collection) =>
     current = @state.get("loaded_collections_count")
+
     @state.set("loaded_collections_count", current + 1)
     @trigger "collection_loaded", collection.name
     collection.unbind "reset"
 
-  set = @initialCollections
-  Luca.CollectionManager.loadCollectionsByName.call(@, set, collectionDidLoad)
-
+  _(@initialCollections).each (name) =>
+    collection = @getOrCreate(name)
+    collection.once "reset", ()->
+      collectionDidLoad(collection)
+    collection.fetch()
 
 handleInitialCollections = ()->
   @state.set({loaded_collections_count: 0, collections_count: @initialCollections.length })
-  @state.bind "change:loaded_collections_count", ()=> 
-    @collectionCountDidChange()
+  @state.bind "change:loaded_collections_count", ()=> @collectionCountDidChange()
 
   if @useProgressLoader
     @loaderView ||= new Luca.components.CollectionLoaderView(manager: @,name:"collection_loader_view")
 
   loadInitialCollections.call(@)
 
-  @
+  @

data/src/managers/socket_manager.coffee

@@ -0,0 +1,54 @@
+# Luca.SocketManager is an abstraction
+# around various websocket services such as
+# faye.js, socket.io, now.js, etc.
+#
+# It provides a common interface for adding
+# push / async functionality to Collections,
+# Models, and the like, regardless of the
+# transport mechanism used.
+#
+# Simply bind to it, and any message that comes
+# across the channel you subscribe to, will be
+# bubbled up as a Backbone.Event with the message
+# contents as your argument
+class Luca.SocketManager
+  constructor: (@options={})->
+    _.extend Backbone.Events
+
+    @loadTransport()
+
+  connect: ()->
+    switch @options.provider
+      when "socket.io"
+        @socket = io.connect( @options.socket_host )
+      when "faye.js"
+        @socket = new Faye.Client( @options.socket_host )
+
+  #### Transport Loading and Configuration
+  #
+  # Luca wraps several popular client side socket abstractions
+  # such as socket.io or faye.js ( more coming soon )
+  #
+  # it provides a common interface on top of these and just
+  # treats them as Backbone.Events which you bind to like you
+  # would on any other Backbone class
+
+  transportLoaded: ()-> @connect()
+
+  transport_script: ()->
+    switch @options.provider
+      when "socket.io" then "#{ @options.transport_host }/socket.io/socket.io.js"
+      when "faye.js" then "#{ @options.transport_host }/faye.js"
+
+  loadTransport: ()->
+    script = document.createElement 'script'
+    script.setAttribute "type", "text/javascript"
+    script.setAttribute "src", @transport_script()
+    script.onload = @transportLoaded
+
+    if Luca.util.isIE()
+      script.onreadystatechange = ()=>
+        if script.readyState is "loaded"
+          @transportLoaded()
+
+    document.getElementsByTagName('head')[0].appendChild script

data/{app/assets/javascripts/luca/concerns → src/modules}/deferrable.coffee

@@ -1,14 +1,13 @@
-# TODO
-# 
-# This is horrendous code.  I need to replace it ASAP
-Luca.concerns.Deferrable = 
+# TODO THis module is going to be deprecated as it has been gradually gut over time
+Luca.modules.Deferrable = 
   configure_collection: (setAsDeferrable=true)->
     return unless @collection
 
     if _.isString( @collection ) and collectionManager = Luca.CollectionManager?.get()
       @collection = collectionManager.getOrCreate(@collection)
 
-    if _.isObject(@collection) and not Luca.isBackboneCollection(@collection) 
+    # if there is already an instantiated backbone collection don't do anything
+    unless @collection and _.isFunction( @collection.fetch ) and _.isFunction( @collection.reset )
       @collection = new Luca.Collection( @collection.initial_set, @collection )
     
     if @collection?.deferrable_trigger

data/src/modules/grid_layout.coffee

@@ -0,0 +1,3 @@
+Luca.modules.GridLayout = 
+  _included: (view, module)->
+    # implement  

data/{app/assets/javascripts/luca/concerns/loadmaskable.coffee → src/modules/load_mask.coffee}

@@ -1,30 +1,18 @@
-Luca.concerns.LoadMaskable = 
-  __initializer: ()->
-    return if @loadMask is false or not @loadMask?
+Luca.modules.LoadMaskable = 
+  _included: (self, module)->
+    _.bindAll self, "applyLoadMask", "disableLoadMask"
 
     if @loadMask is true
-      @loadMask = 
-        enableEvent: "enable:loadmask"
-        disableEvent: "disable:loadmask"
+      @defer ()=>
+        @$el.addClass('with-mask')
 
-    @on "collection:fetch", ()=> @trigger "enable:loadmask"
-    @on "collection:reset", ()=> @trigger "disable:loadmask"
+        if @$('.load-mask').length is 0
+          @loadMaskTarget().prepend Luca.template(@loadMaskTemplate, @)
+          @$('.load-mask').hide()
+      .until("after:render")
 
-    @on "after:render", ()->
-      @$el.addClass('with-mask')
-      if @$('.load-mask').length is 0 and @loadMaskTemplate?
-        @loadMaskTarget().prepend Luca.template(@loadMaskTemplate, @)
-        @$('.load-mask').hide()
-    , @
-
-    @on(@loadMask.enableEvent, @applyLoadMask, @)
-    @on(@loadMask.disableEvent, @applyLoadMask, @)
-
-  showLoadMask: ()->
-    @trigger("enable:loadmask")
-
-  hideLoadMask: ()->
-    @trigger("disable:loadmask")
+      @on (@loadmaskEnableEvent || "enable:loadmask"), @applyLoadMask
+      @on (@loadmaskDisableEvent || "disable:loadmask"), @applyLoadMask
 
   loadMaskTarget: ()->
     if @loadMaskEl? then @$(@loadMaskEl) else @$bodyEl()

data/src/plugins/development_tool_helpers.coffee

@@ -0,0 +1,21 @@
+Luca.DevelopmentToolHelpers = 
+  refreshCode: ()->
+    view = @
+
+    _( @eventHandlerProperties() ).each (prop)->
+      view[ prop ] = view.definitionClass()[prop]
+
+    if @autoBindEventHandlers is true
+      @bindAllEventHandlers()
+
+    @delegateEvents()
+
+  eventHandlerProperties: ()->
+    handlerIds = _( @events ).values()
+    _( handlerIds ).select (v)->
+      _.isString(v)
+
+  eventHandlerFunctions: ()->
+    handlerIds = _( @events ).values()
+    _( handlerIds ).map (handlerId)=>
+      if _.isFunction(handlerId) then handlerId else @[handlerId]