luca 0.9.76 → 0.9.89

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
@@ -25,23 +25,26 @@ end
 class App < Sinatra::Base
   set :root, File.expand_path('../', __FILE__)
   set :sprockets, Sprockets::Environment.new(root)
-  set :precompile, [ /\w+\.(?!js|css).+/, /application.(css|js)$/ ]
   set :assets_prefix, 'assets'
   set :assets_path, File.join(root, 'public', assets_prefix)
 
   sprockets.register_engine '.luca', Luca::Template 
 
   configure do
-    sprockets.append_path(File.join(root, 'assets', 'stylesheets'))
-    sprockets.append_path(File.join(root, 'assets', 'javascripts'))
+    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'))
     sprockets.append_path(File.join(root, 'vendor', 'assets', 'stylesheets'))
-    sprockets.append_path(File.join(root, 'assets', 'images'))
     sprockets.append_path(File.join(root, 'vendor', 'assets', 'images'))
 
     sprockets.context_class.instance_eval do
       include AssetHelpers
     end
+
   end
 
   helpers do
@@ -56,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-ui.js

@@ -0,0 +1 @@
+//= require ./luca/index

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

@@ -0,0 +1,8 @@
+#= require_tree ./templates
+#= require_self
+#= require ./config
+#= require ./util
+#= require ./managers
+#= require ./core
+#= require ./containers/container
+#= require ./framework

data/{src → 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.
@@ -52,6 +110,12 @@ application.publicInterface
   # 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
+  mainControllerContainer: undefined
+
   # Key Handler
   #
   # One responsibility of the application, since it is a viewport which monopolizes the entire screen
@@ -61,21 +125,23 @@ application.publicInterface
   useKeyHandler: false
 
   # You can configure key events by specifying them by their name, as it exists in Luca.keyMap. For example:
-  #
-  keyEvents: {}
 
-  # keyEvents
-  #   keyup: keyUpHandler
-  #   enter: enterHandler
-  #   meta:
-  #     up: metaUpHandler
-  #   control:
-  #     forwardslash: controlSlashHandler
-  #     keyup: controlUpHandler
-  #   control_meta:
-  #     keydown: metaControlKeyDownHandler
-  #
+  # 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`.
   #
+  # Example:
+  # ```coffeescript
+  #   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
@@ -88,6 +154,19 @@ application.publicInterface
     templateContainer: "Luca.templates"
   ]
 
+  # create getter methods for the various
+  # roles in the application's components on the
+  # application itself.  false by default.
+  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
   initialize: (@options={})->
     app             = @
     appName         = @name
@@ -95,19 +174,26 @@ application.publicInterface
 
     Luca.Application.registerInstance(@)
 
-    Luca.containers.Viewport::initialize.apply @, arguments
+    Luca.concerns.StateModel.__initializer.call(@)
 
-    @state = new Luca.Model( @defaultState )
+    # The Collection Manager is responsible for managing instances 
+    # of collections, usually to guarantee only a single collection is
+    # instantiated for a given resource, to maintain 'authoritative' 
+    # representations of models.
+    @setupCollectionManager()
+
+    # Socket Manager provides a bridge between remote pub/sub providers and 
+    # the backbone.events interface on various components in the system.
+    @setupSocketManager()
+
+    Luca.containers.Viewport::initialize.apply @, arguments
 
     # The Controller is the piece of the application that handles showing
     # and hiding 'pages' of the app.  The Application has a navigate_to
     # method which delegates to the controller, and allows you to navigate
     # to a given page, or component, by its name.  The controller integrates
     # with the state machine of the application
-    @setupMainController() if @useController is true
-
-    # The Collection Manager is responsible
-    @setupCollectionManager()
+    @setupMainController() if @useController is true 
 
     # we will render when all of the various components
     # which handle our data dependencies determine that
@@ -126,10 +212,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
@@ -147,12 +231,12 @@ application.publicInterface
         window[ appName ] = app
         app.boot()
 
+    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 )
@@ -182,6 +266,8 @@ application.publicInterface
   # of the views
   boot: ()->
     @trigger "ready"
+    for service in [@collectionManager, @socket, @router]
+      service?.trigger("ready")
 
   # delegate to the collection manager's get or create function.
   # use App.collection() to create or access existing collections
@@ -225,7 +311,7 @@ application.privateInterface
 
     if keyEvent = source?[keyname]
       if @[keyEvent]? and _.isFunction(@[keyEvent])
-        @[keyEvent]?.call(@)
+        @[keyEvent]?.call(@, e, keyname, keyEvent)
       else
         @trigger(keyEvent, e, keyname)
 
