search

takafumir / rails_amp

RailsAmp is a Ruby on Rails plugin for AMP(Accelerated Mobile Pages).
MIT License
65 stars 26 forks source link
accelerated-mobile-pages amp amp-html amphtml html rails rails-amp ruby

readme

RailsAmp Build Status

RailsAmp is a Ruby on Rails plugin that makes it easy to build views for AMP(Accelerated Mobile Pages).

Supported Versions

Rails 4.1, 4.2, 5.0

Installation

In your Gemfile:

gem 'rails_amp'

And install:

$ bundle install

And then, generate codes and files:

$ rails generate rails_amp:install

This step generates the followings.

insert  config/initializers/mime_types.rb
create  config/rails_amp.yml
create  app/views/layouts/rails_amp_application.amp.erb

In config/initializers/mime_types.rb:

Mime::Type.register_alias 'text/html', RailsAmp.default_format

This line must be added to make rails to recognize the amp format. The default format is :amp. You can change the value in config/rails_amp.yml

Configurations

You can change RailsAmp configurations in your config/rails_amp.yml. Write configs with yaml.

In config/rails_amp.yml:

# ### Here are some config samples to use rails_amp.

# --------------------------------------------------
# To enable amp on specific controllers and actions.
# --------------------------------------------------
# ### Enable amp on users all actions.
# targets:
#   users:
#
# ### Enable amp on users#index, users#show, posts#index, posts#show.
# ### controller: action1 action2 action3 ...
# targets:
#   users: index show
#   posts: index show
#
# ### Enable amp on all controllers and actions.
# targets:
#   application: all
#
# ### Disable amp completely.
# targets:
#
targets:
  users: index show

# --------------------------------------------------
# To set initial configurations.
# --------------------------------------------------
# ### Enable Google Analytics page tracking. Set your Google Analytics Account.
# analytics: UA-*****-*
#
# ### Change default amp format. The default value is amp.
# ### If you want to use 'mobile' as amp format, set 'mobile' to default_format.
# ### And you can access the amp page like /users/index.mobile
# default_format: mobile
#
# ### Set formats that used as amp. The default is html.
# ### These formats are used in the order, when the amp specialized view like 'users/index.amp.erb' is not found.
# lookup_formats: html xhtml

Examples

Set the controllers and actions that you want to enable amp.

Enable amp on users all actions except for new, create, edit, update, destroy actions.

targets:
  users:

Note that RailsAmp automatically excludes the post-method related actions new, create, edit, update, destroy that originally provided by Rails from the amp targets.

Enable amp on some specific controllers and actions. e.g.) users#index, users#show, posts#show.

targets:
  users: index show
  posts: show

Enable amp on all controllers and actions. (It's a bit dangerous, so I don't recommend.)

targets:
  application: all

Disable amp completely.

targets:

Other configurations.

Enable Google Analytics page tracking. Set your Google Analytics Account.

analytics: UA-*****-*

Change the amp default format. The default value is 'amp'. If you want to use 'mobile' as the default format, set 'mobile' to default_format. And you can access the amp page like http://example.com/users.mobile.

default_format: mobile

Change formats that used as amp. The default is html. These formats are used in the order, when the amp specialized view like app/views/users/index.amp.erb is not found.

lookup_formats: html xhtml

Note that you need to restart a server to reload the configurations after changing config/rails_amp.yml.

Setup

Add the following code in your default layout head like application.html.erb.

In app/views/layouts/application.html.erb:

<%= rails_amp_amphtml_link_tag %>

This code will put out the html header to inform where the amp url is.

<link rel="amphtml" href="http://example.com/users.amp" />

AMP link for root_url(root_path)

When you enable amp on the controller and action for root_url, the helper rails_amp_amphtml_link_tag will put out the following amphtml link in the root url.

In your config/routes.rb:

root 'home#index'

And, in config/rails_amp.yml:

targets:
  home: index

The helper rails_amp_amphtml_link_tag will put out the following in the root url.

In http://example.com/:

<link rel="amphtml" href="http://example.com/home/index.amp" />

So, you need to add a routing for this amp url.

In your config/routes.rb:

get '/home/index', to: 'home#index'

Customize AMP layout

In app/views/layouts/rails_amp_application.amp.erb:

<!doctype html>
<html amp>
  <head>
    <meta charset="utf-8">
    <title>Rails AMP</title>
    <link rel="canonical" href="https://github.com/takafumir/rails_amp/blob/master/<%= rails_amp_canonical_url %>" />
    <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">

    <!-- Set page data type by JSON-LD with schema.org. -->
    <script type="application/ld+json">
      {
        "@context": "http://schema.org",
        "@type": "*****",
        "mainEntityOfPage": "*****",
        "datePublished": "*****"
      }
    </script>

    <!-- Write custom css sytle for amp html here. -->
    <style amp-custom>
      body {
      }
      amp-img {
      }
    </style>

    <%= rails_amp_google_analytics_head %>
    <%= rails_amp_html_header %>
  </head>
  <body>
    <%= rails_amp_google_analytics_page_tracking %>
    <%= yield %>
  </body>
