Embed JS Widgets Smoothly with Rails: A Step-by-Step Guide

Creating a custom JavaScript widget that can be embedded in client websites is a powerful way to extend the reach of your Ruby on Rails application. Whether it's a chat box, an analytics tracker, or any other interactive element, a custom widget lets you bring functionality directly to users. Let’s walk through the steps of building a secure, embeddable widget and cover the best practices.

Table of Contents

 1. Step 1: Setup
 2. Step 2: Creating an Embed Code for Clients
 3. Step 3: Embedding Your Widget in an Iframe (Optional)
 4. Step 4: Setting Headers for Iframe Embedding
 5. Step 5: Test the Widget
 6. Step 6: Adding Version Support with Versioned Routes and Controllers

Step 1: Setup

Create a new Rails endpoint: This endpoint will serve the JavaScript code for your widget. Typically, this could be an action within a WidgetsController:

# app/controllers/widgets_controller.rb
class WidgetsController 



<p>Configure the Route: Set up a route to make the widget accessible.<br>
</p>

<pre class="brush:php;toolbar:false"># config/routes.rb
Rails.application.routes.draw do
  get '/widget.js', to: 'widgets#show', as: :widget
end

Serve JavaScript from the Controller: In Rails, you can respond with JavaScript by setting the appropriate content type.

# app/controllers/widgets_controller.rb
class WidgetsController 



<p>Write the JavaScript Code for Your Widget: The widget script typically includes the logic to render a custom HTML element or iframe on the client’s page.<br>
</p>

<pre class="brush:php;toolbar:false">// app/views/widgets/show.js.erb
(function() {
  const widgetDiv = document.createElement('div');
  widgetDiv.id = 'custom-widget';
  widgetDiv.innerHTML = "<p>This is your custom widget content!</p>";
  document.body.appendChild(widgetDiv);
})();

Step 2: Creating an Embed Code for Clients

To allow clients to embed your widget, provide a JavaScript snippet they can copy and paste into their HTML:

<!-- Client Embeddable Code -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/widget.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Step 3: Embedding Your Widget in an Iframe (Optional)

Consider embedding the widget content in an iframe for more isolation and control over styling. This approach keeps the widget's styling and behavior separate from the client's site.

Update the JavaScript Code to create an iframe for the widget:

// app/views/widgets/show.js.erb
(function() {
  const iframe = document.createElement('iframe');
  iframe.src = "";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

Define a New Route and View for the Widget Content:

# config/routes.rb
Rails.application.routes.draw do
  get '/widget_content', to: 'widgets#content', as: :widget_content
end

# app/controllers/widgets_controller.rb
def content
  render layout: false
end

Create the Widget Content HTML: Create a view to render inside the iframe

<!-- app/views/widgets/content.html.erb -->
<div>



<h2>
  
  
  Step 4: Setting Headers for Iframe Embedding
</h2>

<p>Configure the appropriate HTTP headers to ensure your widget works securely in an iframe. There are two primary headers to consider:</p>

<p><strong>Remove the X-Frame-Options Header</strong>: The X-Frame-Options header is deprecated but still widely respected by many browsers. To remove it, add the following configuration in an initializer:<br>
</p>

<pre class="brush:php;toolbar:false"># config/initializers/security_headers.rb
Rails.application.config.action_dispatch.default_headers.delete('X-Frame-Options')

Set the Frame-Ancestors Directive:The modern and more flexible approach is to use Content-Security-Policy with the frame-ancestors directive, which allows you to specify the domains allowed to embed your widget in an iframe. Adjust this header as needed based on your security requirements.

# config/initializers/security_headers.rb
Rails.application.config.action_dispatch.default_headers.merge!({
  'Content-Security-Policy' => "frame-ancestors 'self' https://trusted-domain.com"
})

This configuration allows your app to be embedded in iframes only by the specified domains. Replace https://trusted-domain.com with the actual domains you trust.

Step 5: Test the Widget

Once you’ve set up the widget and headers, test the widget by embedding it on a test page in various browsers to ensure compatibility. If you’ve used frame-ancestors, confirm that only the specified domains can embed your widget and that the widget displays as expected.

Step 6: Adding Version Support with Versioned Routes and Controllers

As your widget evolves, you may introduce new features or improvements that not all clients are ready to adopt immediately. Supporting multiple versions of your widget ensures backward compatibility, allowing clients to upgrade at their own pace without disrupting their existing integrations.

Implementing Version Support Using Versioned Routes and Controllers

Define Versioned Routes

Start by setting up separate routes for each version of your widget. Namespacing each version keeps your code organized and allows you to manage different versions independently.

# app/controllers/widgets_controller.rb
class WidgetsController 



<h4>
  
  
  Create Versioned Controllers
</h4>

<p>For each version, create a controller within its namespace. This separation ensures that changes in one version don't affect others.<br>
</p>

<pre class="brush:php;toolbar:false"># config/routes.rb
Rails.application.routes.draw do
  get '/widget.js', to: 'widgets#show', as: :widget
end

# app/controllers/widgets_controller.rb
class WidgetsController 



<h4>
  
  
  Create Version-Specific JavaScript and HTML Views
</h4>

<p>Each version can have its own JavaScript and HTML files, allowing you to tailor functionality and appearance per version.</p>

<p><strong>Version 1 JavaScript:</strong><br>
</p>

<pre class="brush:php;toolbar:false">// app/views/widgets/show.js.erb
(function() {
  const widgetDiv = document.createElement('div');
  widgetDiv.id = 'custom-widget';
  widgetDiv.innerHTML = "<p>This is your custom widget content!</p>";
  document.body.appendChild(widgetDiv);
})();

Version 1 Content:

<!-- Client Embeddable Code -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/widget.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Version 2 Content:

// app/views/widgets/show.js.erb
(function() {
  const iframe = document.createElement('iframe');
  iframe.src = "";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

Final Thoughts

Creating an embeddable widget for a Rails application involves a few key considerations: serving JavaScript securely, managing styles, and configuring headers correctly for iframe compatibility. By following the steps above, you’ll have a widget that clients can easily add to their sites, expanding the usability of your Rails application.