luca 0.9.8 → 0.9.9

data/spec/{core → javascripts/core}/collection_spec.coffee

@@ -201,7 +201,7 @@ describe "Registering with the collection manager", ->
 
     registerSpy = sinon.spy()
 
-    private = new Luca.Collection [],
+    privateCollection = new Luca.Collection [],
       name: "private"
       manager: manager
       private: true

data/spec/{core → javascripts/core}/view_spec.coffee

@@ -1,10 +1,59 @@
+describe "Inheriting Events", ->
+  beforeEach ->
+    eventTester = Luca.register("Luca.EventTester").extends("Luca.View")
+    eventTester.defines
+      _inheritEvents: 
+        "click input" : "clickHandler"  
+
+      bodyTemplate: ()->
+        "<input type='text' />"
+
+      clickHandler: ()->
+        @trigger("clicked:on:me")
+
+    inheritor = Luca.register("Luca.EventInheritor").extends("Luca.EventTester")
+    inheritor.defines
+      events:
+        "blur input": "blurHandler"
+
+      hmm: ()->
+        @trigger("hmm:what")
+
+      blurHandler: ()->
+        @trigger("blurred:me")    
+
+  it "should register event handlers", ->
+    view = new Luca.EventInheritor()
+    view.render()
+    view.registerEvent("keydown input", "hmm")
+    expect( view.events["keydown input"] ).toEqual "hmm"
+
+  it "should register event handlers", ->
+    view = new Luca.EventInheritor()
+    view.render()
+    expect( _(view.events).keys().length ).toEqual 2
+
+  it "should inherit dom events defined under _inheritEvents", ->
+    view = new Luca.EventInheritor()
+    view.render()
+    view.$('input').trigger("click")
+    expect( view ).toHaveTriggered("clicked:on:me")
+
+  it "should rely on events as normal", ->
+    view = new Luca.EventInheritor()
+    view.render()
+    view.$('input').trigger("blur")
+    expect( view ).toHaveTriggered("blurred:me")
+
+
+
+
 # In order to maintain backward compatibility with older apps,
 # I feel compelled to keep around the old deferrable hack job that is in place.
 #
 # However, selectively, I will go through and upgrade the way 
 # render() gets wrapped on luca components, so that the API is easier 
 # to understand.
-
 describe 'Rendering Strategies', ->
   Luca.View.renderStrategies.spy = sinon.spy()
   Luca.View.renderStrategies.spec = (_userSpecified)->
@@ -102,43 +151,6 @@ describe "Luca.View", ->
     view = new Luca.View(additionalClassNames:"yes-yes yall")
     expect( view.$el.is(".yes-yes.yall") ).toEqual true
 
-
-describe "Development Tool Helpers", ->
-  beforeEach ->
-    _.def("Luca.views.IntrospectionView").extends("Luca.View").with
-      include:["Luca.concerns.DevelopmentToolHelpers"]
-
-    @view = new Luca.views.IntrospectionView 
-      events:
-        "click .a" : "clickHandler"
-        "hover .a" : "hoverHandler"
-
-      clickHandler: ()-> "click"
-      hoverHandler: ()-> "hover"
-
-      collection_one: new Luca.Collection([],name:"collection_one")
-      collection_two: new Luca.Collection([],name:"collection_two")
-      view_one: new Luca.View(name:"view_one")
-      view_two: new Luca.View(name:"view_two")
-      model_one: new Luca.Model(name:"model_one")
-      model_two: new Luca.Model(name:"model_two")
-
-  it "should know the names of functions which are event handlers", ->
-    names = @view.eventHandlerProperties()
-    expect( names ).toEqual ["clickHandler","hoverHandler"]
-
-  it "should know which properties are other views", ->
-    viewNames = _( @view.views() ).pluck("name")
-    expect( viewNames ).toEqual ["view_one","view_two"]
-
-  it "should know which properties are other models", ->
-    modelNames = _( @view.models() ).map (m)-> m.get('name')
-    expect( modelNames ).toEqual ["model_one","model_two"]
-
-  it "should know which properties are other collections", ->
-    collectionNames = _( @view.collections() ).pluck("name")
-    expect( collectionNames ).toEqual ["collection_one","collection_two"]
-
 describe "DOM Helper Methods", ->
   it "should use the $html method to inject into the $el", ->
     view = new Luca.View()
@@ -219,7 +231,7 @@ describe "The Collection Events API", ->
     @manager ||= new SampleManager()
     @collection = @manager.getOrCreate("sample")
 
-  it "should call the resetHandler callback on the view", ->
+  xit "should call the resetHandler callback on the view", ->
     view = new SampleView()
     collection = @manager.get("sample")
     collection.reset([])

data/spec/lib/component_definition_spec.rb

