Bookends

A Rails engine serving the shared header and footer for Heroku Marketing-styled properties.

Installation

Add this line to your application's Gemfile:

gem 'bookends', '<current version>'

And then execute:

bundle install

Usage

rails g bookends:install

Sites using Bookends

Please make sure the owners of the following properties are apprised of changes to Bookends:

Legacy

There's a legacy branch with bookends 9.x, which relied on Bourbon and Neat and is still used in elements.

Development

Spin up

After checking out the repo, run bundle install to install dependencies. Then, run bin/test to run the tests.

Install and release

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, commit changes, 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.

See all rake tasks with rake -T

Testing it in an app locally

Rails version

  1. In a terminal session, change directory to spec/test_app
  2. Ensure that any changes in a consumer app are made in the test_app (a skeleton Rails app)
  3. Run rails s
  4. open http://localhost:3000

Jekyll version

Be sure to use the 2.x version on the two_ex branch

  1. gem install bookends --local ../bookends/pkg/bookends-<latest_pkg> from the root of the Jekyll project.

Run rake build from bookends if there are no *.gem files in bookends/pkg/

  1. bundle install from the Jekyll application
  2. bookends install from the Jekyll application
  3. Boot up the Jekyll application
  4. If you make changes to Bookends's templates, make sure to run the installer from step 3.

Glostick Notes

Glostick is a project by HIT to standardize the header across Heroku properties. Naturally, this fits well with Bookends. We use styles and slightly modified markup from Glostick in Bookends. Important things to note:

  • Bookends uses a helper to decode cookie sent from API under the heroku.com domain.
    • This cookie contains a logged in user's email and display name.
    • Fernet must be included in the project with Bookends as it is used to decode the cookie.
    • To decode the cookie, Bookends requires Fernet (> 2.0) to decode the cookie
    • A shared secret provided by API must be set to the SESSION_COOKIE_SECRET_PRIMARY config var. Bookends also provides a fall back SESSION_COOKIE_SECRET_SECONDARY should that first value need to change.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/heroku/bookends.