luca 0.9.2 → 0.9.4

data/assets/javascripts/sandbox/views/builder/component_list.coffee

@@ -0,0 +1,38 @@
+_.def("Sandbox.views.ComponentList").extends("Luca.components.CollectionView").with
+  name:                     "component_list"
+  id:                       "component_list"
+  collection:               "components"
+  itemTagName:              "div"
+  autoBindEventHandlers: true
+  events:
+    "click div.collection-item a" : "clickHandler"
+
+  itemRenderer: (item, model, index)->
+    Luca.util.make("a",{"data-index":index}, model.className() )
+
+  filterByName: (name)->
+    models = @collection.query
+      className:
+        $likeI:name
+
+    @collection.reset( models, silent: true )
+    @refresh()
+
+    if name?.length is 0 
+      @resetToDefault()
+
+  resetToDefault: ()->
+    @collection.reset( @initialComponents, silent: true )
+    @refresh()
+
+  beforeRender: ()->
+    success = (collection, response)=>
+      @initialComponents = response
+
+    @collection.fetch(success: success)  
+
+  clickHandler: (e)->
+    e.preventDefault()
+    me = my = $( e.target )
+    component = @collection.at( my.data('index') )
+    @trigger "selected", component

data/assets/javascripts/sandbox/views/builder/project_browser.coffee

@@ -0,0 +1,14 @@
+_.def("Sandbox.views.ProjectBrowser").extends("Luca.core.Container").with
+  className: "project-browser"
+  components:[
+    type: "text_field"
+    name: "component_list_filter"
+    additionalClassNames: "well"
+    className: "component-list-filter-form"
+    placeHolder: "Find a component"
+    hideLabel: true
+    prepend: "?"
+  ,
+    type: "component_list"
+    name: "component_list"
+  ]

data/assets/javascripts/sandbox/views/builder.coffee

@@ -0,0 +1,133 @@
+_.def("Sandbox.views.Builder").extends("Luca.core.Container").with
+  name: "builder"
+  id: "builder"
+  defaultCanvasPosition: 'below'
+  componentEvents:
+    "editor_container toggle:search:option" : "toggleSearchOption"
+
+  components:[
+    ctype: "container"
+    name:"editor_container"
+    additionalClassNames: 'row-fluid'
+    className: "builder-editor-container"
+    styles: 
+      position: "absolute"
+      
+    bottomToolbar:
+      buttons:[
+        group: true
+        align: "left"
+        buttons:[
+          eventId: "toggle:search:option"
+          icon:"search"
+          classes:"search-options component-search"
+        ,
+          eventId: "toggle:search:option"
+          icon: "list-alt"
+          classes: "search-options saved-components"
+        ]
+      ,
+        eventId:"toggle:settings"
+        icon: "cog"
+        align: 'right'
+      ]
+    components:[
+      ctype: "builder_editor"  
+      name: "builder_editor"
+      className:"builder-editor"
+      styles: 
+        position: "relative"
+        width: "100%"
+        top: "0"
+        left: "0"
+    ,
+      type: "project_browser"
+      className:"project-browser"
+      name: "project_browser"
+      styles: 
+        position: "relative"
+        width: "30%"
+        top: "0"
+        left: "0"
+    ]
+  ]
+
+  initialize: (@options={})->
+    Luca.core.Container::initialize.apply(@, arguments)
+
+    _.bindAll @, "toggleSearchOption"
+
+    canvas = type: "builder_canvas", className: "builder-canvas"
+
+    @state = new Backbone.Model
+      canvasLayout: "horizontal-split"  
+      canvasPosition: (@defaultCanvasPosition || "above")
+      ratio: 0.4
+
+    @state.bind "change:canvasLayout", ()=>
+      @$el.removeClass().addClass @state.get("canvasLayout")
+
+    if @state.get('canvasPosition') is "above"
+      @components.unshift( canvas )
+    else
+      @components.push( canvas )
+
+
+
+  canvas: ()-> 
+    Luca("builder_canvas")
+
+  editor: ()-> 
+    Luca("builder_editor")
+
+  componentList: ()-> 
+    Luca("component_list")
+
+  toggleSearchOption: (button)->
+    button.toggleClass('active')
+
+  # TODO
+  # Find a pure CSS solution this is garbage.
+  fitToScreen: ()->
+    @$el.addClass("canvas-position-#{ @state.get('canvasPosition') }")
+
+    viewportHeight = $(window).height()
+    half = viewportHeight * @state.get('ratio') 
+
+    toolbarHeight = 0
+    toolbarHeight += @$('.toolbar-container.top').height() * @$('.toolbar-container.top').length
+
+    filterHeight = 0
+    filterHeight += @$('.component-list-filter-form').height()
+
+    @canvas().$el.height( half - toolbarHeight - 40 )
+
+    @componentList().$el.height( half - filterHeight - 50 )
+
+    @editor().$el.height( half )
+    @editor().setHeight( half )
+
+  activation: ()->
+    @fitToScreen()
+
+  deactivation: ()->
+    # implement
+
+  afterRender: ()->
+    @_super "afterRender", @, arguments
+    componentList = Luca("component_list")
+    componentList.on "selected", (component)->
+      Luca("builder_editor").setValue( component.get('source') )
+      Luca("builder_editor").state.set('currentMode','coffeescript')
+
+    @$('.component-list-filter-form input[type="text"]').on "keydown", ()->
+      componentList.filterByName $(this).val()
+
+    @$('.component-list-filter-form input[type="text"]').on "keyup", ()->
+      val = $(this).val()
+      componentList.filterByName('') if val.length is 0
+
+  beforeRender: ()->
+    Luca.core.Container::beforeRender?.apply(@, arguments)
+    @$el.removeClass().addClass @state.get("canvasLayout")
+

