DEV Community

loading...
Cover image for Magazine the WordPress Plugin for PrintCSS

Magazine the WordPress Plugin for PrintCSS

azettl profile image Andreas Originally published at printcss.blog ・7 min read

In the last few weeks, I am working on a WordPress Plugin, which allows you to generate PDFs from one or multiple posts/pages. Initially, it was designed to work only with my PrintCSS Cloud, which I introduced in the previous article, but now the plugin is opened to any rendering tool you want to use.

Installation and Setup

All you need to do to install the plugin is download it from Gumroad. You can pay what you want starting from $0!

Once you installed the ZIP file via the WordPress ‘Upload Plugins’ function or placed the extracted folder in your ‘wp-content/plugins’ directory, you need to activate the plugin.

After the installation, you will need to provide an API key or locally installed rendering tool command on the settings page under ‘Settings’ > ‘Magazine’.

The Settings of the Magazine PluginThe Settings of the Magazine Plugin

On the settings screen, you find the following options.

  • Rendering Tool: Depending on the filled API Key and Local Command Options, you see the supported rendering tools here. You need to use at least one of the API or the local command options for a rendering tool to appear in this selection.

  • RapidAPI Key: To send the PrintCSS Cloud API request, you need to subscribe to a plan on RapidAPI. With this, you get the API key required to authenticate with the PrintCSS Cloud REST service. The PrintCSS Cloud supports the rendering tools WeasyPrint, PagedJS, and Vivliostyle.

  • DocRaptor Key: To send the DocRaptor API request, you need to subscribe to a plan on docraptor.com. With this, you get the API key that is required to authenticate with the REST service.

  • Typeset.sh Project Key & Project Token: To send the request to the typeset.sh API, you need to subscribe to a plan on typeset.sh. With this, you get the project key and token required to authenticate with their REST service.

  • Local Command: If you have a PDF rendering tool installed locally, you can provide the command here, be aware that the tool needs to support getting the HTML via STDIN and needs to return the PDF via STDOUT.

  • AH Formatter Example: /usr/AHFormatterV71_64/run.sh -x 4 -d @STDIN -o @STDOUT

  • Prince Example: prince — no-warn-css — javascript -

  • PDFreactor Example: cd /path/to/sh/script/ && ./pdfreactor.sh (Get the script on GitHub)

Change the Demo Theme and Add Multiple Themes

All magazine themes are placed in the ‘wp-content/magazine_themes’ folder and can be directly edited there. If you prefer editing your theme directly in the WordPress UI, you can do so under ‘Appearance’ > ‘Magazine’.

The Magazine Theme EditorThe Magazine Theme Editor

A magazine theme for PDF generation is using the following files. All of them are optional. If you use the magazine theme editor, all files will be generated even if you do not provide any content for some of them.

Besides editing the theme, you can also duplicate, upload and download themes from this section in the WordPress backend.

HTML

In the HTML section of the magazine theme editor, you can edit all HTML files.

  • Prefix (prefix.html): The prefix HTML you can use for front covers or intros, basically anything which should be added only once at the beginning of the PDF. In the prefix, you can not use any placeholders.

  • Post (post.html): The post HTML will be loaded whenever you want to render a Blogpost PDF; this file gets added once per selected Blogpost. So if you choose 5 Blogposts, this HTML gets repeated five times. Within the post HTML, you can use any placeholders, for example, the {{title}} to always show the current Blogpost title.

  • Page (page.html): The page HTML will be loaded whenever you want to render a PDF from a page. This file gets added once per selected page. So if you choose five pages, this HTML gets repeated five times. Within the page HTML, you can use any placeholders, for example, the {{title}} to always show the current page title.

  • Postfix (postfix.html): The postfix HTML you can use for back covers or indexes, basically anything which should be added only once at the end of the PDF. In the postfix, you can not use any placeholders.

You can leave any of these HTML files empty if you do not need them. For example, if you do not need a cover, do not put content into the prefix HTML.

CSS

