luca 0.9.7 → 0.9.8

data/CHANGELOG

@@ -200,3 +200,41 @@
   - Renaming 'mixin' and 'module' functionality to 'concern'
   - Luca.concerns now follow the active support concern in spirit, with __included hooks, ClassMethods handling, etc
   - Introducing an optional Concern for Luca.Model classes, called ModelPresenter.
+  - The callback argument passed to CardView activate, now gets called in the context of the activated component
+
+0.9.75
+  - Component registration is now beautifully readable and self documenting,
+    and flexible.  Minimally only requires one call to Luca.register().  
+    This allows you to be as descriptive as you like when defining a component, 
+    and does not require you to call any definition methods which do not 
+    make literary sense in your component description. 
+
+  - Component definition now supports specifying class methods.
+
+  - Luca.initialize('Namespace') will setup a complete namespace for 
+    your application, and give you a Namespace() method which works similar
+    to the Luca() helper.
+
+  - Added Luca.config.modelBootrstrap and Luca.config.baseParams as pointers
+    to either properties, or methods, which can be used to configure Luca.Collection behavior
+  - Luca.onReady is now the preferred way of launching the application.
+  - Added Luca.Application.routeTo, Luca.Application.controller 
+    route building helpers
+
+0.9.78
+  - Added experimental ability to integrate router into the application itself, via the @routes property
+  - Temporary fix for double rendering bug in containers which had css class based assignments on their containers.
+  - Added experimental support for Luca.SocketManager
+  - Introducing @stateChangeEvents property for views which mixin the StateModel concern. 
+  - Added additional ComponentDefinition methods: public, private, configuration, methods
+  - Component MetaData tracks descendants()
+  - SelectField defaults to valueType integer when valueField is "id"
+
+0.9.8
+  - Luca follows Sprockets / Asset Pipeline Conventions
+  - Renamed 
+    - Luca.core.Container to Luca.Container
+    - Luca.components.Panel to Luca.Panel
+  - Added Sortable Concern
+  - Added Luca.log()
+  - Added ability to create aliases / deprecations of components with warning messages

data/Gemfile

@@ -15,4 +15,5 @@ group :test, :development do
   gem 'rb-fsevent', '>= 0.9.1'
   gem 'pry'
   gem 'guard-jasmine'
+  gem 'jasmine'
 end

data/Gemfile.lock

@@ -1,6 +1,7 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    addressable (2.3.2)
     childprocess (0.3.1)
       ffi (~> 1.0.6)
     coderay (0.9.8)
@@ -8,6 +9,7 @@ GEM
       coffee-script-source
       execjs
     coffee-script-source (1.2.0)
+    diff-lcs (1.1.3)
     ejs (1.0.0)
     execjs (1.2.13)
       multi_json (~> 1.0)
@@ -28,6 +30,15 @@ GEM
     haml (3.1.4)
     hike (1.2.1)
     i18n (0.6.0)
+    jasmine (1.3.0)
+      jasmine-core (>= 1.3.0)
+      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)
@@ -41,9 +52,23 @@ GEM
       rack
     rake (0.9.2.2)
     rb-fsevent (0.9.1)
+    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)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.0)
     ruby_parser (2.3.1)
       sexp_processor (~> 3.0)
+    rubyzip (0.9.9)
     sass (3.1.12)
+    selenium-webdriver (2.26.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)
@@ -59,6 +84,7 @@ GEM
     uglifier (1.2.0)
       execjs (>= 0.3.0)
       multi_json (>= 1.0.2)
+    websocket (1.0.4)
 
 PLATFORMS
   ruby
@@ -70,6 +96,7 @@ DEPENDENCIES
   guard-jasmine
   guard-sprockets2
   haml
+  jasmine
   pry
   rake
   rb-fsevent (>= 0.9.1)

data/README.md

@@ -7,21 +7,6 @@ and clean single page applications.
 It uses twitter bootstrap compatible markup and css naming conventions, 
 making it possible to generate completely styled user interfaces with JSON alone.
 
