luca 0.9.89 → 0.9.91

data/CHANGELOG

@@ -275,5 +275,15 @@
 
 0.9.88
   - Fixed a bug in StateModel concern
-  - Luca.View which define an @_events property on their prototypes will have 
+  - Luca.View which define an @_inheritEvents property on their prototypes will have 
     that event configuration persist into @events of views which extend from them
+
+0.9.9
+  - Added luca executable which includes:
+    - documentation generator
+    - sync command for running Luca.CodeSyncManager in development
+  - Removes some unused components
+  - API changes for Luca.components.Controller
+  - Removing rails dependencies
+  - Middleman site for documentation and examples 
+  - Improving documentation for core components

data/Gemfile

@@ -4,14 +4,17 @@ gem "sinatra", :require => "sinatra/base"
 gem 'coffee-script', '>= 2.2.0'
 gem "uglifier", '>= 1.0.3'
 gem "sass", '>= 3.1.10'
-gem "sprockets", '>= 2.0.2'
+gem "sprockets", ">= 2.4.5"
 gem 'ejs'
 gem 'haml'
 gem 'redcarpet'
 gem 'rake'
 gem 'hogan_assets'
 gem 'haml_assets'
-gem 'active_support'
+gem 'activesupport', '>= 3.2.12'
+gem 'listen'
+gem 'faye'
+gem 'thin'
 
 group :test, :development do
   gem 'faker'

data/Gemfile.lock

@@ -1,122 +1,150 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    active_support (3.0.0)
-      activesupport (= 3.0.0)
-    activesupport (3.0.0)
+    activesupport (3.2.12)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
     addressable (2.3.2)
-    childprocess (0.3.1)
-      ffi (~> 1.0.6)
-    coderay (0.9.8)
+    childprocess (0.3.8)
+      ffi (~> 1.0, >= 1.0.11)
+    coderay (1.0.9)
     coffee-script (2.2.0)
       coffee-script-source
       execjs
-    coffee-script-source (1.2.0)
+    coffee-script-source (1.4.0)
+    cookiejar (0.3.0)
+    daemons (1.1.9)
     diff-lcs (1.1.3)
-    ejs (1.0.0)
-    execjs (1.2.13)
+    ejs (1.1.1)
+    em-http-request (1.0.3)
+      addressable (>= 2.2.3)
+      cookiejar
+      em-socksify
+      eventmachine (>= 1.0.0.beta.4)
+      http_parser.rb (>= 0.5.3)
+    em-socksify (0.2.1)
+      eventmachine (>= 1.0.0.beta.4)
+    eventmachine (1.0.0)
+    execjs (1.4.0)
       multi_json (~> 1.0)
-    faker (1.0.1)
-      i18n (~> 0.4)
-    ffi (1.0.11)
-    guard (0.9.2)
-      ffi (>= 0.5.0)
-      thor (~> 0.14.6)
-    guard-jasmine (0.9.13)
+    faker (1.1.2)
+      i18n (~> 0.5)
+    faye (0.8.8)
+      cookiejar (>= 0.3.0)
+      em-http-request (>= 0.3.0)
+      eventmachine (>= 0.12.0)
+      faye-websocket (>= 0.4.0)
+      rack (>= 1.0.0)
+      yajl-ruby (>= 1.0.0)
+    faye-websocket (0.4.7)
+      eventmachine (>= 0.12.0)
+    ffi (1.4.0)
+    guard (1.6.2)
+      listen (>= 0.6.0)
+      lumberjack (>= 1.0.2)
+      pry (>= 0.9.10)
+      terminal-table (>= 1.4.3)
+      thor (>= 0.14.6)
+    guard-jasmine (1.13.0)
       childprocess
-      guard (>= 0.8.3)
+      guard (>= 1.1.0)
       multi_json
       thor
     guard-sprockets2 (0.0.6)
       guard
       sprockets (~> 2.0)
-    haml (3.1.4)
+    haml (4.0.0)
+      tilt
     haml_assets (0.2.1)
       haml
       tilt
     hike (1.2.1)
-    hogan_assets (1.3.4)
+    hogan_assets (1.5.0)
       execjs (>= 1.2.9)
       sprockets (>= 2.0.3)
       tilt (>= 1.3.3)
-    i18n (0.6.0)
-    jasmine (1.3.0)
-      jasmine-core (>= 1.3.0)
+    http_parser.rb (0.5.3)
+    i18n (0.6.1)
+    jasmine (1.3.1)
+      jasmine-core (~> 1.3.1)
       rack (~> 1.0)
       rspec (>= 1.3.1)
       selenium-webdriver (>= 0.1.3)
