render_async 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7348b088d336af949c92c6132a741fac0d1ccdda790d216fcd4a8bfba852dc0
-  data.tar.gz: 0ad8ed64d193321f04d6c623e4ed18992cd5638f0302a8736242c135dabb17ef
+  metadata.gz: 301c0dec3cac35c32dd7946334151d2c968fe8f182006b1e67e4fc21655e1899
+  data.tar.gz: 0df8c63b19c81621726efb95c993377caa81c554ba29d29d782451f5a4116d21
 SHA512:
-  metadata.gz: 68b8ebb7fa1bc91b5dcb51f7f86bde67fa404cb4159f73e98c1d75bb54ee9775f2cf13ef5373d2c1d8750ff9130dfa28fab3a85bffe1649eb529becba0006f32
-  data.tar.gz: 3809facb7cb728243aaed8d215dd29607c88baec7781b2df109cc7b91223d2fc919903db3a72c6b5ba2222739323964785e7cb34c0dff8b9e841113756095e2c
+  metadata.gz: 261185dde786cf96d86e1d9abb5e9d67d0b0b431786adb4459f3f230621d55e34ebd89ed98950f27fb0541af355c26150ef766bae254e3ea28d7367f504ce388
+  data.tar.gz: 6af545d420676f1a39c98fe43dda6c63f66c8d944faab86ed57f4912dfc65243b6e350a538156389d5ed7e3ae63a579c28cd1a4161597bb09d504c79c9b93dfa

data/README.md

@@ -26,11 +26,10 @@ JavaScript is injected into `<%= content_for :render_async %>` so you choose
 where to put it.
 
 ## Installation
-S
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'Sender_async'
+gem 'render_async'
 ```
 
 And then execute:
@@ -46,7 +45,7 @@ And then execute:
 
 2. Then create a route that will `config/routes.rb`:
     ```ruby
-    get :comment_stats, :controller => :comments
+    get :comment_stats, controller: :comments
     ```
 
 3. Fill in the logic in your controller (e.g. `app/controllers/comments_controller.rb`):
@@ -54,7 +53,7 @@ And then execute:
     def comment_stats
       @stats = Comment.get_stats
 
-      render :partial => "comment_stats"
+      render partial: "comment_stats"
     end
     ```
 
@@ -74,23 +73,62 @@ And then execute:
 
 Advanced usage includes information on different options, such as:
 
