inniAccounts Invoice Design Kit

What is this?

This design kit allows you to create completely personalised invoice layouts to use within inniAccounts. Invoice layouts are simply one or more HTML files and an SCSS style file. You'll use Liquid markup in your HTML file to insert data from your invoice. Your HTML invoice layout will be transformed into a PDF by our servers using wkhtmltopdf - an open source PDF generator.

This kit contains Ruby scripts to help you develop your invoice: the scripts will create HTML and PDF previews of your layout.

Note: If you just want to change the colour or add a logo to an existing invoice layout then you don't need this kit - you can do this via the inniAccounts application. This kit is for confident HTML users who want to create custom layouts.

Quick start

• You'll need Ruby, Bundler & Git installed
• Fork this repository
• Install wkhtmltopdf
• Install fonts locally from lib/fonts
• Run bundle install to install the Ruby Gems
• Run guard - this will watch source files in invoice_designs for changes and automagically output previews to invoice_previews

Creating a layout

To create an invoice layout, simply create a new subdirectory in invoice_designs and give it a reasonable name. To get started, copy the starter theme 'blank' - copy body.html, footer.html, header.html and style.scss from ./blank into your new directory. Guard should pick up the change and build a preview for you in invoice_previews. You can now hack away.

Anatomy of a layout

HTML templates

Your layout consists of three HTML files - the body, the header and the footer. The header and footer will be repeated on every page of your invoice. The body will be split over multiple pages, if needed. You should use liquid markup in your HTML to insert invoice data at run time, you'll also use Liquid tags to create the loop for outputting the invoice lines (i.e. {% for Line in Invoice.Lines %}...). You can view the data model for an invoice in lib/data.yaml.

Stylesheet (style.scss)

You'll (obviously) use style.scss to apply formatting to your HTML. We use SCSS to allow you to set and use variable, plus, of course, write concise CSS. Your stylesheet must start with the following:

/* Theme settings: */
$name:                'My amazing invoice';
$author:              'Cath Green, Camdle Ltd';
$orientation:         'Portrait';
$page-margin-top:     11.5cm;
$page-margin-bottom:  1.5cm;
$page-margin-left:    1cm;
$page-margin-right:   1cm;

• The name and author will be shown in the layout picker in the inniAccounts app.
• Orientation: Portrait or Landscape
• Margins: must be specified in cm. The top and bottom margin determine the height of your header and footer. See the notes in the SCSS file in the blank theme for details on how to set these correctly.

There are four optional variables to allow the user to customise the fonts and colours used in your layout. The value of these can be set by the user when they choose their invoice layout in the app. If you use these variables in your stylesheet the user will be prompted to set them - if you don't, they won't appear in the user interface. It's a good idea to set some default values. The code block looks like this:

/* User settings & defaults: */
$font-title: Helvetica, sans-serif  !default;
$font-body: Helvetica, sans-serif  !default;
$color-primary: #DE4498 !default;
$color-secondary: #333 !default;

In this case, by specifying these four variables, the user will be prompted to set them. Our invoice renderer will prepend your stylesheet at runtime with the user's values. That's why we're using !default above - it means that it will only use your default value if the user hasn't set one.

The final run-time variable is $logo. We'll base64 encode the user's logo image (if set) and prepend your stylesheet. To use the logo in your stylesheet, you can use code like this:

@if $logo {
  #logo {
    content:$logo;
      // We need to multiple the target size (6x3cm) by 1.25
      max-width:6cm * 1.25;
      max-height:3cm * 1.25;
  }
}

Helpful hints

Header and footer sizing

To correctly size your header and footer, look at the SCSS in the blanks theme. TL;DR: set $page-margin-top & $page-margin-bottom to the height of your header / footer, including any page top / bottom margins. Then set $true-margin-top & $true-margin-bottom to the page margins you desire.

Developing with a logo placeholder

Add this to the top of your stylesheet: $logo: url('http://placehold.it/350x100')

Guard problems?

If guard isn't working for you, you can also just issue a rake command to build your preview

Helpful browser extension

Chrome's LivePage extension is very helpful - it will automatically reload the preview page when you edit your source. It's great for dual monitor development.

Fonts

The following fonts are available to use in invoices:

• Windows Server system fonts
• The fonts in lib/fonts, including Font Awesome for iconography

These fonts are installed and available on our production servers. At the moment it is not possible to use external fonts (e.g. web fonts loaded via CSS) due to rendering bugs with wkhtmltopdf.

Font combinations

Here's a few useful font combos (heading + body)

• Lobster + Cabin
• Montserrat + Neuton
• Montserrat + Cardo
• Montserrat + Playfair Display
• Lato + Merriweather
• Oswald + Quattrocento
• Dancing Script + EB Garamond
• Fjalla One + Cantarell
• Quicksand + EB Garamond

Testing your layout

To test your layout, issue the command rake qa [name of your theme's directory]. This will generate 5 different invoice PDFs: short; long; no reference number; overseas and one with a customised style. Take a look at all of the PDFs to ensure they've rendered as you expect.

Sharing your layouts

You can use this kit to create layouts for your own personal use. We also welcome high quality layouts to share with the rest of the inniAccounts community. If you'd like to share your design please issue a pull request and we'll take a look at your layout.