-Luca combines the functionality of other open source libraries as well, but you are not
-required to use any of them if you don't like.
-
-### Dependencies
-
-- [Bootstrap by Twitter](https://twitter.github.com/bootstrap)
-- [Backbone-Query by David Tonge](https://github.com/davidgtonge/backbone_query)
-- [Underscore String by Esa-Matti Suuronen](https://github.com/epeli/underscore.string)
-
-### Development Tool Dependencies:
-
-- [CodeMirror IDE](https://codemirror.net)
-- [CoffeeScript Compiler](https://coffeescript.org)
-
-
 ### Using With Rails Asset Pipeline
 
 ```ruby
@@ -33,41 +18,59 @@ In your css manifest:
 
 ```css
   /*
-   *= require 'luca-ui-full'
-   *= require 'luca-ui-development-tools'
+   *= require 'luca'
   */
 ```
 
 All Javascript Dependencies:
 
 ```javascript
-   //= require 'underscore'
-   //= require 'underscore-string.min'
-   //= require 'jquery'
-   //= require 'backbone'
-   //= require 'bootstrap.min.js'
-   //= require 'luca-ui.min.js'
-   //= require 'luca-ui-development-tools.min.js'
+  //= require 'luca/dependencies'
+  //= require 'luca'
 ```
 
-Or you can just use the dependencies we rely on.  Latest backbone.js, underscore.js, underscore.string.js, twitter boostrap js and css:
-
-```
-  //= require 'luca-ui-full.min.js'
-```
-
-## Standalone With Twitter Bootstrap ( development tools are optional )
-```html
-  <html>
-    <head>
-      <link rel="stylesheet" href='luca-ui-full.css' />
-      <link rel="stylesheet" href='luca-ui-development-tools.css' />
-    </head>
-    <body>
-      <script type='text/javascript' src="luca-ui-full.min.js" /> 
-      <script type='text/javascript' src="luca-ui-development-tools.min.js" /> 
-    </body>
-  </html>
+Your App:
+```javascript
+  Luca.initialize('App', {
+    // will look in window.AppBootstrap for an object
+    // keyed on your collection's cache_keys() for automatically
+    // populating collections on page load
+    modelBootstrap: true,
+    // will look in window.AppBaseParams for an object
+    // or function used to determine the query parameters to
+    // be sent on every request
+    baseParams: true
+  });
+
+  JST['home'] = function() {
+    // content
+  };
+
+  App.register('App.views.Home').extends('Luca.View').defines({
+    template: "home",
+    events: {
+      "click .menu-handler" : "clickMenuHandler"
+    },
+    clickMenuHandler: function(e){
+
+    }
+  });
+
+  App.register('App.Application').extends('Luca.Application').defines({
+    // will use the Application classes internal controller
+    // to make the home 'page' active in the viewport
+    routes:{
+      "" : "home"  
+    }
+    components:[
+      name: "home"
+      type: "home"
+    ]
+  });
+
+  AppNamespace.onReady(function(){
+    (new AppNamespace.Application).boot()
+  })
 ```
 
 ## Rails Generator

data/ROADMAP

@@ -1,33 +1,10 @@
-Framework
----------
-Extract hooks into module
+Luca.Collection.query
+  - add function pipeline to run filter, and options 
+    objects through.  anything can inject itself
+    into the pipeline.  
 
-General
--------
-- Make development mode options easily disabled
-- Integrate with requireJs or some other AMD system
-- Move to node.js for build / testing
-- Replace .luca template with standard jst
-- Eliminate underscore-string dependency.  just copy necessary functions.
-- Eliminate pointless CSS selectors
+    basically, remove this from the view.
 
-- Rely on data attributes for functionality instead of css selectors
-- BUT in general don't tie views to the DOM anyway
+  - write a backbone-query -> squeel -> activerecord bridge
 
-Luca.View
----------
-- Add StateMachine model to all instances of Luca.View
 
-Containers
-----------
-- Luca.core.Container should relay all activation events to @components
-
-Luca.CollectionManager
-----------------------
-- Add concept of base params for a given scope of the collection manager
-
-Luca.Application
-----------------
-- Modify boot sequence so that rendering can happen on DOM ready, but all other
-  operations, such as fetching collections, etc, can happen immediately upon
-  initialization

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
+#= require ./framework

data/{src → app/assets/javascripts/luca}/components/application.coffee

@@ -1,22 +1,14 @@
-application = Luca.register       "Luca.Application"
-application.extends               "Luca.containers.Viewport"
-
 # Luca.Application
 #
 # The Application class is the global state tracking mechanism
 # for your single page application, as well as the entry point.
-#
-# By default it contains a main controller which is a Luca.components.Controller instance.
-#
-# In a typical Luca application, the router will use the applications @navigate_to() method to switch
-# from page to page on the main controller, or any other controllers nested inside of it.
-#
-# You would control flow when the controller fires activation events on the nested view components inside of it.
-#
-# Decoupling application control flow from the URL Fragment from Backbone.History and preventing
-# your components from directly caring about the URL Fragment, allows you to build applications as
-# isolated components which can run separately or nested inside of other applications.
-application.defines
+application = Luca.register       "Luca.Application"
+application.extends               "Luca.containers.Viewport"
+
+application.triggers              "controller:change",
+                                  "action:change"
+
+application.publicInterface
   name: "MyApp"
 
   # The Application uses a Backbone.Model as a state machine, which
@@ -49,6 +41,7 @@ application.defines
   # 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
@@ -90,34 +83,46 @@ application.defines
   # will get wrapped by the main controller unless you
   # set useController = false
   components:[
-    ctype: 'template'
+    type: 'template'
     name: 'welcome'
     template: 'sample/welcome'
     templateContainer: "Luca.templates"
   ]
 
+  # DOCUMENT
+  createRoleBasedGetters: false
+  useSocketManager: false
+  socketManagerOptions: {}
+
+  # Don't create getters on this component
+  # for the nested components
   initialize: (@options={})->
     app             = @
     appName         = @name
     alreadyRunning  = Luca.getApplication?()
 
-    Luca.Application.instances ||= {}
-    Luca.Application.instances[ appName ] = app
+    Luca.Application.registerInstance(@)
 
-    Luca.containers.Viewport::initialize.apply @, arguments
+    Luca.concerns.StateModel.__initializer.call(@)
+
+    # 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()
 
-    @state = new Luca.Model( @defaultState )
+    # 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
     # we are ready
@@ -156,6 +161,8 @@ application.defines
         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.
   #
@@ -191,6 +198,9 @@ application.defines
   # of the views
   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.
   # use App.collection() to create or access existing collections
@@ -212,11 +222,7 @@ application.defines
   navigate_to: (component_name, callback)->
     @getMainController().navigate_to(component_name, callback)
 
-  getMainController: ()->
-    return @components[0] if @useController is true
-    Luca.cache('main_controller')
-
-  #
+application.privateInterface
   keyHandler: (e)->
     return unless e and @keyEvents
 
@@ -248,16 +254,16 @@ application.defines
     # the active card on the global state chart
     @getMainController()?.bind "after:card:switch", (previous,current)=>
       @state.set(active_section:current.name)
-      app.trigger "page: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 "sub:page:change"
+          app.trigger "action:change", previous.name, current.name
 
   setupMainController: ()->
     if @useController is true
@@ -266,8 +272,11 @@ application.defines
       @components = [
         type: 'controller'
         name: "main_controller"
+        role: "main_controller"
         components: definedComponents
       ]
+      
+      @getMainController = ()=> @findComponentByRole('main_controller')
 
       @defer( @setupControllerBindings, false ).until("after:components")
 
@@ -296,26 +305,46 @@ application.defines
       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)
+
+    routerConfig = routerClass.prototype
+    routerConfig.routes ||= {}
+    routerConfig.app = @
 
-    if _.isString( @router )
-      routerClass = Luca.util.resolve(@router)
-      @router = new routerClass({app})
+    if _.isObject( @routes )
+      for routePattern, endpoint of @routes
+        [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.
     # you can control which by setting the @startHistoryOn property
     if @router and @autoStartHistory
       @autoStartHistory = "before:render" if @autoStartHistory is true
-      @defer( Luca.util.startHistory, false).until(@, @autoStartHistory)
+      @defer( Luca.Application.startHistory, false).until(@, @autoStartHistory)
 
   setupKeyHandler: ()->
     return unless @keyEvents
@@ -330,5 +359,89 @@ application.defines
     for keyEvent in (@keypressEvents || ["keydown"])
       $( document ).on( keyEvent, handler )
 
-Luca.util.startHistory = ()->
-  Backbone.history.start()
+application.classInterface
+  instances:{}
+
+  # Public: For purely informational purposes, describes the structure
+  # of the Application's controller views, and their nested controllers views.
+  pageHierarchy: ()->
+    app = Luca()
+    mainController = app.getMainController()
+
+    getTree = (node)->  
+      return {} unless node.components? or node.pages?
+
+      _( 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() or Luca.getAppliction()
+  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.
+  # 
+  # 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()
+
+    callback = undefined    
+    specifiedAction = undefined
+
+    routeHelper = (args...)->
+      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]
+        target = Luca(page)
+
+        if page is last 
+          callback = if specifiedAction? and target[ specifiedAction ]?
+            _.bind(target[ specifiedAction ], target)
+          else if target.routeHandler?
+            target.routeHandler  
+
+        callback ||= if _.isFunction(nextItem)
+          _.bind(nextItem, target)
+        else if _.isObject(nextItem) 
+          if action = nextItem.action and target[action]?
+            _.bind(target[action], target)
+
+        path = path.navigate_to page, ()->
+          callback?.apply(target, args)
+
+    routeHelper.action = (action)->
+      specifiedAction = action
+      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
+
+application.register()

data/{src → app/assets/javascripts/luca}/components/base_toolbar.coffee

@@ -1,7 +1,7 @@
-_.def('Luca.components.Toolbar').extends('Luca.core.Container').with
+_.def('Luca.components.Toolbar').extends('Luca.Container').with
 
 toolbar = Luca.register     "Luca.components.Toolbar"
-toolbar.extends             "Luca.core.Container"
+toolbar.extends             "Luca.Container"
 
 toolbar.defines
   className: 'luca-ui-toolbar toolbar'