luca 0.9.7 → 0.9.8

data/app/assets/javascripts/luca/core/registry/component_definition.coffee

@@ -0,0 +1,318 @@
+# 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.
+#
+# Under the hood it isn't much more than Backbone.View.extend(@proto)  
+#
+# Luca provides a self-documenting component generation language which
+# allows you to build the @proto property in a way which captures the intent
+# of the interface being described.  
+#
+# Example:
+#   myForm = MyApp.register    'MyForm'
+# 
+#   myForm.extends             'Luca.components.FormView'
+#
+#   myForm.triggers            'some:custom:hook'
+#
+#   myForm.publicMethods
+#     publicMethod: ()-> ...
+#
+#   myForm.classMethods 
+#     classMethod: ()-> ...
+#
+# This gives us the ability to inspect our component registry at run time,
+# auto-generate nice documentation, build development tools, etc.
+
+class ComponentDefinition
+  constructor:(componentName, @autoRegister=true)->
+    @namespace = Luca.util.namespace()
+    @componentId = @componentName = componentName
+    @superClassName = 'Luca.View' 
+    @properties ||= {}
+    @_classProperties ||= {}
+
+    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('.') )
+
+    Luca.define.__definitions.push(@)
+
+  @create: (componentName, autoRegister=Luca.config.autoRegister)->
+    new ComponentDefinition(componentName, autoRegister)
+
+  isValid: ()->
+    return false unless _.isObject(@properties) 
+    return false unless Luca.util.resolve(@superClassName)?
+    return false unless @componentName?
+    true
+
+  isDefined: ()->
+    @defined is true
+
+  isOpen: ()->
+    !!(@isValid() and not @isDefined())
+
+  meta: (key, value)->
+    metaKey = @namespace + '.' + @componentId
+    metaKey = metaKey.replace(/^\./,'')
+    data = Luca.registry.addMetaData(metaKey, key, value)
+
+    @properties.componentMetaData = ()->
+      Luca.registry.getMetaDataFor(metaKey)
+
+  # 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)-> 
+    @
+
+  aliases: (@_aliases...)->
+    @meta("aliases", @_aliases)
+    @
+
+  replaces: (replaces...)->
+    @_aliases ||= []
+    for old in replaces
+      @_aliases.push(old)
+      Luca.util.deprecateComponent(old, @componentName)
+
+  triggers: (hooks...)->
+    _.defaults(@properties ||= {}, hooks: []) 
+    for hook in hooks
+      @properties.hooks.push(hook) 
+
+    @properties.hooks = _.uniq(@properties.hooks)
+
+    @meta("hooks", @properties.hooks)
+    @
+
+  includes: (includes...)->
+    _.defaults(@properties ||= {}, include: []) 
+    for include in includes
+      @properties.include.push(include) 
+    @properties.include = _.uniq(@properties.include)
+    @meta("includes", @properties.include)
+    @
+
+  mixesIn: (concerns...)->
+    _.defaults(@properties ||= {}, concerns: []) 
+    for concern in concerns
+      @properties.concerns.push(concern) 
+    @properties.concerns = _.uniq(@properties.concerns)
+
+    @meta("concerns", @properties.concerns)
+    @
+
+  contains: (components...)->
+    _.defaults(@properties, components: [])
+    @properties.components = components 
+    @
+
+  validatesConfigurationWith:(validationConfiguration={})->
+    @meta "configuration validations", validationConfiguration
+    @properties.validatable = true
+    @
+
+  beforeDefinition: (callback)->
+    @_classProperties.beforeDefinition = callback  
+    @
+
+  afterDefinition: (callback)->
+    @_classProperties.afterDefinition = callback  
+    @
+
+  classConfiguration: (properties={})->
+    @meta("class configuration", _.keys(properties))
+    _.defaults((@_classProperties||={}), properties)
+    @
+
+  configuration: (properties={})->
+    @meta("public configuration", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  publicConfiguration: (properties={})->
+    @meta("public configuration", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  privateConfiguration: (properties={})->
+    @meta("private configuration", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  classInterface: (properties={})->
+    @meta("class interface", _.keys(properties))
+    _.defaults((@_classProperties||={}), properties)
+    @
+
+  methods: (properties={})->
+    @meta("public interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  public: (properties={})->
+    @meta("public interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  publicInterface: (properties={})->
+    @meta("public interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  private: (properties={})->
+    @meta("private interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  privateInterface: (properties={})->
+    @meta("private interface", _.keys(properties) )
+    _.defaults((@properties||={}), properties)
+    @
+
+  # This is the end of the chain. It MUST be called
+  # in order for the component definition to be complete. 
+  definePrototype: (properties={})->
+    _.defaults((@properties||={}), 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))
+
+    @meta("super class name", @superClassName )
+    @meta("display name", @componentName)
+
+    @properties.displayName = @componentName
+    
+    @properties.componentMetaData = ()->
+      Luca.registry.getMetaDataFor(@displayName)
+
+    @_classProperties?.beforeDefinition?(@)
+
+    definition = at[@componentId] = Luca.extend(@superClassName,@componentName, @properties)
+
+    if _.isArray( @properties?.include )
+      for include in @properties.include
+        include = Luca.util.resolve(include) if _.isString(include)
+        if not include?
+          console.log "Attempt to include module failed. #{ include } not defined."
+        _.extend(definition::, include)
+
+    if @_aliases?
+      for alias in @_aliases
+        eval("#{ alias } = definition;")
+
+    if @autoRegister is true 
+      componentType = "view" if Luca.isViewPrototype( definition )
+
+      if Luca.isCollectionPrototype( definition )
+        Luca.Collection.namespaces ||= []
+        Luca.Collection.namespaces.push( @namespace )
+        componentType = "collection" 
+
+      componentType = "model" if Luca.isModelPrototype( definition )
+
+      # automatically register this with the component registry
+      Luca.registerComponent( _.string.underscored(@componentId), @componentName, componentType)
+
+    @defined = true
+
+    unless _.isEmpty(@_classProperties)
+      _.extend(definition, @_classProperties)
+
+
+
+    definition?.afterDefinition?.call(definition, @)
+
+    definition
+
+
+# Aliases for the mixin definition
+cd = ComponentDefinition::
+
+cd.concerns = cd.behavesAs = cd.uses = cd.mixesIn 
+
+# Aliases for the final call on the define proxy
+cd.register = cd.defines = cd.defaults = cd.exports = cd.defaultProperties = cd.definePrototype
+
+cd.defaultsTo = cd.enhance = cd.with = cd.definePrototype
+
+cd.publicMethods = cd.publicInterface
+cd.privateMethods = cd.privateInterface
+cd.classProperites = cd.classMethods = cd.classInterface
+
+_.extend (Luca.define = ComponentDefinition.create),
+  __definitions: []
+  incomplete: ()->
+    _( Luca.define.__definitions ).select (definition)-> 
+      definition.isOpen()
+  close: ()->
+    for open in Luca.define.incomplete()
+      open.register() if open.isValid()
+    Luca.define.__definitions.length = 0
+  findDefinition: (componentName)->
+    _( Luca.define.__definitions ).detect (definition)->
+      definition.componentName is componentName
+
+Luca.register = (componentName)->
+  new ComponentDefinition(componentName, true)
+
+_.mixin def: Luca.define
+
+# The last method of the ComponentDefinition 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={})->
+  superClassName  = Luca.util.checkDeprecationStatusOf(superClassName)
+  superClass      = Luca.util.resolve( superClassName, (window || global) )
+
+  unless _.isFunction(superClass?.extend)
+    throw "Error defining #{ childName }. #{ superClassName } is not a valid component to extend from"
+
+  superMetaData = Luca.registry.getMetaDataFor(superClassName)
+  superMetaData.descendants().push(childName)
+
+  properties.displayName = childName
+
+  properties._superClass = ()->
+    superClass.displayName ||= superClassName
+    superClass
+
+  properties._super = (method, context=@, args=[])->
+    # TODO: debug this better
+    # protect against a stack too deep error in weird cases
+    @_superClass().prototype[method]?.apply(context, args)
+
+  definition = superClass.extend(properties)
+
+  if _.isArray( properties?.include )
+    for include in properties.include
+      include = Luca.util.resolve(include) if _.isString(include)
+      _.extend(definition::, include)
+
+  definition
+

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

@@ -0,0 +1,4 @@
+#= require ./concerns
+#= require ./component_definition
+#= require ./registry
+#= require ./meta_data

data/app/assets/javascripts/luca/core/registry/meta_data.coffee

@@ -0,0 +1,97 @@
+Luca.registry.componentMetaData = {}
+
+Luca.registry.getMetaDataFor = (componentName)->
+  new MetaDataProxy(Luca.registry.componentMetaData[ componentName ])
+
+Luca.registry.addMetaData = (componentName, key, value)->
+  data = Luca.registry.componentMetaData[ componentName ] ||= {}
+  data[ key ] = _(value).clone()
+  data
+
+class MetaDataProxy
+  constructor: (@meta={})->
+    _.defaults @meta, 
+      "super class name" : ""
+      "display name" : ""
+      "descendants": []
+      "aliases": []
+      "public interface" : []
+      "public configuration" : [] 
+      "private interface" : []
+      "private configuration" : [] 
+      "class configuration" : []
+      "class interface" : []
+
+  superClass: ()->
+    Luca.util.resolve(@meta["super class name"])
+
+  componentDefinition: ()->
+    Luca.registry.find @meta["display name"]
+
+  componentPrototype: ()->
+    @componentDefinition()?.prototype
+
+  prototypeFunctions: ()->
+    _.functions( @componentPrototype() )
+
+  classAttributes: ()->
+    _.uniq @classInterface().concat( @classConfiguration() )
+
+  publicAttributes: ()->
+    _.uniq @publicInterface().concat( @publicConfiguration() )
+
+  privateAttributes: ()->
+    _.uniq @privateInterface().concat( @privateConfiguration() )
+
+  classMethods: ()->
+    list = _.functions( @componentDefinition() )
+    _( list ).intersection( @classAttributes() )
+
+  publicMethods: ()->
+    _( @prototypeFunctions() ).intersection( @publicAttributes() )
+
+  privateMethods: ()->
+    _( @prototypeFunctions() ).intersection( @privateAttributes() )
+
+  classConfiguration: ()->
+    @meta["class configuration"]
+
+  publicConfiguration: ()->
+    @meta["public configuration"]
+
+  privateConfiguration: ()->
+    @meta["private configuration"]
+
+  classInterface: ()->
+    @meta["class interface"]
+
+  publicInterface: ()->
+    @meta["public interface"]
+
+  privateInterface: ()->
+    @meta["private interface"]
+
+  triggers: ()->
+    @meta["hooks"]
+
+  hooks: ()->
+    @meta["hooks"]
+
+  descendants: ()->
+    @meta["descendants"] 
+  styleHierarchy: ()->
+    list = _( @classHierarchy() ).map (cls)->
+      Luca.util.toCssClass(cls, 'views', 'components', 'core','fields','containers')
+
+    _( list ).without('backbone-view','luca-view')
+      
+  classHierarchy: ()->
+    list = [ @meta["display name"], @meta["super class name"]]
+
+    proxy = @superClass()?.prototype?.componentMetaData?()
+
+    until not proxy
+      list = list.concat( proxy?.classHierarchy() )
+      proxy = proxy.superClass()?.prototype?.componentMetaData?()
+
+    _( list ).uniq()

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

@@ -13,7 +13,10 @@ componentCacheStore =
 Luca.config.defaultComponentClass = Luca.defaultComponentClass  = 'Luca.View'
 Luca.config.defaultComponentType  = Luca.defaultComponentType   = 'view'
 
-Luca.registry.aliases = 
+Luca.registry.deprecatedComponents = {}
+Luca.registry.componentAliases = {}
+
+Luca.registry.typeAliases = 
   grid:         "grid_view"
   form:         "form_view"
   text:         "text_field"
@@ -76,13 +79,11 @@ Luca.registry.namespaces = (resolve=true)->
   _( registry.namespaces ).map (namespace)->
     if resolve then Luca.util.resolve( namespace ) else namespace
 
-
-
 # Lookup a component in the Luca component registry
-# by it's ctype identifier.  If it doesn't exist,
+# by it's type identifier.  If it doesn't exist,
 # check any other registered namespace
 Luca.registry.lookup = (ctype)->
-  if alias = Luca.registry.aliases[ ctype ] 
+  if alias = Luca.registry.typeAliases[ ctype ] 
     ctype = alias
     
   c = registry.classes[ctype]
@@ -119,7 +120,10 @@ Luca.registry.classes = (toString=false)->
       className: className
       ctype: ctype
 
-Luca.cache = Luca.cacheInstance = (cacheKey, object)->
+Luca.registry.find = (search)->
+  Luca.util.resolve(search) || Luca.define.findDefinition(search)
+
+Luca.cache = Luca.registry.cacheInstance = (cacheKey, object)->
   return unless cacheKey?
   return object if object?.doNotCache is true
 

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

@@ -0,0 +1,47 @@
+Luca.templates ||= {}
+
+if window.JST?
+  for templateId, templateFn of JST when templateId.match(/^luca\/templates\//)
+    Luca.templates[ templateId.replace('luca/templates/','') ] = templateFn
+    _( JST ).delete( templateId )
+
+# 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 }$")
+
+    luca = _( Luca.templates ).detect (fn,template_id)->
+      needle.exec( template_id )
+
+    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

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

@@ -32,6 +32,9 @@ view.triggers           "before:initialize",
 
 # Luca.View decorates Backbone.View with some patterns and conventions.
 view.defines
+  identifier: ()->
+    (@displayName || @type ) + ":" + (@name || @role || @cid)
+
   initialize: (@options={})->
     @trigger "before:initialize", @, @options
 
@@ -44,7 +47,7 @@ view.defines
 
     @$el.attr("data-luca-id", @name || @cid)
     
-    Luca.cacheInstance( @cid, @ )
+    Luca.registry.cacheInstance( @cid, @ )
 
     @setupHooks _( Luca.View::hooks.concat( @hooks ) ).uniq()
 
@@ -54,6 +57,8 @@ view.defines
         
     @trigger "after:initialize", @
 
+    _.bindAll(@, @bindMethods...) if @bindMethods?.legth > 0
+
   #### Hooks or Auto Event Binding
   #
   # views which inherit from Luca.View can define hooks
@@ -72,6 +77,10 @@ view.defines
   registerEvent: (selector, handler)->
     @events ||= {}
     @events[ selector ] = handler
+
+    if _.isObject(selector)
+      _.extend(@events, selector)
+      
     @delegateEvents()
 
   definitionClass: ()->
@@ -87,8 +96,9 @@ view.defines
     Luca.util.selectProperties( Luca.isBackboneView, @ )
 
   debug: (args...)->
-    return unless @debugMode or window.LucaDebugMode?
-    console.log [(@name || @cid), args...] 
+    if @debugMode is true or window.LucaDebugMode is true
+      args.unshift @identifier()
+      console.log args...
 
   trigger: ()->
     if Luca.enableGlobalObserver
@@ -101,12 +111,17 @@ view.defines
 
 Luca.View._originalExtend = Backbone.View.extend
 
-Luca.View.renderWrapper = (definition)->
-  _base = definition.render
-
-  _base ||= Luca.View::$attach
+# Note:
+#
+# I will be removing this prior to 1.0.  Optimizing for collection based
+# views does not belong in here, so the deferrable / collection binding stuff
+# needs to go.  
+#
+# Being able to defer rendering until the firing of an event on another object
+# is something that does ask for some syntactic sugar though, so need to rethink.
 
-  definition.render = ()->
+Luca.View.renderStrategies = 
+  legacy: ( _userSpecifiedMethod )->
     view = @
     # if a view has a deferrable property set
 
@@ -120,7 +135,7 @@ Luca.View.renderWrapper = (definition)->
       trigger = if @deferrable_event then @deferrable_event else Luca.View.deferrableEvent 
 
       deferred = ()->
-        _base.call(view)
+        _userSpecifiedMethod.call(view)
         view.trigger("after:render", view)
 
       view.defer(deferred).until(target, trigger)
@@ -139,11 +154,51 @@ Luca.View.renderWrapper = (definition)->
 
     else
       @trigger "before:render", @
-      _base.apply(@, arguments)
+      _userSpecifiedMethod.apply(@, arguments)
       @trigger "after:render", @
 
       return @
 
+  improved: (_userSpecifiedMethod)->
+    @trigger "before:render", @
+
+
+    deferred = ()=>
+      _userSpecifiedMethod.apply(@, arguments)
+      @trigger "after:render", @            
+
+    console.log "doing the improved one", @deferrable
+
+    if @deferrable? and not _.isString(@deferrable)
+      throw "Deferrable property is expected to be a event id"
+
+    if _.isString(@deferrable)
+      console.log "binding to #{ @deferrable } on #{ @cid }"
+      view.on @deferrable, ()->
+        console.log "did the improved one"
+        deferred.call(view)
+        view.unbind(listenForEvent, @)
+
+    else
+      deferred.call(@)
+
+
+
+Luca.View.renderWrapper = (definition)->
+  _userSpecifiedMethod = definition.render
+
+  _userSpecifiedMethod ||= ()-> @trigger "empty:render"
+
+  definition.render = ()->
+    strategy = Luca.View.renderStrategies[ @renderStrategy ||= "legacy" ]
+
+    unless _.isFunction(strategy)
+      throw "Invalid rendering strategy.  Please see Luca.View.renderStrategies"
+
+    strategy.call(@, _userSpecifiedMethod)
+
+    @
+
   definition
 
 bindAllEventHandlers = ()->
@@ -153,7 +208,10 @@ bindAllEventHandlers = ()->
 bindEventHandlers = (events={})->
   for eventSignature, handler of events
     if _.isString(handler)
-      _.bindAll @, handler
+      try
+        _.bindAll @, handler
+      catch e
+        console.log "Error binding to handler - #{handler} = #{e} #{@identifier()}"
 
 Luca.View.deferrableEvent = "reset"
 

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

@@ -0,0 +1,7 @@
+#= require jquery
+#= require underscore-min
+#= require underscore-string.min
+#= require backbone-min
+#= require backbone-query.min
+#= require bootstrap.min
+#= require_self

data/{src/tools → app/assets/javascripts/luca/development}/code_mirror_field.coffee

@@ -9,7 +9,7 @@ defaultOptions =
   tabSize: 2
   electricChars: false
 
-Luca.define("Luca.tools.CodeMirrorField").extends("Luca.components.Panel").with
+Luca.define("Luca.tools.CodeMirrorField").extends("Luca.Panel").with
   bodyClassName: "codemirror-wrapper"
   preProcessors: []
   postProcessors: []
@@ -44,6 +44,7 @@ Luca.define("Luca.tools.CodeMirrorField").extends("Luca.components.Panel").with
 
   afterRender: ()->
     @instance = CodeMirror( @$bodyEl()[0], @codemirrorOptions() )
+    console.log "After Render On Code Mirror Field"
     @setMaxHeight()
     @setHeight()