luca 0.8.599 → 0.9.0

data/src/core/view.coffee

@@ -1,6 +1,4 @@
 #### Luca Base View
-Luca.View = Backbone.View.extend
-  base: 'Luca.View'
 
 # The Luca.View class adds some very commonly used patterns
 # and functionality to the stock Backbone.View class. Features
@@ -8,82 +6,19 @@ Luca.View = Backbone.View.extend
 # against a Backbone.Model or Backbone.Collection reset event, Caching
 # views into a global Component Registry, and more.
 
-Luca.View.originalExtend = Backbone.View.extend
+_.def("Luca.View").extends("Backbone.View").with
 
-# By overriding Backbone.View.extend we are able to intercept
-# some method definitions and add special behavior around them
-# mostly related to render()
-Luca.View.extend = (definition)->
-  #### Rendering
-  #
-  # Our base view class wraps the defined render() method
-  # of the views which inherit from it, and does things like
-  # trigger the before and after render events automatically.
-  # In addition, if the view has a deferrable property on it
-  # then it will make sure that the render method doesn't get called
-  # until.
-
-  _base = definition.render
-
-  _base ||= ()->
-    container = if _.isFunction(@container) then @container() else @container
-
-    return @ unless $(container) and @$el
-
-    $(container).append( @$el )
-
-    return @
-
-  definition.render = ()->
-    if @layoutTemplate?
-      @$el.html()
-
-    if @deferrable
-      @trigger "before:render", @
-
-      @deferrable.bind @deferrable_event, _.once ()=>
-        _base.apply(@, arguments)
-        @trigger "after:render", @
-
-      # we might not want to fetch immediately upon
-      # rendering, so we can pass a deferrable_trigger
-      # event and not fire the fetch until this event
-      # occurs
-      if !@deferrable_trigger
-        @immediate_trigger = true
-
-      if @immediate_trigger is true
-        @deferrable.fetch()
-      else
-        @bind @deferrable_trigger, _.once ()=>
-          @deferrable.fetch()
-
-      return @
-
-    else
-      @trigger "before:render", @
-      _base.apply(@, arguments)
-      @trigger "after:render", @
-
-      return @
-
-  Luca.View.originalExtend.call(@, definition)
-
-_.extend Luca.View.prototype,
-  applyStyles: (styles={})->
-    for setting, value  of styles
-      @$el.css(setting,value)
-
-    @
+  additionalClassNames:[]
 
   debug: ()->
     return unless @debugMode or window.LucaDebugMode?
     console.log [(@name || @cid),message] for message in arguments
 
   trigger: ()->
-    if Luca.enableGlobalObserver and @observeEvents is true
-      Luca.ViewObserver ||= new Luca.Observer(type:"view")
-      Luca.ViewObserver.relay @, arguments
+    if Luca.enableGlobalObserver
+      if Luca.developmentMode is true or @observeEvents is true
+        Luca.ViewObserver ||= new Luca.Observer(type:"view")
+        Luca.ViewObserver.relay @, arguments
 
     Backbone.View.prototype.trigger.apply @, arguments
 
@@ -96,17 +31,16 @@ _.extend Luca.View.prototype,
     "deactivation"
   ]
 
-  # which event should we listen to on
-  # our deferrable property, before we
-  # trigger the actual rendering
-  deferrable_event: "reset"
-
   initialize: (@options={})->
 
     _.extend @, @options
 
     @cid = _.uniqueId(@name) if @name?
 
+    if template = @bodyTemplate
+      @$el.empty()
+      Luca.View::$html.call(@, Luca.template(template, @) )
+
     #### View Caching
     #
     # Luca.View(s) which get created get stored in a global cache by their
@@ -118,10 +52,11 @@ _.extend Luca.View.prototype,
     @setupHooks( unique )
 
     if @autoBindEventHandlers is true
-      _( @events ).each (handler,event)=>
-        if _.isString(handler)
-          _.bindAll @, handler
+      @bindAllEventHandlers()
 
+    if @additionalClassNames
+      @additionalClassNames = @additionalClassNames.split(" ") if _.isString(@additionalClassNames)
+      @$el.addClass( additional ) for additional in @additionalClassNames
 
     @trigger "after:initialize", @
 
@@ -129,7 +64,36 @@ _.extend Luca.View.prototype,
 
     @delegateEvents()
 
