luca 0.9.8 → 0.9.9

data/app.rb

@@ -1,7 +1,10 @@
-
+$LOAD_PATH.unshift( File.join(File.dirname(__FILE__),'lib') )
 require 'rubygems'
 require 'bundler'
-Bundler.require
+require 'luca'
+require 'redcarpet'
+require 'active_support/core_ext'
+Bundler.require(:default, :development)
 
 require 'faker'
 
@@ -11,9 +14,6 @@ module AssetHelpers
   end
 end
 
-require "#{ File.expand_path('../', __FILE__) }/lib/luca/template.rb"
-require "#{ File.expand_path('../', __FILE__) }/lib/luca/code_browser.rb"
-
 module Luca
   class Template
     def self.namespace
@@ -31,6 +31,10 @@ class App < Sinatra::Base
   sprockets.register_engine '.luca', Luca::Template 
 
   configure do
+    HoganAssets::Config.configure do |config|
+      config.template_namespace = 'JST'
+    end    
+    
     sprockets.append_path(File.join(root, 'app', 'assets', 'stylesheets'))
     sprockets.append_path(File.join(root, 'app', 'assets', 'javascripts'))
     sprockets.append_path(File.join(root, 'vendor', 'assets', 'javascripts'))
@@ -40,6 +44,7 @@ class App < Sinatra::Base
     sprockets.context_class.instance_eval do
       include AssetHelpers
     end
+
   end
 
   helpers do
@@ -54,41 +59,4 @@ class App < Sinatra::Base
     erb :jasmine
   end
 
