luca 0.6.6

data/src/core/container.coffee

@@ -0,0 +1,256 @@
+#### The Component Container
+#
+# The Component Container is a nestable component
+# which is responsible for laying out the many components
+# it contains, assigning them to a DOM container, and
+# automatically instantiating and rendering the components
+# in their proper place.  
+Luca.core.Container = Luca.View.extend 
+  className: 'luca-ui-container'
+
+  componentClass: 'luca-ui-panel'
+  
+  isContainer: true
+
+  hooks:[
+    "before:components",
+    "before:layout",
+    "after:components",
+    "after:layout",
+    "first:activation"
+  ]
+
+  rendered: false
+
+  components: []
+
+  initialize: (@options={})->
+    _.extend @, @options
+
+    @setupHooks( Luca.core.Container::hooks )
+
+    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()
+  #   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() 
+  #
+  beforeRender: ()->
+    @debug "container before render"
+    @doLayout() 
+    @doComponents()
+
+  doLayout: ()->
+    @debug "container do layout"
+    @trigger "before:layout", @
+    @prepareLayout()    
+    @trigger "after:layout", @
+
+  doComponents: ()->
+    @debug "container do components"
+
+    @trigger "before:components", @, @components
+    @prepareComponents()
+    @createComponents()
+    @renderComponents()
+    @trigger "after:components", @, @components
+
+  applyPanelConfig: (panel, panelIndex)->
+    style_declarations = []
+    
+    style_declarations.push "height: #{ (if _.isNumber(panel.height) then panel.height + 'px' else panel.height ) }" if panel.height
+    style_declarations.push "width: #{ (if _.isNumber(panel.width) then panel.width + 'px' else panel.width ) }" if panel.width
+    style_declarations.push "float: #{ panel.float }" if panel.float
+    
+    config = 
+      classes: panel?.classes || @componentClass
+      id: "#{ @cid }-#{ panelIndex }"
+      style: style_declarations.join(';')
+
+  # prepare layout is where you would perform the DOM element
+  # creation / manipulation for how your container lays out
+  # its components.  Minimally you will want to set the
+  # container property on each component.
+  prepareLayout: ()->
+    @debug "container prepare layout"
+    @componentContainers = _( @components ).map (component, index) =>
+      @applyPanelConfig.apply @, [ component, index ]
+    
+    if @appendContainers
+      _( @componentContainers ).each (container)=>
+        @$el.append Luca.templates["containers/basic"](container) 
+
+  # prepare components is where you would set necessary object
+  # attributes on the components themselves.
+  prepareComponents: ()-> 
+    @debug "container prepare components"
+    @components = _( @components ).map (object, index) =>
+      panel = @componentContainers[ index ]
+      object.container = if @appendContainers then "##{ panel.id }" else @el
+
+      object
+
+  createComponents: ()->
+    @debug "container create components"
+    map = @componentIndex = 
+      name_index: {}
+      cid_index: {}
+
+    @components = _( @components ).map (object, index)=>
+      # you can include normal backbone views as components
+      # you will want to make sure your render method handles
+      # adding the views @$el to the appropriate @container
+      component = if _.isObject( object ) and object.render and object.trigger
+        object
+      else
+        object.ctype ||= Luca.defaultComponentType || "template"
+        Luca.util.lazyComponent( object )
+
+      # if we're using base backbone views, then they don't extend themselves
+      # with their passed options, so this is a workaround
+      if !component.container and component.options.container
+        component.container = component.options.container
+      
+      if map and component.cid?
+        map.cid_index[ component.cid ] = index
+      
+      if map and component.name?
+        map.name_index[ component.name ] = index
+
+      component
+    
+    @debug "components created", @components
+  # Trigger the Rendering Pipeline process on all of the nested
+  # components
+  renderComponents: (@debugMode="")->
+    @debug "container render components"
+    _(@components).each (component)=> 
+      component.getParent = ()=> @ 
+      $( component.container ).append $(component.el)
+
+      try
+        component.render()
+      catch e
+        console.log "Error Rendering Component #{ component.name || component.cid }", component
+        console.log e.message
+        console.log e.stack
+
+  #### 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
+  # of the nested components.  Components which hide / display
+  # other components, such as a CardView or TabContainer
+  # will trigger first:activation on the components as they become
+  # displayed.
+  firstActivation: ()->  
+    _( @components ).each (component)=>
+      activator = @
+      
+      # apply the first:activation trigger on the component, in the context of the component
+      # passing as arguments the component itself, and the component doing the activation
+      unless component?.previously_activated is true 
+        component?.trigger?.apply component, ["first:activation", [component, activator] ]
+        component.previously_activated = true
+
+  #### Component Finder Methods
+  select: (attribute, value, deep=false)->
+    components = _( @components ).map (component)->
+      matches = []
+      test = component[ attribute ]
+
+      matches.push( component ) if test is value
+
+      if deep is true and component.isContainer is true
+        matches.push component.select(attribute, value, true)
+
+      _.compact matches
+
+    _.flatten( components )
+
+  findComponentByName: (name, deep=false)-> 
+    @findComponent(name, "name_index", deep)
+
+  findComponentById: (id, deep=false)-> 
+    @findComponent(id, "cid_index", deep)
+
+  findComponent: (needle, haystack="name", deep=false)->
+    position = @componentIndex?[ haystack ][ needle ]
+    component = @components?[ position ]
+
+    return component if component
+    
+    if deep is true
+      sub_container = _( @components ).detect (component)-> component?.findComponent?(needle, haystack, true)
+      sub_container?.findComponent?(needle, haystack, true)
+  
+  # run a function for each component in this container
+  # and any nested containers in those components, recursively
+  # pass false as the second argument to skip the deep recursion
+  eachComponent: (fn, deep=true)->
+    _( @components ).each (component)=>
+      fn.apply component, [component]
+      component?.eachComponent?.apply component, [fn,deep] if deep
+  
+  indexOf: (name)->
+    names = _( @components ).pluck('name')
+    _( names ).indexOf(name)
+  
+  activeComponent: ()->
+    return @ unless @activeItem
+    return @components[ @activeItem ]
+
+  componentElements: ()-> $(".#{ @componentClass }", @el)
+ 
+  getComponent: (needle)-> 
+    @components[ needle ]
+  
+  rootComponent: ()-> 
+    !@getParent?
+
+  getRootComponent: ()-> 
+    if @rootComponent() then @ else @getParent().getRootComponent()
+
+Luca.register "container", "Luca.core.Container"

