luca 0.9.8 → 0.9.9

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

@@ -12,7 +12,7 @@ if window.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)->
+Luca.template = (template_name, variables, partials)->
   window.JST ||= {}
 
   if _.isFunction(template_name)
@@ -34,6 +34,10 @@ Luca.template = (template_name, variables)->
 
   template = luca || jst
 
+  if template instanceof Hogan.template
+    if variables?
+      return template.render(variables, partials)
+
   return template(variables) if variables?
 
   template

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

@@ -1,16 +1,89 @@
+# `Luca.View` is an enhanced `Backbone.View` which provides common patterns for view components,
+# and various helper methods and configuration conventions.
+#
+# #### Instance caching / naming
+#
+# If you provide a `@name` property to your views, they will be accessible by that property
+# using the Application helper.    
+#
+#       view = new Luca.View(name:"my_view")
+#       Luca("my_view") === view
+#
+# #### CSS @className conventions
+#  
+# In order to make it easier to componentize your views, extending from `Luca.View` will
+# enable CSS class based inheritance based on the names of the view class.
+#
+# ##### For Example:
+#
+#       base = Luca.register  "App.views.BaseViewClass"
+#       base.extends          "Luca.View"
+#       base.defines
+#         className: "some-other-class"
+#
+#       child = Luca.register "App.views.ChildViewClass"
+#       child.extends         "App.views.BaseViewClass"
+#       child.defines
+#         myClasses: ()->
+#           @$el.attr('class') 
+#     
+#     view = new App.views.ChildViewClass()
+#     view.myClasses() #=> "app-base-view-class app-child-view-class some-other-class"
+#
+# This establishes a convention for css class names, and allows you to componetize your css
+# along with the component by joining them based on the name of your view class.  When using
+# Sass scoping / nesting it fits very nicely together.
+#
+# #### Internal state machine
+# 
+# Any `Luca.View` class which defines a `@stateful` property will automatically generate a
+# `@state` model that can be used to get/set attributes on the view as well as bind to change events on these attributes.  
+# 
+# This gives your views a dedicated place to store state, and you can bind to your data models separately
+# and update the DOM without confusing the two. 
+# 
+#       statefulView = Luca.register    "App.views.StatefulView"
+#       statefulView.extends            "Luca.View"
+#
+#       statefulView.defines
+#         # Passing an object allows you to set default values on the @state model.
+#         stateful:
+#           attribute: "value"
+#
+#         # Whenever the attribute specified changes, call the specified method.
+#         stateChangeEvents:
+#           "attribute" : "onAttributeChange"
+#         
+#         onAttributeChange: (stateMachine, attributeValue)->
+#           @doSomethingWhenAttributeChanges()
+#
+#  If this type of declarative style isn't your thing, you can still bind to events in code:
+#       
+#       view = new App.views.StatefulView()
+#       view.on "state:change:attribute", (stateMachine, attributeValue)=> @$el.html("New Attribute: #")
+#       view.set "attribute", "something"
+# 
+# #### Event binding helpers
+# 
+# In addition to the `@stateChangeEvent` bindings documented above, you have available
+# to you similar configuration helpers for binding to events emitted by the singletons:
+#
+# - `Luca.Application` via `@applicationEvents` 
+# - `Luca.CollectionManager` via `@collectionEvents`
+# - `Luca.SocketManager` via `@socketEvents`
 view = Luca.register    "Luca.View"
-
 view.extends            "Backbone.View"
 
 # includes are extensions to the prototype, and have no special behavior
 view.includes           "Luca.Events",
-                        "Luca.concerns.DomHelpers"
+                        "Luca.concerns.DomHelpers",
+                        "Luca.concerns.DevelopmentToolHelpers"
 
 # concerns are includes with special property / method conventions
 # which customize the components through the use of __initializer and
 # __included method names.  These will be called every time an instance
 # is created, and the first time the mixin is used to enhance a component.
