BetterFrame

Everyone hates iframes. This is why this rails plugin exists.

You'll get a much smoother usage of your app when embedded. Basically what this plugin does is the following:

  • Inject your html code onto the foreign website.
  • Handle all events (link clicking, form submitting) with javascript.
  • Write the browser history to make the navigation as normal as possible.
  • Write rails path + parameter onto the foreign site.

Installation

Add this line to your application's Gemfile:

gem 'better_frame'

And then execute:

$ bundle

Usage

Internal (in your rails app)

**NOTE: you need to make all your forms remote: true as this should not redirect to the rails app if you're submitting a form.

To start, you need to mount the engine in your rails routes:

# config/routes.rb
Rails.application.routes.draw do
  mount BetterFrame::Engine => "/better_frame"

  ...
end

As this only works with setting the Access-Control-Allow-Origin header, you'll need to include a concern to your controllers to make it available for better_frame to load. (You also may include it in your ApplicationController if you want.)

# app/controllers/examples_controller.rb
class ExamplesController < ApplicationController
  include BetterFrameable
end

You'll have to set the Access-Control-Allow-Origin using the BETTER_FRAME_ORIGIN environment variable.

 $ export BETTER_FRAME_ORIGIN=http://example.com

Or using dotenv

BETTER_FRAME_ORIGIN=http://example.com

Side note: If you have protect_from_forgery with: ... in your controller you have to delete that because of the cross site origin requests.

Javascript:

If you need something like $(document).ready, better_frame fires an event with better_frame:load. This event is fired everytime the side is loaded with better_frame.

Usage:

$("#app-content").on("better_frame:load", function(){
    alert("site was loaded with better_frame!");
});

HTML

By default, better_frame will override all anchor tags, except the ones with target=_blank. If you want to skip some specific links from being catched by better_frame you can use the data-ignore-better-frame attribute (e.g. mailto: links):

<a href="mailto:[email protected]" data-ignore-better-frame>mail example user</a>"

External (on your website which should embed the rails app)

NOTE: you need to have jQuery on the website which is embedding your rails app

On your website do the following:

<div id="app-content" data-baseurl="http://example.com/my_site" data-railsurl="http://my-rails-app.com"></div>
<script src="http://my-rails-app.com/better_frame" type="text/javascript"></script>

In <script src="..." needs the better_frame route to be placed. As defined in the routes in your rails application. (See internal usage)

IMPORTANT!!

Since this plugin is writing the history of your browser, as long as you stay on the site this will work perfectly (when using history back and forward), but if you reload the site, you have to make sure that your foreign site stays on the baseurl no matter what's after the baseurl.

E.g. Visiting http://example.com/my_site loads up your javascript and the root of the rails app. Then you click a link of your rails app let's say products, which will link to /products on your rails app. This will work properly and you'll see that the URL has changed to: http://example.com/my_site/products Now if you reload your website has to render the http://example.com/my_site (baseurl) but without changing the URL. If you set up your website like that you can pass in arguments and paths.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake false to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/better_frame. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.