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 < ApplicationController
  def show
    # Your widget code here
  end
end

Configure the Route: Set up a route to make the widget accessible.

# 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 < ApplicationController
  def show
    response.headers['Content-Type'] = 'application/javascript'
    render layout: false
  end
end

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.

// 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 = "<%= widget_content_url %>";
  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 id="iframe-widget">
  <p>This is the widget content in an iframe.</p>
</div>

Step 4: Setting Headers for Iframe Embedding

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

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

# 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.

# config/routes.rb
Rails.application.routes.draw do
  namespace :v1 do
    get '/widget.js', to: 'widgets#show', as: :widget_v1
    get '/widget_content', to: 'widgets#content', as: :widget_content_v1
  end

  namespace :v2 do
    get '/widget.js', to: 'widgets#show', as: :widget_v2
    get '/widget_content', to: 'widgets#content', as: :widget_content_v2
  end

  # Add more versions as needed
end

Create Versioned Controllers

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

# app/controllers/v1/widgets_controller.rb
module V1
  class WidgetsController < ApplicationController
    def show
      response.headers['Content-Type'] = 'application/javascript'
      render 'v1/widgets/show', layout: false
    end

    def content
      render 'v1/widgets/content', layout: false
    end
  end
end

# app/controllers/v2/widgets_controller.rb
module V2
  class WidgetsController < ApplicationController
    def show
      response.headers['Content-Type'] = 'application/javascript'
      render 'v2/widgets/show', layout: false
    end

    def content
      render 'v2/widgets/content', layout: false
    end
  end
end

Create Version-Specific JavaScript and HTML Views

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

Version 1 JavaScript:

// app/views/v1/widgets/show.js.erb
(function() {
  console.log("Widget Version 1 Loaded");
  const iframe = document.createElement('iframe');
  iframe.src = "<%= widget_content_v1_url %>";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

Version 1 Content:

<!-- app/views/v1/widgets/content.html.erb -->
<div id="iframe-widget-v1">
  <p>This is the widget content for version 1.</p>
</div>

Version 2 JavaScript:

// app/views/v2/widgets/show.js.erb
(function() {
  console.log("Widget Version 2 Loaded with New Features");
  const iframe = document.createElement('iframe');
  iframe.src = "<%= widget_content_v2_url %>";
  iframe.style.width = "400px"; // Updated dimensions
  iframe.style.height = "300px";
  document.body.appendChild(iframe);
})();

Version 2 Content:

<!-- app/views/v2/widgets/content.html.erb -->
<div id="iframe-widget-v2">
  <p>This is the widget content for version 2 with new features!</p>
</div>

Provide Versioned Embed Codes to Clients

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

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.