API

James Adam edited this page Nov 6, 2013 · 7 revisions

There are two basic things the backend server API provides: printing, and previewing. Let's start with the previewing.

Preview

To preview, you make a simple request:

GET http://printer.exciting.io/preview?url=<url>

A url parameter can be sent as either a GET or a POST request.

You can also POST with HTML in the content parameter; this is particularly useful if you can’t make your content available at a publicly-accessible URL.

The preview action also accepts a width parameter, which defaults to "384". You can use this if the printer you are targeting has a different usable width.

However you send the request, you’ll be redirected to a page where, in a few seconds, you’ll see an image that approximates what will be sent to the printer (although there is still some further processing to make it monochrome, for example).

If you make the request programmatically, you’ll probably be returned a JSON object which contains the URL for the preview.

Example

# Generate a simple html page
$ cat > /tmp/printer-test.html
<html><head></head><body><h1>Printer test page</h1></body></html>
<ctrl-d to escape>

# Send the content of the html to the printer preview
$ curl http://printer.exciting.io/preview --data-urlencode content@/tmp/printer-test.html
# or
$ curl http://printer.exciting.io/preview -F"content=</tmp/printer-test.html"
{"location":"http://printer.exciting.io/preview/pending/<id-here>"}

# Finally, visit the location returned in the JSON response above, e.g.
$ open http://printer.exciting.io/preview/pending/<id-here>

Printing

To print a page, you need to make a very similar request:

GET http://printer.exciting.io/print/<printer_id>?url=<url>

The server will process the page at that URL, and in a short while (normally less than a minute) it will be available for the printer with that ID to download.

You can also send a POST request using either the url or content parameters, as above.

FYI: The render process

When rendering (either for preview, or for printing), the server will remove any preview class that exists on the body of the page, and then attempt to convert it to a 384-pixel-wide image.

This preview class can be very useful if you want to be able to design the page in “simulated printout” form, but leave the page unadorned by backgrounds and margins when it is being processed for printing. You can achieve this by hiding any extraneous items and changing margins and backgrounds in the absence of the preview class.

The server provides a sample stylesheet that will do this very simply for you.

The rendering is performed by phantomjs running on Linux, and so there are a fairly limited number of system fonts available to you. It’s worth bearing this in mind.

Of course, if you know how to install more fonts, you can always run your own copy of the server yourself; my source code is available for anyone to use and improve on.

Alternatively, if you want to improve phantomjs to use web-fonts, then I’d greatly appreciate it!