amp-html

Reliable high-:zap: apps with AMP & Rails.

amp-html is a universal solution to integrate the AMP Project into your Rails app with ease. It enables you to quickly spin-up, build and test your app with AMP, while fulfilling the app's unique requirements. It comes with a bunch of superpowers like user authentication, notifications, blogs, animations and support for assets in AMP.

Use the powerful features of AMP to make your Rails app consistently fast, beautiful and high-performing across devices and distribution platforms.

Follow the Getting Started Guide, Demo

• Information
  • Quick info
  • The amp-html wiki
  • Bug reports
  • Example applications
  • Contributing
  • Versioning
  • Deprecations
• Installation
  • Generators
  • Test and validate AMP
• Usage
  • Views
  • Controllers
  • SplitView
• Guides
• Components
• Configuration
• To Do
• Contributors
• License

Changelog, Grab it from Rubygems

Rails >= 5.0
Ruby >= 2.3

The amp-html Wiki has lots of additional information about amp-html including many "how-to" articles and answers to the most frequently asked questions. Please browse the Wiki after finishing this README:

https://github.com/jonhue/amp-html/wiki

If you discover a problem with amp-html, we would like to know about it. However, we ask that you please review these guidelines before submitting a bug report:

https://github.com/jonhue/amp-html/wiki/Bug-reports

There are a few example applications available on GitHub that demonstrate various features of amp-html. You can view them here:

https://github.com/jonhue/amp-html/wiki/Example-Applications

We hope that you will consider contributing to amp-html. Please read this short overview for some information about how to get started:

Contributing, Code of Conduct

amp-html follows Semantic Versioning 2.0 as defined at http://semver.org.

Deprecations are combined with new major releases of amp-html. You can see a full list of past and future deprecations here.

You can also follow the Getting Started Guide.

amp-html works with Rails 5 onwards. You can add it to your Gemfile with:

gem 'amp-html'

And then execute:

$ bundle

Or install it yourself as:

$ gem install amp-html

If you always want to be up to date fetch the latest from GitHub in your Gemfile:

gem 'amp-html', github: 'jonhue/amp-html'

Now generate the files necessary:

$ rails g mozaic:install
$ rails g amp_html

Replace the contents of your app/views/layouts/application.html.erb file with:

= amp_mozaic do
    = yield

Lastly, make sure to remove Turbolinks from your apps asset pipeline (app/assets/javascripts/application.js) as it does not work well with AMP.

You can check whether your document is using AMP or not by using the amp? method:

- if amp?
    = component 'amp/mustache' do
        -# ...

Note: This method is also available at controller level.

When you are using SplitView along with media/form/etc. elements, you don't have to use amp? to render the appropriate element. amp-html automatically overrides the default Rails helpers if your document is using AMP.

If you are using SplitView, you are able to override the default format (html/amp) by passing the amp parameter. However in a lot of cases you want to specify the format from within the path of the URL:

class PostsController < ApplicationController

    def index
        amp_path # to use `'amp'` as path
        amp_path 'custom-path' # to use `'custom-path'` as path
    end

end

You are also able to manually enable or disable AMP for a specific controller action:

class PostsController < ApplicationController

    def index
        amp # to enable AMP
        amp = false # to disable AMP
    end

end

SplitView allows you to serve html and amp versions of your views. To get started, enable and configure SplitView:

AmpHtml.configure do |config|
    config.split_view = true
    config.split_view_default = 'amp'
end

Now you can use amp-html's view and controller methods to determine whether a document uses html or amp as format.

Whether you are just getting started or you are looking to implement some of the powerful features of amp-html, the guides in the amp-html wiki are here to your rescue.

https://github.com/jonhue/amp-html/wiki/Guides

amp-html is component based. You can learn more about components and find the full reference in the amp-html wiki.

https://github.com/jonhue/amp-html/wiki/Docs

You can configure amp-html by passing a block to configure. This can be done in config/initializers/amp-html.rb:

AmpHtml.configure do |config|
    config.split_view = false
end

• split_view Enable SplitView to allow for AMP enabled and AMP disabled versions of your views. Takes a boolean. Defaults to false.
• split_view_default The default view version if no amp param is present in the request. Must be either 'amp' or 'html'. Defaults to 'amp'.

Here is the full list of current projects.

To propose your ideas, initiate the discussion by adding a new issue.

Give the people some ❤️ who are working on this project. See them all at:

https://github.com/jonhue/amp-html/graphs/contributors

MIT License

Copyright (c) 2017 Jonas Hübotter

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.