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.
Top comments (0)