-    jasmine-core (1.3.0)
-    libwebsocket (0.1.7.1)
-      addressable
-      websocket
-    method_source (0.6.7)
-      ruby_parser (>= 2.3.1)
-    multi_json (1.0.4)
-    pry (0.9.7.4)
-      coderay (~> 0.9.8)
-      method_source (~> 0.6.7)
-      ruby_parser (>= 2.3.1)
-      slop (~> 2.1.0)
+    jasmine-core (1.3.1)
+    listen (0.7.2)
+    lumberjack (1.0.2)
+    method_source (0.8.1)
+    multi_json (1.6.1)
+    pry (0.9.12)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
     rack (1.5.2)
-    rack-protection (1.1.4)
+    rack-protection (1.3.2)
       rack
-    rake (0.9.2.2)
-    rb-fsevent (0.9.1)
+    rake (10.0.3)
+    rb-fsevent (0.9.3)
     redcarpet (2.2.2)
     rspec (2.12.0)
       rspec-core (~> 2.12.0)
       rspec-expectations (~> 2.12.0)
       rspec-mocks (~> 2.12.0)
-    rspec-core (2.12.0)
-    rspec-expectations (2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
       diff-lcs (~> 1.1.3)
-    rspec-mocks (2.12.0)
-    ruby_parser (2.3.1)
-      sexp_processor (~> 3.0)
+    rspec-mocks (2.12.2)
     rubyzip (0.9.9)
-    sass (3.1.12)
-    selenium-webdriver (2.26.0)
+    sass (3.2.5)
+    selenium-webdriver (2.30.0)
       childprocess (>= 0.2.5)
-      libwebsocket (~> 0.1.3)
       multi_json (~> 1.0)
       rubyzip
-    sexp_processor (3.0.9)
-    sinatra (1.3.1)
-      rack (~> 1.3, >= 1.3.4)
-      rack-protection (~> 1.1, >= 1.1.2)
+      websocket (~> 1.0.4)
+    sinatra (1.3.4)
+      rack (~> 1.4)
+      rack-protection (~> 1.3)
       tilt (~> 1.3, >= 1.3.3)
-    slop (2.1.0)
+    slop (3.4.3)
     sprockets (2.8.2)
       hike (~> 1.2)
       multi_json (~> 1.0)
       rack (~> 1.0)
       tilt (~> 1.1, != 1.3.0)
-    thor (0.14.6)
+    terminal-table (1.4.5)
+    thin (1.5.0)
+      daemons (>= 1.0.9)
+      eventmachine (>= 0.12.6)
+      rack (>= 1.0.0)
+    thor (0.17.0)
     tilt (1.3.3)
-    uglifier (1.2.0)
+    uglifier (1.3.0)
       execjs (>= 0.3.0)
-      multi_json (>= 1.0.2)
-    websocket (1.0.4)
+      multi_json (~> 1.0, >= 1.0.2)
+    websocket (1.0.7)
+    yajl-ruby (1.1.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  active_support
+  activesupport (>= 3.2.12)
   coffee-script (>= 2.2.0)
   ejs
   faker
+  faye
   guard-jasmine
   guard-sprockets2
   haml
   haml_assets
   hogan_assets
   jasmine
+  listen
   pry
   rake
   rb-fsevent (>= 0.9.1)
   redcarpet
   sass (>= 3.1.10)
   sinatra
-  sprockets (>= 2.0.2)
+  sprockets (>= 2.4.5)
+  thin
   uglifier (>= 1.0.3)

data/Rakefile

@@ -2,6 +2,7 @@
 task :environment do
   require './app'
   require 'pry'
+  require 'luca'
 end
 
 
@@ -9,8 +10,15 @@ stylesheets = ["luca-ui-bootstrap.css","luca-ui-development-tools.css","sandbox.
 scripts = ["dependencies.js","sandbox.js"]
 
 namespace :release do
+  desc "Zip up the assets"
+  task :zip => :environment do
+    `cp vendor/assets/javascripts/luca.min.js vendor/assets/javascripts/luca-dependencies.min.js vendor/assets/stylesheets/luca-ui.css .`  
+    `zip downloads/luca-#{ Luca::Version }.zip luca.min.js luca-dependencies.min.js luca-ui.css`
+    `rm luca-ui.css luca.min.js luca-dependencies.min.js`
+  end
+
   desc "Compile and Minify"
-  task :all => [:assets,:minify]
+  task :all => [:assets,:minify,:zip]
   desc "Compile all the assets"
   task :assets => :environment do
     File.open( File.join(App.root,'vendor','assets','stylesheets','luca-development.css'), 'w+' ) do |fh|
@@ -40,7 +48,7 @@ namespace :release do
   end
 
   desc "Build the gem"
-  task :gem => [:assets,:minify] do
+  task :gem => [:assets,:minify,:zip] do
     `gem build luca.gemspec`
   end
 

data/app/assets/javascripts/luca/components/application.coffee

@@ -86,6 +86,18 @@ application.publicConfiguration
   # listen for on this component before you start history
   autoStartHistory: "before:render"
 
+  # use Backbone.history push state?
+  pushState: false
+
+  # If the server renders the entire page
+  # first, then we should start history silently.
+  startHistorySilently: false
+
+  # In cases where we use pushState, we need to tell
+  # the application what the actual root url of our app
+  # is, since everything after would otherwise be a hashbang 
+  rootUrl: undefined
+  
   # we will create a collection manager singleton
   # by default unless otherwise specified.
   useCollectionManager: true
@@ -110,63 +122,42 @@ application.publicConfiguration
   # with several 'pages' so to speak
   useController: true
 
-  # if you have special rendering requirements for
-  # the application's components, you can assign the
-  # specific element you want to render the container
-  # to inside of the #viewport
+  # If your Application does not behave as a Viewport that monopolizes
+  # its entire element, but instead you wish to render the application
+  # controller to a specific element,  you can specify the css selector of that element.
   mainControllerContainer: undefined
 
-  # Key Handler
-  #
-  # One responsibility of the application, since it is a viewport which monopolizes the entire screen
-  # is to relay keypress events from the document, to whatever views are interested in responding to them.
-  #
-  # This functionality is disabled by default.
-  useKeyHandler: false
-
-  # You can configure key events by specifying them by their name, as it exists in Luca.keyMap. For example:
-
   # keyEvents understands the following modifiers:
-  # `⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, and `⌘`.
-
+  # - `⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, and `⌘`.
   # The following special keys can be used for shortcuts:
   # `backspace`, `tab`, `clear`, `enter`, `return`, `esc`, `escape`, `space`,
   # `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `del`, `delete`
   # and `f1` through `f19`.
   #
+  # **Note**: This requires the keymaster.js library to be loaded.  This library is included
+  # with the bundled dependencies that ship with Luca.
+  #
   # Example:
-  # ```coffeescript
-  #   application.configuration
-  #     keyEvents:
-  #       '⌘+r, ctrl+r': "keyHandlerFunction"
-  #     keyHandlerFunction: -> alert 'something + r was pressed'
-  # ```
+  #       application.configuration
+  #         keyEvents:
+  #           '⌘+r, ctrl+r': "keyHandlerFunction"
+  #         keyHandlerFunction: -> alert 'something + r was pressed'
   keyEvents: {}
 
-  # applications have one component, the controller.
-  # any components defined on the application class directly
-  # will get wrapped by the main controller unless you
-  # set useController = false
-  components:[
-    type: 'template'
-    name: 'welcome'
-    template: 'sample/welcome'
-    templateContainer: "Luca.templates"
-  ]
-
-  # create getter methods for the various
-  # roles in the application's components on the
-  # application itself.  false by default.
+  # create getter methods for the various roles in the application's components on the application itself.
   createRoleBasedGetters: false
 
-  # create an instance of Luca.SocketManager
-  # which is a Backbone.Events style abstraction that
+  # create an instance of Luca.SocketManager which is a Backbone.Events style abstraction that
   # sits on top of services like faye, or socket.io 
   useSocketManager: false
   socketManagerOptions: {}
 
-  # Don't create getters on this component
-  # for the nested components
+application.publicMethods
+  # Creating your Application and all of its components and pages is 
+  # generally as simple as creating an instance of your Application class:
+  #       Luca.onReady ()->
+  #         window.MyApp = new Luca.Application() 
+  #         window.MyApp.boot()
   initialize: (@options={})->
     app             = @
     appName         = @name
@@ -254,7 +245,8 @@ application.publicConfiguration
     @get("active_sub_section")
 
   activePages: ()->
-    @$('.luca-ui-controller').map (index,element)=> $(element).data('active-section')
+    console.log "This method will be getting removed in Luca 1.0"
+    @$('.luca-controller').map (index,element)=> $(element).data('active-section')
 
   # boot should trigger the ready event, which will call the initial call
   # to render() your application, which will have a cascading effect on every
@@ -274,47 +266,31 @@ application.publicConfiguration
   collection: ()->
     @collectionManager.getOrCreate.apply(@collectionManager, arguments)
 
+  # Get an attribute from our internal state machine
   get: (attribute)->
     @state.get(attribute)
 
+  # Set an attribute on our internal state machine
   set: (attribute, value, options)->
     @state.set.apply(@state, arguments)
 
+  # Access a named view by its @name property. 
   view: (name)->
     Luca.cache(name)
 
-  #### Navigation Hooks
-  #
   # delegate to the main controller so that we can switch the active section
+  # easily directly from the application.  If passed a callback, this function
+  # will get called in the context of the activated component.  This method is useful
+  # inside of custom route handlers if you are manually defining them on a `Backbone.Router`
+  # instead of using the built in `@routes` helper.
   navigate_to: (component_name, callback)->
     @getMainController().navigate_to(component_name, callback)
 
-application.privateInterface
-  keyHandler: (e)->
-    return unless e and @keyEvents
-
-    isInputEvent = $(e.target).is('input') || $(e.target).is('textarea')
-
-    return if isInputEvent
-
-    keyname = Luca.keyMap[ e.keyCode ]
-
-    return unless keyname
-
-    meta = e?.metaKey is true
-    control = e?.ctrlKey is true
-
-    source = @keyEvents
-    source = if meta then @keyEvents.meta else source
-    source = if control then @keyEvents.control else source
-    source = if meta and control then @keyEvents.meta_control else source
-
-    if keyEvent = source?[keyname]
-      if @[keyEvent]? and _.isFunction(@[keyEvent])
-        @[keyEvent]?.call(@, e, keyname, keyEvent)
-      else
-        @trigger(keyEvent, e, keyname)
-
+application.privateMethods
+  # Any time the Application's main controller changes its active page
+  # we track the name of that page ( aka section ) on our state machine.
+  # If the active page on the main controller is another controller component,
+  # then we will track that controller's active component as our active sub section.
   setupControllerBindings: ()->
     app = @
     # any time the main controller card switches we should track
@@ -332,6 +308,12 @@ application.privateInterface
           @state.set(active_sub_section:current.name)
           app.trigger "action:change", previous.name, current.name
 
+  # A typical structure for a Luca.Application is that it will act as a `Viewport` which
+  # monopolizes the entire top level element in your dom ( either the body tag, or a top 
+  # level element just underneath it)  This `Viewport` is an abstract element where we can
+  # setup global event bindings, like keyBindings and such.  The `Viewport` will generally
+  # contain a `Luca.components.Controller` instance called "main_controller" that is responsible
+  # for displaying the active page for a given route. 
   setupMainController: ()->
     if @useController is true
       definedComponents = @components || []
@@ -385,12 +367,18 @@ application.privateInterface
       collectionManagerOptions.autoStart = false
       @collectionManager = new @collectionManagerClass( collectionManagerOptions )
 
+  # If our application is configured with a `@socketManagerOptions` property,
+  # it will create a socket manager instance for us automatically.  It won't
+  # start the socket manager process until the `@boot()` method is called on the application. 
   setupSocketManager: ()->
     return if _.isEmpty(@socketManagerOptions)
     _.extend(@socketManagerOptions, autoStart: false)
 
     @socket = new Luca.SocketManager(@socketManagerOptions) 
-  
+ 
+  # Sets up an instance of the Backbone.Router, and sets up the
+  # call to start the history tracking API once the appropriate
+  # application events have been fired. 
   setupRouter: ()->
     return if not @router? and not @routes?
 
@@ -421,6 +409,9 @@ application.privateInterface
       @autoStartHistory = "before:render" if @autoStartHistory is true
       @defer( Luca.Application.startHistory, false).until(@, @autoStartHistory)
 
+  # The default implementation of setupKeyHandler is kept around for backward
+  # compatibility purposes.  In Luca 1.0 we will be using keymaster.js for our
+  # key binding setup. 
   setupKeyHandler: ()->
     return unless @keyEvents
 
@@ -434,11 +425,12 @@ application.privateInterface
     for keyEvent in (@keypressEvents || ["keydown"])
       $( document ).on( keyEvent, handler )
 
-application.classInterface
+application.classMethods
   instances:{}
 
-  # Public: For purely informational purposes, describes the structure
-  # of the Application's controller views, and any of their nested controllers views.
+  # An application inspection helper, it describes the structure of this application's
+  # controlled components.  For an application that consists of multiple nested controllers
+  # it will recursively walk each controller and build a tree of the various pages / controlers.
   pageHierarchy: ()->
     app             = Luca()
     mainController  = app.getMainController()
@@ -455,19 +447,15 @@ application.classInterface
 
     getTree( mainController )
 
-  # Private: registers the instance of the Luca.Appliction
+  # Registers this instance of the Luca.Appliction
   # so that it is available via the Luca() helper, or through
-  # a call to Luca.Application.get()
+  # a call to Luca.Application.get().
   registerInstance: (app)->
     Luca.Application.instances[ app.name ] = app
 
-  # Keymaster understands the following modifiers:
-  # `⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, and `⌘`.
-
-  # The following special keys can be used for shortcuts:
-  # `backspace`, `tab`, `clear`, `enter`, `return`, `esc`, `escape`, `space`,
-  # `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `del`, `delete`
-  # and `f1` through `f19`.
+  # If the keymaster library is present, swap out the 
+  # setupKeyHandler method with something which will enable 
+  # keymaster support instead of our legacy system.
   checkForKeymaster: ()->
     if window?.key?.noConflict
       Luca.key = window.key.noConflict()
@@ -476,13 +464,12 @@ application.classInterface
         return unless @keyEvents
         Luca.util.setupKeymaster(@keyEvents, "all").on(@)
 
-  # Private: Recursively navigates down the controller page hierarchy
-  # to the page you specify by name.  You can specify the 
-  # method which is to be called at the end of the chain.
-  # 
   # This is used internally by the Application as it sets up
   # the @routes property and uses it to configure the Luca.Router
-  # instance for your app.
+  # instance for your app.  It allows you to specify the page you want
+  # to monopolize the viewport in your application by name, and regardless
+  # of how deeply nested that page may be among your controllers, it will know 
+  # what to do.  
   routeTo: (pages...)->
     last = _( pages ).last()
     first = _( pages ).first()
@@ -494,7 +481,7 @@ application.classInterface
       path = @app || Luca()
       index = 0
 
-      # we can specify a page by name, and not have to know its full path
+      # we can specify a page by name, and not have to know its full path.
       if pages.length is 1 and target = Luca(first)
         pages = target.controllerPath()
 
@@ -504,6 +491,9 @@ application.classInterface
         target = Luca(page)
 
         if page is last 
+          if specifiedAction? and not target[specifiedAction]? and not target.routeHandler?
+            console.log "You specified a component action to call when a route matches, but it does not exist on the component"
+
           callback = if specifiedAction? and target[ specifiedAction ]?
             _.bind(target[ specifiedAction ], target)
           else if target.routeHandler?
@@ -528,7 +518,10 @@ application.classInterface
   # modify how Backbone.history.start is called.  This will get called
   # by the Application instance in response to the @autoStartHistory property.
   startHistory: ()->
-    Backbone.history.start()
+    Backbone.history.start
+      pushState: @pushState
+      rootUrl: @rootUrl
+      silent: @startHistorySilently
 
 application.afterDefinition ()->
   Luca.routeHelper = Luca.Application.routeTo

data/app/assets/javascripts/luca/components/collection_view.coffee

@@ -151,15 +151,19 @@ collectionView.publicMethods
     if models.length is 0
       @trigger("empty:results", query, options)
 
-    index = 0
-    for model in models
-      @$append @makeItem(model, index++)
+    @renderModels(models, query, options)
 
     @trigger("after:refresh", models, query, options)
 
     @
 
+
 collectionView.privateMethods
+  renderModels: (models, query, options)->
+    index = 0
+    for model in models
+      @$append @makeItem(model, index++)
+
   # Determines which attributes should be set on the item DOM element. 
   attributesForItem: (item, model)->
     _.extend {}, class: @itemClassName, "data-index": item.index, "data-model-id": item.model.get('id')
@@ -178,14 +182,14 @@ collectionView.privateMethods
 
     ""
 
-  # Uses the various options passed to the `CollectionView` to assemble a call to `Backbone.View::make`.
+  # Uses the various options passed to the `CollectionView` to assemble a call to `Luca.View::make`.
   makeItem: (model, index)->
     item = if @prepareItem? then @prepareItem.call(@, model, index) else (model:model, index: index)
     attributes = @attributesForItem(item, model) 
     content = @contentForItem(item)
 
     try
-      Backbone.View::make(@itemTagName, attributes, content)
+      Luca.View::make(@itemTagName, attributes, content)
     catch e
       console.log "Error generating DOM element for CollectionView", @, model, index