luca 0.9.8 → 0.9.9

data/site/docs/application.html

@@ -1,41 +0,0 @@
-          <h1>Luca.Application</h1>
-<p>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.   
-
-</p>
-<p>Luca.Application is a type of Viewport class which handles things such as:
-
-</p>
-<ul>
-<li>collection manager ( manages your collections for you ) </li>
-<li>socket manager ( relays websocket events as Backbone.Events )</li>
-<li>url fragment router (<code>Backbone.Router</code>)</li>
-<li>global attributes and change event bindings</li>
-<li>page controller ( displays a unique page of the application) </li>
-<li>active view, active sub view helpers</li>
-</ul>
-<p>The Luca.Application stores its state in a <code>Backbone.Model</code>, which means you can <code>get()</code> and <code>set()</code> 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.
-
-</p>
-<p>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.
-
-</p>
-<pre><code class="lang-coffeescript">  _.def("MyView").extends("Luca.View").with
-    name: "my_view"
-
-    applicationEvents:
-      "change:status" : "onStatusChange"
-
-    onStatusChange: (app, currentStatus)-&gt;
-      if currentStatus is "inactive"
-        @markInactive()
-
-    markInactive: ()-&gt;
-      # 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")</code></pre>

data/site/docs/caching.html

@@ -1,43 +0,0 @@
-<h1>Method Caching and Computed Properties on Luca Collection and Model</h1>
-<p>The concept of computed properties ( on the model ) or cached methods ( on the collection )
-optimizes for cases where you call a method that performs calculations or some other operations
-whose value is dependent on the model and its underlying attributes.
-
-</p>
-<h2>Cached Methods on Luca.Collection</h2>
-<p>Luca provides a configuration API for Luca.Collection where you specify the method whose value
-you wish to cache, and the change events which get bubbled up from the models that would change
-the value, in essence expiring the cache.  In addition to change events, standard events on the
-collection for when a model is added or removed will expire the cached value.
-
-</p>
-<pre><code class="lang-coffeescript">  _.def("MyCollection").extends("Luca.Collection").with
-    name:"my_collection"
-
-    cachedMethods:[
-      "expensiveMethod:attributeOne,attributeTwo",
-      "anotherExpensiveMethod"
-    ] 
-
-    expensiveMethod: ()-&gt;
-      @map (model)-&gt; model.get('attributeOne') + model.getAttribute('two')
-
-    anotherExpensiveMethod: ()-&gt;
-      @map (model)-&gt; model.value()</code></pre>
-<p>In the example above, the expensiveMethod is dependent on the attributeOne and attributeTwo attributes
-on each of the models in the collection, therefor if any of these values change, the cache needs to be expired.
-
-</p>
-<p>the anotherExpensiveMethod call is not dependent on any specific values, so will only expire any time a new model
-is added or removed, or the collection is reset.
-
-</p>
-<h2>Computed Properties on Luca.Model</h2>
-<pre><code class="lang-coffeescript">  _.def("MyModel").extends("Luca.Model").with
-    computed:
-      "expensiveMethod" : ["dependencyOne","dependencyTwo"]
-
-    expensiveMethod: ()-&gt;
-      @get("dependencyOne") + @get("dependencyTwo")</code></pre>
-<p>In the example above, once expensiveMethod is called, its value will be cached and will be invalidated
-any time the dependencyOne or dependencyTwo attribute changes and triggers a change:dependencyTwo event.</p>

data/site/docs/collection.html

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

data/site/docs/collection_manager.html

@@ -1,71 +0,0 @@
-<h1>The Luca Collection Manager</h1>
-<p>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.
-
-</p>
-<p>You can use CollectionManager independently, or you will get one by default
-when you use a Luca.Application with the default configuration.
-
-</p>
-<p>A CollectionManager has a name property which is 'primary' by default.  If
-you call <code>Luca.CollectionManager.get()</code> 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.
-
-</p>
-<h2>Named Collections and Auto-Registering</h2>
-<p>You can configure your Luca.Collection classes to have their instances automatically
-register with the collection manager.  By specifying a <code>@name</code> property on your collection prototypes, they will automatically attempt to register with the running collection manager instance ( via <code>Luca.CollectionManager.get()</code> ) as soon as they are initialized.
-
-</p>
-<p>You can specify which manager you want a collection to register with by specifying a <code>@manager</code> 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.
-
-</p>
-<pre><code class="lang-coffeescript">  _.def("MyCollection").extends("Luca.Collection").with
-    name: "my_collection"
-    manager: "AppInstance.collectionManager"</code></pre>
-<h2>Private Collections</h2>
-<p>You may not always want to use the global, single authoritative instance of a collection.  In this case, you can specify a <code>@private</code> or <code>@anonymous</code> property on your collection, and it will skip registering with the collection manager.
-
-</p>
-<h2>Collection Class Naming</h2>
-<p>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.
-
-</p>
-<h2>Initial Collections</h2>
-<p>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.
-
-</p>
-<pre><code class="lang-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()</code></pre>
-<h2>Event Relaying</h2>
-<p>By default <code>@relayEvents</code> 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.  
-
-</p>
-<p>Event triggers will look like <code>collection_name event</code>:
-
-
-</p>
-<pre><code class="lang-coffeescript">  collection = new App.collections.SampleCollection([],name:"sample_collection")
-  manager = new Luca.CollectionManager(collectionNamespace:App.collections)
-
-  manager.on "sample_collection reset", ()=&gt; @doSomething() 
-
-  # will trigger 'reset' and call doSomething()
-  collection.fetch()</code></pre>