data/src/core/field.coffee

@@ -0,0 +1,68 @@
+Luca.core.Field = Luca.View.extend
+  className: 'luca-ui-text-field luca-ui-field'
+  
+  isField: true
+
+  template: 'fields/text_field'
+   
+  labelAlign: 'top'
+
+  hooks:[
+    "before:validation",
+    "after:validation",
+    "on:change"
+  ]
+
+  # see: http://twitter.github.com/bootstrap/base-css.html
+  statuses: [
+    "warning"
+    "error"
+    "success"
+  ]
+
+  initialize: (@options={})->
+    _.extend @, @options
+    Luca.View::initialize.apply(@, arguments)
+
+    @input_id ||= _.uniqueId('field') 
+    @input_name ||= @name 
+    @helperText ||= ""
+    @label ||= "*#{ @label }" if @required and not @label?.match(/^\*/)
+    @inputStyles ||= ""
+
+    @disable() if @disabled
+
+    @updateState( @state )
+    @placeHolder ||= ""
+
+  beforeRender: ()->
+    if Luca.enableBootstrap
+      @$el.addClass('control-group')
+
+    @$el.addClass('required') if @required
+
+    @$el.html Luca.templates[ @template ]( @ )
+    @input = $('input', @el)
+  
+  change_handler: (e)->
+    @trigger "on:change", @, e 
+
+  disable: ()->
+    $("input",@el).attr('disabled', true)
+  
+  enable: ()->
+    $("input", @el).attr('disabled', false)  
+
+  getValue: ()-> 
+    @input.attr('value')
+
+  render: ()->
+    $( @container ).append( @$el )
+
+  setValue: (value)-> 
+    @input.attr('value', value)
+  
+  updateState: (state)->
+    _( @statuses ).each (cls)=> 
+      @$el.removeClass(cls)
+      @$el.addClass(state)

data/src/core/observer.coffee

@@ -0,0 +1,17 @@
+class Luca.Observer
+  constructor: (@options={})->
+    _.extend @, Backbone.Events
+    @type = @options.type
+
+    if @options.debugAll
+      @bind "event", (t, args...)=>
+        console.log "Observed #{ @type } #{ (t.name || t.id || t.cid) }", t, _(args).flatten()
+
+  relay: (triggerer, args...)->
+    @trigger "event", triggerer, args
+    @trigger "event:#{ args[0] }", triggerer, args.slice(1)
+
+Luca.Observer.enableObservers = (options={})->
+  Luca.enableGlobalObserver = true
+  Luca.ViewObserver = new Luca.Observer _.extend(options, type:"view")
+  Luca.CollectionObserver = new Luca.Observer _.extend(options, type:"collection")

data/src/core/view.coffee