-  $container: ()-> $(@container)
+  #### JQuery / DOM Selector Helpers
+  $wrap: (wrapper)->
+    if !wrapper.match(/[<>]/)
+      wrapper = @make("div",class:wrapper)
+
+    @$el.wrap( wrapper )
+
+  $template: (template, variables={})->
+    @$el.html( Luca.template(template,variables) )
+
+  $html: (content)->
+    @$el.html( content )
+
+  $append: (content)->
+    @$el.append( content )
+
+  #### Containers
+  #
+  # Luca is heavily reliant on the concept of Container views.  Views which
+  # contain other views and handle inter-component communication between the
+  # component views.  The default render() operation consists of building the
+  # view's content, and then attaching that view to its container.
+  #
+  # 99% of the time this would happen automatically
+  $attach: ()->
+    @$container().append( @el )
+
+  $container: ()->
+    $(@container)
+
   #### Hooks or Auto Event Binding
   #
   # views which inherit from Luca.View can define hooks
@@ -147,13 +111,14 @@ _.extend Luca.View.prototype,
     set ||= @hooks
 
     _(set).each (eventId)=>
-      parts = eventId.split(':')
-      prefix = parts.shift()
+      fn = Luca.util.hook( eventId )
+
+      callback = ()=>
+        @[fn]?.apply @, arguments
 
-      parts = _( parts ).map (p)-> _.string.capitalize(p)
-      fn = prefix + parts.join('')
+      callback = _.once(callback) if eventId?.match(/once:/)
 
-      @bind eventId, ()=> @[fn].apply @, arguments if @[fn]
+      @bind eventId, callback
 
 
   #### Luca.Collection and Luca.CollectionManager integration
@@ -207,3 +172,111 @@ _.extend Luca.View.prototype,
     @events ||= {}
     @events[ selector ] = handler
     @delegateEvents()
+
+  bindAllEventHandlers: ()->
+    _( @events ).each (handler,event)=>
+      if _.isString(handler)
+        _.bindAll @, handler
+
+  definitionClass: ()->
+    Luca.util.resolve(@displayName, window)?.prototype
+
+  # refreshCode happens whenever the Luca.Framework extension
+  # system is run after there are running instances of a given component
+
+  # in the context of views, what this means is that each eventHandler which
+  # is bound to a specific object via _.bind or _.bindAll, or autoBindEventHandlers
+  # is refreshed with the prototype method of the component that it inherits from,
+  # and then delegateEvents is called to refresh any of the updated event handlers
+
+  # in addition to this, all properties of the instance of a given view which are
+  # also backbone views will have the same process run against them
+  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]
+
+  collections: ()-> Luca.util.selectProperties( Luca.isBackboneCollection, @ )
+  models: ()-> Luca.util.selectProperties( Luca.isBackboneModel, @ )
+  views: ()-> Luca.util.selectProperties( Luca.isBackboneView, @ )
+
+
+originalExtend = Backbone.View.extend
+
+customizeRender = (definition)->
+  #### Rendering
+  #
+  # Our base view class wraps the defined render() method
+  # of the views which inherit from it, and does things like
+  # trigger the before and after render events automatically.
+  # In addition, if the view has a deferrable property on it
+  # then it will make sure that the render method doesn't get called
+  # until.
+
+  _base = definition.render
+
+  _base ||= Luca.View::$attach
+
+
+  definition.render = ()->
+    view = @
+    # if a view has a deferrable property set
+
+    if @deferrable
+      target = @deferrable_target
+
+      unless Luca.isBackboneCollection(@deferrable)
+        @deferrable = @collection
+
+      target ||= @deferrable
+      trigger = if @deferrable_event then @deferrable_event else "reset"
+
+      view.defer ()->
+        _base.call(view)
+        view.trigger "after:render", view
+      .until(target,trigger)
+
+      view.trigger "before:render", @
+
+      autoTrigger = @deferrable_trigger || @deferUntil
+
+      if !autoTrigger?
+        target[ (@deferrable_method||"fetch") ].call(target)
+      else
+        fn = _.once ()=> @deferrable[ (@deferrable_method||"fetch") ]?()
+        (@deferrable_target || @ ).bind(@deferrable_trigger, fn)
+
+      return @
+
+    else
+      @trigger "before:render", @
+      _base.apply(@, arguments)
+      @trigger "after:render", @
+
+      return @
+
+  definition
+
+# By overriding Backbone.View.extend we are able to intercept
+# some method definitions and add special behavior around them
+# mostly related to render()
+Luca.View.extend = (definition)->
+  definition = customizeRender( definition )
+  originalExtend.call(@, definition)
+