@@ -0,0 +1,63 @@
+require "spec_helper"
+
+describe ComponentDefinition do
+  let(:path) { File.join(Rails.root,"spec","support","fixtures","component.coffee")}
+  let(:definition) { ComponentDefinition.new(path) }
+
+  it "should be valid" do
+    definition.should be_valid
+  end
+
+  it "should recognize the class being defined" do
+    definition.class_name.should == "Luca.SampleComponent"
+  end
+
+  it "should know the type alias" do
+    definition.type_alias.should == "sample_component"
+  end
+
+  it "should be view based" do
+    definition.should be_view_based
+  end
+
+  it "should have a css class identifier" do
+    definition.css_class_identifier.should == "luca-sample-component"
+  end
+
+  it "should know the class it extends" do
+    definition.extends.should == "Luca.View"
+  end
+
+  it "should detect the definition variable name" do
+    definition.definition_proxy_variable_name.should == "component"
+  end
+
+  it "should tell me which methods are defined" do
+    definition.defines_methods.should == ["methodOne","methodTwo"]
+  end
+
+  it "should tell me which properties are defined" do
+    definition.defines_properties.should == ["privateSetting","el","bodyClassName", "publicSetting"]
+  end
+
+  it "should tell me where a method is defined" do
+    definition.find_definition_of("methodOne").line_number.should > 0
+  end
+
+  it "should tell me where a property is defined" do
+    definition.find_definition_of("privateSetting").line_number.should > 0
+  end
+
+  it "should find the documentation for a method definition" do
+    definition.find_comments_above("methodOne").should_not be_empty
+  end
+
+  it "should produce human readable documentation for a method definition" do
+    definition.documentation_for("methodOne").should == "here is some documentation for methodOne"
+  end
+
+  it "should not pick up things which aren't documentation" do
+    definition.documentation_for("bodyClassName").should == ""
+  end
+
+end

data/spec/lib/input_compiler_spec.rb

@@ -0,0 +1,9 @@
+require "spec_helper"
+
+describe AssetCompiler do
+  xit "should compile coffeescript" do 
+    input = "console.log(foo) for foo in [1,2,3]"
+    compiler = AssetCompiler.new(mode:"coffeescript", input: input)
+    compiler.output.should == "haha"
+  end
+end

data/spec/lib/luca_application_spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+
+describe LucaApplication do
+  let(:repo) { LucaApplication.new("tools") }
+  let(:application_file_path) { File.join(repo.send(:coffeescripts_location),'tools_application.coffee') }
+
+  it "should retrieve source code for a component" do
+    source_length = repo.source_code_for_class("Tools.Application").length
+    file_length = File.size( repo.find_definition_file_for_class('Tools.Application') )
+    file_length.should be_within(5).of( source_length ) 
+  end
+
+  it "should map all component definitions to their respective files" do
+    map = repo.component_definition_filemap
+    map["Tools.Application"].should == application_file_path
+  end
+
+  xit "should find a template object by its filename" do
+  end
+
+  it "should find a component definition by class name" do
+    repo.find_component_definition_for_class('Tools.Application').should be_present
+    repo.find_component_definition_for_class('Tools.Collection').should be_present
+  end
+
+  it "should detect the namespace" do
+    repo.namespace.should == "Tools"
+  end
+
+end

data/spec/support/fixtures/application.coffee

@@ -0,0 +1,45 @@
+application = Tools.register      "Tools.Application"
+application.extends               "Luca.Application" 
+
+application.configuration
+  el: '#viewport'
+  bodyClassName: "viewport-body"
+
+  bindMethods:[
+    "toggleLayout"
+  ]
+
+  topToolbar:
+    buttons:[
+      label: "Toggle Layout"
+      eventId: "toggle:layout"
+    ]
+
+  bottomToolbar:
+    buttons:[]
+
+  fluid: false
+  applyWrapper: false
+  autoBoot: false
+  useController: false
+  name: 'ToolsApp'
+  router:             "Tools.Router"
+  collectionManager:  "ToolsCollectionManager"
+
+application.contains
+  type: "component_inspector"
+  role: "component_inspector"
+  className: "work-area row-fluid"
+
+application.publicMethods
+  currentApplication: ()->
+    "tools"
+    
+  toggleLayout: ()->
+    Tools().getComponentInspector().cycleLayout()
+
+application.privateMethods
+  boundaries: ()->
+    [0,60,400,460]
+
+application.register()

data/spec/support/fixtures/component.coffee

@@ -0,0 +1,34 @@
+# This is a sample component definition file 
+# for the luca framework.  The header of the file
+# is used to describe the general purpose of the component.
+component = Luca.register "Luca.SampleComponent"
+component.extends         "Luca.View"
+
+# We can comment on a specific entry such as the mixins.
+component.mixesIn         "SomeMixin"
+
+component.privateConfiguration
+  # this is a basic description of the private setting.
+  # expects: Boolean
+  privateSetting: false 
+  el: '#viewport'
+  bodyClassName: "viewport-body"
+  
+component.publicConfiguration
+  # this is a comment for the public setting
+  publicSetting: ["1,2,3"]
+  
+component.publicMethods
+  # here is some documentation for methodOne 
+  methodOne: ()->
+    @thisIsSomeMethodicalShitSon()
+    @puttingAllsortsOfCode
+      allUp: "InYo"
+      bidness: "Baby"
+
+  # here is a multi line comment for methodTwo
+  # it is pretty dope
+  # that i can do this
+  methodTwo: (butThistime="withSomArguments", youKnow=[], man={})->
+    @okCool()
+