+  - [Passing in a container ID](#passing-in-a-container-id)
+  - [Passing in a container class name](#passing-in-a-container-class-name)
   - [Passing in HTML options](#passing-in-html-options)
   - [Passing in an HTML element name](#passing-in-an-html-element-name)
   - [Passing in a placeholder](#passing-in-a-placeholder)
   - [Passing in an event name](#passing-in-an-event-name)
+  - [Handling errors](#handling-errors)
   - [Caching](#caching)
+  - [Doing non-GET requests](#doing-non-get-requests)
   - [Using with Turbolinks](#using-with-turbolinks)
   - [Using with respond_to and JS format](#using-with-respond_to-and-js-format)
   - [Nested Async Renders](#nested-async-renders)
+  - [Configuration](#configuration)
 
-### Passing in HTML options
+### Passing in a container ID
+
+`render_async` renders an element that gets replaced with the content
+of your request response. In order to have more control over the element
+that renders first (before the request), you can set the ID of that element.
+
+To set ID of the container element, you can do the following:
+```erb
+<%= render_async users_path, container_id: 'users-container' %>
+```
+
+Rendered code in the view:
+```html
+<div id="users-container">
+</div>
+
+...
+```
+
+### Passing in a container class name
 
-`render_async` takes two arguments, `path` and `html_options`.
+`render_async` renders an element that gets replaced with the content of your
+request response. If you want to style that element, you can set the class name
+on it.
+
+```erb
+<%= render_async users_path, container_class: 'users-container-class' %>
+```
+
+Rendered code in the view:
+```html
+<div id="render_async_18b8a6cd161499117471" class="users-container-class">
+</div>
+
+...
+```
+
+### Passing in HTML options
 
-* `path` is the AJAX-capable controller action you're looking to call via
-  `GET`. e.g. `comments_stats_path`, `posts_path`, etc.
-* `html_options` is an optional hash that gets passed to a rails
-  `javascript_tag`, to drop html tags into the `script` element.
+`render_async` can accept `html_options` argument.
+`html_options` is an optional hash that gets passed to a Rails'
+`javascript_tag`, to drop HTML tags into the `script` element.
 
 Example of utilizing `html_options` with a `nonce`:
 ```erb
@@ -168,7 +206,7 @@ after your partial is loaded through `render_async`.
 
 Example of passing it to `render_async`:
 ```erb
-<%= render_async users_path, :event_name => "users-loaded" %>
+<%= render_async users_path, event_name: "users-loaded" %>
 ```
 
 Rendered code in view:
@@ -192,6 +230,38 @@ document.addEventListener("users-loaded", function() {
 });
 ```
 
+NOTE: Dispatching events is also supported for older browsers that don't
+support Event constructor.
+
+### Handling errors
+
+`render_async` let's you handle errors by allowing you to pass in `error_message`
+and `error_event_name`.
+
+- `error_message`
+
+  passing an `error_message` will render a message if the AJAX requests fails for
+  some reason
+  ```erb
+  <%= render_async users_path,
+                   error_message: '<p>Sorry, users loading went wrong :(</p>' %>
+  ```
+
+- `error_event_name`
+
+  calling `render_async` with `error_event_name` will dispatch event in the case
+  of an error with your AJAX call.
+  ```erb
+  <%= render_asyc users_path, error_event_name: 'users-error-event' %>
+  ```
+
+  You can then catch the event in your code with:
+  ```js
+  document.addEventListener('users-error-event', function() {
+    // I'm on it
+  })
+  ```
+
 ### Caching
 
 `render_async` can utilize view fragment caching to avoid extra AJAX calls.
@@ -204,7 +274,7 @@ In your views (e.g. `app/views/comments/show.html.erb`):
 
 Then, in the partial (e.g. `app/views/comments/_comment_stats.html.erb`):
 ```erb
-<% cache render_async_cache_key(request.path), :skip_digest => true do %>
+<% cache render_async_cache_key(request.path), skip_digest: true do %>
   <div class="col-md-6">
     <%= @stats %>
   </div>
@@ -217,6 +287,25 @@ Then, in the partial (e.g. `app/views/comments/_comment_stats.html.erb`):
 * You can expire cache simply by passing `:expires_in` in your view where
   you cache the partial
 
+### Doing non-GET requests
+
+By default, `render_async` creates AJAX GET requests for the path you provide.
+If you want to change this behaviour, you can pass in a `method` argument to
+`render_async` view helper.
+
+```erb
+<%= render_async users_path, method: 'POST' %>
+```
+
+You can also set `body` and `headers` of the request if you need them.
+
+```erb
+<%= render_async users_path,
+                 method: 'POST',
+                 data: { fresh: 'AF' },
+                 headers: { 'Content-Type': 'text' } %>
+```
+
 ### Using with Turbolinks
 
 On Turbolinks applications, you may experience caching issues when navigating
@@ -243,7 +332,7 @@ def comment_stats
     format.js do
       @stats = Comment.get_stats
 
-      render :partial => "comment_stats"
+      render partial: "comment_stats"
     end
   end
 end
@@ -257,7 +346,7 @@ You can get around it by specifying the content type to `text/html` in the
 render call:
 
 ```ruby
-render :partial => "comment_stats", :content_type => 'text/html'
+render partial: "comment_stats", content_type: 'text/html'
 ```
 
 ### Nested Async Renders
@@ -287,6 +376,28 @@ For example:
 <%= content_for :render_async %>
 ```
 
+### Configuration
+
+`render_async` renders Vanilla JS (regular JavaScript, non-jQuery code)
+**by default** in order to fetch the request from the server.
+
+If you want `render_async` to use jQuery code, you need to configure it to do
+so.
+
+You can configure it by doing the following anywhere before you call
+`render_async`:
+```rb
+RenderAsync.configure do |config|
+  jquery = true # This will render jQuery code, and skip Vanilla JS code
+end
+```
+
+Also, you can do it like this:
+```rb
+# This will render jQuery code, and skip Vanilla JS code
+RenderAsync.configuration.jquery = true
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/app/views/render_async/_render_async.html.erb

@@ -1,16 +1,34 @@
-<<%= html_element_name %> id="<%= container_id %>">
+<<%= html_element_name %>
+  id="<%= container_id %>"
+  class="<%= container_class %>"
+>
   <%= placeholder %>
 </<%= html_element_name %>>
 
 <% content_for :render_async do %>
   <%= javascript_tag html_options do %>
-    <%= render partial: 'render_async/request',
-               formats: [:js],
-               locals:  { container_id: container_id,
-                          path: path,
-                          method: method,
-                          data: data,
-                          event_name: event_name,
-                          headers: headers } %>
+    <% if RenderAsync.configuration.jquery %>
+      <%= render partial: 'render_async/request_jquery',
+                 formats: [:js],
+                 locals:  { container_id: container_id,
+                            path: path,
+                            method: method,
+                            data: data,
+                            event_name: event_name,
+                            headers: headers,
+                            error_message: error_message,
+                            error_event_name: error_event_name } %>
+    <% else %>
+      <%= render partial: 'render_async/request_vanilla',
+                 formats: [:js],
+                 locals:  { container_id: container_id,
+                            path: path,
+                            method: method,
+                            data: data,
+                            event_name: event_name,
+                            headers: headers,
+                            error_message: error_message,
+                            error_event_name: error_event_name } %>
+    <% end %>
   <% end %>
 <% end %>

data/app/views/render_async/_request_jquery.js.erb

@@ -0,0 +1,45 @@
+if (window.jQuery) {
+  (function($) {
+    $(document).ready(function() {
+      var headers = <%= headers.to_json.html_safe %>;
+      var csrfTokenElement = document.querySelector('meta[name="csrf-token"]')
+      if (csrfTokenElement)
+        headers['X-CSRF-Token'] = csrfTokenElement.content
+
+      $.ajax({
+        url: '<%= path.html_safe %>',
+        method: '<%= method %>',
+        data: "<%= escape_javascript(data.to_s.html_safe) %>",
+        headers: headers
+      }).done(function(response) {
+        $("#<%= container_id %>").replaceWith(response);
+
+        <% if event_name.present? %>
+          var event = undefined;
+          if (typeof(Event) === 'function') {
+            event = new Event("<%= event_name %>");
+          } else {
+            event = document.createEvent('Event');
+            event.initEvent('<%= event_name %>', true, true);
+          }
+          document.dispatchEvent(event);
+        <% end %>
+      }).error(function(response) {
+        $("#<%= container_id %>").replaceWith('<%= error_message.try(:html_safe) %>');
+
+        <% if error_event_name.present? %>
+          var event = undefined;
+          if (typeof(Event) === 'function') {
+            event = new Event("<%= error_event_name %>");
+          } else {
+            event = document.createEvent('Event');
+            event.initEvent('<%= error_event_name %>', true, true);
+          }
+          document.dispatchEvent(event);
+        <% end %>
+      });
+    });
+  }(jQuery));
+} else {
+  console.warn("Looks like you've enabled jQuery for render_async, but jQuery is not defined");
+};

data/app/views/render_async/_request_vanilla.js.erb

@@ -0,0 +1,56 @@
+(function() {
+  document.addEventListener("DOMContentLoaded", function() {
+    var request = new XMLHttpRequest();
+    var asyncRequest = true;
+    var SUCCESS = 200;
+    var ERROR = 400;
+
+    request.open('<%= method %>', '<%= path.html_safe %>', asyncRequest);
+
+    var headers = <%= headers.to_json.html_safe %>;
+    var csrfTokenElement = document.querySelector('meta[name="csrf-token"]')
+    if (csrfTokenElement)
+      headers['X-CSRF-Token'] = csrfTokenElement.content
+
+    Object.keys(headers).map(function(key) {
+      request.setRequestHeader(key, headers[key]);
+    });
+
+    request.onreadystatechange = function() {
+      if (request.readyState === 4) {
+        if (request.status >= SUCCESS && request.status < ERROR) {
+          var container = document.getElementById('<%= container_id %>');
+          container.outerHTML = request.response;
+
+          <% if event_name.present? %>
+            var event = undefined;
+            if (typeof(Event) === 'function') {
+              event = new Event("<%= event_name %>");
+            } else {
+              event = document.createEvent('Event');
+              event.initEvent('<%= event_name %>', true, true);
+            }
+            document.dispatchEvent(event);
+          <% end %>
+        } else {
+          var container = document.getElementById('<%= container_id %>');
+          container.outerHTML = '<%= error_message.try(:html_safe) %>';
+
+          <% if error_event_name.present? %>
+            var event = undefined;
+            if (typeof(Event) === 'function') {
+              event = new Event("<%= error_event_name %>");
+            } else {
+              event = document.createEvent('Event');
+              event.initEvent('<%= error_event_name %>', true, true);
+            }
+            document.dispatchEvent(event);
+          <% end %>
+        }
+      }
+    };
+
+    var body = "<%= escape_javascript(data.to_s.html_safe) %>";
+    request.send(body);
+  });
+})();

data/lib/render_async.rb

@@ -1,5 +1,24 @@
 require "render_async/version"
 require "render_async/view_helper"
 require "render_async/engine" if defined? Rails
+require "render_async/configuration"
 
 ActionView::Base.send :include, RenderAsync::ViewHelper if defined? ActionView::Base
+
+module RenderAsync
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configuration
+    @configuration ||= RenderAsync::Configuration.new
+  end
+
+  def self.reset
+    @configuration = RenderAsync::Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/render_async/configuration.rb

@@ -0,0 +1,9 @@
+module RenderAsync
+  class Configuration
+    attr_accessor :jquery
+
+    def initialize
+      @jquery = false
+    end
+  end
+end

data/lib/render_async/version.rb

@@ -1,3 +1,3 @@
 module RenderAsync
-  VERSION = "1.3.0".freeze
+  VERSION = "1.4.0".freeze
 end

data/lib/render_async/view_helper.rb

@@ -19,23 +19,34 @@ module RenderAsync
 
     def render_async(path, options = {}, &placeholder)
       html_element_name = options.delete(:html_element_name) || 'div'
-      container_id = "render_async_#{SecureRandom.hex(5)}#{Time.now.to_i}"
+      container_id = options.delete(:container_id) || generate_container_id
+      container_class = options.delete(:container_class)
       event_name = options.delete(:event_name)
       placeholder = capture(&placeholder) if block_given?
       method = options.delete(:method) || 'GET'
       data = options.delete(:data)
       headers = options.delete(:headers) || {}
+      error_message = options.delete(:error_message)
+      error_event_name = options.delete(:error_event_name)
 
       render 'render_async/render_async', html_element_name: html_element_name,
                                           container_id: container_id,
+                                          container_class: container_class,
                                           path: path,
                                           html_options: options,
                                           event_name: event_name,
                                           placeholder: placeholder,
                                           method: method,
                                           data: data,
-                                          headers: headers
+                                          headers: headers,
+                                          error_message: error_message,
+                                          error_event_name: error_event_name
     end
 
+    private
+
+    def generate_container_id
+      "render_async_#{SecureRandom.hex(5)}#{Time.now.to_i}"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: render_async
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Kasper Grubbe
@@ -83,11 +83,13 @@ files:
 - README.md
 - Rakefile
 - app/views/render_async/_render_async.html.erb
-- app/views/render_async/_request.js.erb
+- app/views/render_async/_request_jquery.js.erb
+- app/views/render_async/_request_vanilla.js.erb
 - bin/console
 - bin/integration-tests
 - bin/setup
 - lib/render_async.rb
+- lib/render_async/configuration.rb
 - lib/render_async/engine.rb
 - lib/render_async/version.rb
 - lib/render_async/view_helper.rb

data/app/views/render_async/_request.js.erb

@@ -1,57 +0,0 @@
-if (window.jQuery) {
-  (function($) {
-    $(document).ready(function() {
-      var headers = <%= headers.to_json.html_safe %>;
-      var csrfTokenElement = document.querySelector('meta[name="csrf-token"]')
-      if (csrfTokenElement)
-        headers['X-CSRF-Token'] = csrfTokenElement.content
-
-      $.ajax({
-        url: '<%= path.html_safe %>',
-        method: '<%= method %>',
-        data: "<%= escape_javascript(data.to_s.html_safe) %>",
-        headers: headers
-      }).always(function(response) {
-        $("#<%= container_id %>").replaceWith(response);
-
-        <% if event_name.present? %>
-          document.dispatchEvent(new Event("<%= event_name %>"));
-        <% end %>
-      });
-    });
-  }(jQuery));
-} else {
-  (function() {
-    document.addEventListener("DOMContentLoaded", function() {
-      var request = new XMLHttpRequest();
-      var asyncRequest = true;
-      var SUCCESS = 200;
-      var ERROR = 400;
-
-      request.open('<%= method %>', '<%= path.html_safe %>', asyncRequest);
-
-      var headers = <%= headers.to_json.html_safe %>;
-      var csrfTokenElement = document.querySelector('meta[name="csrf-token"]')
-      if (csrfTokenElement)
-        headers['X-CSRF-Token'] = csrfTokenElement.content
-
-      Object.keys(headers).map(function(key) {
-        request.setRequestHeader(key, headers[key]);
-      });
-
-      request.onload = function() {
-        if (request.status >= SUCCESS && request.status < ERROR) {
-          var container = document.getElementById('<%= container_id %>');
-          container.outerHTML = request.response;
-
-          <% if event_name.present? %>
-            document.dispatchEvent(new Event("<%= event_name %>"));
-          <% end %>
-        }
-      };
-
-      var body = "<%= escape_javascript(data.to_s.html_safe) %>";
-      request.send(body);
-    });
-  })();
-}