data/src/framework.coffee

@@ -1,18 +1,39 @@
-window.Luca =
-  VERSION: "0.8.599"
+# 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 _.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()
+
+_.extend Luca,
+  VERSION: "0.9.0"
   core: {}
   containers: {}
   components: {}
   modules: {}
   util: {}
   fields: {}
-  component_cache:
-    cid_index: {}
-    name_index: {}
-  registry:
-    classes: {}
-    namespaces:["Luca.containers","Luca.components"]
+  registry:{}
+
+# for triggering / binding to component definitions
+_.extend Luca, Backbone.Events
 
+# 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
@@ -25,6 +46,32 @@ Luca.enableGlobalObserver = false
 # 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))
+
+Luca.isComponent = (obj)->
+  Luca.isBackboneModel(obj) or Luca.isBackboneView(obj) or Luca.isBackboneCollection(obj)
+
 Luca.isBackboneModel = (obj)->
   _.isFunction(obj?.set) and _.isFunction(obj?.get) and _.isObject(obj?.attributes)
 
@@ -34,101 +81,6 @@ Luca.isBackboneView = (obj)->
 Luca.isBackboneCollection = (obj)->
   _.isFunction(obj?.fetch) and _.isFunction(obj?.reset)
 
-# adds an additional namespace to look for luca ui
-# components.  useful for when you define a bunch of
-# components in your own application's namespace
-Luca.registry.addNamespace = (identifier)->
-  Luca.registry.namespaces.push( identifier )
-  Luca.registry.namespaces = _( Luca.registry.namespaces ).uniq()
-
-# stores or looks up a component in the component cache
-# by its backbone @cid or by its component_name
-Luca.cache = (needle, component)->
-  Luca.component_cache.cid_index[ needle ] = component if component?
-
-  component = Luca.component_cache.cid_index[ needle ]
-
-  # optionally, cache it by tying its name to its cid for easier lookups
-  if component?.component_name?
-    Luca.component_cache.name_index[ component.component_name ] = component.cid
-  else if component?.name?
-    Luca.component_cache.name_index[ component.name ] = component.cid
-
-  return component if component?
-
-  # perform a lookup by name if the component_id didn't turn anything
-  lookup_id = Luca.component_cache.name_index[ needle ]
-
-  Luca.component_cache.cid_index[ lookup_id ]
-
-# Takes an string like "deep.nested.value" and an object like window
-# and returns the value of window.deep.nested.value.  useful for defining
-# references on objects which don't yet exist, as strings, which get
-# evaluated at runtime when such references will be available
-Luca.util.resolve = (accessor, source_object)->
-  _( accessor.split(/\./) ).inject (obj,key)->
-    obj = obj?[key]
-  , source_object
-
-# A better name for Luca.util.nestedValue
-Luca.util.nestedValue = Luca.util.resolve
-
-# turns a word like form_view into FormView
-Luca.util.classify = (string="")->
-  _.string.camelize( _.string.capitalize( string ) )
-
-# Lookup a component in the Luca component registry
-# by it's ctype identifier.  If it doesn't exist,
-# check any other registered namespace
-Luca.registry.lookup = (ctype)->
-  c = Luca.registry.classes[ctype]
-
-  return c if c?
-
-  className = Luca.util.classify(ctype)
-
-  parents = _( Luca.registry.namespaces ).map (namespace)-> Luca.util.nestedValue(namespace, (window || global))
-
-  _( parents ).chain().map((parent)-> parent[className]).compact().value()?[0]
-
-# one of the main benefits of Luca is the ability to structure your app as
-# large blocks of JSON configuration.  In order to convert an object into
-# a Luca component, we lookup the object's class by converting its ctype / type
-# property into a class that has been registered in the component registry
-Luca.util.lazyComponent = (config)->
-  ctype = config.ctype || config.type
-
-  componentClass = Luca.registry.lookup( ctype )
-
-  throw "Invalid Component Type: #{ ctype }.  Did you forget to register it?" unless componentClass
-
-  constructor = eval( componentClass )
-
-  new constructor(config)
-
-# for lazy component creation
-Luca.register = (component, constructor_class)->
-  exists = Luca.registry.classes[component]
-
-  if exists? and !window.TestRun?
-    console.log "Attempting to register component with the signature #{ component }. Already exists"
-  else
-    Luca.registry.classes[component] = constructor_class
-
-Luca.available_templates = (filter="")->
-  available = _( Luca.templates ).keys()
-
-  if filter.length > 0
-    _( available ).select (tmpl)-> tmpl.match(filter)
-  else
-    available
-
-Luca.util.isIE = ()->
-  try
-    Object.defineProperty({}, '', {})
-    return false
-  catch e
-    return true
 
 # This is a convenience method for accessing the templates
 # available to the client side app, either the ones which ship with Luca
