Home

Awesome

Motion

Gem Version npm version Build Status Maintainability Test Coverage Ruby Code Style JavaScript Code Style

Motion allows you to build reactive, real-time frontend UI components in your Rails application using pure Ruby. Check out some live examples and the code for the examples.

Installation

  1. Install Motion gem and JS package

Motion has Ruby and JavaScript parts, execute both of these commands:

bundle add motion
yarn add @unabridged/motion
  1. Install ViewComponent

You need a view component library to use Motion. Technically, any view component library that implements the render_in interface that landed in Rails 6.1 should be compatible, but Motion is actively developed and tested against Github's ViewComponent.

Installation instructions for ViewComponent are here.

  1. Install ActionCable

Motion communicates over and therefore requires ActionCable.

  1. Run install script

After installing all libraries, run the install script:

bin/rails g motion:install

This will install 2 files, both of which you are free to leave alone.

How does it work?

Motion allows you to mount special DOM elements (henceforth "Motion components") in your standard Rails views that can be real-time updated from frontend interactions, backend state changes, or a combination of both.

Frontend interactions

Frontend interactions can update your Motion components using standard JavaScript events that you're already familiar with: change, blur, form submission, and more. You can invoke Motion actions manually using JavaScript if you need to.

The primary way to handle user interactions on the frontend is by using map_motion:

class MyComponent < ViewComponent::Base
  include Motion::Component

  attr_reader :total

  def initialize(total: 0)
    @total = 0
  end

  map_motion :add

  def add
    @total += 1
  end
end

To invoke this motion on the frontend, add data-motion='add' to your component's template:

<div>
  <span><%= total %></span>
  <%= button_tag "Increment", data: { motion: "add" } %>
</div>

This component can be included on your page the same as always with ViewComponent:

<%= render MyComponent.new(total: 5) %>

Every time the "Increment" button is clicked, MyComponent will call the add method, re-render your component and send it back to the frontend to replace the existing DOM. All invocations of mapped motions will cause the component to re-render, and unchanged rendered HTML will not perform any changes.

Backend interactions

Backend changes can be streamed to your Motion components in 2 steps.

  1. Broadcast changes using ActionCable after an event you care about:
class Todo < ApplicationModel
  after_commit :broadcast_created, on: :create

  def broadcast_created
    ActionCable.server.broadcast("todos:created", name)
  end
end
  1. Configure your Motion component to listen to an ActionCable channel:
class TopTodosComponent < ViewComponent::Base
  include Motion::Component

  stream_from "todos:created", :handle_created

  def initialize(count: 5)
    @count = count
    @todos = Todo.order(created_at: :desc).limit(count).pluck(:name)
  end

  def handle_created(name)
    @todos = [name, *@todos.first(@count - 1)]
  end
end

This will cause any user that has a page open with TopTodosComponent mounted on it to re-render that component's portion of the page.

All invocations of stream_from connected methods will cause the component to re-render everywhere, and unchanged rendered HTML will not perform any changes.

Periodic Timers

Motion can automatically invoke a method on your component at regular intervals:

class ClockComponent < ViewComponent::Base
  include Motion::Component

  def initialize
    @time = Time.now
  end

  every 1.second, :tick

  def tick
    @time = Time.now
  end
end

Motion::Event and Motion::Element

Methods that are mapped using map_motion accept an event parameter which is a Motion::Event. This object has a target attribute which is a Motion::Element, the element in the DOM that triggered the motion. Useful state and attributes can be extracted from these objects, including value, selected, checked, form state, data attributes, and more.

  map_motion :example

  def example(event)
    event.type # => "change"
    event.name # alias for type

    # Motion::Element instance, the element that received the event.
    event.target

    # Motion::Element instance, the element with the event handler and the `data-motion` attribute
    event.element


    # Element API examples
    element.tag_name # => "input"
    element.value # => "5"
    element.attributes # { class: "col-xs-12", ... }

    # DOM element with aria-label="..."
    element[:aria_label]

    # DOM element with data-extra-info="..."
    element.data[:extra_info]

    # ActionController::Parameters instance with all form params. Also
    # available on Motion::Event objects for convenience.
    element.form_data
  end

See the code for full API for Event and Element.

Callbacks

Motion has callbacks which will let you pass data from a child component back up to the parent. Callbacks are created by calling bind with the name of a method on the parent component which will act as a handler. It returns a new callback which can be passed to child components like any other state. To invoke the handler from the callback, use call. If the handler accepts an argument, it will receive anything that is passed to call.

parent_component.rb

  # this will be called from the child component
  def do_something(message)
    puts "Colonel Sandurz says: "
    puts message
  end

parent_component.html.erb

  <%= render ChildComponent.new(on_click: bind(:do_something)) %>

child_component.rb

  attr_reader :on_click

  map_motion :click

  def initialize(on_click:)
    @on_click = on_click
  end

  def click
    on_click.call("Do something!") # an argument can be passed into `call`
  end

child_component.html.erb

  <%= button_tag "You gotta help me, I can't make decisions!", data: { motion: "click" } %>

Limitations

Roadmap

Broadly speaking, these initiatives are on our roadmap:

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/unabridged/motion.

License

The gem is available as open source under the terms of the MIT License.