Thumbnails

How do you show users what a template or a created document looks like before they download it? ReportingCloud renders the pages as images: a preview of every template in a template picker, the first page of each invoice in a list, a page overview before a document is sent. Two endpoints do this, one for a document you send with the request and one for a template in your template storage, and both return one image per page in the size and format you choose.

How Thumbnails Work

The two endpoints take the same options and differ in where the document comes from:

Both take these optional query parameters:

The response is a JSON array of Base64 strings, one image per page, in page order. If fromPage is greater than toPage, the response is null instead of an array.

A request is refused with 400 Bad Request and a plain-text message in these cases:

• "Template not valid": zoomFactor is not between 10 and 400, or fromPage is less than 1.
• "Page numbers not valid": fromPage or toPage is greater than the number of pages.
• "The image format is not supported": imageFormat is not one of the four formats.
• "No merge data found in body": the body of document/thumbnails is empty or is not a JSON string.
• "Template doesn't exist in storage": the template name of templates/thumbnails is not in the storage.

A zoomFactor, fromPage or toPage that is not an integer is ignored, and its default is used, but one given without a value is refused with 400 and the JSON body {"Message":"The request is invalid."}. An empty imageFormat gets 500 Internal Server Error, and so does a body of document/thumbnails whose JSON string is not Base64. Data in a format that document/thumbnails doesn't support is not refused: it is rendered as plain text.

Both endpoints count against the document quota: each successful request adds one document, however many pages it renders, and a response of null counts as well. They have no test parameter. Plans and Licensing lists the quota of each plan, and every request needs the Authorization header that Authentication describes.

Create Thumbnails of a Document With curl

The following commands render the first three pages of invoice.docx at half their size and save each image as a file:

# Wrap the Base64 string of the document in a JSON string
base64 -w 0 invoice.docx | jq -Rs . > document.json

curl "https://api.reporting.cloud/v1/document/thumbnails?zoomFactor=50&fromPage=1&toPage=3&imageFormat=PNG" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json \
  --output thumbnails.json

# Decode each Base64 string of the array into page-1.png, page-2.png ...
count=$(jq length thumbnails.json)
for i in $(seq 0 $((count - 1))); do
  jq -r ".[$i]" thumbnails.json | base64 -d > "page-$((i + 1)).png"
done

The commands work as follows:

• base64 -w 0 encodes the file on one line, and jq -Rs . makes a JSON string of it, which is the whole body.
• The query parameters select the pages, the size and the format. Keep the URL in quotes: the shell would otherwise treat each & as the end of a command.
• The response is an array with one Base64 string per page. jq -r ".[$i]" takes one element without quotes, and base64 -d decodes it into an image file.

Create Thumbnails of a Stored Template With curl

A template in the storage needs no body. The following request renders the first page of the demo template sample_invoice.tx, which every trial account has in its storage, as a JPG image at 50 percent:

curl "https://api.reporting.cloud/v1/templates/thumbnails?templateName=sample_invoice.tx&zoomFactor=50&fromPage=1&toPage=1&imageFormat=JPG" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  --output thumbnails.json

jq -r ".[0]" thumbnails.json | base64 -d > sample-invoice.jpg

A document that you have created with the merge or the convert endpoint doesn't have to be uploaded to the storage first: send it to POST /v1/document/thumbnails.

Create Thumbnails With .NET

The .NET SDK, the NuGet package TXTextControl.ReportingCloud, has a method for each endpoint, among them the two thumbnail endpoints. The following console application renders three pages of a document and the first page of a stored template:

using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(
    Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

byte[] document = File.ReadAllBytes("invoice.docx");

// Pages 1 to 3 at a zoom factor of 50 percent
List<string> pages = rc.GetDocumentThumbnails(document, 50, 1, 3, ImageFormat.PNG);

for (int i = 0; i < pages.Count; i++)
{
    // Each element is a Base64 string: decode it into the image file
    File.WriteAllBytes($"page-{i + 1}.png", Convert.FromBase64String(pages[i]));
}

// The first page of a template in the storage
List<string> preview = rc.GetTemplateThumbnails("sample_invoice.tx", 50, 1, 1, ImageFormat.PNG);
File.WriteAllBytes("sample-invoice.png", Convert.FromBase64String(preview[0]));

The code works as follows:

• GetDocumentThumbnails takes the document as a byte array, then the zoom factor, the first and the last page and an ImageFormat value: PNG, JPG, GIF or BMP. All arguments after the document are optional, with the defaults 100, 1, 0 and ImageFormat.PNG; a last page of 0 renders up to the end of the document.
• GetTemplateThumbnails takes the template name and the zoom factor, followed by the same optional arguments.
• In an application for .NET or .NET Core, both methods return a List<string> of Base64 strings, which Convert.FromBase64String decodes. In an application for .NET Framework, the package returns a List<System.Drawing.Image> instead, with images you can save with Image.Save.
• A refused request throws an ArgumentException whose message is the response body.

In the PHP SDK, the methods are getDocumentThumbnails($documentFilename, $zoomFactor, $fromPage, $toPage, $imageFormat) and getTemplateThumbnails($templateName, $zoomFactor, $fromPage, $toPage, $imageFormat). All five arguments are required, page numbers start at 1, and each element of the returned array is the binary data of one image. The Java and Ruby SDKs offer template thumbnails only.

Choose the Size and the Pages

• Size. zoomFactor is a percentage of the page size, from 10 to 400. A value of 100, the default, renders the page at its full size at 96 dpi, 816 by 1056 pixels for a Letter page; smaller values give smaller images for a preview list.
• First page only. For a single preview image, set fromPage=1&toPage=1, or pass 1, 1 as the page arguments in the SDKs.
• Every page. Leave out fromPage and toPage, or set toPage=0, and the array has one image for every page. Every request counts as one document, so rendering all pages at once uses less quota than one request per page.
• Page count first. To know how many pages a stored template has before you render it, ask the pagecount endpoint that Managing Templates describes.

Next Steps

• Converting Documents: convert the document itself into another format.
• Managing Templates: upload templates, list them and read their page count.
• Supported File Formats: the formats of each endpoint.
• Errors and Status Codes: what a refused request means.