unpoly-rails 0.62.1 → 2.0.0.pre.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '079979a47b22899b849e8b53275d23c2f6bf8a4ac14bf1b6001ac00330518cc9'
-  data.tar.gz: 033c8335552505a36214999db839d7c54a7e22c93fd168d8d8b25b7ccb5e40aa
+  metadata.gz: 6ae929555ac3d1c4f901618fed559ec3c2d53f5117de889d72c81518e158f946
+  data.tar.gz: 4a7bbc9f22a3fab1127b6c4bf3e0f930f1a300725549367025bc50c45c6ebdca
 SHA512:
-  metadata.gz: d7be2bf8bd27d709d479000a591320731ac8fdbe2c0f613883a41af4258d4125bf4e793ec1712f83f56083f27335c39d1a5136cc8a501440fe35403ebd536cff
-  data.tar.gz: d4493b591597cda5245c5d0cf5000d034922cde09316fc030776ceacaaf44330975199eb3b9bd1c5c3a61134c56e38a8f175f6b7e126c50c33c54377d3e31927
+  metadata.gz: 3ce5945794168936c808619d4ebd3a7490355dfadd7337324d40b68f2d211fc13149c46439abf693776e27c452a02f4acee78247b4196fc60bf27f94a1856b6f
+  data.tar.gz: d9c4f06cbc704414871a006c17b6ec1b7cb4d2f76c70c091f6585dc89265fa7f7e650e376e3ba632e4f75bb04049999fe0bc6644875b950616fb6ced4246b7dd

data/.yardopts

@@ -1 +1 @@
---markup=markdown --main=README_RAILS.md
+--markup=markdown --main=README_RAILS.md --exclude .

data/CHANGELOG.md

@@ -6,6 +6,66 @@ Changes to this project will be documented in this file.
 You may browse a formatted and hyperlinked version of this file at <https://unpoly.com/changes>.
 
 