-view.mixesIn            "DomHelpers", 
+view.mixesIn            "DomHelpers",
                         "Templating",
                         "EnhancedProperties",
                         "CollectionEventBindings",
@@ -18,10 +91,10 @@ view.mixesIn            "DomHelpers",
                         "StateModel"
 
 # Luca.View classes have the concept of special events called hooks
-# which allow you to tap into the lifecycle events of your view to 
+# which allow you to tap into the lifecycle events of your view to
 # customize their behavior.  This is especially useful in subclasses.
 #
-# You can utilize a @hook method by camelcasing the triggers defined below: 
+# You can utilize a @hook method by camelcasing the triggers defined below:
 view.triggers           "before:initialize",
                         "after:initialize",
                         "before:render",
@@ -30,84 +103,163 @@ view.triggers           "before:initialize",
                         "activation",
                         "deactivation"
 
+view.publicConfiguration
+  # Specifying a `@name` for your views is useful for views which
+  # there will only be one instance.  This allows you to reference
+  # the view instances by name using the application helper:
+  #       Luca("my_view_name")
+  name: undefined
+
+  # Setting this property to true will automatically bind the context
+  # of your event handler methods to the instance of this view.  This
+  # saves you from having to manually do:
+  #
+  #       Luca.View.extend
+  #         events:
+  #           "click .one" : "oneHandler"
+  #           "click .two" : "twoHandler"
+  #         initialize: ()->
+  #           _.bindAll(@, "oneHandler", "twoHandler")
+  #
+  #  Instead:
+  #
+  #       Luca.View.extend
+  #         autoBindEventHandlers: true
+  #         events: 
+  #           "click .one" : "oneHandler"
+  #
+  # Optionally, you can define an array of method names you want bound
+  # to this view:
+  #
+  #       Luca.View.extend
+  #         bindMethods:["oneHandler","twoHandler"]
+  #
+  autoBindEventHandlers: false
+
+  # 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.   
+  _inheritEvents: undefined
+
+
+
 # Luca.View decorates Backbone.View with some patterns and conventions.
-view.defines
+view.publicMethods
   identifier: ()->
     (@displayName || @type ) + ":" + (@name || @role || @cid)
 
+  # Calls Backbone.View::remove, and removes the view from the 
+  # instance cache.  Triggers a "before:remove" event.
+  remove: ()->
+    @trigger("before:remove", @)
+    Luca.remove(@)
+    Backbone.View::remove.apply(@, arguments)
+
   initialize: (@options={})->
     @trigger "before:initialize", @, @options
 
     _.extend @, @options
 
     if @autoBindEventHandlers is true or @bindAllEvents is true
-      bindAllEventHandlers.call(@) 
+      bindAllEventHandlers.call(@)
 
     @cid = _.uniqueId(@name) if @name?
 
     @$el.attr("data-luca-id", @name || @cid)
-    
+
     Luca.registry.cacheInstance( @cid, @ )
 
     @setupHooks _( Luca.View::hooks.concat( @hooks ) ).uniq()
 
     Luca.concern.setup.call(@)
 
-    @delegateEvents()
-        
+    @delegateEvents() unless _.isEmpty(@events)
+
     @trigger "after:initialize", @
 
     _.bindAll(@, @bindMethods...) if @bindMethods?.legth > 0
 
-  #### 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: Luca.util.setupHooks
+    unless _.isEmpty(@_inheritEvents)
+      for eventId, handler of @_inheritEvents
+        @registerEvent(eventId, handler)
+
+
+  debug: (args...)->
+    if @debugMode is true or window.LucaDebugMode is true
+      args.unshift @identifier()
+      console.log args...
+
+  trigger: ()->
+    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::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 ||= {}
-    @events[ selector ] = handler
 
     if _.isObject(selector)