@@ -235,31 +321,35 @@ application.privateInterface
     # the active card on the global state chart
     @getMainController()?.bind "after:card:switch", (previous,current)=>
       @state.set(active_section:current.name)
-      app.trigger "controller:change"
+      app.trigger "controller:change", previous.name, current.name
 
     # any time the card switches on one of the sub controllers
     # then we should track the active sub section on the global state chart
     @getMainController()?.each (component)=>
-      type = component.type || component.type
+      type = component.type || component.ctype
       if type.match(/controller$/)
         component.bind "after:card:switch", (previous,current)=>
           @state.set(active_sub_section:current.name)
-          app.trigger "action:change"
+          app.trigger "action:change", previous.name, current.name
 
   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
@@ -286,19 +376,43 @@ application.privateInterface
       collectionManagerOptions =
         name: @collectionManager
 
+
     # let's try and get the collection manager by name if we can
     @collectionManager = Luca.CollectionManager.get?( collectionManagerOptions.name )
 
     # if we can't, then we will have to create one ourselves
     unless _.isFunction(@collectionManager?.get)
+      collectionManagerOptions.autoStart = false
       @collectionManager = new @collectionManagerClass( collectionManagerOptions )
 
+  setupSocketManager: ()->
+    return if _.isEmpty(@socketManagerOptions)
+    _.extend(@socketManagerOptions, autoStart: false)
+
+    @socket = new Luca.SocketManager(@socketManagerOptions) 
+  
   setupRouter: ()->
-    app = @
+    return if not @router? and not @routes?
+
+    routerClass = Luca.Router
+    routerClass = Luca.util.resolve(@router) if _.isString(@router)
 
-    if _.isString( @router )
-      routerClass = Luca.util.resolve(@router)
-      @router = new routerClass({app})
+    routerConfig = routerClass.prototype
+    routerConfig.routes ||= {}
+    routerConfig.app = @
+
+    if _.isObject( @routes )
+      for routePattern, endpoint of @routes
+        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
+
+    @router = new routerClass(routerConfig) 
 
     # if this application has a router associated with it
     # then we need to start backbone history on a certain event.
@@ -321,9 +435,54 @@ application.privateInterface
       $( document ).on( keyEvent, handler )
 
 application.classInterface
-  instances: {}
+  instances:{}
+
+  # Public: For purely informational purposes, describes the structure
+  # of the Application's controller views, and any of their nested controllers views.
+  pageHierarchy: ()->
+    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?
+        memo
+      , {}
+
+    getTree( mainController )
+
+  # Private: registers the instance of the Luca.Appliction
+  # so that it is available via the Luca() helper, or through
+  # 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`.
+  checkForKeymaster: ()->
+    if window?.key?.noConflict
+      Luca.key = window.key.noConflict()
+
+      Luca.Application::setupKeyHandler = ()->
+        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.
   routeTo: (pages...)->
     last = _( pages ).last()
     first = _( pages ).first()
@@ -335,35 +494,44 @@ application.classInterface
       path = @app || Luca()
       index = 0
 
+      # 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()
 
+      # when we do know the full path
       for page in pages when _.isString(page)
         nextItem = pages[++index]
-        action = undefined
+        target = Luca(page)
 
-        if _.isFunction(nextItem)
-          action = nextItem
-        else if _.isObject(nextItem) and nextItem.action?
-          action = nextItem.action
-        else if page is last and routeHandler = Luca(last)?.routeHandler
-          action = Luca.util.read(routeHandler)
+        if page is last 
+          callback = if specifiedAction? and target[ specifiedAction ]?
+            _.bind(target[ specifiedAction ], target)
+          else if target.routeHandler?
+            target.routeHandler  
 
-        if _.isString( action )
-          callback = ()-> 
-            @[ action ].apply(@, args)
+        callback ||= if _.isFunction(nextItem)
+          _.bind(nextItem, target)
+        else if _.isObject(nextItem) 
+          if action = nextItem.action and target[action]?
+            _.bind(target[action], target)
 
-        if _.isFunction( action )
-          callback = nextItem
+        path = path.navigate_to page, ()->
+          callback?.apply(target, args)
 
-        path = path.navigate_to(page, callback)
+    routeHelper.action = (action)->
+      specifiedAction = action
+      routeHelper
 
-      routeHelper.action = (action)->
-        pages.push(action: action)
-
-      return routeHelper
+    routeHelper
 
+  # Public: you can override Luca.Application.startHistory to 
+  # 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()
 
+application.afterDefinition ()->
+  Luca.routeHelper = Luca.Application.routeTo
+  Luca.Application.checkForKeymaster()
+
 application.register()