-  Luca::CodeBrowser.look_for_source_in( File.join(File.expand_path('../', __FILE__),'src') )
-
-  get "/luca/source-map.js" do
-    source_map = {}
-
-    files = (["src/**/*.coffee","assets/javascripts/sandbox/**/*.coffee"]).map do |location|
-      Dir.glob("#{ App.root }/#{ location }")
-    end
-
-    files.flatten.each do |file|
-      definitions = IO.read(file).lines.to_a.grep /_\.def/
-
-      definitions.each do |definition|
-        component = definition.match(/_\.def\(['"](.+)['"]\)\./)
-
-        if component and component[1]
-          componentId = component[1].gsub(/['"].*$/,'')
-          if componentId
-            source_map[ componentId ] = {className:componentId,file:file,source:IO.read(file)}
-          end
-        end
-      end      
-    end
-
-    JSON.generate source_map.values
-  end
-
-  get "/components" do
-    if params[:component]
-      component = params[:component]
-      source = Luca::CodeBrowser.get_source_for( component )
-      {className:component, source:source}.to_json
-    else
-      Luca::CodeBrowser.map_source
-    end
-  end
-
 end

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

@@ -4,5 +4,5 @@
 #= require ./util
 #= require ./managers
 #= require ./core
-#= require ./containers
+#= require ./containers/container
 #= require ./framework

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

@@ -1,14 +1,72 @@
-# Luca.Application
+# The `Luca.Application` is the main entry point into your Application.
+# It acts as a global state machine, page controller, and router, in addition
+# to providing access to other singletons such as the CollectionManager, and SocketManager.
+# 
+# The structure of a common `Luca.Application` is that it contains one or many `Pages` which
+# themselves are made up of the components of your application.  One `Page` is visible at a time
+# and which page is displayed is managed by an instance of the `Luca.components.Controller` class.
 #
-# The Application class is the global state tracking mechanism
-# for your single page application, as well as the entry point.
+# ### Example Configuration  
+#     application = Luca.register     "App.Application"
+#     application.extends             "Luca.Application"
+#
+#     application.defines
+#       name: "MyApplication"
+#       routes: 
+#         "" : "home"
+#         "standard/backbone/style/:route" : "name_of_page#name_of_method"
+#
+#       components:[
+#         name: "home"
+#       ,
+#         type: "your_view"
+#         name: "name_of_page"
+#         name_of_method: (routeParam)->
+#           @doSomethignToSetupYourPageWithThePassed(routeParam)  
+#       ]
+#
+#   App.onReady ()->
+#     window.MyApp = new App.Application();
+#     window.MyApp.boot() 
+#
+# #### @routes and pages
+#
+# In the above example, our application contains two pages, one with the name 'home'
+# and one with the name 'name_of_page'.  It also specifies a `@routes` property which
+# is identical to the configuration you would see in a standard `Backbone.Router`.
+#
+# Whenever the route matches 'standard/backbone/style/route' the `App.Application` instance
+# will send an instruction to the `Luca.components.Controller` to `activate` the page whose name
+# is passed in the `@routes` config.
+# 
+# If that page defines a method called `@routeHandler` it will be called with the parameters
+# from the route.  In the `@routes` config you can specify your own route handler method
+# by using the rails style `page_name#action` and it will call the `@action` method instead
+# on the view named `page_name`.
+#
+# The `App.Application` instance, also accessible by `window.MyApp`, or through the helper `App()`
+# or `Luca.getApplication()` maintains the state of which page is active.  You can access this
+# in your code by calling `App().activePage()`.
+#
+# #### Controllers
+# 
+# The `Luca.components.Controller` is a special type of component which contains 
+# other views, or `Pages` which only one will be visible at any given time.  It expects
+# that each page will have its own unique `@name` property.  A `Luca.components.Controller` can
+# contain other controllers, providing you with a way of structuring your application layout
+# in an organized, hierarchal fashion. 
+#
+# By default, any `Luca.Application` will have one `Luca.components.Controller` automatically
+# created named 'main_controller' which is accessible by `MyApp.getMainController()`.  Any
+# components you define on the `Luca.Application` instance will be wrapped by the main controller
+# automatically unless you specify `@useController = false` in your Application component definition.
 application = Luca.register       "Luca.Application"
 application.extends               "Luca.containers.Viewport"
 
 application.triggers              "controller:change",
                                   "action:change"
 
-application.publicInterface
+application.publicConfiguration
   name: "MyApp"
 
   # The Application uses a Backbone.Model as a state machine, which
@@ -16,7 +74,7 @@ application.publicInterface
   # most importantly to bind to change events of certain attributes.
   #
   # the @defaultState property will be the default attributes
-  defaultState: {}
+  stateful: {}
 
   # if autoBoot is set to true, the application will
   # attempt to boot on document ready.
@@ -28,6 +86,18 @@ application.publicInterface
   # 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
@@ -41,7 +111,6 @@ application.publicInterface
   # just pass a reference to the class you would like to use.
   collectionManagerClass: "Luca.CollectionManager"
 
-
   # Luca plugin apps are apps which mount onto existing
   # luca apps, and will not have the behavior of a main
   # app which acts as a singleton
@@ -53,49 +122,42 @@ application.publicInterface
   # with several 'pages' so to speak
   useController: true
 
-  # Key Handler
+  # 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
+
+  # keyEvents 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`.
   #
-  # 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:
+  # **Note**: This requires the keymaster.js library to be loaded.  This library is included
+  # with the bundled dependencies that ship with Luca.
   #
+  # Example:
+  #       application.configuration
+  #         keyEvents:
+  #           '⌘+r, ctrl+r': "keyHandlerFunction"
+  #         keyHandlerFunction: -> alert 'something + r was pressed'
   keyEvents: {}
 
-  # keyEvents
-  #   keyup: keyUpHandler
-  #   enter: enterHandler
-  #   meta:
-  #     up: metaUpHandler
-  #   control:
-  #     forwardslash: controlSlashHandler
-  #     keyup: controlUpHandler
-  #   control_meta:
-  #     keydown: metaControlKeyDownHandler
-  #
-  #
-
-  # 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"
-  ]
-
-  # DOCUMENT
+  # 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
+  # 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
@@ -123,6 +185,7 @@ application.publicInterface
     # to a given page, or component, by its name.  The controller integrates
     # with the state machine of the application
     @setupMainController() if @useController is true 
+
     # we will render when all of the various components
     # which handle our data dependencies determine that
     # we are ready
@@ -140,10 +203,8 @@ application.publicInterface
     # keyEvents:
     #   meta:
     #     forwardslash: "altSlashHandler"
-    if @useKeyRouter is true
-      console.log "The useKeyRouter property is being deprecated. switch to useKeyHandler instead"
-
-    @setupKeyHandler() if (@useKeyHandler is true or @useKeyRouter is true) and @keyEvents?
+    if (@useKeyHandler is true or @useKeyRouter is true) and @keyEvents?
+      @setupKeyHandler() 
 
     # if the application is a plugin designed to modify the behavior
     # of another app, then don't claim ownership.  otherwise the most common
@@ -164,11 +225,9 @@ application.publicInterface
     Luca.trigger "application:available", @
 
   # @activeView() returns a reference to the instance of the view
-  # which is currently monopolizing the viewport.
-  #
-  # this will be whicever component is active on the controllers
-  # nested within the main controller, if there are any, or the view
-  # itself which is active on the main controller.
+  # which is currently monopolizing the viewport.  In an application
+  # which uses a controller hierarchy, it will be the last controller
+  # has activated one of its pages.
   activeView: ()->
     if active = @activeSubSection()
       @view( active )
@@ -186,7 +245,8 @@ application.publicInterface
     @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
@@ -199,7 +259,6 @@ application.publicInterface
   boot: ()->
     @trigger "ready"
     for service in [@collectionManager, @socket, @router]
-      console.log "Trigggering Ready On", service
       service?.trigger("ready")
 
   # delegate to the collection manager's get or create function.
@@ -207,47 +266,31 @@ application.publicInterface
   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(@)
-      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
@@ -265,20 +308,30 @@ 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 || []
-
-      @components = [
+      base =  
         type: 'controller'
         name: "main_controller"
         role: "main_controller"
         components: definedComponents
-      ]
-      
-      @getMainController = ()=> @findComponentByRole('main_controller')
 
-      @defer( @setupControllerBindings, false ).until("after:components")
+      if @mainControllerContainer?
+        _.extend(base, container: @mainControllerContainer)
+
+      @components = [base]
+    
+    @getMainController = ()=> 
+      @findComponentByRole('main_controller')
+
+    @defer( @setupControllerBindings, false ).until("after:components")
 
   setupCollectionManager: ()->
     return unless @useCollectionManager is true
@@ -314,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?
 
@@ -332,7 +391,11 @@ application.privateInterface
 
     if _.isObject( @routes )
       for routePattern, endpoint of @routes
-        [page, action] = endpoint.split(' ')
+        if endpoint.match(/\ /)
+          [page, action] = endpoint.split(' ')
+        else if endpoint.match(/\#/)
+          [page, action] = endpoint.split('#')
+
         fn = _.uniqueId(page)
         routerConfig[fn] = Luca.Application.routeTo(page).action(action)
         routerConfig.routes[ routePattern ] = fn
@@ -346,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
 
@@ -359,18 +425,20 @@ 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 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()
+    app             = Luca()
+    mainController  = app.getMainController()
 
     getTree = (node)->  
       return {} unless node.components? or node.pages?
 
+      # recursively walks the pages on a controller
       _( node.components || node.pages ).reduce (memo, page)->
         memo[ page.name ] = page.name
         memo[ page.name ] = getTree(page) if page.navigate_to?
@@ -379,19 +447,29 @@ 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() or Luca.getAppliction()
+  # a call to Luca.Application.get().
   registerInstance: (app)->
     Luca.Application.instances[ app.name ] = app
 
-  # 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.
-  # 
+  # 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()
+
+      Luca.Application::setupKeyHandler = ()->
+        return unless @keyEvents
+        Luca.util.setupKeymaster(@keyEvents, "all").on(@)
+
   # 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()
@@ -403,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()
 
@@ -413,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?
@@ -437,11 +518,13 @@ 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
+  Luca.Application.checkForKeymaster()
 
 application.register()