Adding the Embed Workflow UI components to a Ruby on Rails application

This guide will walk you through adding the Embed Workflow UI components to a Ruby on Rails application.

You will need an Embed Workflow account to get started.

Source code can be found here.

Rails Application

Skip step one if you already have a Rails application you want to use.

1. Create a Rails Application

Create our rails demo application (skipping a bunch of stuff we don’t need).

rails new embed-workflow-rails-sample --minimal -J -O -M
cd ./embed-workflow-rails-sample

2. Add gems

We need a way to add environment variables so let’s add dotenv-rails.

gem "dotenv-rails"

Also, add jwt so we can safely authenticate with Embed Workflow.

gem "jwt"

bundle install

Create your .env to add the environment variables: EMBED_WORKFLOW_SECRET_KEY, EMBED_WORKFLOW_PUBLISHABLE_KEY, and EMBED_WORKFLOW_USER_KEY.

EMBED_WORKFLOW_SECRET_KEY=sk_test_12345
EMBED_WORKFLOW_PUBLISHABLE_KEY=pk_test_12345
EMBED_WORKFLOW_USER_KEY=main

Replace the environment variables with your test keys. Find them on your account API access page.

3. Create a Workflow Controller

We will create new endpoints (/workflows) but you are not limited to any particular one. Our UI components are your building blocks.

rails generate controller workflows index show new --no-test-framework --no-helper --skip-routes

Update the rails router with:

resources :workflows, only: [:index, :new, :show]

To authenticate our components, we will need to generate a JWT token and make it available in our views. Here is an example of how you can accomplish this with a before_action:

before_action :load_embed_workflow_jwt

def load_embed_workflow_jwt
  return @embed_workflow_jwt if defined?(@embed_workflow_jwt)

  current_time = Time.now.to_i
  exp          = current_time + 3600
  payload      = { sub: ENV["EMBED_WORKFLOW_USER_KEY"], exp: exp, iat: current_time }

  @embed_workflow_jwt = JWT.encode(payload, ENV["EMBED_WORKFLOW_SECRET_KEY"], "HS256")
end

4. Loading Resources

The UI Docs will offer more detail to getting set up.

Our views must load Embed Workflow’s external CSS and JS files. You may download and serve locally or use script/link tags.

<link rel="stylesheet" media="screen" href="https://cdn.ewf.to/ewf-####.css">
<script src="https://cdn.ewf.to/ewf-####.js"></script>

NOTE: replace #### with the latest version. You can find it here.

These scripts will be reused in our application so create the partial app/views/workflows/_embed_workflow_scripts.html.

5. Creating a Workflow

Now it is time to embed our first component – Workflow Form.

Add the following HTML to /app/views/workflows/new.html.erb

<%= render "embed_workflow_scripts" %>

<div>
  <%= link_to "Back to workflows", workflows_path %>
</div>

<h1>New workflow</h1>

<div>
  <div class="EWF__workflow_form" data-after-success="openWorkflow"></div>
</div>

<script type="text/javascript">
  var loadEmbed = function () {
    EWF.load("<%= ENV['EMBED_WORKFLOW_PUBLISHABLE_KEY'] %>", { jwt: "<%= @embed_workflow_jwt %>" });
  }

  loadEmbed();

  var openWorkflow = function (workflow) {
    window.location = "/workflows/" + workflow.hashid;
  }
</script>

6. List Workflows

After creating a workflow, we will want to display them in a list. The – Workflows Table component is perfect for that.

Update /app/views/workflows/index.html.erb to:

<%= render "embed_workflow_scripts" %>

<%= link_to "New workflow", new_workflow_path %>

<h1>Workflows</h1>

<div>
  <div class="EWF__workflows_table" data-on-click="openWorkflow"></div>
</div>

<script type="text/javascript">
  var loadEmbed = function () {
    EWF.load("<%= ENV['EMBED_WORKFLOW_PUBLISHABLE_KEY'] %>", { jwt: "<%= @embed_workflow_jwt %>" });
  }

  loadEmbed();

  var openWorkflow = function (hashid) {
    window.location = "/workflows/" + hashid;
  }
</script>

7. Manage Workflow

Selecting a workflow will take us to our show.html.erb.

<%= render "embed_workflow_scripts" %>

<%= link_to "Back to Workflows", workflows_path %>

<div class="EWF__workflow_settings" data-hashid="<%= params[:id] %>"></div>

<script type="text/javascript">
  var loadEmbed = function () {
    EWF.load("<%= ENV['EMBED_WORKFLOW_PUBLISHABLE_KEY'] %>", { jwt: "<%= @embed_workflow_jwt %>" });
  }

  loadEmbed();
</script>

8. Test it out

Navigate to http://localhost:3000/workflows and see it in action.

9. Customize Colors

Configure you primary color with CSS by setting the css variable --ewf-color-primary with rgb digits. Add the css:

body {
  --ewf-color-primary: 249, 115, 22;
}

What Next?

Source code can be found here.

Check out our UI docs to explore all of the components.

Looking for API access? API Docs