@@ -0,0 +1,190 @@
+#### 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
+# such as auto event binding, the facilitation of deferred rendering
+# against a Backbone.Model or Backbone.Collection reset event, Caching
+# views into a global Component Registry, and more.
+
+Luca.View.originalExtend = Backbone.View.extend
+
+# 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 )
+    @
+
+
+  definition.render = ()->
+    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()
+
+    else
+      @trigger "before:render", @
+      _base.apply(@, arguments)
+      @trigger "after:render", @
+
+  Luca.View.originalExtend.apply @, [definition]
+
+_.extend Luca.View.prototype,
+  debug: ()->
+    return unless @debugMode or window.LucaDebugMode?
+    console.log [(@name || @cid),message] for message in arguments
+
+  trigger: ()->
+    if Luca.enableGlobalObserver
+      Luca.ViewObserver ||= new Luca.Observer(type:"view")
+      Luca.ViewObserver.relay @, arguments
+
+    Backbone.View.prototype.trigger.apply @, arguments
+
+  hooks:[
+    "after:initialize"
+    "before:render"
+    "after:render"
+    "first:activation"
+    "activation"
+    "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?
+
+    #### View Caching
+    #
+    # Luca.View(s) which get created get stored in a global cache by their
+    # component id.  This allows us to re-use views when it makes sense
+    Luca.cache( @cid, @ )
+
+    unique = _( Luca.View.prototype.hooks.concat( @hooks ) ).uniq()
+
+    @setupHooks( unique )
+
+    if @autoBindEventHandlers is true
+      _( @events ).each (handler,event)=>
+        if _.isString(handler)
+          _.bindAll @, handler
+
+
+    @trigger "after:initialize", @
+
+    @registerCollectionEvents()
+
+  $container: ()-> $(@container)
+  #### Hooks or Auto Event Binding
+  #
+  # views which inherit from Luca.View can define hooks
+  # or events which can be emitted from them.  Automatically,
+  # any functions on the view which are named according to the
+  # convention will automatically get run.
+  #
+  # by default, all Luca.View classes come with the following:
+  #
+  # before:render     : beforeRender()
+  # after:render      : afterRender()
+  # after:initialize  : afterInitialize()
+  # first:activation  : firstActivation()
+  setupHooks: (set)->
+    set ||= @hooks
+
+    _(set).each (event)=>
+      parts = event.split(':')
+      prefix = parts.shift()
+
+      parts = _( parts ).map (p)-> _.capitalize(p)
+      fn = prefix + parts.join('')
+
+      @bind event, ()=> @[fn].apply @, arguments if @[fn]
+
+
+  #### Luca.Collection and Luca.CollectionManager integration
+
+  # under the hood, this will find your collection manager using
+  # Luca.CollectionManager.get, which is a function that returns
+  # the first instance of the CollectionManager class ever created.
+  #
+  # if you want to use more than one collection manager, over ride this
+  # function in your views with your own logic
+  getCollectionManager: ()->
+    @collectionManager || Luca.CollectionManager.get?.call()
+
+  ##### Collection Events
+  #
+  # By defining a hash of collectionEvents in the form of
+  #
+  # "books add" : "onBookAdd"
+  #
+  # the Luca.View will bind to the collection found in the
+  # collectionManager with that key, and bind to that event.
+  # a property of @booksCollection will be created on the view,
+  # and the "add" event will trigger "onBookAdd"
+  #
+  # you may also specify a function directly.  this
+  #
+  registerCollectionEvents: ()->
+    manager = @getCollectionManager()
+
+    _( @collectionEvents ).each (handler, signature)=>
+      [key,event] = signature.split(" ")
+
+      collection = @["#{ key }Collection"] = manager.getOrCreate( key )
+
+      if !collection
+        throw "Could not find collection specified by #{ key }"
+
+      if _.isString(handler)
+        handler = @[handler]
+
+      unless _.isFunction(handler)
+        throw "invalid collectionEvents configuration"
+
+      try
+        collection.bind(event, handler)
+      catch e
+        console.log "Error Binding To Collection in registerCollectionEvents", @
+        throw e

data/src/framework.coffee

@@ -0,0 +1,110 @@
+_.mixin( _.string )
+
+window.Luca =
+  VERSION: "0.6.6"
+  core: {}
+  containers: {}
+  components: {}
+  modules: {}
+  fields: {}
+  util: {}
+  registry:
+    classes: {}
+    namespaces:["Luca.containers","Luca.components"]
+  component_cache:
+    cid_index: {}
+    name_index: {}
+
+
+# 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
+
+# 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
+Luca.util.nestedValue = (accessor, source_object)->
+  _( accessor.split(/\./) ).inject (obj,key)->
+    obj = obj?[key]
+  , source_object
+
+# 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 = _.camelize _.capitalize( ctype )
+
+  parents = _( Luca.registry.namespaces ).map (namespace)-> Luca.util.nestedValue(namespace, (window || global))
+
+  _.first _.compact _( parents ).map (parent)-> parent[className]
+
+# creates a new object from a hash with a ctype property
+# matching something in the Luca registry
+Luca.util.lazyComponent = (config)->
+  ctype = config.ctype
+
+  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?
+    throw "Can not 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
+
+$ do ->
+  $('body').addClass('luca-ui-enabled')