Shine PDF Documentation
Shine PDF uses the mPDF library to generate a PDF on-the-fly from an ExpressionEngine template.
At its core, Shine PDF is simply a tag pair that accepts channel:entries parameters and outputs entry data accordingly:
{exp:shine_pdf:make channel="good" url_title="vibes"} ... {/exp:shine_pdf:make}
...but let's take a closer look at just what the mPDF library can do with your templates.
OUTPUTTING HEADERS AND FOOTERS
Everything between the bespoke {pdf_header}{/pdf_header}
and {pdf_footer}{/pdf_footer}
tag pairs will be extracted from the document and placed in the header and footer areas of every PDF page.
Listen very carefully - any ExpressionEngine data held between these tags will be parsed only once.
SPECIAL TAGS
No, these are not standards compliant. At all. However, neither is PDF, so you're quite safe.
<pagebreak/>
- Does exactly what it says on the tin - if you're exporting via a WYSIWYG editor you might want to consult the Oracle on how to add custom elements to the editor's formatting toolbar. This is definitely doable with Wygwam (CKeditor) and TinyMCE. Note that this tag is self-closing.
[page]
- Prints the current page number.
[total_pages]
- Prints the number of pages in the entire document, beginning at 1.
PARSING CSS
Just add any CSS files you deem relevant somewhere between the {exp:shine_pdf:make}
tag pair.
Don't worry about where they are in the code - as mentioned above, we're not relying on any doctype-related standards rules.
METADATA
Simply write the document's title in a
<title></title>
HTML tag pair. Other metadata options to follow.
PAGE FORMATTING
This is likely what you've been waiting for. mPDF provides a number of page formatting options, all of which are voluntary. The default document produced comprises portrait-formatted, A4 (210mm x 297mm) pages, with left & right margins of 15mm and top & bottom margins of 16mm. Tag options (and their defaults) are listed below. Units default to millimetres for canvas measurements, and to points for typographical sizes.
Please bear in mind that none of these tags is compulsory, and any & all can be ommitted from the module tag pair as you wish. Please note also that all parameters that can be supplied to the {exp:channel:entries}
tag pair can be supplied to the {exp:shine_pdf:make}
tag pair.
{exp:shine_pdf:make
format="A4"
default_font_size="11"
default_font="Helvetica"
margin_left="15"
margin_right="15"
margin_top="16"
margin_bottom="16"
margin_header="9"
margin_footer="9"
orientation="p"
margin_top_auto="no"
margin_bottom_auto="no"
}
PARAMETERS UP CLOSE
format
A0, A1, A2, A3, A4 (default), A5, A6, A7, A8, A9, A10
B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10
C0, C1, C2, C3, C4, C5, C6, C7, C8, C9, C10
4A0, 2A0
RA0, RA4
SRA0, SRA1, SRA2, SRA3, SRA4
Letter, Legal, Executive, Folio Demy
Royal A (Type A paperback 111x178mm), Royal B (Type B paperback 128x198mm)
default_font_size
Any size in points. Numerical value only. This is the font size that will be defaulted to if none is specified by your CSS.
default_font
Helvetica, Times or Courier accepted. In order to provide a failsafe, please ensure that any custom fonts specified within your CSS are stored locally on your machine as well and referenced by their default family names. The realms of web font embedding remain enemy territory to this day.
margin_left
The left page margin in millimetres. Numerical value only.
margin_right
The right page margin in millimetres. Numerical value only.
margin_top
The top margin down to the page's body content, in millimetres. Numerical value only. If a header is set and margin_top_auto is set to "no", ensure that this margin takes into account the height of the header.
margin_bottom
The bottom margin up to the page's body content, in millimetres. Numerical value only. If a footer is set and margin_bottom_auto is set to "no", ensure that this margin takes into account the height of the footer.
margin_header
The header's margin from the top of the page in millimetres. Numerical value only, and only pertinent if a header is set.
margin_footer
The footer's margin from the bottom of the page in millimetres. Numerical value only. Only relevant if a footer is set.
orientation
Accepts "portrait" or "landscape".
margin_top_auto
pad
- The value for margin_top
will be used to set a fixed distance between the bottom of the header and the top of the document body.
stretch
- The value for margin_top
sets a minimum distance between the top of the page and the top of the document body.
no
(default) - margin_top
and margin_header
need to be specified explicitly in order for the page to display correctly. If both of the above options do not work for you, rest assured this one will.
margin_bottom_auto
As above, except applies to the relationship between the footer and the bottom of the document.
CAVEATS
All conditionals in your PDF template will only be parsed inside the {exp:shine_pdf:make}
tag pair.
Also, you will not be able to use {embed}
tags within the template. Not that they should really be necessary.