In the magazine theme editor’s CSS section, you can edit all CSS files of any theme.

  • Main (style.css): The main CSS is loaded for any rendering you do. In the main CSS, you can not use any placeholders.

  • Post (post.css): The post CSS will be loaded whenever you want to render a Blogpost PDF; this file gets added once per selected Blogpost. So if you choose 5 Blogposts, this CSS gets repeated five times. Within the post CSS, you can use any placeholders, for example, the {{slug}} to get one class per Blogpost slug.

  • Page (page.css): The page CSS will be loaded whenever you want to render a page PDF; this file gets added once per selected page. So if you choose five pages, this CSS gets repeated five times. Within the post CSS, you can use any placeholders, for example, the {{slug}} to get one class per page slug.

You can also leave any of these CSS files empty if you do not need them. For example, if you do not need a Blogpost specific CSS, do not put content into the post CSS file.

JavaScript

In the magazine theme editor’s JavaScript section, you can edit all JavaScript files of your theme. Be aware that some rendering tools only support HTML and CSS.

  • Main (script.js): The main JavaScript is loaded for any rendering you do. In the main JavaScript, you can not use any placeholders.

  • Post (post.js): The post JavaScript will be loaded whenever you want to render a Blogpost PDF; this file gets added once per selected Blogpost. So if you choose 5 Blogposts, this JavaScript gets repeated five times. Within the post JavaScript, you can use any placeholders, for example, the {{slug}} to get one class per Blogpost slug.

  • Page (page.js): The page JavaScript will be loaded whenever you want to render a page PDF; this file gets added once per selected page. So if you choose five pages, this JavaScript gets repeated five times. Within the post JavaScript, you can use any placeholders, for example, the {{slug}} to get one class per page slug.

You can leave any of these JavaScript files empty if you do not need them. For example, if you do not need a Blogpost specific JavaScript, do not put content into the post JavaScript file.

The Placeholders

The placeholders {{slug}}, {{title}}, {{feature_image}} and {{content}} are for the post/page slug, title, feature image and content. Additionally you can use the placeholders {{author}}, {{date}}, {{date_gmt}}, {{excerpt}}, {{status}}. If you need to show the date of the post/page in a different format you can use the placeholders {{year}}, {{month}}, {{day}}, {{hour}}, {{minute}}.

Please be aware that images need to be available via a public URL for the APIs to use them.

ACF is also supported. Just add {{ACF_YOUR_FIELD_NAME}}. Important: use the name, not the label!

The Widget

If your WordPress theme support widgets, you can configure a simple PDF rendering widget for your frontend. The widget options are the title of your PDF rendering link and the magazine theme you want to render the PDF with. This way, you allow your users to generate PDFs anytime they want to.

The Magazine Render PDF Widget with Text and Theme Options.The Magazine Render PDF Widget with Text and Theme Options.

Shortcode

You can also use a shortcode to display a link to render the PDF in any location of your post or page.

The primary usage is just the tag and an attribute that defines the theme [magazine theme="Demo"]. If you also want to change the text of the link, you can pass it with [magazine theme="Demo" text="Click here for PDF Version"].

Backend and Bulk PDF Rendering

When you want to render a PDF from one or multiple pages/blog posts, just navigate to the ‘All Posts’ or ‘All Pages’ sites in the backend. Select the pages/posts you want to have in your PDF and click on the ‘Bulk Actions’ dropdown. Depending on your magazine themes, you will see one or multiple entries like ‘Render PDF with Demo Theme’, select the theme you like and click on apply. Currently, the rendering process is always synchronous, so you will need to wait for the API/local tool to answer.

Bulk Actions for the three different Magazine Themes on my system.Bulk Actions for the three different Magazine Themes on my system.

The resulting PDF is stored in the Media Library. It is also offered to you for downloading in a notification on the page where you started the rendering process.

Result NotificationResult Notification

The plugin is currently in alpha status, and I am looking forward to your feedback and ideas on how to improve it.

Lastly, again the link for you to download the plugin: Magazine (gumroad.com).

Discussion (2)

Collapse
florincornea profile image
Cornea Florin

I've worked with WordPress in the past and this plugin seems to be amazing, I will definitely give it a try and also, probably I will start reading your entire article series from the beginning. Great work!!

Collapse
azettl profile image
Andreas Author

Thanks a lot! Let me know if you have any questions or face any issues with the plugin or PrintCSS!

Forem Open with the Forem app