data/assets/javascripts/sandbox/views/docs_controller.coffee

@@ -0,0 +1,7 @@
+_.def("Sandbox.views.DocsController").extends("Luca.components.Controller").with
+  name: "docs"
+  defaultCard: "docs_index"
+  components:[
+    name: "docs_index"
+    bodyTemplate: "sandbox/docs_index"
+  ]

data/assets/javascripts/sandbox/views/inspector/instance_filter.coffee

@@ -0,0 +1,18 @@
+_.def("Sandbox.views.InstanceFilter").extends("Luca.components.FormView").with
+  name: "instance_filter"
+  well: true
+  horizontal: true
+  inline: true
+  toolbar: false
+  components:[
+    ctype:"type_ahead_field"
+    label:"Find by name"
+    source: ()-> 
+      names = _( Luca.registry.instances() ).pluck('name')
+      _.uniq _( names ).compact()
+  ,
+    ctype: "type_ahead_field"
+    label: "Find by class"
+    source: ()->
+      Luca.registry.classes(true)
+  ]

data/assets/javascripts/sandbox/views/inspector.coffee

@@ -0,0 +1,11 @@
+_.def("Sandbox.views.ApplicationInspector").extends("Luca.tools.ApplicationInspector").with
+  name: "application_inspector"
+  additionalClassNames: ["modal"]
+
+  toggle:(options=backdrop:false)->
+    @render() unless @rendered is true
+    @$el.modal(options)
+
+  components:[
+    ctype:"instance_filter"
+  ]

data/assets/javascripts/sandbox.coffee

@@ -1,4 +1,6 @@
 #= require ./sandbox/config
+#= require_tree ./sandbox/models
+#= require_tree ./sandbox/collections
 #= require_tree ./sandbox/templates
 #= require_tree ./sandbox/views
 #= require ./sandbox/router

data/assets/stylesheets/luca-ui-full.css

@@ -0,0 +1,3 @@
+/*
+ *= require luca-ui-bootstrap.css
+*/

data/assets/stylesheets/sandbox/builder.scss

@@ -0,0 +1,79 @@
+#builder {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+
+  .project-browser-container {
+    margin: 0px; 
+    .component-list-filter-form.well {
+      padding: 4px;
+      input {
+        width: 80%;  
+      }
+      span.add-on {
+        cursor: pointer;
+      }    
+      .control-group {
+        padding: 0px;
+
+      }
+    }    
+
+    #component_list {
+      overflow: scroll;
+      height:100%;
+      .collection-item {
+        padding: 3px 0px 3px 4px;
+        cursor: pointer;
+      }
+    }
+  }
+
+  .builder-editor-container {
+    .builder-editor {
+      margin-left: 0px;
+    }
+    .CodeMirror {
+      font-size: 1.2em;
+      line-height: 1.5; 
+    }
+  }
+
+
+  .builder-canvas + .builder-editor {
+    position: fixed;
+    bottom: 0;
+    width: 100%;
+  }
+
+  .builder-canvas {
+    padding: 20px;  
+  }
+
+  .toolbar-container {
+    padding-right: 12px;
+
+    .luca-ui-toolbar.toolbar-bottom {
+      margin-top: 0px;
+    }
+    .luca-ui-toolbar.toolbar-top {
+      margin-bottom: 0px;
+    }
+ }
+}
+
+#builder.canvas-position-below {
+  .builder-editor {
+    border-bottom: 1px solid #999;  
+    -moz-box-shadow: 0px 0px 1px #333;
+    -webkit-box-shadow: 0px 0px 1px #333;
+    box-shadow: 0px 0px 1px #333;    
+  }
+}
+
+.project-browser {
+  width: 30%;
+  top: 0px;
+  left: 0px;
+}
+

