lanes 0.0.5 → 0.0.8

data/docs/todo-example-part-1.md

@@ -0,0 +1,71 @@
+---
+title: TODO MVC Example
+position_after: command
+---
+
+As is required by all new frameworks, this is an example of creating a TODO application using the Lanes framework.
+
+First install Lanes via Rubygems.  `gem install lanes`
+
+As always when using Lanes, the first thing you'll need to do is generate your application.  We will name this app simply as `todo`
+
+{% highlight bash %}
+lanes new todo
+{% endhighlight %}
+
+This will create a new directory with a skeleton Lanes application.  Read more about the directories and what their purposes are at {% doc_link command heading:'lanes new' %}.
+
+[Our example app at this point](https://github.com/argosity/lanes-todo-demo/tree/2d649b314a826cbbdbf54e3f72041caeeee8e428)
+
+# Setup
+
+A sample database configuration file is located in `config/database.yml` which will use a postgresql database named todo_dev.  For the purposes of this example, we'll just create a new postgresql database that matches the configuration: `createdb todo_dev`
+
+Fire up the lanes testing server: `lanes serve`.  The test server will start the app and you can view it at: `http://localhost:8888/`.   You should see a simple "Todo" message.  You can also view the Jasmine specs at `http://localhost:8888/spec`
+
+We'll copy the styles from the [TodoMVC template](https://github.com/tastejs/todomvc/tree/master/template).
+
+Looking at the Todo app, it has four distinct areas. A `sidebar`, `header`, `footer` and `listing` views. We can create views for them by executing `lanes generate view <name>`, where '< name >' is the view to create. [commit](https://github.com/argosity/lanes-todo-demo/commit/758d0e63359db18ee0291467656454c9fc1c3573)
+
+First we take the TodoMVC html template and break it apart into sections and copy them to each view.  We're then able to plug each view's reference into the Screen as subviews. [commit](https://github.com/argosity/lanes-todo-demo/commit/8c5178a76f2a8abc0ffadbafb1239f7a8ba113b9)
+
+Next we'll create a data model `lanes generate model task title:string{80} completed:boolean` [commit](https://github.com/argosity/lanes-todo-demo/commit/5080c286aa4fb35a2b8372cc86ca4e9e18a18c3f)
+
+Since a task should default to being non-completed, we'll edit the migration to default that field to `false` and add a validation to the model [commit](https://github.com/argosity/lanes-todo-demo/commit/e3f7edf9f2863f0669cccac13f7f8e2b88276b5a)
+
+Run migration: `lanes db migrate`
+
+We'll also create a TaskSummary model that is in charge of summarizing the state of the tasks.  It will listen to the tasks collection and perform calculations when events occur. [commit](https://github.com/argosity/lanes-todo-demo/commit/65da191ee749ab749855e06ce69c3bd09662e0d5)
+
+# Data and events
+
+## Header View
+It's responsible for interaction with the "What needs to be done?" input.  When text is present and the "enter" key is pressed, it should save a record and add it to the collection.  We're able to do so in [just a few lines of code](https://github.com/argosity/lanes-todo-demo/blob/master/client/todo/views/Header.coffee#L22-L25)
+
+We can easily test that it performs as it should by [adding a few specs](https://github.com/argosity/lanes-todo-demo/blob/master/spec/todo/views/HeaderSpec.coffee#L18-L29). 
+
+## Listing View
+This view is a bit more complex.  It has a parent view which handles toggling all todo's between being complete and pending, and a collection of subviews that model each individual task. [ListingView](https://github.com/argosity/lanes-todo-demo/blob/master/client/todo/views/Listing.coffee)
+
+Each TaskView is responsible for handling it's own editing state and saving value to it's model.
+
+## Footer View
+The only action this view takes is to delete any tasks that are marked as complete when the "Clear Completed" button is clicked.  It also displays quite a few values from our TasksSummary.  Lane's declarative bindings make these easy to wire up. [FooterView](https://github.com/argosity/lanes-todo-demo/blob/master/client/todo/views/Footer.coffee)
+
+You might notice that Lanes makes it super easy to batch update or delete a collection.  The footer simply calls destroyAll on the "completed" sub-collection provided by the TaskSummary.  Since that sub-collection filters the main collection to only contain "completed" tasks, it's safe to just destroy all the model's in one go.  It's so easy in fact that the FooterView demonstrates an alternative use of events.  The function is directly given to the "events" property, rather than a method reference. [Save Call](https://github.com/argosity/lanes-todo-demo/blob/master/client/todo/views/Footer.coffee#L27)
+
+# Routing
+
+For a simple app like the this one, it's easiest to just allow the URL change to trigger what the filtered collection is displaying.  We set that up when the screen is initialized. [Routing](https://github.com/argosity/lanes-todo-demo/blob/master/client/todo/Router.coffee)
+
+# Deploying
+
+For the example we'll host it on Heroku.  Other deployments should be similar to deploying a Rails application.
+
+Simply commit the source and add a remote per Heroku's instructions: [https://devcenter.heroku.com/articles/git](https://devcenter.heroku.com/articles/git)
+
+When you `git push heroku`, Heroku will notice that Lanes uses sprockets and will automatically run `rake assets:precompile`, and then run the application using the puma webserver.
+
+On first deploy and when your db schema has changed, you will have to provision and migrate the database on Heroku by running: `heroku run rake db:migrate`
+
+

data/docs/view.md

@@ -0,0 +1,275 @@
+---
+title: View
+heading: Lanes.Data.View
+---
+
+Lanes provides a Lanes.Views.Base class that all other views extend from.
+
+In their simplest form, a view simply renders a string into a DOM element. They provide a mediating interface between data and the DOM.
+
+Since both Models, Collections, and the DOM emit events, a view's job is to listen to the events and then manipulate the other parties data structures.
+
+Lanes' base view provides numerous hooks and helper functions to make the process of responding to events and relaying them easier.
+
+Views can also be nested inside other views and will bubble relevant events up to thier parent views.
+
+Views inherit from [Ampersand State](http://ampersandjs.com/docs#ampersand-state), and therefore support all the same methods and declarations that it does.
+
+<aside>
+Unlike Backbone.js, when the view is rendered the old el (if present)
+is discared and an new one is created at the same point in the DOM.
+This prevents the doubly nested divs issue that Backbone experiences,
+but can be suprising behaviour for those who aren't expecting it.
+</aside>
+
+### API Reference
+
+# initialize
+
+`new View({options})`
+
+Called by the constructor after the view is initialized.  initialize can be used by your views for performing initialization of the class.
+
+Views have several options that will be copied to the view if they are given to initialize. Those options and their types are el (element), model (state), collection (collection), pubSub (boolean), parent (object), subviewId (string).
+
+``` coffee
+
+class MyView extends Lanes.Views.Base
+
+    initialize: (options)->
+        this.magic = options.answer
+
+view = new MyView( answer: 42 )
+# view.magic => 42
+
+```
+
+# source
+
+The "source" property is a way for Lanes to detect where the view was loaded from. When Lanes sets up a new class it sets it to the "magic" FILE variable.  Lanes Coffeescript pre-processor will set the FILE to the proper values for each file.  The Base View uses the information contained in source to auto-load views and models from the correct location.
+
+# el
+
+A reference to a DOM element that is controlled by the view.
+
+All views have a single DOM element.  If a view does is not provided an el when it's created, it will construct one when the render method is called.
+
+# template
+
+Either an string or a function that returns a string.  The string can be either a path to a pre-compiled template, or a HTML string.
+
+
+``` coffee
+class MyView extends Lanes.Views.Base
+    template: "<div><p>Hello World</p></div>"
+
+view = new MyView
+view.render()
+
+# view.el.innerHTML => <div><p>Hello World</p></div>
+```
+
+
+
+``` coffee
+class MyView extends Lanes.Views.Base
+    template: "views/myview"
+
+view = new MyView
+# attempt to render a template from path "views/myview"
+view.render()
+```
+
+
+``` coffee
+# Contained in file MyView.coffee
+
+class MyApp.Views.MyView extends Lanes.Views.Base
+    source: FILE
+
+view = new MyView
+# will use the "source" information to render
+# a template from "myapp/views/my_view"
+view.render()
+```
+
+# templateName
+
+A string (or function that returns one) that contains the name of a template.  The template will be loaded from the same path but using the templateName instead of one with the same name as the file.
+
+``` coffee
+class MyApp.Views.MyView extends Lanes.Views.Base
+    source: FILE
+    templateName: "contents"
+
+view = new MyView
+# will use the "source" information to render
+# a template from "myapp/views/contents"
+view.render()
+```
+
+# subviews
+
+Subviews are View classes that should be rendered at a given point on the DOM once conditions are met.
+
+In order for a subview to render, the parent's el must have a valid reference to the DOM element to render the subview into, as well as all data for the subview being present.
+
+When Subviews are created they are passed the parent view and any other options that were specified.
+
+Definitions for subviews apre specified using:
+
+ * A "view" or "component" key, given either as a class or a string that contains the keypath to the object.
+ * Either a "container" or "hook" reference.  If one is not given, it will default to a hook with the same name as the subview reference.  For instace the "heading" subview below will default to `data-hook="heading"`
+ * A model or collection reference.  If a collection reference is given, the collection will render using a collectionView.
+ * Options.  Either a object, a function, or a reference to a class method to call.
+
+
+``` coffee
+class MyApp.Views.MyView extends Lanes.Views.Base
+    subviews:
+        heading:
+            view: MyApp.WeirdNamespace.Heading
+            model: 'model.person'
+            options: {uppercase: true}
+        grid:
+            component: "Grid"
+            container: 'div.grid'
+            options: 'gridOptions'
+        names:
+            view: "NamesItem"
+            container: "div.names"
+            collection: 'collection'
+    gridOptions: -> { count: this.count() }
+    template: "<div>
+           <div data-hook='heading'></div>
+           <div data-hook='finder'></div>
+           <div class='grid'></div>
+           <div class='names'></div>
+        </div>"
+```            
+
+Notes:
+
+ * **heading**
+    * Is specified as a class object.  `MyApp.WeirdNamespace.Heading` must be defined prior to the file being read and should be a "view like" object.
+    * It's model will be set to the value from `model.person`, and it will not be rendered until `model.person` is set to a truthy value.
+    * When the view is created it will be passed `{uppercase: true}` as it's options.
+    * No `selector` or `hook` was provided.  It will default to rendering to `data-hook="heading"`
+ * **grid**
+   * is using a component named "Grid".  When the subview is ready to be created, Lanes will look for a class in the "Components" namespace: `Lanes.Components.Grid`
+   * Will render to the "div.grid" element.
+   * It's options will be set from the value returned by calling the `gridOptions` method.
+ * **names**
+   * Since the "view" is given as a simple string, Lanes will search for it in the MyApp namespace, and will expect `MyApp.Views.NamesItem` to be defined
+   * A collection is specified.  A collectionView will be created and the NamesItem class given as the child view to the collectionView.  The collectionView will then handle rendering the collection whenever it has items added/removed.
+   
+
+# subviewOptions(name,def)
+
+When subviews are created, they are initialized with an options object containing the parent view, and any other options that are returned by the `subviewOptions` method.
+
+The base view's implementation simply returns any options that were given on the subview's definition.
+
+Other views may override this method as a convienct way to specify the same options for all subviews.
+
+In the below example, each of the subviews will be initialied with:
+`{ parent: (MyView instance), model: (MyView instance).model, status: "red"}`
+
+
+``` coffee
+class MyApp.Views.MyView extends Lanes.Views.Base
+    subviews:
+        heading:
+            view: 'Heading'
+        footer:
+            view: 'Footer'
+    subviewOptions: ->
+        {model: @model, status: "red"}
+
+```
+
+
+
+# events
+
+Listens for DOM events that occur within the view _(under it's el)_.  Events are specified as a
+ hash containing "event selector" for the key and either a name of a method or function for the value.
+
+If the selector is ommited, the event will be bound to the root element.
+
+
+``` coffee
+class MyApp.Views.MyView extends Lanes.Views.Base
+    template: "<div><a class='title'>click me!</a></div>"
+    events:
+        "click .title": "onTitleClick"
+        "click": -> console.log("I feel like I was clicked somewhere")
+    onTitleClick: ->
+        console.log "Title Was Clicked!"
+```
+
+# ui
+
+A View will often need to access a given DOM element repeatedly.  By specifying a the elements as part of the UI property, they will be cached when the view is rendered for speedy access.
+
+Additionally elements cached in the UI can be refered to in bindings as a convience.
+
+
+``` coffee
+class MyApp.Views.MyView extends Lanes.Views.Base
+    ui:
+        title: "a.title"
+    template: "<div><a class='title'>click me!</a></div>"
+    events:
+        "click @ui.title": "onTitleClick"
+    onTitleClick: ->
+        console.log "Title Was Clicked!"
+    performOperation: ->
+        this.ui.title.hide()
+        runOperation()
+        this.ui.title.show()
+```
+
+### _Note:_ UI elements are not accessible until the view is rendered.
+
+# query(selector)
+
+Returns a single element based on CSS selector scoped to this.el
+if you pass an empty string it return `this.el`.
+
+Is more efficient that using the `$` method which calls out to jQuery
+
+``` coffee
+class MyView extends Lanes.Views.Base
+    template: "<div><a class='title'>click me!</a></div>"
+
+view = new MyView
+view.render()
+# get the first element the class "title"
+view.query('.title').click()
+```
+
+# $(selector)
+
+The same as `query`, but uses jQuery to find the selection, and may return more than just one
+element.  Is essentially just a shortcut to running $el.find.  It runs queries scoped within the view's element.
+
+``` coffee
+class MyView extends Lanes.Views.Base
+    template: "<div><a class='title'>click me!</a></div>"
+
+view = new MyView
+view.render()
+# get the first element the class "title"
+view.$('.title').click()
+```
+
+# parentScreen()
+
+Walks up the parent chain, attempting to find a screen.  If it's found once is returned, otherwise returns null.
+
+It's sometimes useful to relay events up to a level where the user can make note of them.  This method provides a way to obtain a reference to the owning screen.
+
+# remove()
+
+Recursively calls remove() on all subviews, than removes itself form the DOM and unbinds all event listeners.

data/lanes.gemspec

@@ -41,13 +41,15 @@ Gem::Specification.new do |spec|
     spec.add_dependency "hashie",                 "~> 3.3"
     spec.add_dependency "rack-test",              "~> 0.6"
     spec.add_dependency "minitest-around",        "~> 0.2"
+    spec.add_dependency "mocha",                  "~> 1.1"
     spec.add_dependency "guard-minitest",         "~> 2.3"
     spec.add_dependency "yui-compressor",         "~> 0.12"
+    spec.add_dependency "closure-compiler",       "~> 1.1"
     spec.add_dependency "guard-jasmine",          "~> 2.0"
     spec.add_dependency "rake",                   "~> 10.0"
     spec.add_dependency "jasmine-core",           "~> 2.0"
     spec.add_dependency "require_all",            "~> 1.3"
-
+    spec.add_dependency "sanitize",               "~> 3.0"
     spec.add_development_dependency "bundler",    "~> 1.5"
     spec.add_development_dependency "growl",      "~> 1.0"
     spec.add_development_dependency "pry-byebug", "~> 2.0"

data/lib/lanes/api/helper_methods.rb

@@ -3,6 +3,14 @@ module Lanes
 
         module HelperMethods
 
+            def lanes_javascript_tag
+                javascript_tag( Extensions.require_workspace? ? 'lanes/workspace' : 'lanes/minimal' )
+            end
+
+            def lanes_stylesheet_tag
+                stylesheet_tag( Extensions.require_workspace? ? 'lanes/workspace' : 'lanes/minimal' )
+            end
+            
             def client_bootstrap_data
                 Oj.dump(Extensions.client_bootstrap_data(self), mode: :compat)
             end

data/lib/lanes/api/javascript_processor.rb

@@ -20,19 +20,23 @@ module Lanes
             end
 
             def wrap_js(scope, js)
-                ns  = namespace(scope)
+                dirs = scope.logical_path.split(File::SEPARATOR)
+                ns   = dirs.many? ? dirs.first.camelize : nil
+                file = dirs.last
+                # if the file is being loaded under the "lanes" directory
+                # it's not an extension
                 if ns && ns != "Lanes"
                     ref = "(window.Lanes ? window.Lanes['#{ns}'] : null)"
-                    "(function(Lanes, #{ns}, NAMESPACE, _, window, undefined) {\n#{js}\n})(window.Lanes, #{ref}, {ref:#{ref},name:'#{ns}'}, window._, window);"
+                    "(function(Lanes, #{ns}, _, window, FILE, undefined)"\
+                      "{\n#{js}\n})(window.Lanes,#{ref},window._, window,"\
+                      "{namespace:#{ref},extension:'#{ns}',file:'#{file}'});"
                 else
-                    "(function(Lanes, NAMESPACE, _, window, undefined) {\n#{js}\n})(window.Lanes, {ref:window.Lanes,name:'Lanes'}, window._, window);"
+                    "(function(Lanes, _, window, FILE, undefined)"\
+                      "{\n#{js}\n})(window.Lanes,window._, window,"\
+                      "{namespace:window.Lanes,extension:'Lanes',file:'#{file}'});"
                 end
             end
 
-            def namespace(scope)
-                dirs = scope.logical_path.split(File::SEPARATOR)
-                return dirs.many? ? dirs.first.camelize : nil
-            end
         end
 
         class CoffeeScriptWrapper < JsAssetCompiler
@@ -41,10 +45,10 @@ module Lanes
             CONSTRUCTOR = /constructor\s*:/
             EXTENDING_CLASS = /class\s+([\w|\.]+)\s+extends\s+([\w|\.]+)\s*?\n/
 
-            # Coffeescript has two shortcomings with regards to Ampersandjs
+            # Coffeescript has two shortcomings with regards to Lanes
             #
-            # The first is that it's extends format is incompatible with Ampersandjs,
-            # Ampersandjs does quite a bit more via it's own .extend methods.
+            # The first is that it's extends format is incompatible with AmpersandState,
+            # State does quite a bit more via it's own .extend methods.
             # Accordingly, we substitute our own "extend" call whenever we encounter a coffeescript extends
             #
             # The second issue is that if a constructor isn't present, coffeescript with generate it's own

data/lib/lanes/api/pub_sub.rb

@@ -1,9 +1,3 @@
-require "oj"
-
-require_relative "updates"
-
-require 'message_bus'
-
 module Lanes
     module API
 
@@ -13,7 +7,13 @@ module Lanes
                 MessageBus.publish channel, data #Oj.dump(data, mode: :compat)
             end
 
-            def self.initialize
+            def self.initialize(api)
+                return unless Extensions.require_pub_sub?
+                require "oj"
+                require_relative "updates"
+                require 'message_bus'
+                api.use MessageBus::Rack::Middleware
+
                 # Use OJ - it encodes dates properly as ISO 8601
                 # https://github.com/moment/moment/issues/1407
                 Oj.mimic_JSON()