luca 0.9.2 → 0.9.4

data/site/docs/collection_manager.html

@@ -0,0 +1,71 @@
+<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

@@ -0,0 +1,118 @@
+       <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

@@ -0,0 +1,153 @@
+
+          <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>

data/site/docs/view.html

@@ -0,0 +1,128 @@
+<h1>Luca.View</h1>
+<p>The <code>Luca.View</code> class is the base class for Luca components. A number of patterns and optimizations that are helpful in your view classes have been extracted into the base class.
+
+</p>
+<h2>Hooks</h2>
+<p>The concept of hooks in Luca is that components can trigger events, and we can bind to them as normally, and that this is good.  However, where it is more useful or cleaner to just define methods that represent some part of the component lifecycle, we provide a configuration API for doing that.
+
+</p>
+<pre><code class="lang-coffeescript">  _.def("Luca.View").extends("Backbone.View").with
+    hooks:[
+      "after:initialize"   # =&gt; @afterInitialize
+      "before:render"      # =&gt; @beforeRender
+      "after:render"       # =&gt; @afterRender
+      "first:activation"   # =&gt; @firstActivation
+      "activation"         # =&gt; @activation
+      "deactivation"       # =&gt; @deactivation
+    ]</code></pre>
+<p>Any Luca.View which defines an <code>@afterInitialize</code> method, or a <code>@beforeRender</code> method, will automatically call that method when the corresponding event is triggered.  
+
+</p>
+<p><strong>Note on extending hook methods</strong>
+
+</p>
+<p>If you want to maintain the functionality of the component you are extending from, you will have to remember to call the prototype method like such:
+
+</p>
+<pre><code class="lang-coffeescript">  _.def("MyView").extends("Luca.View").with
+    beforeRender: ()-&gt;
+      @_super("beforeRender", @, arguments)
+
+      # or, if you prefer 
+      Luca.View::beforeRender?.apply(@, arguments)</code></pre>
+<h2>The @render() method</h2>
+<p>The default implementation of @render() simply appends the view's <code>@$el</code> to the DOM element represented by the <code>$(@container)</code> property on the view.
+
+</p>
+<p>Whatever method you choose to implement for your <code>@render()</code> call should behave similar to how the Backbone.View::render() expects, in that it should return an instance of the view.
+
+</p>
+<p>Additionally, the call to <code>@render()</code> will trigger <code>before:render</code> and <code>after:render</code> as which, on a Luca.View is configured as a hook.  So any <code>@beforeRender()</code> and <code>@afterRender()</code> method will get called as well, if they exist.
+
+</p>
+<h2>Before Render</h2>
+<p>Since in Luca, the actual render method just attaches the view to its container, setup related methods for building your view's content are best put in the <code>beforeRender()</code> method.  In addition to this, there are other options available for filling the content of the view, like <code>@bodyTemplate</code>.
+
+</p>
+<h2>Luca.template helper</h2>
+<p><code>Luca.template()</code> is a util function which allows you reference your client side template system.  It accepts a name of a template ( which, if not found, it will attempt to match one for you ) and an object of interpolations to pass to the template function
+
+</p>
+<p><code>Luca.available_templates()</code> is a util function, useful for debugging, to see which templates are available to you.
+
+</p>
+<h2>Configuration Options</h2>
+<ul>
+<li><p><code>@additionalClassNames</code> - an array of CSS classes to apply to the view's <code>@$el</code>.  This is helpful for inheritance of views.</p>
+</li>
+<li><p><code>@name</code> - Setting a name property on your view, will allow you to reference the instance of that view later.</p>
+</li>
+</ul>
+<pre><code class="lang-coffeescript">  view = new Luca.View(name:"my_view")
+
+  Luca("my_view") is view # =&gt; true</code></pre>
+<ul>
+<li><p><code>@wrapperClass</code> - automatically wraps the view with a div with this as the CSS class.</p>
+</li>
+<li><p><code>@bodyTemplate</code> - will apply the content of the template to your view </p>
+</li>
+<li><p><code>@bindAllEvents</code> - true or false automatically bind all event handler methods to the context of your view's instance</p>
+</li>
+<li><p><code>@applicationEvents</code> - configuration similar to the DOM <code>@events</code> configuration on Backbone.View.  Used to bind to events triggered by the <code>Luca.Application.get()</code> object.  You can customize which application you use by setting <code>@app</code> to either reference the app, or to the name of a given application.</p>
+</li>
+<li><p><code>@collectionEvents</code> - configuration similar to the DOM <code>@events</code> configuration on Backbone.View.  Used to bind to events triggered by the <code>Luca.CollectionManager.get()</code> object.  </p>
+</li>
+</ul>
+<h2>Luca.View::$bodyEl()</h2>
+<p>In your <code>Luca.View</code> definitions, If you set the <code>@bodyTemplate</code> property to one of the available templates, then on <code>initialize</code> the view will set the HTML of its DOM element to the contents of the template.
+
+</p>
+<p>This is useful in cases where there is a fair amount of structural, or otherwise static DOM content in your view, and one of the standard <code>Luca.core.Container</code> components is not suited for what you want to do.  The <code>Luca.components.Panel</code> view is basically just a <code>Luca.View</code> which has additional DOM containers for footers and headers.  It accomplishes this through the use of the <code>@bodyClassName</code> and <code>@bodyTagName</code> properties.  
+
+</p>
+<p><code>@bodyClassName</code> and <code>@bodyTagName</code> work the same way the <code>@className</code> and <code>@tagName</code> properties work on standard Backbone views.  They are used to create a DOM element via <code>Backbone.View.prototype.make(@bodyTagName,class:@bodyClassName,id:@bodyId</code> 
+
+</p>
+<p>If you use <code>view.$bodyEl()</code> instead of the standard <code>view.$el()</code> that ships with Backbone, all of the standard DOM manipulation methods available will be scoped to the CSS selector that corresponds to the actual body element of your view.
+
+</p>
+<h2>Deferrable Rendering</h2>
+<p>The jury is still out as to whether or not deferrable rendering is a useful pattern, or whether it is too complex. The use case it was trying to optimize is for views which can only be rendered in response to an event being fired on another object.  Such as <code>Backbone.Collection::fetch</code>.  
+
+</p>
+<p>If this is what you are doing, then this feature is for you.
+
+</p>
+<p>The options available for views which use the <code>@deferrable</code> property are as follows:
+
+</p>
+<ul>
+<li><code>@deferrable</code> - if you set a reference to an object, such as a collection, on the @deferrable property, then the call to <code>view.render()</code> will actually just set up an event binding to the <code>reset</code> event of your collection, and it will automatically call <code>fetch</code> for you on that collection.  </li>
+</ul>
+<p>If you set <code>@deferrable</code> to true then the view will expect a <code>@collection</code> property.
+
+</p>
+<ul>
+<li><p><code>@deferrable_method</code>  - a call to <code>@render()</code> on a <code>@deferrable</code> view will automatically call this method on the <code>@deferrable</code> object.</p>
+</li>
+<li><p><code>@deferrable_trigger</code> - if you use the deferrable system , by default, it will automatically call the <code>@deferrable_method</code> on your <code>@deferrable</code> object when you call <code>@render()</code>.  However, if you want to defer this method being fired even later, just set the <code>@deferrable_trigger</code> property to whatever trigger your view will listen for.</p>
+</li>
+</ul>
+<p>A useful example would be for views which get rendered hidden, and activated if and only if the user does a specific action.  ( For example, a TabView activating a secondary tab ).  If that action triggers an event, and you want to delay the render process if and only if that event is triggered.
+
+</p>
+<h2>Helpers</h2>
+<ul>
+<li><p><code>view.$template</code> calls <code>view.$.html()</code> on your view, with whatever is returned from the template.  Delegates to <code>Luca.template(templateName, customizationHash)</code></p>
+</li>
+<li><p><code>view.$wrap</code> the same as <code>view.$el.wrap()</code> -- accepts a CSS class name string, or a DOM element</p>
+</li>
+<li><p><code>view.$append</code> the same as <code>view.$el.append()</code></p>
+</li>
+<li><p><code>view.$container</code> - references <code>$( view.container )</code>.  Note: the @container property is set on a view when it belongs to the <code>@components</code> property of a <code>Luca.core.Container</code> instance.  It is just a standard CSS selector.</p>
+</li>
+<li><p><code>view.registerEvent()</code> manipulates your <code>@events</code> configuration on your Backbone.View and then calls <code>@delegateEvents</code> to make sure they are live.</p>
+</li>
+</ul>
+<h2>Backbone Component Helpers</h2>
+<p>Views which have properties on them referencing other views, models, or collections, can access those objects by calling <code>view.models()</code> or <code>view.views()</code> or <code>view.collections()</code>.  This is mainly useful for introspection, debugging, or what not.</p>