-      _.extend(@events, selector)
-      
+      @events = _.extend(@events, selector)
+    else
+      if _.isFunction(handler) || (_.isString(handler) && @[handler]?)
+        @events[selector] = handler 
+
     @delegateEvents()
 
+view.privateMethods
+  # Returns a reference to the class which this view is an instance of.
   definitionClass: ()->
     Luca.util.resolve(@displayName, window)?.prototype
 
-  collections: ()-> 
+  # Returns a list of all of the collections which are properties on this view.
+  _collections: ()->
     Luca.util.selectProperties( Luca.isBackboneCollection, @ )
 
-  models: ()-> 
+  # Returns a list of all of the models which are properties on this view.
+  _models: ()->
     Luca.util.selectProperties( Luca.isBackboneModel, @ )
 
-  views: ()-> 
+  # Returns a list of all of the views which are properties on this view.
+  _views: ()->
     Luca.util.selectProperties( Luca.isBackboneView, @ )
 
-  debug: (args...)->
-    if @debugMode is true or window.LucaDebugMode is true
-      args.unshift @identifier()
-      console.log args...
-
-  trigger: ()->
-    if Luca.enableGlobalObserver
-      if Luca.developmentMode is true or @observeEvents is true
-        Luca.ViewObserver ||= new Luca.Observer(type:"view")
-        Luca.ViewObserver.relay @, arguments
+  # 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: Luca.util.setupHooks
 
-    Backbone.View.prototype.trigger.apply @, arguments
+# 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
 
@@ -115,12 +267,12 @@ Luca.View._originalExtend = Backbone.View.extend
 #
 # 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.  
+# 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.
 
-Luca.View.renderStrategies = 
+Luca.View.renderStrategies =
   legacy: ( _userSpecifiedMethod )->
     view = @
     # if a view has a deferrable property set
@@ -132,10 +284,11 @@ Luca.View.renderStrategies =
         @deferrable = @collection
 
       target ||= @deferrable
-      trigger = if @deferrable_event then @deferrable_event else Luca.View.deferrableEvent 
+      trigger = if @deferrable_event then @deferrable_event else Luca.View.deferrableEvent
 
       deferred = ()->
         _userSpecifiedMethod.call(view)
+        @rendered = true
         view.trigger("after:render", view)
 
       view.defer(deferred).until(target, trigger)
@@ -155,6 +308,7 @@ Luca.View.renderStrategies =
     else
       @trigger "before:render", @
       _userSpecifiedMethod.apply(@, arguments)
+      @rendered = true
       @trigger "after:render", @
 
       return @
@@ -162,10 +316,9 @@ Luca.View.renderStrategies =
   improved: (_userSpecifiedMethod)->
     @trigger "before:render", @
 
-
     deferred = ()=>
       _userSpecifiedMethod.apply(@, arguments)
-      @trigger "after:render", @            
+      @trigger "after:render", @
 
     console.log "doing the improved one", @deferrable
 
@@ -203,7 +356,7 @@ Luca.View.renderWrapper = (definition)->
 
 bindAllEventHandlers = ()->
   for config in [@events, @componentEvents, @collectionEvents, @applicationEvents] when not _.isEmpty(config)
-    bindEventHandlers.call(@, config)    
+    bindEventHandlers.call(@, config)
 
 bindEventHandlers = (events={})->
   for eventSignature, handler of events

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

@@ -1,7 +1,9 @@
 #= require jquery
 #= require underscore-min
 #= require underscore-string.min
+#= require hogan.js
 #= require backbone-min
 #= require backbone-query.min
 #= require bootstrap.min
+#= require keymaster.min
 #= require_self

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