data/site/docs/containers.html

@@ -1,118 +0,0 @@
-       <h1>Container Views in Luca.js</h1>
-<p>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.
-
-</p>
-<p>The purpose of a Container is to faciliate the communication between the components.
-
-</p>
-<p>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.
-
-</p>
-<h2>Containers are meant to generate your structural DOM elements</h2>
-<p>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.  
-
-</p>
-<p>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.
-
-</p>
-<h2>Layout and Rendering Customization</h2>
-<p>The call to <code>render()</code> 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. 
-
-</p>
-<p>All render() methods on Luca.View are wrapped and will trigger <code>before:render</code> and <code>after:render</code> 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.
-
-</p>
-<p>The chain started by a call to <code>container.render()</code> is as follows:
-
-</p>
-<pre><code class="lang-coffeescript">  beforeRender()
-
-  # layout functions
-  @trigger "before:layout" # =&gt; or run beforeLayout() if it exists
-  @prepareLayout()
-  @trigger "after:layout" # =&gt; or run afterLayout() if it exists</code></pre>
-<p>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.
-
-</p>
-<p>It will put each DOM container elemement in a @componentContainers property on
-your container object.
-
-</p>
-<p>After prepareLayout is the components cycle:
-
-</p>
-<pre><code class="lang-coffeescript">  @trigger "before:components" # =&gt; or run beforeComponents() if it exists
-  @prepareComponents()
-  @createComponents()
-  @trigger "before:render:components"
-  @renderComponents()
-  @trigger "after:components" # =&gt; or run afterComponents() if it exists</code></pre>
-<h2>A Note on Container inheritance</h2>
-<p>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:
-
-</p>
-<pre><code class="lang-coffeescript">  _.def("MyContainer").extends("Luca.core.Container").with
-    prepareLayout: ()-&gt;
-      # 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()</code></pre>
-<h2>The <code>ctype</code> property</h2>
-<p>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.
-
-</p>
-<pre><code class="lang-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" 
-    ]</code></pre>
-<p>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.
-
-</p>
-<p>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.
-
-</p>
-<pre><code class="lang-coffeescript">  _.def("ContainerTwo").extends("Luca.core.Container").with
-    components:["component_one","component_two"]</code></pre>
-<h2>Convenience Methods on the Container</h2>
-<p>You have access to several methods which work on the components which belong to your views.  These methods are:
-
-</p>
-<ul>
-<li>pluck : plucks an attribute for each component</li>
-<li>invoke: invokes a method for each component</li>
-<li>each: run the passed iterator on eachComponent, recursively.  You can turn off the recursion by passing false as your second argument.</li>
-<li>indexOf: get the index of a component by it's name property</li>
-<li>selectByAttribute: selects all components whose attribute matches a given value</li>
-</ul>

data/site/docs/events.html

