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

## Installation

Add this line to your application's Gemfile:

```ruby
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:

* [www](https://github.com/heroku/www)
* [blog](https://github.com/heroku/blog)
* [engineering](https://github.com/heroku/engineering)
* [elements](https://github.com/heroku/elements)

## Development

### Spin up
After checking out the repo, run `bin/setup` to install dependencies. Then, run
`rake` 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`, 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](https://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. `open http://localhost:3000`
4. `rails s` and refresh your browser

#### 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/`
2. `bundle install` from the Jekyll application
3. `bookends install` from the Jekyll application
4. boot up the Jekyll application
5. If you make changes to Bookends's templates, make sure to run the installer from step 3.

## Glostick Notes
[Glostick](https://github.com/heroku/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](https://github.com/fernet/fernet-rb) 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.