data/tutorials/component-driven-design.md

@@ -0,0 +1,140 @@
+## Component Driven Design
+
+The Luca framework is designed to encourage Component Driven Design for your single page application.  In the simplest instance, components can be single purpose elements composed of a View, an optional Template, and CSS.  Or, as your application grows in complexity, your components will grow to encapsulate multiple smaller components.
+
+Good component design dictates that each component should only care about itself and not be aware of anything outside of it.  A good component provides a public API for working with everything inside of it.
+
+Luca provides a special type of View called 'Luca.Container` which is designed to faciliate the communication between multiple components.
+
+
+### Component Definition Registry
+
+The component definition style employed by Luca makes it easy to manage a registry of components in your application.  It provides more granular methods for definining the properties and methods on your component prototype.  In the end, everything
+gets put together and the component is defined just as you would define a standard Backbone component.
+
+In Luca, you can call Luca.View.extend just as you would Backbone.View.extend.  But doing so will bypass the component registry
+and a lot of the helpers in the framework that are designed to help you manage the complexity of your application as it grows.
+
+#### Step One: Defining a simple list component
+```
+list = App.register 		"App.views.BooksList"
+list.extends 				"Luca.CollectionView"
+
+list.defines
+  autoBindEventHandlers: true
+  events:
+    "click .book" : "selectBook"
+    
+  collection: "books"
+  itemTemplate: "book_listing"
+  itemClassName: "book"
+  
+  selectBook: (e)->
+    $element 	= $(e.target)
+    bookId   	= $element.data('model-id')
+    bookModel 	= @collection.get(bookId)
+    
+    @trigger "book:selected", bookModel, e
+     
+```
+
+#### Step Two: Defining a details view
+
+Below we will define another component.  The syntax below is optional, and is essentially the same as above, however we will take advantage of the more granular options available to us for the purpose of making our definition more readable.  Here we are explicit about our intent for the method `@renderBookDetails` by specifying it as public, any component which makes use of this knows that it will interact with the public interface.
+
+In addition to providing more readable code, these methods are used to automatically generate nice documentation for your components.
+
+```
+details = App.register 		"App.views.BookDetails"
+
+details.extends 			"Luca.View"
+
+
+details.publicMethods
+  renderBookDetails: (bookModel)->
+    @$el.html( Luca.template("book_details", bookModel))
+
+
+details.register() # the call to register is the same as defines() but is more readable on its own.
+```
+
+#### Step Three: Putting the components together 
+
+Now that we have defined two components, they can be used on their own or as members of a larger composite view.
+
+In the below example, we create a `Luca.Container` which contains the two components we defined above and facilitates
+communication between them by listening to the events they emit and passing them to interested parties.
+
+```
+browser = App.register 	"App.views.BooksBrowser"
+
+browser.extends 			"Luca.Container"
+
+component.defines
+  # This component will be unique, there will only ever be one instance of it.
+  # Other parts of our application will be able to access it by `App("books_browser")`
+  name: "books_browser"
+  
+  # Will be rendered with the `row-fluid` class on it. Enabling our subcomponents
+  # to add their own `span6` classes to position themselves in a bootstrap style grid.
+  rowFluid: true
+  
+  # faciliate the communication between our subcomponents by listening to the events
+  # they emit and routing them to interested parties.
+  componentEvents:
+    "list book:selected" : "viewBookDetails"
+     
+  components:
+    role: "list"
+	type: "books_list"
+	span: 3
+  ,
+    role: "details"
+    type: "book_details"
+    span: 9
+	
+ # This method will get called in response to the componentEvent binding that we declared.
+ # It will take the message and pass it to the component with the role `details`
+ viewBookDetails: (bookModel)->
+   @getDetails().renderBookDetails(bookModel)
+```
+
+#### A Note on the @type alias:
+
+Whenever you register a component using the style above, type aliases will be created for you.  `BookDetails` will be `book_details`, `BooksBrowser` will be `books_browser` and so on.  This allows you to compose containers by specifying a JSON object with strings, as opposed to manually instantiating the object yourself and having to type out the full name of the component every time. 
+
+#### Using your components
+
+The components we defined can be used in isolation, or as parts of other components. 
+
+We could simply render the BooksBrowser into the DOM directly:
+
+```
+  browser = new App.views.BooksBrowser()
+  $('body').html( browser.render().el )
+```
+
+Or include it in a page of our application:
+
+```
+  MyApp = new App.Application
+    routes:
+      "" : "books_browser"
+      "books/:title" : "books_browser#loadBook"
+    
+    collectionManager:
+      initialCollections:[
+        "books"
+      ]
+    
+    getCollection: (collectionName)->
+      @collectionManager.getOrCreate(collectionName)
+      
+  	components:[
+  	  name: "books_browser"
+  	  type: "books_browser"
+  	  loadBook: (title)->
+  	    bookModel = App().getCollection("books").findByTitle(title)
+  	    @viewBookDetails(bookModel)
+  	]
+```