@@ -0,0 +1,173 @@
+# 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 || "//localhost:9292/faye"
+  namespace:  "luca"
+  channel:    Luca.config.codeSyncChannel || "/luca-code-sync"
+
+codeManager.classMethods
+  setup: (options={})->
+    @codeSyncManager = new Luca.CodeSyncManager(options) 
+    @codeSyncManager.trigger "ready"
+
+codeManager.privateMethods
+  initialize: (@attributes={})->
+    unless @attributes.host?
+      _.extend(@attributes, host: (@host || Luca.config.codeSyncHost))
+
+    Luca.SocketManager::initialize.call(@, @attributes)
+    @bindToChannel()
+
+  start: ()->
+    @trigger "ready"
+
+  bindToChannel: ()->
+    if @client?
+      @client.subscribe @channel, ()=>
+        @onChangesNotification.apply(@, arguments)
+    else
+      @on "change:client", (socketManager, client)=>
+        @client.subscribe @channel, ()=>
+          @onChangesNotification.apply(@, arguments)    
+
+  # changeData is a payload that gets sent over the socket
+  # whenever an asset that is being watched changes. 
+  # it is different if the type of file is css or javascript.
+  onChangesNotification: (changeData={}, applicationName)->
+    return if _.isEmpty(changeData)
+    data = _( changeData ).values()[0] || {}
+
+    if data.type is "template"
+      @processTemplate(data)
+      @rerunSyncPad(data.type)
+
+    if data.type is "component_definition"
+      @processComponentDefinitionChange(data)
+      @processJavascriptChange(data)
+      
+      _.delay ()=>
+        @rerunSyncPad(data.type)
+      , 25
+
+    if data.type is "javascript"
+      @processJavascriptChange(data)
+
+    if data.type is "stylesheet" and data?.path
+      @processStylesheetChange(data)
+
+  rerunSyncPad: ()->
+    if last = @get("last_syncpad_javascript_payload")
+      @processJavascriptChange(last)
+
+  processTemplate: (change={})->
+    fn = ()->
+      eval( change.contents )
+
+    fn.apply(window)
+
+  processComponentDefinitionChange: (change={})->
+    return if _.isEmpty(change)
+    @components ||= Luca.collections.Components.generate() 
+
+    if change.class_name? 
+      component = @components.findByClassName( change.class_name )
+
+      if component && change.source_file_contents?
+        component.set(source_file_contents: change.source_file_contents )
+
+  processJavascriptChange: (change={})->
+    return unless change?.compiled
+    existing = $("body script[data-path='#{ change.source }']")
+
+    # just to be clean
+    if existing.length > 1
+      existing.remove()
+
+    if change.source?.match(/syncpad/) and change?.compiled and true
+      @set("last_syncpad_javascript_payload", change)
+
+    script = @make("script", {"data-path": change.source, type:"text/javascript"}, change.compiled)
+    $('body').append(script)
+
+  processStylesheetChange: (change={})->
+    return if _.isEmpty(change)
+
+    if change.path?.match(/syncpad/) or Luca.config.codeSyncStylesheetMode is "single"
+      @syncStylesheet(change)
+    else
+      @replaceStylesheetAndEverythingAfter(change.path)
+
+  replaceStylesheetAndEverythingAfter: (path)->
+    stylesheet  = path.replace('./app/assets/stylesheets', Luca.config.assetsUrlPrefix )
+    stylesheet  = stylesheet.replace('.scss','')
+    existing    = $("link[href*='#{ stylesheet }']")
+    parent      = existing.parent()
+
+    return unless existing.length > 0
+
+    replaced = existing.clone()
+    comesAfter = existing.nextAll('link')
+    cloned = comesAfter.clone()
+
+    $(existing, comesAfter).remove()
+
+    parent.append( replaced )
+    parent.append( cloned )
+
+  syncStylesheet: (change)->
+    existing = $("head style[data-file='#{ change.path }']")
+
+    if existing.length > 0
+      existing.remove()
+
+    if change.compiled? or change.contents?
+      link = @make("style",{"data-file":change.path, type:"text/css"}, change.compiled || change.contents)
+      $('head').append( link )
+
+codeManager.defines
+  make: Luca.View::make