breezy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 28b02ed9694b5b85d6646507c147c938500ecd7c
+  data.tar.gz: 3d0e115680c7b088dd4ed03376d18bbdfdca392f
+SHA512:
+  metadata.gz: 252ac9b68b92cdfa5ee57e7a49521f6338f54042e3d17d8a34a73de377d4b69f8f680897209e619b6b65a8e6a4b2a9ce715bd67190d12445d4f33bb3accf867c
+  data.tar.gz: 93e38dea643db06c33a8542d116a4baa861c0b2a85f54e12130b6945346f51bc75c76cff45d2bad2588aa813aaef81bd09e4463bc4e45b0b3850ae3dbf8a3ed3

data/README.md

@@ -0,0 +1,326 @@
+# Breezy
+Breezy makes it easy (even boring) to create single-page, multi-page, and sometimes-single-page applications with ReactJS and classic Rails.
+
+[![Sauce Test Status](https://saucelabs.com/browser-matrix/jho406-bensonhurst.svg)](https://saucelabs.com/u/jho406-bensonhurst)
+
+## What you can do:
+
+1. Page to page transitions without reloading
+2. Russian Doll cache aware JS content with structural sharing that makes implementing `shouldComponentUpdate` as easy as extending ReactJS's `PureComponent`
+3. Defered rendering of slow loading parts of your page without API endpoints (e.g. dashboards that load later on direct visits)
+4. Async actions that load different parts of your page without API endpoints (e.g. pagination, infinite scroll)
+
+
+Breezy is the lovechild of Turbolinks (also a hard fork), Server Generated Javascript Responses (created with BreezyTemplates), and ReactJS that bring you all of the above features while keeping complexity low.
+
+Unlike Turbolink's view-over-the-wire approach, a Breezy app is content-over-the-wire to your ReactJS frontend. Each controller gets two views, one for your content that you write using the included BreezyTemplates, and the other for your markup which you write in ReactJS. Breezy features are achieved with `XMLHTTPRequest`s for the next page's content (or a branch of it via key paths) before firing a `breezy:load` event that you can use with `ReactDOM.render`.
+
+## Quick Peek
+Starting with a Rails project with Breezy [installed](#installation), ReactJS in your asset pipeline, and [something](https://github.com/reactjs/react-rails) [to](https://github.com/Shopify/sprockets-commoner) transform JSX to JS.
+
+Add a route and controller as you normally would.
+```ruby
+# config/routes.rb
+resources :posts
+
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  # Allow breezy to take over HTML requests
+  before_action :use_breezy_html
+
+  def index
+    @greeting = 'hello'
+  end
+
+  def new
+    ....some stuff here...
+  end
+end
+```
+
+Use the included BreezyTemplates to create your content.
+
+```ruby
+#app/views/posts/index.js.breezy
+
+json.heading @greeting
+
+# `defer: true` will no-op the following block on a direct
+# visit, use null as a standin value, and append additional
+# javascript in the response to fetch only this content node
+# (no-oping other sibiling blocks) and graft it in the right
+# place on the client side.
+json.dashboard(defer: true) do
+  sleep 10
+  json.num_of_views 100
+end
+
+# Go ahead, use your rails helpers, including i18n.
+json.new_post_path new_post_path
+
+json.footer 'something'
+```
+
+Then write your remaining view in JSX. The content you wrote earlier gets passed here.
+
+```ruby
+# app/assets/javascripts/views/PostIndex.js.jsx
+
+App.Views.PostsIndex = function(json) {
+  // Deferment will use `null` as the standin value.
+  // Hence the need for `json.dashboard || {}`.
+  // Breezy will then fetch the missing node
+  // and call `ReactDOM.render` a second time
+
+  var dashboard = json.dashboard || {};
+
+  return (
+    <h1> {json.heading}</h1>
+    <div> {dashboard.num_of_views} </div>
+
+    # Page to page without reloading
+    <a href={json.new_post_path} data-bz-remote> Create </a>
+
+    <div>{json.footer}</div>
+  )
+}
+```
+
+## Installation
+Breezy does not include ReactJS, you'll have to download it seperately and include it in your path. Or just include [react-rails](https://github.com/reactjs/react-rails).
+
+```
+gem 'breezy', git: 'https://github.com/jho406/Breezy.git'
+```
+
+Then use the provided installation generator:
+```
+rails g breezy:install
+```
+
+If you need to add breezy and JSX views:
+```
+rails g breezy:view Posts new index
+```
+
+# Navigation and Forms
+Breezy intercepts all clicks on `<a>` and all submits on `<form>` elements enabled with `data-bz-remote`. Breezy will `preventDefault` then make the same request using XMLHttpRequest with a content type of `.js`. If there's an existing request, Breezy will cancel it unless the `data-bz-async` option is used.
+
+Once the response loads, a `breezy:load` event will be fired with the JS object that you created with BreezyTemplates. If you used the installation generator, the event will be set for you in the `<head>` element of your layout:
+
+```javascript
+document.addEventListener('breezy:load', function(event){
+  var props = {
+    view: event.data.view,
+    data:  event.data.data
+  }
+  ReactDOM.render(React.createElement(window.App.Components.View, props), document.getElementById('app'));
+});
+```
+
+## The data-bz-* attribute API
+
+Attribute          | default value            | description
+-------------------|--------------------------|------------
+`data-bz-remote`   | For `<a>` the default is `get`. For forms, the default is `post` if a method is not specified. | Use this to create seamless page to page transitions. Works for both links and forms. You can specify the request method by giving it a value, e.g `<a href='foobar' data-bz-remote=post>`. For forms, the request method of the form is used. `<form action=foobar method='post' data-bz-remote>`.
+`data-bz-async`      | `false`                  | Fires off an async request. Responses are pushed into a queue will be evaluated in order of click or submit.
+`data-bz-push-state` | `true`                   | Captures the element's URL in the browsers history. Normally used with `data-bz-async`.
+`data-bz-silent`     | false                    | To be used with the `breezy_silent?` ruby helper. Useful if you don't want to perform a redirect or render. Just return a 204, and Breezy will not fire a `breezy:load` event.
+
+
+# Events
+Event                 | Argument `originalEvent.data`  | Notes
+----------------------|--------------------------------|-------
+`breezy:load`          | {data}                         | Triggered on document, when Breezy has succesfully loaded content, to be used with `ReactDOM.render`. Yes the key is a bit weird. You have to access it like so `event.data.data`.
+`breezy:click`         | {url}                          | Triggered on the element when a form or a link enabled with data-bz-remote is clicked. Cancellable with event.preventDefault().
+`breezy:request-error` | null or {xhr}                  | Triggered on the element when on XHR onError (network issues) or when async option is used and recieves an error response.
+`breezy:request-start` | {url}                          | Triggered on the element just before a XHR request is made.
+`breezy:request-end`   | {url}                          | Triggered on the element, when a XHR request is finished.
+`breezy:restore`       | null                           | Triggered on document, when a page cached is loaded, just before `breezy:load`
+
+## JS API Reference
+
+### Breezy.visit
+
+Usage:
+```javascript
+Breezy.visit(location)
+Breezy.visit(location, { pushState, silent, async })
+```
+Performs an Application Visit to the given _location_ (a string containing a URL or path).
+
+- If the pushState option is specified, Breezy will determine wheather to add the visitation to the browsers history. The default value is `true`.
+- If async is specified, Breezy will make an async request and add the onload callback to a queue to be evaluated (calling `breezy:load`) in order of fire. The default value is `false`, this means if there's an existing request or a queue of async requests, Breezy will cancel all of them and give priority to the most recent call.
+- If silent is specified, a request header X-SILENT will be set. use in tadem with the `breezy_silent?` ruby method for when you want to perform an action but return a 204 instead of a redirect or render. Breezy will ignore 204s and will not attempt to fire `breezy:load`.
+
+
+### Breezy.graftByKeypath
+
+Usage:
+```javascript
+Breezy.graftByKeypath(keyPath, object, {type});
+```
+Place a new object at the specified keypath of Breezy's content tree on the current page and across other pages in its cache. Parent objects are clone and `breezy:load` is finally called.
+
+When referencing an array of objects, you have the option of providing an id instead of an index. For example:
+
+```
+a.b.some_array_element_id_of_your_choice=1.c.d
+```
+
+If type is specified as `add`. Breezy will push the object at the keyPath (assuming its an array) instead of of replacing.
+
+
+### Breezy.replace
+Usage:
+```javascript
+Breezy.replace({data, title, csrf_token, assets})
+```
+Replaces the current page content and triggers a `reload:load`. Normally used to inject content to Breezy on a direct visit. Breezy's generators will set this up for you.
+
+## Ruby Helpers
+
+
+### use_breezy_html
+Usage:
+```ruby
+  class PostController < ApplicationController
+    before_action :use_breezy_html
+  end
+```
+
+On direct visits, Breezy will render an empty page. If you used the installation generator, Breezy will also inject your content view created by BreezyTemplates into a script header, then fire a `breezy:load` event that you can use with `ReactDOM.render`.
+
+### breezy_silient?
+Usage:
+
+```
+class PostController < ApplicationController
+  def create
+  ...
+    if breezy_silent?
+      ...
+    end
+  end
+end
+```
+
+Used in conjuction with `data-bz-silent` for `204` responses. Great for when you want to run a job and don't want to render anything back to the client.
+
+## BreezyTemplate Templates, your content view
+BreezyTemplates is a sibling of JBuilderTemplates, both inheriting from the same [parent](https://github.com/rails/jbuilder/blob/master/lib/jbuilder.rb). Unlike Jbuilder, BreezyTemplate generates Server Generated Javascript and has a few differences listed below.
+
+###Partials
+Partials are only supported as an option on attribute or array! `set!`s.
+Usage:
+
+```ruby
+# We use a `nil` because of the last argument hash. The contents of the partial is what becomes the value.
+json.post nil, partial: "blog_post"
+
+or
+
+# Set @post as a local `article` within the `blog_post` partial.
+json.post @post, partial: "blog_post", as: 'article'
+
+or
+# Add more locals
+json.post @big_post, partial: "blog_post", locals: {email: 'tests@test.com'}
+
+or
+
+# Use a partial for each element in an array
+json.array! @posts, partial: "blog_post", as: :blog_post
+```
+
+### Caching
+Caching is only available as an option on an attribute and can be used in tandem with partials.
+
+Usage:
+
+```ruby
+json.author(cache: ["some_cache_key"]) do
+  json.first_name "tommy"
+end
+
+or
+
+json.profile "hello", cache: "cachekey"
+
+or
+
+json.profile nil, cache: "cachekey", partial: "profile", locals: {email: "test@test.com"}
+```
+
+
+### No merge of duplicate `set!`s
+Unlike Jbuilder, BreezyTemplates will not merge duplicate `set!`s. Instead, the last duplicate will override the first.
+
+Usage:
+```ruby
+json.address do
+  json.street '123 road'
+end
+
+json.address do
+  json.zip 10002
+end
+```
+
+would become
+
+```json
+{address: {zip:10002}}
+```
+
+### Deferment
+You can defer rendering of expensive content using the `defer: true` option available in blocks. Behind the scenes BreezyTemplates will no-op the block entirely, replace the value with a `null` as a standin, and append a `Breezy.visit(/somepath?_breezy_filter=keypath.to.node)` to the response. When the client recieves the payload, `breezy:load` will be fired, then the appended `Breezy.visit` will be called to fetch and graft the missing node before firing `breezy:load` a second time.
+
+Usage:
+```ruby
+json.dashboard(defer: true) do
+  sleep 10
+  json.some_fancy_metric 42
+end
+```
+
+#### Working with arrays
+If you want to defer elements in an array, you should add a key as an option on `array!` to help breezy generate a more specific keypath, otherwise it'll just use the index.
+
+```ruby
+data = [{id: 1, name: 'foo'}, {id: 2, name: 'bar'}]
+
+json.array! data, key: :id do
+  json.greeting defer: true do
+    json.greet 'hi'
+  end
+end
+```
+
+### Filtering nodes
+As seen previously, Breezy can filter your content tree for a specific node. This is done by adding a `_breezy_filter=keypath.to.node` in your URL param and setting the content type to `.js`. BreezyTemplates will no-op all node blocks that are not in the keypath, ignore deferment and caching (if an `ActiveRecord::Relation` is encountered, it will append a where clause with your provided id) while traversing, and return the node. Breezy will then graft that node back onto its tree on the client side and call `breezy:onload` with the new tree. This is done automatically when using deferment, but you can use this param separately in tandem with `data-bz-remote`.
+
+For example, to create seamless ajaxy pagination for a specific part of your page, just create a link like the following:
+
+```html
+  <a href="posts?page_num=2&_breezy_filter=key.path.to.posts" data-bz-remote> Next Page </a>
+```
+
+Filtering works off your existing route and content tree, so no additional API necessary.
+
+
+##Running the tests
+
+Ruby:
+
+```
+BUNDLE_GEMFILE=Gemfile.rails50 bundle
+BUNDLE_GEMFILE=Gemfile.rails50 rake test
+```
+
+JavaScript:
+
+```
+bundle install
+bundle exec blade runner
+```

data/lib/assets/javascripts/breezy.coffee

@@ -0,0 +1,4 @@
+#= require_self
+#= require breezy/start
+
+@Breezy = {}

data/lib/breezy.rb

@@ -0,0 +1,71 @@
+require 'breezy/version'
+require 'breezy/xhr_headers'
+require 'breezy/xhr_redirect'
+require 'breezy/xhr_url_for'
+require 'breezy/cookies'
+require 'breezy/x_domain_blocker'
+require 'breezy/render'
+require 'breezy/helpers'
+require 'breezy/configuration'
+require 'breezy_template'
+
+module Breezy
+  module Controller
+    include XHRHeaders, Cookies, XDomainBlocker, Render, Helpers
+
+    def self.included(base)
+      if base.respond_to?(:before_action)
+        base.before_action :set_xhr_redirected_to, :set_request_method_cookie
+        base.after_action :abort_xdomain_redirect
+      else
+        base.before_filter :set_xhr_redirected_to, :set_request_method_cookie
+        base.after_filter :abort_xdomain_redirect
+      end
+
+      if base.respond_to?(:helper_method)
+        base.helper_method :breezy_tag
+        base.helper_method :breezy_silient?
+        base.helper_method :breezy_snippet
+        base.helper_method :use_breezy_html
+        base.helper_method :breezy_filter
+      end
+    end
+  end
+
+  class Engine < ::Rails::Engine
+    config.breezy = ActiveSupport::OrderedOptions.new
+    config.breezy.auto_include = true
+
+    initializer :breezy do |app|
+      ActiveSupport.on_load(:action_controller) do
+        next if self != ActionController::Base
+
+        if app.config.breezy.auto_include
+          include Controller
+        end
+
+        ActionDispatch::Request.class_eval do
+          def referer
+            self.headers['X-XHR-Referer'] || super
+          end
+          alias referrer referer
+        end
+
+        require 'action_dispatch/routing/redirection'
+        ActionDispatch::Routing::Redirect.class_eval do
+          prepend XHRRedirect
+        end
+      end
+
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Template.register_template_handler :breezy, BreezyTemplate::Handler
+        require 'breezy_template/dependency_tracker'
+        require 'breezy/active_support'
+
+        (ActionView::RoutingUrlFor rescue ActionView::Helpers::UrlHelper).module_eval do
+          prepend XHRUrlFor
+        end
+      end
+    end
+  end
+end

data/lib/breezy/active_support.rb

@@ -0,0 +1,21 @@
+# https://github.com/rails/jbuilder/issues/204
+
+if Rails.version >= '4.1'
+  module ActiveSupport
+    module JSON
+      module Encoding
+        class JSONGemEncoder
+          alias_method :original_jsonify, :jsonify
+
+          def jsonify(value)
+            if ::BreezyTemplate::Template::Digest === value
+              value
+            else
+              original_jsonify(value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/breezy/configuration.rb

@@ -0,0 +1,21 @@
+module Breezy
+  class Configuration
+    attr_accessor :track_assets
+
+    def initialize
+      @track_assets = ['application.js', 'application.css']
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.configure
+    yield configuration
+  end
+end