@@ -1,153 +0,0 @@
-
-          <h2>Event Binding Syntactic Sugar</h2>
-<p><code>Luca.Events</code> provides you with some additional event binding sugar.
-
-</p>
-<p><strong>once</strong>
-
-</p>
-<p><code>once</code> is how you would run one function in response to an event, but only once.
-
-</p>
-<pre><code class="lang-coffeescript">  view = new Luca.View()
-
-  view.once "event:gets:triggered", ()-&gt;
-    alert('sup baby')
-
-  view.trigger("event:gets:triggered")</code></pre>
-<p><strong>defer until</strong>
-
-</p>
-<p><code>defer</code> is similar to `once', but with syntax I like a little better:
-
-</p>
-<pre><code class="lang-coffeescript">  _.def("MyView").extends("Luca.View").with
-    initialize: ()-&gt;
-      @defer(@setup).until("event:gets:triggered")</code></pre>
-<p>If you want to defer a callback until an event gets triggered on some other object:
-
-</p>
-<pre><code class="lang-coffeescript">
-  _.def("MyView").extends("Luca.View").with
-
-    initialize:()-&gt;
-        @defer(@setup).until(@someObject,"triggers:an:event")
-
-    setup: ()-&gt;</code></pre>
-<h2>Component Bindings</h2>
-<p>Luca provides a number of configuration API for its components
-which facilitate the binding of a component's methods to events that
-occur on instances of the CollectionManager and Application objects. 
-
-</p>
-<p>For Luca.core.Container classes there is also a component events 
-binding API that allows you to declare in your container which events
-to listen for on that container's components  
-
-</p>
-<h2>Auto Context Binding For Event Handlers</h2>
-<p>By setting the @bindAllEvents property to true on your prototype definitions,
-all event handler methods on your view will automatically be bound to the context
-of the view.  
-
-</p>
-<pre><code class="lang-coffeescript">  _.def('MyApp.views.AutoBoundView').extends('Luca.View').with
-
-    bindAllEvents: true
-
-    events:
-      "click a.btn" : "clickHandler"
-      "click a.btn.btn-danger" : "dangerHandler"
-
-    initialize:()-&gt;
-      # You no longer need to do this
-      # if you want to have these handlers run
-      # in the context of this view
-      _.bindAll @, "clickHandler", "dangerHandler"</code></pre>
-<h2>Collection Manager Event Binding</h2>
-<p>Luca Applications which use the Luca.CollectionManager have the benefit of
-a declarative event binding syntax which allows you bind to events on collections
-by their name.  This saves you from having to create a reference to the collection
-in some method, and setup a callback binding.  By simply providing a @collectionEvents
-configuration property on your views, you can eliminate a lot of boilerplate in your components.
-
-</p>
-<p>The format of the @collectionEvents hash is a key which is made up of the collection's name and the event
-separated by a space, and either a function or a name of a method on your view.
-
-</p>
-<pre><code class="lang-coffeescript">  SamplesCollection = Backbone.Collection.extend
-    name: "samples"
-    url: "/api/v1/samples"
-
-  _.def("MyView").extends("Luca.View").with
-    # NOTE: you may omit this property and
-    # it will use Luca.CollectionManager.get() to 
-    # get the main instance.
-    collectionManager: "main"
-
-    collectionEvents:
-      "samples reset" : "samplesResetHandler"
-
-    samplesResetHandler: (collection)-&gt;
-      if collection.length &gt; 1
-        @doSomething()</code></pre>
-<h2>Application Event Binding</h2>
-<p>Similar to the CollectionManager event binding API, there is a similar API for binding to the global application
-object. Most applications will have a single application instance, that is either available on the global object
-or through a call to <code>Luca.getApplication()</code>.
-
-</p>
-<p>It is in the Application instance that global state tracking should occur.  Should your views want to respond to changes
-in global application state, you can provide an @applicationEvents configuration property. The format is a key value
-pair, where the key represents the event being triggered by the application, and the value is a name of a method on 
-your view or an anonymous function.
-
-</p>
-<pre><code class="lang-coffeescript">  App = new Luca.Application
-    name: "main"
-
-    defaultState:
-      currentMode: "solid"
-
-  _.def("AppBoundView").extends("Luca.View").with
-    # NOTE: you may omit this and it will use Luca.getApplication()
-    app: "main"
-
-    applicationEvents:
-      "change:currentMode" : "modeChangeHandler"
-
-    modeChangeHandler: ()-&gt;
-      @doSomething()</code></pre>
-<h2>Luca.core.Container Component Events</h2>
-<p>Containers are special views whose only purpose is to render multiple components in a specified configuration, and handle
-all of the communication between the components.  This is what allows Luca components to be extremely re-usable, because they
-never know about views that exist outside of them.
-
-</p>
-<p>By providing a @componentEvents configuration property on your container, you can bind to events on the components in your container
-and relay information about them to other members of the container. The format is a key value pair where the key is a string which
-contains the name of the component and the event it triggers, separated by a space.  The value is a name of a method on your view or an anonymous function.
-
-</p>
-<pre><code class="lang-coffeescript">  # ctype = component_one
-  _.def("ComponentOne").extends("Luca.View").with
-    name:"one"
-    eventHandler: ()-&gt;
-      @trigger "custom:event"
-
-  # ctype = component_two
-  _.def("ComponentTwo").extends("ComponentOne").with
-    name:"two"
-    eventHandler: ()-&gt;
-      @trigger "some:other:event"
-
-  _.def("MyContainer").extends("Luca.core.Container").with
-    components:["component_two","component_one"]
-    componentEvents:
-      "one custom:event" : "customEventHandler"
-
-    # when component named one fires an event
-    # we can handle it here, pass it to two, whatever
-    customEventHandler: ()-&gt;
-      Luca('two').eventHandler()</code></pre>