initial commit

Author: ryanstout

.gitignore

@@ -0,0 +1,2 @@
+_book
+.DS_Store

README.md

@@ -0,0 +1,17 @@
+# Introduction
+
+Volt is a Ruby web framework where your ruby code runs on both the server and the client (via [opal](https://github.com/opal/opal)).  The DOM automatically updates as the user interacts with the page. Page state can be stored in the URL. If the user hits a URL directly, the HTML will first be rendered on the server for faster load times and easier indexing by search engines.
+
+Instead of syncing data between the client and server via HTTP, Volt uses a persistent connection between the client and server. When data is updated on one client, it is updated in the database and any other listening clients (with almost no setup code needed).
+
+Pages HTML is written in a template language where you can put ruby between ```{{``` and ```}}```.  Volt uses data flow/reactive programming to automatically and intelligently propagate changes to the DOM (or any other code wanting to know when a value updates).  When something in the DOM changes, Volt intelligently updates only the nodes that need to be changed.
+
+See some demo videos here:
+** Note: These videos are outdated, new videos coming tomorrow.
+ - [Volt Todos Example](https://www.youtube.com/watch?v=6ZIvs0oKnYs)
+ - [Build a Blog with Volt](https://www.youtube.com/watch?v=c478sMlhx1o)
+ - [Reactive Values in Volt](https://www.youtube.com/watch?v=yZIQ-2irY-Q)
+
+Check out demo apps:
+ - https://github.com/voltrb/todos3
+ - https://github.com/voltrb/contactsdemo

SUMMARY.md

@@ -0,0 +1,46 @@
+# Summary
+
+* [Introduction](README.md)
+* [Goals](introduction/README.md)
+* [Tutorial](tutorial/README.md)
+   * [A Sample App](tutorial/a_sample_app.md)
+* [Docs](docs/README.md)
+   * [Rendering](docs/rendering.md)
+   * [Views](docs/views.md)
+       * [Content Binding](docs/content_binding.md)
+       * [If Binding](docs/if_binding.md)
+       * [Each Binding](docs/each_binding.md)
+       * [Attribute Bindings](docs/attribute_bindings.md)
+       * [Template Bindings](docs/template_bindings.md)
+       * [Escaping](docs/escaping.md)
+   * [Models](docs/models.md)
+       * [Nil Models](docs/nil_models.md)
+       * [Provided Collections](docs/provided_collections.md)
+       * [Store Collections](docs/store_collections.md)
+       * [Sub Collections](docs/sub_collections.md)
+       * [Model Classes](docs/model_classes.md)
+       * [Buffers](docs/buffers.md)
+       * [Validations](docs/validations.md)
+       * [Model State](docs/model_state.md)
+       * [ArrayModel Events](docs/arraymodel_events.md)
+       * [Automatic Model Conversion](docs/automatic_model_conversion.md)
+   * [Controllers](docs/controllers.md)
+       * [Reactive Accessors](docs/reactive_accessors.md)
+   * [Tasks](docs/tasks.md)
+   * [Components](docs/components.md)
+       * [Dependencies](docs/dependencies.md)
+       * [Assets](docs/assets.md)
+       * [Component Generator](docs/component_generator.md)
+       * [Provided Components](docs/provided_components.md)
+   * [Controls](docs/controls.md)
+       * [Control Arguments/Attributes](docs/control_argumentsattributes.md)
+   * [Routes](docs/routes.md)
+       * [Routes File](docs/routes_file.md)
+   * [Channel](docs/channel.md)
+   * [Testing](docs/testing.md)
+   * [Debugging](docs/debugging.md)
+   * [Volt Helpers](docs/volt_helpers.md)
+* [Why Volt](why_volt/README.md)
+* [Getting Help](getting_help/README.md)
+* [Contributing](contributing/README.md)
+

book.json

@@ -0,0 +1,4 @@
+{
+    "title": "Volt Introduction and Docs",
+    "description": "Volt is a Ruby web framework where your ruby code runs on both the server and the client (via opal). The DOM automatically updates as the user interacts with the page. Page state can be stored in the URL. If the user hits a URL directly, the HTML will first be rendered on the server for faster load times and easier indexing by search engines.\n\nInstead of syncing data between the client and server via HTTP, Volt uses a persistent connection between the client and server. When data is updated on one client, it is updated in the database and any other listening clients (with almost no setup code needed).\n\nPages HTML is written in a handlebars-like template language. Volt uses data flow/reactive programming to automatically and intelligently propagate changes to the DOM (or any other code wanting to know when a value updates). When something in the DOM changes, Volt intelligently updates only the nodes that need to be changed."
+}

contributing/README.md

@@ -0,0 +1,3 @@
+# Contributing
+
+You want to contribute?  Great!  Thanks for being awesome!  At the moment, we have a big internal todo list, hop on https://gitter.im/voltrb/volt so we don't duplicate work.  Pull requests are always welcome, but asking about helping on gitter should save some duplication.

docs/README.md

@@ -0,0 +1,4 @@
+# Volt Documentation
+
+The following attempts to document all of the features of Volt.  While the code is always the final source of authority, we will attempt to keep these docs as up to date as possible.
+

docs/arraymodel_events.md

@@ -0,0 +1,15 @@
+## ArrayModel Events
+
+Models trigger events when their data is updated.  Currently, models emit two events: added and removed.  For example:
+
+```ruby
+    model = Model.new
+
+    model._items.on('added') { puts 'item added' }
+    model._items << 1
+    # => item added
+
+    model._items.on('removed') { puts 'item removed' }
+    model._items.delete_at(0)
+    # => item removed
+```

docs/assets.md

@@ -0,0 +1,9 @@
+## Assets
+
+**Note, asset management is still early, and likely will change quite a bit**
+
+In Volt, assets such as JavaScript and CSS (or sass) are automatically included on the page for you.  Anything placed inside of a components asset/js or assets/css folder is served at /assets/{js,css} (via [Sprockets](https://github.com/sstephenson/sprockets)).  Link and script tags are automatically added for each css and js file in assets/css and assets/js respectively.  Files are included in their lexical order, so you can add numbers in front if you need to change the load order.
+
+Any JS/CSS from an included component or component gem will be included as well.  By default [bootstrap](http://getbootstrap.com/) is provided by the volt-bootstrap gem.
+
+**Note: asset bundling is on the TODO list**

docs/attribute_bindings.md

@@ -0,0 +1,51 @@
+# Attribute Bindings
+
+Bindings can also be placed inside of attributes.
+
+```html
+<p class="{{ if _is_cool? }}cool{{ end }}">Text</p>
+```
+
+There are some special features provided to make elements work as "two way bindings":
+
+```html
+<input type="text" value="{{ _name }}" />
+```
+
+## CheckBoxes
+
+In the example above, if ```_name``` changes, the field will update, and if the field is updated, ```_name``` will be changed:
+
+```html
+<input type="checkbox" checked="{{ _checked }}" />
+```
+
+If the value of a checked attribute is ```true```, the checkbox will be shown checked. If it's checked or unchecked, the value will be updated to ```true``` or ```false``` respectively.
+
+## Radio Buttons
+
+Radio buttons bind to a checked state as well, except instead of setting the value to true or false, they set it to a supplied field value.
+
+```html
+<input type="radio" checked="{{ _radio }}" value="one" />
+<input type="radio" checked="{{ _radio }}" value="two" />
+```
+
+When a radio button is checked, whatever checked is bound to is set to the field's value.  When the checked binding value is changed, any radio buttons where the binding's value matches the fields value are checked.  NOTE: This seems to be the most useful behaviour for radio buttons.
+
+## Select Boxes
+
+Select boxes can be bound to a value (while not technically a DOM property, this is another convient behavior Volt adds).
+
+```html
+<select value="{{ _rating }}">
+  <option value="1">*</option>
+  <option value="2">**</option>
+  <option value="3">***</option>
+  <option value="4">****</option>
+  <option value="5">*****</option>
+</select>
+```
+
+When the selected option of the select above changes, ```_rating``` is changed to match.  When ```_rating``` is changed, the selected value is changed to the first option with a matching value.  If no matching values are found, the select box is unselected.
+

docs/automatic_model_conversion.md

@@ -0,0 +1,63 @@
+## Automatic Model Conversion
+
+### Hash -> Model
+
+For convenience, when placing a hash inside of another model, it is automatically converted into a model.  Models are similar to hashes, but provide support for things like persistence and triggering reactive events.
+
+```ruby
+    user = Model.new
+    user._name = 'Ryan'
+    user._profiles = {
+      _twitter: 'http://www.twitter.com/ryanstout',
+      _dribbble: 'http://dribbble.com/ryanstout'
+    }
+
+    user._name
+    # => "Ryan"
+    user._profiles._twitter
+    # => "http://www.twitter.com/ryanstout"
+    user._profiles.class
+    # => Model
+```
+
+Models are accessed differently from hashes.  Instead of using `model[:symbol]` to access, you call a method `model.method_name`.  This provides a dynamic unified store where setters and getters can be added without changing any access code.
+
+You can get a Ruby hash back out by calling `#to_h` on a Model.
+
+### Array -> ArrayModel
+
+Arrays inside of models are automatically converted to an instance of ArrayModel.  ArrayModels behave the same as a normal Array except that they can handle things like being bound to backend data and triggering reactive events.
+
+```ruby
+    model = Model.new
+    model._items << {_name: 'item 1'}
+    model._items.class
+    # => ArrayModel
+
+    model._items[0].class
+    # => Model
+    model._items[0]
+```
+
+
+To convert a Model or an ArrayModel back to a normal hash, call .to_h or .to_a respectively.  To convert them to a JavaScript Object (for passing to some JavaScript code), call `#to_n` (to native).
+
+```ruby
+    user = Model.new
+    user._name = 'Ryan'
+    user._profiles = {
+      _twitter: 'http://www.twitter.com/ryanstout',
+      _dribbble: 'http://dribbble.com/ryanstout'
+    }
+
+    user._profiles.to_h
+    # => {_twitter: 'http://www.twitter.com/ryanstout', _dribbble: 'http://dribbble.com/ryanstout'}
+
+    items = ArrayModel.new([1,2,3,4])
+    # => #<ArrayModel:70226521081980 [1, 2, 3, 4]>
+
+    items.to_a
+    # => [1,2,3,4]
+```
+
+You can get a normal array again by calling .to_a on an ArrayModel.

docs/buffers.md

@@ -0,0 +1,38 @@
+## Buffers
+
+Because the store collection is automatically synced to the backend, any change to a model's property will result in all other clients seeing the change immediately.  Often this is not the desired behavior.  To facilitate building [CRUD](http://en.wikipedia.org/wiki/Create,_read,_update_and_delete) apps, Volt provides the concept of a "buffer".  A buffer can be created from one model and will not save data back to its backing model until .save! is called on it.  This lets you create a form thats not saved until a submit button is pressed.
+
+```ruby
+    store._items << {_name: 'Item 1'}
+
+    item1 = store._items[0]
+
+    item1_buffer = item1.buffer
+
+    item1_buffer._name = 'Updated Item 1'
+    item1_buffer._name
+    # => 'Updated Item 1'
+
+    item1._name
+    # => 'Item 1'
+
+    item1_buffer.save!
+
+    item1_buffer._name
+    # => 'Updated Item 1'
+
+    item1._name
+    # => 'Updated Item 1'
+```
+
+```#save!``` on buffer also returns a [promise](http://opalrb.org/blog/2014/05/07/promises-in-opal/) that will resolve when the data has been saved back to the server.
+
+```ruby
+    item1_buffer.save!.then do
+      puts "Item 1 saved"
+    end.fail do |err|
+      puts "Unable to save because #{err}"
+    end
+```
+
+Calling .buffer on an existing model will return a buffer for that model instance.  If you call .buffer on an ArrayModel (plural sub-collection), you will get a buffer for a new item in that collection.  Calling .save! will then add the item to that sub-collection as if you had done << to push the item into the collection.

docs/channel.md

@@ -0,0 +1,11 @@
+# Channel
+
+Controllers provide a `#channel` method, that you can use to get the status of the connection to the backend.  Channel's access methods are reactive and when the status changes, the watching computations will be re-triggered.  It provides the following:
+
+| method      | description                                               |
+|-------------|-----------------------------------------------------------|
+| connected?  | true if it is connected to the backend                    |
+| status      | possible values: :opening, :open, :closed, :reconnecting  |
+| error       | the error message for the last failed connection          |
+| retry_count | the number of reconnection attempts that have been made without a successful connection |
+| reconnect_interval | the time until the next reconnection attempt (in seconds) |

docs/component_generator.md

@@ -0,0 +1,15 @@
+## Component Generator
+
+Components can easily be shared as a gem.  Volt provides a scaffold for component gems.  In a folder (not in a volt project), simply type: volt gem {component_name}  This will create the files needed for the gem.  Note that all volt component gems will be prefixed with volt- so they can easily be found by others on github and rubygems.
+
+While developing, you can use the component by placing the following in your Gemfile:
+
+```ruby
+gem 'volt-{component_name}', path: '/path/to/folder/with/component'
+```
+
+Once the gem is ready, you can release it to ruby gems with:
+
+    rake release
+
+Remove the path: option in the gemfile if you wish to use the rubygems version.

docs/components.md

@@ -0,0 +1,3 @@
+# Components
+
+Apps are made up of Components.  Each folder under app/ is a component.  When you visit a route, it loads all of the files in the component on the front end, so new pages within the component can be rendered without a new http request.  If a URL is visited that routes to a different component, the request will be loaded as a normal page load and all of that components files will be loaded.  You can think of components as the "reload boundary" between sections of your app.

docs/content_binding.md

@@ -0,0 +1,9 @@
+# Content binding
+
+The most basic binding is a content binding:
+
+```html
+<p>Hello {{ name }}</p>
+```
+
+The content binding runs the Ruby code between {{ and }}, then renders the return value.  Any time the data a content binding relies on changes, the binding will run again and update the text.  Text in content bindings is html escaped by default.

docs/control_argumentsattributes.md

@@ -0,0 +1,36 @@
+# Control Arguments/Attributes
+
+Like other html tags, controls can be passed attributes.  These are then converted into an object that is passed as the first argument to the initialize method on the controller.  The standard ModelController's initialize will then assign the object to the attrs property which can be accessed with ```#attrs```  This makes it easy to access attributes passed in.
+
+```html
+
+<:Body>
+
+  <ul>
+    {{ _todos.each do |todo| }}
+      <:todo name="{{ todo._name }}" />
+    {{ end }}
+  </ul>
+
+<:Todo>
+  <li>{{ attrs.name }}</li>
+```
+
+Instead of passing in individual attributes, you can also pass in a Model object with the "model" attribute and it will be set as the model for the controller.
+
+```html
+<:Body>
+  <ul>
+    {{ _todos.each do |todo| }}
+      <:todo model="{{ todo }}" />
+    {{ end }}
+  </ul>
+
+<:Todo>
+  <li>
+    {{ _name }} -
+    {{ if _complete }}
+      Complete
+    {{ end }}
+  </li>
+```

docs/controllers.md

@@ -0,0 +1,47 @@
+# Controllers
+
+A controller can be any class in Volt, however it is common to have that class inherit from ModelController.  A model controller lets you specify a model that the controller works off of.  This is a common pattern in Volt.  The model for a controller can be assigned by one of the following:
+
+1. A symbol representing the name of a provided collection model:
+
+```ruby
+    class TodosController < ModelController
+      model :page
+
+      # ...
+    end
+```
+
+2. Calling `self.model=` in a method:
+
+```ruby
+    class TodosController < ModelController
+      def initialize
+        self.model = :page
+      end
+    end
+```
+
+When a model is set, any missing methods will be proxied to the model.  This lets you bind within the views without prefixing the model object every time.  It also lets you change out the current model and have the views update automatically.
+
+In methods, the `#model` method returns the current model.
+
+See the [provided collections](#provided-collections) section for a list of the available collection models.
+
+You can also provide your own object to model.
+
+In the example above, any methods not defined on the TodosController will fall through to the provided model.  All views in views/{controller_name} will have this controller as the target for any Ruby run in their bindings.  This means that calls on self (implicit or with self.) will have the model as their target (after calling through the controller).  This lets you add methods to the controller to control how the model is handled, or provide extra methods to the views.
+
+Volt is more similar to an MVVM architecture than an MVC architecture.  Instead of the controllers passing data off to the views, the controllers are the context for the views.  When using a ModelController, the controller automatically forwards all methods it does not handle to the model.  This is convenient since you can set a model in the controller and then access its properties directly with methods in bindings.  This lets you do something like ```{{ _name }}``` instead of something like ```{{ @model._name }}```
+
+Controllers in the app/home component do not need to be namespaced, all other components should namespace controllers like so:
+
+```ruby
+    module Auth
+      class LoginController < ModelController
+        # ...
+      end
+    end
+```
+
+Here "auth" would be the component name.