Skip to content
Branding and other superficial helpers for AAF applications.
HTML Ruby CSS JavaScript
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
doc
lib
sample/rails
spec
.gitignore
.rspec
.rubocop.yml
Gemfile
Guardfile
LICENSE
README.md
Rakefile
aaf-lipstick.gemspec

README.md

AAF Lipstick

Gem Version Build Status Dependency Status Code Climate Coverage Status

Branding and other superficial helpers for Rails applications at AAF.

Copyright 2014-2016, Australian Access Federation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Installation

Dependencies

We have RMagick as a dependency, which requires ImageMagick. This is best achieved on MacOSX using Homebrew:

brew install imagemagick ghostscript

Installing ghostscript fixes an issue where ImageMagick can't find any of the OSX fonts.

On Linux, just install ImageMagick from the package manager.

Rails

Ensure your Gemfile contains these dependencies:

source 'https://rubygems.org'

gem 'rails', '~> 4.2.5'
gem 'sass-rails'
gem 'aaf-lipstick'
gem 'torba-rails'

Perform the necessary setup to include Torba in the Rails application. Create a Torbafile which contains the following:

npm package: 'bootstrap', version: '3.3.6',
    import: %w(dist/css/bootstrap.css dist/js/bootstrap.js dist/fonts/*)
npm package: 'jquery', version: '2.2.1', import: %w(dist/jquery.js)
npm package: 'jquery-validation', version: '1.15.0',
    import: %w(dist/jquery.validate.js)
npm package: 'pickadate', version: '3.5.6',
    import: %w(lib/picker.js lib/picker.date.js
               lib/themes/classic.css lib/themes/classic.date.css)

Ensure you're using the most recent version of each dependency, remembering that Torba requires you to explicitly specify the version you want to use. Lipstick expects to find the assets at the paths created when importing as shown above. If you've updated a dependency version, and are having issues with asset paths, ensure they are still being imported correctly.

Run bundle update and then torba pack to install all the dependencies.

Copy the sample layout, and customise to suit your application.

Include the desired helpers in your ApplicationHelper:

module ApplicationHelper
  include Lipstick::Helpers::LayoutHelper
  include Lipstick::Helpers::NavHelper
  include Lipstick::Helpers::FormHelper

  # ...
end

Include the CSS in your application.css:

//= require aaf-lipstick

And the JS in your application.js:

//= require aaf-lipstick

Include the dynamic error pages in your ApplicationController:

class ApplicationController < ActionController::Base
  include Lipstick::DynamicErrors

Delete your pre-existing static error pages:

git rm public/404.html public/422.html public/500.html

Git ignore these same files (.gitignore):

public/404.html
public/422.html
public/500.html

Generate the static error pages in an initializer (ie. config/initializers/static_errors.rb):

require 'lipstick/errors/static_errors'

Lipstick::StaticErrors.write_public_error_files

Email Template

To use an email banner for message delivery, first register the Sprockets processor with the application, e.g.:

args = ['.aafimg', Lipstick::Images::Processor]
args << { silence_deprecation: true } if Sprockets::VERSION.start_with?('3')
Sprockets.register_engine(*args)

WARN: This only applies to current Rails 4.x and Rails 5.0.x applications. See Lipstick issue 65 for background on deprecation silence and when we'll be addressing it correctly.

Then, create an asset called (for example) app/assets/images/email_banner.png.aafimg:

email_banner(title: 'AAF Style Test',
             environment: 'Rails')

The banner will be compiled into a PNG by the asset pipeline. Once this is done, an email body can be generated in a controller by running:

image = view_context.image_url('email_banner.png')
body = Lipstick::EmailMessage.new(title: 'Test', content: email_body,
                                  image_url: image)

The content received by Lipstick::EmailMessage is processed using Kramdown, so it is acceptable to use mixed markdown and HTML. Take care not to allow arbitrary input from users to be added to the email content, as it is not possible for Lipstick to detect and automatically escape the content.

Mail delivery is not handled by Lipstick.

If you'd like to provide your own .html.erb template, you can provide the optional template parameter:

erb = File.read('./app/views/layouts/email_template.html.erb')
body = Lipstick::EmailMessage.new(title: 'Test', image_url: ..., content: ...,
                                  template: erb)
You can’t perform that action at this time.