mirror of
https://github.com/lloeki/tilt-pdf.git
synced 2025-12-06 10:34:41 +01:00
97 lines
3.2 KiB
Markdown
97 lines
3.2 KiB
Markdown
# Tilt::PDF
|
|
|
|
Integrates PDF generation into a Tilt flow for maxxed out ease of use.
|
|
|
|
Contrary to other solutions, all files will be rendered locally without relying
|
|
on a web server. It follows that even if used in a web server, no concurrent
|
|
requests are being made to render assets.
|
|
|
|
## Dependencies
|
|
|
|
This gem depends on PDFKit, which in turn requires `wkhtmltopdf`. It is
|
|
recommended to use the statically compiled version of the latter, as it is
|
|
built against a patched QT that supports more features.
|
|
|
|
## Usage as a Tilt template
|
|
|
|
Add `tilt-pdf` to your Gemfile. Also add any template engine you may optionally
|
|
want, such as `less` or `slim`.
|
|
|
|
A `foo` template is currently threefold:
|
|
|
|
- `foo.rpdf`: this file is a YAML file containing options pertaining to the PDF
|
|
generation process, such as page size, orientation, metadata, support files,
|
|
headers and footers. Some options are passed as is to PDFKit, and
|
|
subsequently to `wkhtmltopdf`.
|
|
- `foo.html`: this document can be written in any template language you need
|
|
(such as ERB or Slim), and the Tilt template resolution system via extension
|
|
chaining will apply. Tilt will pass the render block to be yielded to this
|
|
document.
|
|
- `foo.css`: this stylesheet can be written in any template language you need
|
|
(such as Sass or Less), and the Tilt template resolution system via extension
|
|
chaining will apply. Tilt will *not* pass the block to be yielded to this
|
|
template.
|
|
|
|
The three files must currently be stored in the *same* directory.
|
|
|
|
Rendering is done the usual Tilt way:
|
|
|
|
```ruby
|
|
require 'tilt-pdf'
|
|
|
|
pdf = Tilt.new('foo.rpdf').render()
|
|
```
|
|
|
|
## The rpdf file
|
|
|
|
This file contains options. If empty, it is made to 'just work' as
|
|
summplemental files will be looked up according to its basename.
|
|
|
|
- `main`: document body, overriding the default derived from the basename.
|
|
- `footer` and `header`: html that will get used for (surprise!) header and
|
|
footers.
|
|
- `stylesheets`: list of stylesheets to include (used for all html, incl.
|
|
headers/footers). Defaults to one file from the basename.
|
|
- `javascripts`: list of javascripts to include (used for all html, incl.
|
|
headers/footers). Defaults to one file from the basename.
|
|
- `pdfkit`: While a few PDFKit options are made available at the toplevel for
|
|
convenience, this key passes all options as-is to PDFKit.
|
|
|
|
Example:
|
|
|
|
```
|
|
title: Foorever young
|
|
page-size: A4
|
|
orientation: landscape
|
|
grayscale: true
|
|
margin-left: 0
|
|
margin-right: 0
|
|
margin-top: 0
|
|
margin-bottom: 0
|
|
pdfkit:
|
|
print-media-type: true
|
|
main: foorever_young.html.slim
|
|
stylesheets:
|
|
- novel.css.less
|
|
- common.css
|
|
javascripts:
|
|
- page_numbering.js.coffee
|
|
footer: footer.html.slim
|
|
```
|
|
|
|
Filenames can be relative or absolute. When relative, they will be evaluated
|
|
as based from the rpdf file.
|
|
|
|
## Rails and ActionView integration
|
|
|
|
Require `tilt/pdf/rails` if you want to set up and register `tilt-pdf` as an
|
|
ActionView template handler. You can do it in an initializer, or straight from
|
|
the Gemfile:
|
|
|
|
```ruby
|
|
gem 'tilt-pdf', require: 'tilt/pdf/rails'
|
|
```
|
|
|
|
Put your three template files *together* in the relevant `app/views/foo` view
|
|
directory, or use absolute paths using application/engine root. Work is in
|
|
progress to enable better integration with Rails file layout.
|