@@ -140,6 +92,9 @@ Luca.util.isIE = ()->
 Luca.template = (template_name, variables)->
   window.JST ||= {}
 
+  if _.isFunction(template_name)
+    return template_name(variables)
+
   luca = Luca.templates?[ template_name ]
   jst = JST?[ template_name ]
 
@@ -152,7 +107,7 @@ Luca.template = (template_name, variables)->
     jst = _( JST ).detect (fn,template_id)->
       needle.exec( template_id )
 
-  throw "Could not find template with #{ template_name }" unless luca || jst
+  throw "Could not find template named #{ template_name }" unless luca || jst
 
   template = luca || jst
 
@@ -160,77 +115,56 @@ Luca.template = (template_name, variables)->
 
   template
 
-#### Component Definition And Inheritance
-#
-# this is a nice way of extending / inheriting
-# this allows for syntactic sugar such as:
-#
-# Luca.define("TestClass").extends("Luca.View").with
-#   property: "value"
-#   name: "whatever"
-#
-# All instances of TestClass defined this way, will have
-# _className properties of 'TestClass' as well as a reference
-# to the extended class 'Luca.View' so that you can inspect
-# an instance of TestClass and know that it inherits from 'Luca.View'
-class DefineProxy
-  constructor:(componentName)->
-    @namespace = (window || global)
-    @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('.') )
-
-  in: (@namespace)-> @
-  from: (@superClassName)-> @
-  extends: (@superClassName)-> @
-  extend: (@superClassName)-> @
-  with: (properties)->
-    at = if @namespaced then Luca.util.resolve(@namespace, (window || global)) else (window||global)
-
-    if @namespaced and _.isUndefined(at)
-      eval("window.#{ @namespace } = {}")
-      at = Luca.util.resolve(@namespace,(window || global))
-
-    at[@componentId] = Luca.extend(@superClassName,@componentName, properties)
-
-    # automatically register this with the component registry
-    Luca.register( _.string.underscored(@componentId), @componentName)
-
-    at[@componentId]
-
-Luca.define = (componentName)->
-  new DefineProxy(componentName)
-
-# An alias for Luca.define
-# which I think reads better:
-#
-# Luca.component('Whatever').extends('Something').with(enhancements)
-Luca.component = Luca.define
-
-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._className = childName
-
-  properties._superClass = ()->
-    superClass._className ||= superClassName
-    superClass
-
-  superClass.extend(properties)
-
-_.mixin
-  component: Luca.define
-
-#### Once We Are Ready To go....
-$ do ->
-  $('body').addClass('luca-ui-enabled')
+Luca.available_templates = (filter="")->
+  available = _( Luca.templates ).keys()
+
+  if filter.length > 0
+    _( available ).select (tmpl)-> tmpl.match(filter)
+  else
+    available
+
+
+
+UnderscoreExtensions =
+  module: (base,module)->
+    _.extend base, module
+    if base.included and _(base.included).isFunction()
+      base.included.apply(base)
+
+  delete: (object, key)->
+    value = object[key]
+    delete object[key]
+    value
+
+  # 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
+  idle: (code, delay=1000)->
+    delay = 0 if window.DISABLE_IDLE
+    handle = undefined
+    ()->
+      window.clearTimeout(handle) if handle
+      handle = window.setTimeout(_.bind(code, @), delay)
+
+  idleShort: (code, delay=100)->
+    delay = 0 if window.DISABLE_IDLE
+    handle = undefined
+    ()->
+      window.clearTimeout(handle) if handle
+      handle = window.setTimeout(_.bind(code, @), delay)
+
+  idleMedium: (code, delay=2000)->
+    delay = 0 if window.DISABLE_IDLE
+    handle = undefined
+    ()->
+      window.clearTimeout(handle) if handle
+      handle = window.setTimeout(_.bind(code, @), delay)
+
+  idleLong: (code, delay=5000)->
+    delay = 0 if window.DISABLE_IDLE
+    handle = undefined
+    ()->
+      window.clearTimeout(handle) if handle
+      handle = window.setTimeout(_.bind(code, @), delay)
+
+_.mixin(UnderscoreExtensions)