Ruby on Rails

You can write an Applin backend in Rails.

Get Started

Learn https://rubyonrails.org/
Create a new Rails project
Add https://rubygems.org/gems/applin-rails

Routes

The Applin frontend sends GET to load a new page.

When refreshing a page, it sends POST if the page has any user-input widgets. The request body is a JSON object containing the page's variables. So all pages with user-input widgets need to handle POST.

When a page has no user-input widgets, the frontend uses GET to refresh the page.

The rpc action also sends POST with the page's variables.

For details, see Frontend-Backend Protocol.

# config/routes.rb
Rails.application.routes.draw do
  # https://guides.rubyonrails.org/routing.html
  get "/healthz", to: proc { [200, {}, ["success"]] }
  
  # Requests for "/" go to HomeController.index.
  root "home#index"
  
  # Frontend sends POST when refreshing a page with user-input widgets. 
  get "/login_page", to: "login#login_page"
  post "/login_page", to: "login#login_page"
  
  # Frontend sends POST for RPC action.
  post "/login", to: "login#login"
end

Controllers

Your server must require "applin/rails" which adds the applin format. Then Rails can recognize Applin requests when it checks the Accept header.

Applin is not affected by CSRF attacks. Rails has automatic CSRF protection for POST requests. We call protect_from_forgery to disable it for Applin requests:

# app/controllers/home_controller.rb
class HomeController < ApplicationController
  # Prevent error "ActionController::InvalidAuthenticityToken (Can't verify CSRF token authenticity.)"
  protect_from_forgery with: :exception, if: -> { !request.format.applin? }
end

Rails automatically parses the POST body JSON object and makes it available in the params object. To learn how to handle request parameters, see the Ruby on Rails Guides. Also see Submitting Data.

Views

Your server can require "applin" and then your views can call Applin module functions to create pages and widgets.

We recommend using the jbuilder JSON template library.

To display a page in the frontend, your server must return a response with the proper content-type header value. If your view template filename ends in .applin.jbuilder then Rails will:

use the JBuilder templating engine to process the template into a response body
add the Applin content-type header to the response

The response body must be a JSON object with a page entry.

# app/views/home/index.applin.jbuilder 
json.page Applin::nav_page(title: "Home Page", poll_seconds: 30) {
  Applin::scroll {
    Applin::column(widgets: [
      Applin::text("text")
    ])
  }
}

Controller-Only

You have the option of defining your pages inside the controller, without view templates.

Use Applin::Rails::send_page and the various functions in the Applin module.

# app/controllers/home_controller.rb
require "applin"
require "applin/rails"

class HomeController < ApplicationController
  include ::Applin
  include ::Applin::Rails
  skip_forgery_protection

  def index
    send_page nav_page(title: "Home Page", poll_seconds: 30) {
      scroll {
        column(widgets: [
          text("text")
        ])
      }
    }
  end
end

Example

https://github.com/leonhard-llc/applin-rails-demo

Applin Documentation