Tessa Client

Gem Version Build Status Coverage Status Code Climate

This gem wraps ActiveStorage to provide some convenience helpers for direct uploading assets, as well as generating public and private asset URLs.

History

This gem was initially conceived as a client to the Tessa asset management service. That service has been deprecated and is being phased out.

In 2022, we moved away from using Tessa to manage our assets and got onto the official Rails ActiveStorage library. Here is the issue tracking the effort. As part of that process, we released the v1.x version of this gem which supports both ActiveStorage and Tessa but uploads all new assets to ActiveStorage.

When that migration is completed, v2.x of this gem will remove all code that accesses the old Tessa service. This gem will transition to being simply a convenience wrapper around ActiveStorage, so that we don't have to re-write as much of our code in our frontend apps.

v6.x of this gem is compatible with ActiveStorage v6 and above. Since v6, ActiveStorage now does everything that this gem used to do, with the exception of Dropzone integration. Therefore, tessa-client v6 only contains the following two modules:

  1. A set of Javascript utilities to integrate Dropzone.js with ActiveStorage direct uploads
  2. A SimpleForm helper to write out the hidden input fields for an ActiveStorage has_one_attached.

Installation

Add this line to your application's Gemfile:

gem 'tessa'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tessa

Usage

We provide no guarantee of support for your use of this gem. It is for internal Watermark use only. Use at your own risk!

The main thing this gem still gives us is direct-uploads using Dropzone.js. Before using this gem it's worthwhile to understand how it works:

Sequence Diagram

When an Asset input is configured using the SimpleForm helper (TODO: https://github.com/watermarkchurch/tessa-client/issues/22), it creates a DropZone div with the css class .tessa-upload. The javascript in app/javascript/tessa/index.js.coffee scans for these divs and configures Dropzone.js.

When a user initiates a file upload via Dropzone, it does an XHR POST to /tessa/uploads. This triggers the lib/tessa/rack_upload_proxy.rb middleware to create a new ActiveStorage blob, and returns the signed upload URL. Dropzone then uploads the file directly to S3 (or wherever ActiveStorage is configured) from the user's browser.

To get all this working, follow these steps:

  1. In your application.js, require the js libraries:

    //= require dropzone
//= require tessa

    Note that this only works if you are using Sprockets. If you are using another bundler, we don't support that yet.

  2. use ActiveStorage to add an attached asset

class Model < ApplicationRecord
  has_one_attached :image
  1. When rendering your form, use the SimpleForm helper to render the dropzone div:
<%= f.input :image,
    as: :asset,
    dropzone: { acceptedFiles: "image/*" },
    hint: "Use an image that is 1440 x 288 in size (5:1 aspect ratio)" %>
  1. Configure your ActiveStorage service to accept direct uploads. The disk service does this automatically. The S3 service requires additional CORS configuration.

Contributing

  1. Fork it ( https://github.com/watermarkchurch/tessa/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request