data/assets/stylesheets/sandbox/sandbox.scss

@@ -1,4 +1,5 @@
-#viewport {
+
+.marketing-content {
   line-height: 1.5;
   color: #333;
 

data/docs/application.md

@@ -0,0 +1,41 @@
+# Luca.Application
+
+A large single-page app generally needs some sort of globally available state tracking object, as well as something which acts as a single entry point into the application, and some sort of gateway to important objects.   
+
+Luca.Application is a type of Viewport class which handles things such as:
+
+- collection manager ( manages your collections for you ) 
+- socket manager ( relays websocket events as Backbone.Events )
+- url fragment router (`Backbone.Router`)
+- global attributes and change event bindings
+- page controller ( displays a unique page of the application) 
+- active view, active sub view helpers
+
+The Luca.Application stores its state in a `Backbone.Model`, which means you can `get()` and `set()` attributes directly on the application, as well as bind to change events on the application itself, and expect the same API you would from a normal model.
+
+The ability to treat the Luca.Application instance as both a view, and a model allows for some clean patterns.  Your views can declaratively list its dependency on the global application state attributes.
+
+```coffeescript
+  _.def("MyView").extends("Luca.View").with
+    name: "my_view"
+
+    applicationEvents:
+      "change:status" : "onStatusChange"
+
+    onStatusChange: (app, currentStatus)->
+      if currentStatus is "inactive"
+        @markInactive()
+
+    markInactive: ()->
+      # mark this view inactive if the application
+      # goes into inactive status
+
+
+  app = Luca.getApplication()
+
+  # this will cause the view named 'my_view' to 
+  # to fire its markInactive() method
+  app.set("status", "inactive")
+
+
+```

data/docs/collection.md

@@ -0,0 +1,79 @@
+# Luca.Collection
+ 
+The `Luca.Collection` class is the base class for Luca components. A number of patterns and optimizations that are helpful in your collection classes have been extracted into the base class.
+
+## Backbone Query Integration
+
+Luca.Collection either extends from `Backbone.Collection`, or if it is available `Backbone.QueryCollection`.  The Query Collection was developed by [Dave Tonge](https://github.com/davidgtonge) and the project can be found on [Github](https://github.com/datapimp/backbone_query).  
+
+`Luca.Collections` which extend from `Backbone.QueryCollection` will have a query method which provides you with an API for filtering your collection's models with an API similar to [MongoDB](http://www.mongodb.org/display/DOCS/Advanced+Queries)
+
+## Bootstrapping your models on page load for performance
+
+A good habit for any single page application is to not populate all of your collections via remote calls to your RESTful API.  In a lot of cases it is better to put the data that needs to end up in your collections into the initial page load.
+
+Luca.Collection classes optimize for this pattern through the bootstrap functionality that is baked into the component.
+
+The bootstrap configuration for `Luca.Collection` classes depends on the collection being defined with a `@cache_key` property. `@cache_key` is either a function which returns a string, or a string, for simple cases.
+
+To make an array of objects available as models for a collection, either store the objects in `Luca.Collection._bootstrapped_models` on a property matching the value of `@cache_key` or use the `Luca.Collection.cache()` method like such:
+
+```html
+  <body>
+    <script type="text/javascript">
+       Luca.Collection.cache("books",[{author:"Jonathan Soeder"}]
+    </script>
+```
+
+This will work with the following collection:
+
+```coffeescript
+  _.def("BooksCollection").extends("Luca.Collection").with
+    name:"books"
+    cache_key: "books"
+```
+
+Any calls to `(new BooksCollection()).fetch()` will look in the cached models first, and avoid an API call.
+
+If you want to refresh the BooksCollection from your API, just pass in an options hash like such:
+
+```coffeescript
+	booksCollection.fetch(refresh:true)
+```
+
+## Base Params for RESTful API
+
+There are a lot of cases where you need every API call to pass along the same parameters ( authentication_tokens, keys, etc )
+
+`Luca.Collection` will wrap the `@url` property or method with a function which appends the base parameters as an HTTP Query Parameter string.
+
+```coffeescript
+  _.def("BooksCollection").extends("Luca.Collection").with
+    name: "books"
+    url: "/api/v1/books"
+  
+  app = Luca.getApplication()
+  
+  app.on "authenticated", ()->
+    Luca.Collection.baseParams = 
+      auth_token: app.get("authentication_token")
+      
+  app.collection("books").url() # => "/api/v1/books?auth_token=123456"
+
+```
+
+## onceLoaded and ifLoaded helpers
+
+There are cases where you want to do something on a collection if it has data, but if it doesn't, you need to fetch that data, and bind a callback to the reset event.  This can get tedious.
+
+Passing a callback to `collection.ifLoaded(callback)` will eliminate the boilerplate in this pattern.
+
+If you only want the callback to run once, use `collection.onceLoaded()`.
+
+In either of these methods, if you don't watch to automatically call `@fetch()` on the collection, pass an autoFetch option set to false
+
+```
+  app.collection("books").ifLoaded ()->
+    @doSomething()
+  , autoFetch: false
+```

data/docs/collection_manager.md

@@ -0,0 +1,76 @@
+# The Luca Collection Manager
+
+The CollectionManager is a single instance which acts as a gateway to 
+the instances of Luca.Collection created in your app.  The intention is
+to provide a central place for creating one, and only one instance of a 
+given collection type.
+
+You can use CollectionManager independently, or you will get one by default
+when you use a Luca.Application with the default configuration.
+
+A CollectionManager has a name property which is 'primary' by default.  If
+you call `Luca.CollectionManager.get()` it will return the CollectionManager
+named 'primary' or the first one ever created.  Attempting to create an additional
+CollectionManager instance with a name that is already used, will throw an error.
+
+## Named Collections and Auto-Registering 
+
+You can configure your Luca.Collection classes to have their instances automatically
+register with the collection manager.  By specifying a `@name` property on your collection prototypes, they will automatically attempt to register with the running collection manager instance ( via `Luca.CollectionManager.get()` ) as soon as they are initialized.
+
+You can specify which manager you want a collection to register with by specifying a `@manager` property on your collection.  This can either be a string, which will get resolved when needed to a variable, or a direct reference to the collection manager.  The string is useful since, when declaring your Luca.Collection prototypes, the collection manager will most likely not be instantiated.
+
+```coffeescript
+  _.def("MyCollection").extends("Luca.Collection").with
+    name: "my_collection"
+    manager: "AppInstance.collectionManager"
+```
+
+## Private Collections
+
+You may not always want to use the global, single authoritative instance of a collection.  In this case, you can specify a `@private` or `@anonymous` property on your collection, and it will skip registering with the collection manager.
+
+## Collection Class Naming
+
+Your custom Luca.Collection classes get named like MyApp.collections.SampleCollection. Through some string magic "SampleCollection" will get turned into "sample_collection".  If you try to call collectionManager.getOrCreate("sample_collection") it will attempt to get a collection named "sample_collection", and if it fails, will create a new instance of MyApp.collections.SampleCollection.  If you want to force your CollectionManager to look in a specific namespace, set a reference to MyApp.collections on Luca.Collection.namespace, otherwise it will look in all of the namespaces it knows about in the Luca.registry and find an appropriate collection.
+
+## Initial Collections
+
+The CollectionManager can be configured with an @initialCollections property, which is an array of names of collection classes, similar to "sample_collection", or actual references to Collection Classes, or strings with their names. The CollectionManager will create instances of the collection for you, and call fetch() on all of them.
+
+```coffeescript
+  _.def("App.collections.SampleCollection").extends("Luca.Collection").with
+    name: "sample_collection"
+
+  _.def("App.collections.ExampleCollection").extends("Luca.Collection").with
+    name: "example_collection"
+
+  class App.CollectionManager extends Luca.CollectionManager
+    initialCollections:[
+      "sample_collection"
+      "example_collection"
+    ]
+
+  # this will create instances of both of the above collections
+  # and call fetch() on all of them
+  collectionManager = new App.CollectionManager()
+```
+
+## Event Relaying
+
+By default `@relayEvents` is set to true on the CollectionManager.  This means that
+any event that is triggered by a collection that is managed by the collection manager will be bubbled up to the manager.  This feature is used by the collectionEvents configuration API used by Luca.View, but can also be used in custom situations as well.  Simply bind to the CollectionManager instance.  
+
+Event triggers will look like `collection_name event`:
+
+
+```coffeescript
+  collection = new App.collections.SampleCollection([],name:"sample_collection")
+  manager = new Luca.CollectionManager(collectionNamespace:App.collections)
+
+  manager.on "sample_collection reset", ()=> @doSomething() 
+
+  # will trigger 'reset' and call doSomething()
+  collection.fetch() 
+```
+

data/docs/container_philosophy.md

@@ -0,0 +1,122 @@
+# Container Views in Luca.js
+
+Containers are types of views which are made up of one or more components.  A component
+is simply another Backbone.View, Luca.View, or one of their descendants.
+
+The purpose of a Container is to faciliate the communication between the components.
+
+The classic example is a FormView.  A FormView is a component which inherits from
+Luca.core.Container and is made up of many Field components, and facilitates the communication between 
+the fields and a Backbone.Model.  The internal implementation of the model and field classes should never know 
+or reference any other component.  This is the job of the FormView.
+
+## Containers are meant to generate your structural DOM elements
+
+Containers generate the structural DOM elements which wrap the individual components, and the container renders these components to the DOM element
+that is assigned to it.  The various types of containers you use will each
+have their own internal logic for the way these DOM elements are laid out, displayed, hidden, showed, etc.  
+
+For example, a ColumnView will show two components side by side and assign
+each one to its own DIV element and use css to lay those columns out as configured.
+A CardView will assign each component to a DIV element, show the active card, and hide the rest.
+
+## Layout and Rendering Customization
+
+The call to `render()` on a container will start a rendering chain on all of the nested components.  You can customize this to your hearts content by tapping into
+the method chain. 
+
+All render() methods on Luca.View are wrapped and will trigger `before:render` and `after:render` events, as well as call any beforeRender or afterRender methods defined on your component. For more about this, see the section about hooks on Luca.View.
+
+The chain started by a call to `container.render()` is as follows:
+
+```coffeescript
+  beforeRender()
+
+  # layout functions
+  @trigger "before:layout" # => or run beforeLayout() if it exists
+  @prepareLayout()
+  @trigger "after:layout" # => or run afterLayout() if it exists
+
+```
+
+prepareLayout is an internal method on Luca.core.Container which will iterate
+over each of your components and call applyDOMconfig passing your components
+configuration to this function.  This will create a DOM element and apply
+any configured inline style declarations, assign a DOM id, css class, as well
+as some data attributes to the element.
+
+It will put each DOM container elemement in a @componentContainers property on
+your container object.
+
+After prepareLayout is the components cycle:
+
+```coffeescript
+  @trigger "before:components" # => or run beforeComponents() if it exists
+  @prepareComponents()
+  @createComponents()
+  @trigger "before:render:components"
+  @renderComponents()
+  @trigger "after:components" # => or run afterComponents() if it exists
+```
+
+## A Note on Container inheritance
+
+If you end up customizing the methods above in the render chain, you may
+want to call the same method on the component you are inheriting from.  Luca
+provides some syntactic sugar for this:
+
+```coffeescript
+  _.def("MyContainer").extends("Luca.core.Container").with
+    prepareLayout: ()->
+      # This is the normal way you would do this
+      Luca.core.Container::prepareLayout.apply(@, arguments)
+
+      # This is the sugary version which you get if you
+      # use the _.def or Luca.define method for declaring
+      # your prototype definitions
+      @_super("prepareLayout", @, arguments)
+
+      @applyMyOwnLayoutCustomizations()
+```
+
+## The `ctype` property
+
+Every Luca.View which gets registered through the Luca.registry will have a ctype value associated with it. The
+ctype property is used when adding components to a Container.
+
+```coffeescript
+  _.def("ComponentOne").extends("Luca.View").with()
+
+  _.def("ComponentTwo").extends("Luca.View").with()
+
+  _.def("ContainerOne").extends("Luca.core.Container").with
+    components:[
+      ctype: "component_one"
+      overriddenValue: "customValue"
+    ,
+      ctype: "component_two"
+      thisGetsPassedToInitialize: "yep" 
+    ]
+```
+
+In the above example, a View class of ContainerOne will be available, and
+any time you create an instance of it and call render on it, it will create
+instances of ComponentOne and ComponentTwo.
+
+Note, if you do not need to customize any of the properties on the component
+views, you can just pass an array of ctype strings.
+
+```coffeescript
+  _.def("ContainerTwo").extends("Luca.core.Container").with
+    components:["component_one","component_two"]
+```
+
+## Convenience Methods on the Container
+
+You have access to several methods which work on the components which belong to your views.  These methods are:
+
+- pluck : plucks an attribute for each component
+- invoke: invokes a method for each component
+- each: run the passed iterator on eachComponent, recursively.  You can turn off the recursion by passing false as your second argument.
+- indexOf: get the index of a component by it's name property
+- selectByAttribute: selects all components whose attribute matches a given value