+2.0.0
+-----
+
+[See Unpoly 2 slides](http://triskweline.de/unpoly2-slides/)
+
+TODO
+----
+
+This list is **far** from complete.
+
+- up.network.config.slowDelay is now 800 (up from 300)
+- up.network.config.cacheSize is now 50 (down from 70)
+- up.network.isBusy() / isIdle() takes preload events into account
+-  up.observe() callback may return a promise that will prevent callback calls while running
+- `[aria-label]` attributes are no longer used to build a target selector
+- Options removed form modals: up-width, up-max-width, up-height. Use up-size or up-class.
+- Failed responses now change the URL
+- TODO ...
+- up.history.config.restoreScroll has been removed.
+- Feedback works when a layer has no history
+- Layer A11Y
+  - inert
+  - aria-hidden
+  - focus new
+  - focus return on close
+- up.nav sets [aria-current]
+- up.history.config.enabled
+- Requests sent by Unpoly no longer have a `X-Requested-With: XMLHttpRequest` header.
+  If you need that old behavior: up.on('up:request:load', function(event) { event.request.headers['X-Requested-With'] = 'XMLHttpRequest' })
+- up.network.config.requestMetaKeys
+- up:link:follow is no longer sent when preloading, up:link:preload still is
+- Preserve focus when validating forms; Add { focus } option for fragment update
+- up.Request.prototype.isFatalError() has been removed without replacement. Network errors now reject with an error, and not a response.
+- [up-main], [up-main=overlay], [up-main=modal]
+- parseSelector can parse attribute selectors with prefix, infix, suffix, space-separated, dash-separated
+- up.validate() may now be called with a form element
+- validating emits up:form:validate instead of up:form:submit
+- When a compiler throws an error, other compilers will now run anyway
+- When a destructor throws an error, other destructors will now run anyway
+- Bootstrap integration
+  - Minimal: active, nav, navbar
+  - Bootstrap modal styles are no longer used for Unpoly modals
+  - Now supports three major Bootstrap versions:
+    - unpoly-bootstrap3.js
+    - unpoly-bootstrap4.js
+    - unpoly-bootstrap5.js
+- Hungry elements no longer get the transition by default. You need to set [up-transition] on the hungry element.
+- Rejections are now shown if the log is enabled
+- up.on() can passive: true
+- Preloads on touchstart and mousedown
+- Digit groups separators (`60_000`) are a stage 3 ES6 feature and also supported in number attributes.
+
+
+1.0.0
+-----
+
+- TODO
+
+
+
 0.62.1
 ------
 
@@ -73,7 +133,6 @@ This release also exposes some convenience functions and selectors:
   [`input[up-validate]`](/input-up-validate) was supported.
 
 
-
 0.60.3
 ------
 

data/README.md

@@ -31,7 +31,7 @@ Overview:
 
 Install dependencies for tests:
 
-- Install Ruby 2.1.2
+- Install Ruby 2.3.8
 - Install Bundler by running `gem install bundler`
 - `cd` into `spec_app`
 - Install dependencies by running `bundle install`
@@ -64,17 +64,9 @@ To prepare a new version:
 1. Edit `lib/unpoly/rails/version.rb` and bump the version number. Use [semantic versioning](http://semver.org/).
 2. Add an entry to `CHANGELOG.md`
 3. Commit and push the version bump and `CHANGELOG.md`
+4. Log into Rubygems and npm
 
-Now we can release a new version. **This requires your to be logged into Rubygems and npm**:
-
-1. From the project root, type `rake publish:build`. This will output minified JS and CSS files to the `dist` folder. It also updates the `package.json` for npm.
-2. Commit and push the generated files. There is a rake task `rake publish:commit` that helps with this.
-3. From the project root, type `rake publish:release`. This will publish a new gem version to Rubygems.org.
-4. It will also push a tag for this version, which Bower requires for its own versioning scheme. Finally it publishes to npm.
-
-Always remember to build, commit and push build artifacts before calling `rake publish:release` so the Git tag points to the correct commit.
-
-If you have done this process a few times and know what you're doing, you can call `rake publish:all` to run all these steps in sequence.
+Now you can call `rake release:all` to publish to Rubygems and npm.
 
 After you have published all release channels, remember to:
 

data/README_RAILS.md

@@ -1,7 +1,9 @@
 unpoly-rails: Ruby on Rails bindings for Unpoly
 ===============================================
 
-[Unpoly](https://unpoly.com) is a backend-agnostic [unobtrusive JavaScript](https://en.wikipedia.org/wiki/Unobtrusive_JavaScript) framework. `unpoly-rails` gives your [Ruby on Rails](http://rubyonrails.org/) application some convenience candy when you are using Unpoly in your frontend.
+[Unpoly](https://unpoly.com) is a backend-agnostic [unobtrusive JavaScript](https://en.wikipedia.org/wiki/Unobtrusive_JavaScript) framework. `unpoly-rails` gives a [Ruby on Rails](http://rubyonrails.org/) application some convenience methods to communicate with an Unpoly-enhanced frontend.
+
+Note that the bindings provided by `unpoly-rails` are entirely optional. You are free to use Unpoly with Rails without the `unpoly-rails` gem.
 
 
 Features
@@ -11,28 +13,78 @@ The methods documented below are available in all controllers, views and helpers
 
 ### Detecting a fragment update
 
-To test whether the current request is a [fragment update](https://unpoly.com/up.link):
+Use `up?` to test whether the current request is a [fragment update](https://unpoly.com/up.link):
 
 ```ruby
-up?
+up? # => true or false
 ```
 
-To retrieve the CSS selector that is being [updated](https://unpoly.com/up.link):
+To retrieve the CSS selector that is being [updated](https://unpoly.com/up.link), use `up.target`:
 
 ```ruby
-up.target
+up.target # => '.content'
 ```
 
-The Unpoly frontend will expect an HTML response containing an element that matches this selector. If no such element is found, an error is shown to the user.
-
-Server-side code is free to optimize its response by only returning HTML that matches this selector:
+The Unpoly frontend will expect an HTML response containing an element that matches this selector. Your Rails app is free to render a smaller response that only contains HTML matching the targeted selector. You may call `up.target?` to test whether a given CSS selector has been targeted:
 
 ```ruby
 if up.target?('.sidebar')
-  = render 'expensive_sidebar_partial'
+  render('expensive_sidebar_partial')
+end
+```
+
+Fragment updates may target different selectors for successful (HTTP status `200 OK`) and failed (status `4xx` or `5xx`) responses.
+Use these methods to inspect the target for failed responses:
+
+- `up.fail_target`: The CSS selector targeted for a failed response
+- `up.fail_target?(selector)`: Whether the given selector is targeted for a failed response
+- `up.any_target?(selector)`: Whether the given selector is targeted for either a successful or a failed response
+
+### Changing the render target
+
+The server may instruct the frontend to render a different target by assigning a new CSS selector to the `up.target` property:
+
+```ruby
+unless signed_in?
+  up.target = 'body'
+  render 'sign_in'
+end
+```
+
+The frontend will use the server-provided target for both successful (HTTP status `200 OK`) and failed (status `4xx` or `5xx`) responses.
+
+
+### Rendering nothing
+
+Sometimes it's OK to render nothing, e.g. when you know that the current layer is to be closed.
+
+In this case you may call `up.render_nothing`:
+
+```ruby
+class NotesController < ApplicationController
+  def create
+    @note = Note.new(note_params)
+    if @note.save
+      if up.layer.overlay?
+        up.accept_layer(@note.id)
+        up.render_nothing
+      else
+        redirect_to @note
+      end
+    end
+  end
 end
 ```
 
+This will render a 200 OK response with a header `X-Up-Target: none` and an empty body.
+
+You may render nothing with a different HTTP status by passing a `:status` option:
+
+```
+up.render_nothing(status: :bad_request)
+```
+
+
 ### Pushing a document title to the client
 
 To force Unpoly to set a document title when processing the response:
@@ -43,6 +95,36 @@ up.title = 'Title from server'
 
 This is useful when you skip rendering the `<head>` in an Unpoly request.
 
+### Emitting events on the frontend
+
+You may use `up.emit` to emit an event on the `document` after the
+fragment was updated:
+
+```ruby
+class UsersController < ApplicationController
+
+  def show
+    @user = User.find(params[:id])
+    up.emit('user:selected', id: @user.id)
+  end
+
+end
+```
+
+If you wish to emit an event on the current [layer](https://unpoly.com/up.layer)
+instead of the `document`, use `up.layer.emit`:
+
+```ruby
+class UsersController < ApplicationController
+
+  def show
+    @user = User.find(params[:id])
+    up.layer.emit('user:selected', id: @user.id)
+  end
+
+end
+```
+
 ### Detecting an Unpoly form validation
 
 To test whether the current request is a [form validation](https://unpoly.com/input-up-validate):
@@ -72,12 +154,211 @@ class UsersController < ApplicationController
 end
 ```
 
+### Detecting a fragment reload
+
+To test whether the current request was made to [reload](https://unpoly.com/up.reload) or [poll](https://unpoly.com/up-poll) a fragment:
+
+```ruby
+up.reload?
+```
+
+You also retrieve the time when the fragment being reloaded was previously inserted into the DOM:
+
+```ruby
+up.reload_from_time # returns a Time object
+```
+
+The server can compare the time from the request with the time of the last data update.
+If no more recent data is available, the server can [render nothing](/X-Up-Target):
+
+  ```ruby
+  class MessagesController < ApplicationController
+
+    def index
+      if up.reload_from_time == current_user.last_message_at
+        up.render_nothing
+      else
+        @messages = current_user.messages.order(time: :desc).to_a
+        render 'index'
+      end
+    end
+
+  end
+  ```
+
+Only rendering when needed saves <b>CPU time</b> on your server, which spends most of its response time rendering HTML.
+
+This also reduces the <b>bandwidth cost</b> for a request/response exchange to **~1 KB**.
+
+
+### Working with context
+
+Calling `up.context` will return the [context](https://unpoly.com/up.context) object of the targeted layer.
+
+The context is a JSON object shared between the frontend and the server.
+It persists for a series of Unpoly navigation, but is cleared when the user makes a full page load.
+Different Unpoly [layers](https://unpoly.com/up.layer) will usually have separate context objects,
+although layers may choose to share their context scope. 
+
+You may read and change the context object. Changes will be sent to the frontend with your response.
+
+```ruby
+class GamesController < ApplicationController
+
+  def restart
+    up.context[:lives] = 3
+    render 'stage1'
+  end
+
+end
+```
+
+Keys can be accessed as either strings or symbols:
+
+```ruby
+puts "You have " + up.layer.context[:lives] + " lives left"
+puts "You have " + up.layer.context['lives'] + " lives left"
+````
+
+You may delete a key from the frontend by calling `up.context.delete`:
+
+```ruby
+up.context.delete(:foo)
+````
+
+You may replace the entire context by calling `up.context.replace`: 
+
+```
+context_from_file = JSON.parse(File.read('context.json))
+up.context.replace(context_from_file)
+```
+
+`up.context` is an alias for `up.layer.context`.
+
+
+### Accessing the targeted layer
+
+Use the methods below to interact with the [layer](/up.layer) of the fragment being targeted.
+
+Note that fragment updates may target different layers for successful (HTTP status `200 OK`) and failed (status `4xx` or `5xx`) responses.
+
+#### `up.layer.mode`
+
+Returns the [mode](https://unpoly.com/up.layer.mode) of the targeted layer (e.g. `"root"` or `"modal"`).
+
+#### `up.layer.root?`
+
+Returns whether the targeted layer is the root layer.
+
+#### `up.layer.overlay?`
+
+Returns whether the targeted layer is an overlay (not the root layer).
+
+#### `up.layer.context`
+
+Returns the [context](https://unpoly.com/up.context) object of the targeted layer.
+See documentation for `up.context`, which is an alias for `up.layer.context`.
+
+#### `up.layer.accept(value)`
+
+[Accepts](https://unpoly.com/up.layer.accept) the current overlay.
+
+Does nothing if the root layer is targeted.
+
+Note that Rails expects every controller action to render or redirect.
+Your action should either call `up.render_nothing` or respond with `text/html` content matching the requested target.
+
+#### `up.layer.dismiss(value)`
+
+[Dismisses](https://unpoly.com/up.layer.dismisses) the current overlay.
+
+Does nothing if the root layer is targeted.
+
+Note that Rails expects every controller action to render or redirect.
+Your action should either call `up.render_nothing` or respond with `text/html` content matching the requested target.
+
+#### `up.layer.emit(type, options)`
+
+[Emits an event](https://unpoly.com/up.layer.emit) on the targeted layer.
+
+#### `up.fail_layer.mode`
+
+Returns the [mode](https://unpoly.com/up.layer.mode) of the layer targeted for a failed response.
+
+#### `up.fail_layer.root?`
+
+Returns whether the layer targeted for a failed response is the root layer.
+
+#### `up.fail_layer.overlay?`
+
+Returns whether the layer targeted for a failed response is an overlay.
+
+#### `up.fail_layer.context`
+
+Returns the [context](https://unpoly.com/up.context) object of the layer targeted for a failed response.
+
+
+### Managing the client-side cache
+
+The Unpoly frontend caches server responses for a few minutes, making requests to these URLs return instantly.
+Only `GET` requests are cached. The *entire* cache is cleared after every non-`GET` request (like `POST` or `PUT`).
+
+The server may override these defaults. For instance, the server can clear Unpoly's client-side response cache, even for `GET` requests:
+
+```ruby
+up.cache.clear
+```
+
+You may also clear a single page:
+
+```ruby
+up.cache.clear('/notes/1034')
+```
+
+You may also clear all entries matching a URL pattern:
+
+```ruby
+up.cache.clear('/notes/*')
+```
+
+You may also prevent cache clearing for an unsafe request:
+
+```ruby
+up.cache.keep
+```
+
+Here is an longer example where the server uses careful cache management to keep as much of the client-side cache as possible:
+
+```ruby
+def NotesController < ApplicationController
+
+  def create
+    @note = Note.create!(params[:note].permit(...))
+    if @note.save
+      up.cache.clear('/notes/*') # Only clear affected entries
+      redirect_to(@note)
+    else
+      up.cache.keep # Keep the cache because we haven't saved
+      render 'new'
+    end
+  end
+  ...
+end
+```
+
+
+### Preserving Unpoly-related request information through redirects
+
+`unpoly-rails` patches [`redirect_to`](https://api.rubyonrails.org/classes/ActionController/Redirecting.html#method-i-redirect_to)
+so Unpoly-related request information (like the CSS selector being targeted for a fragment
+update) will be preserved for the action you redirect to.
+
+
 ### Automatic redirect detection
 
-`unpoly-rails` installs a `before_action` into all controllers which echoes the request's URL as a response header `X-Up-Location` and the request's
+`unpoly-rails` installs a [`before_action`](https://api.rubyonrails.org/classes/AbstractController/Callbacks/ClassMethods.html#method-i-before_action) into all controllers which echoes the request's URL as a response header `X-Up-Location` and the request's
 HTTP method as `X-Up-Method`.
 
-The Unpoly frontend [requires these headers to detect redirects](https://unpoly.com/form-up-target#redirects), which are otherwise undetectable for an AJAX client.
 
 ### Automatic method detection for initial page load
 
@@ -93,7 +374,7 @@ What you still need to do manually
 
 ### Failed form submissions must return a non-200 status code
 
-Unpoly lets you submit forms via AJAX by using the [`form[up-target]`](https://unpoly.com/form-up-target) selector or [`up.submit()`](https://unpoly.com/up.submit) function.
+Unpoly lets you submit forms via AJAX by using the [`form[up-follow]`](https://unpoly.com/form-up-submit) selector or [`up.submit()`](https://unpoly.com/up.submit) function.
 
 For Unpoly to be able to detect a failed form submission,
 the form must be re-rendered with a non-200 HTTP status code.
@@ -122,11 +403,11 @@ Development
 
 ### Before you make a PR
 
-Before you make a PR, please have some discussion about the proposed change by [opening an issue on GitHub](https://github.com/unpoly/unpoly/issues/new).
+Before you create a pull request, please have some discussion about the proposed change by [opening an issue on GitHub](https://github.com/unpoly/unpoly/issues/new).
 
 ### Running tests
 
-- Install Ruby 2.1.2
+- Install Ruby 2.3.8
 - Install Bundler by running `gem install bundler`
 - `cd` into `spec_app`
 - Install dependencies by running `bundle install`