</html>

Customize the page data type by JSON-LD with schema.org, and write custom css styles in the <style amp-custom> block. You can customize any other parts of this amp layout file as you like, but you need to follow the amp restrictions.

Canonical link for root_url(root_path)

When you enable amp on the controller and action for root_url, the helper rails_amp_canonical_url will put out the following canonical link tag in the amp url for root_url.

In http://example.com/home/index.amp:

<link rel="canonical" href="http://example.com/home/index" />

If you want to use the root_url as the canonical url, you should customize the codes.

<% if controller_path == 'home' && action_name == 'index'  %>
  <link rel="canonical" href="https://github.com/takafumir/rails_amp/blob/master/<%= root_url %>" />
<% else %>
  <link rel="canonical" href="https://github.com/takafumir/rails_amp/blob/master/<%= rails_amp_canonical_url %>" />
<% end %>

Usage

To access amp pages, add the amp default format at the end of the url before queries like the followings.

http://example.com/users.amp
http://example.com/users.amp?sort=name

If you change the amp default format, you have to use it as the format.

In your config/rails_amp.yml

default_format: mobile

Access the amp pages.

http://example.com/users.mobile
http://example.com/users.mobile?sort=name

When not creating another view for amp. (When the template for amp not found)

If you don't create another view for amp (When the template for amp not found), RailsAmp tries to find amp-available formats accoding to the config lookup_formats, and uses the existing html view for the amp page as is.

e.g.) When you enable amp on users#index in config and don't create another amp view like app/views/users/index.amp.erb, RailsAmp uses the existing html view like app/views/users/index.html.erb for the amp page.

Then, you can access the amp page as http://example.com/users.amp by adding the amp default format at the end of the url before queries.

When creating another view for amp.

If you want to use specialized views for amp pages, you can create another view for amp like app/views/users/index.amp.erb. When accessing http://example.com/users.amp, the amp specialized view will be used.

If you change the amp default format, create the view template with the format.

In config/rails_amp.yml:

default_format: mobile

Create the view template as app/views/users/index.mobile.erb, and access the amp page as http://example.com/users.mobile.

View Helpers

You can use a helper amp_renderable? in views. Use amp_renderable? in your existing html views to switch some codes. Here is a sample to switch codes for Twitter tweet display.

<% if amp_renderable? %>
  <!-- For amp -->
  <amp-twitter width=486 height=657
    layout="responsive"
    data-tweetid="*****"
    data-cards="hidden">
    <blockquote placeholder class="twitter-tweet" data-lang="en">*****</blockquote>
  </amp-twitter>
<% else %>
  <!-- For normal html -->
  <blockquote class="twitter-tweet" data-lang="ja">*****</blockquote>
  <script async src="https://github.com/takafumir/rails_amp/raw/master//platform.twitter.com/widgets.js" charset="utf-8"></script>
<% end %>

Supported AMP tags

RailsAmp supports a tag <amp-img> so far.

amp-img

You have to use the <amp-img> tag to render images in amp pages, instead of a normal html tag <img>. When you use a rails built-in helper image_tag in view templates, RailsAmp automatically renders images with the <amp-img> tag in amp format pages. Also, the helper image_tag renders images with the <img> tag in normal html format pages.

The <amp-img> tag requires width and height attributes. When the image_tag helper is used with a size or width, height option, the <amp-img> tag uses the option's value as its width and height attributes.

If the image_tag helper doesn't have a size or width or height option, RailsAmp computes the image size using FastImage. FastImage is a great gem to fetch the size and other information of an image quickly. If FastImage even cannot fetch the image size, the <amp-img> tag's width and height attributes are set to 300 and 300.

So, for amp format pages, I recommend that you use the image_tag helper with a size or width, height option as much as possible.

Check AMP validation

In Google Chrome browser:

  1. Start the Developer Tools.
  2. Select the Console tab.
  3. Access the amp page with #development=1 like http://localhost:3000/users.amp#development=1

If AMP validation successful shows, the amp page is valid. If some errors are detected, fix your existing html view using the amp_renderable? helper or create another amp specialized view.

References

Accelerated Mobile Pages Project

Contributing

  1. Fork it ( https://github.com/takafumir/rails_amp/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License

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

Author

Takafumi Yamano