Aspose Document Conversion Add-on
Overview
Cloudinary is a cloud-based service that provides an end-to-end image management solution including uploads, storage, manipulations, optimizations and delivery.
Cloudinary offers a very rich set of image manipulation and format conversion capabilities. Cloudinary allows you to upload images and non-image raw files to the cloud. Images and PDF files can be converted to various image formats and can be cropped on-the-fly and further manipulated to match the graphic design of your websites and mobile applications.
Aspose is a leading vendor of development components, including a powerful set of file management and conversion products. Cloudinary provides an add-on for using Aspose's Office document conversion capabilities, fully integrated into Cloudinary's image management and manipulation pipeline.
With Aspose's document conversion add-on, you can extend Cloudinary's powerful format conversion and image manipulation capabilities with automatic conversion of your Word documents, Excel spreadsheets and PowerPoint presentations to PDF documents and image thumbnails.
Convert Office documents to images
Before you start, if you haven't done so already, please sign-up to a free Cloudinary account. After signing up, you can try the Aspose document conversion add-on for free and later on subscribe to an Aspose document conversion add-on plan that best matches your usage requirements.
To simplify the add-on integration, you can use Cloudinary's client libraries for: Ruby on Rails, Python & Django, PHP, Node.js, jQuery, AngularJS, Java, .NET, iOS, Android and Scala.
In order to convert Office documents to images, you will first need to tell Cloudinary to convert them to the PDF format using the Aspose add-on. Converting Office documents to the PDF file format can be done while uploading 'raw' files to Cloudinary, either from your server-side code or directly from the browser.
As the following code sample shows, a Word document is uploaded to Cloudinary as a raw file. The 'resource_type' parameter should be set to either 'raw' or 'auto' if you want Cloudinary to automatically detect whether the uploaded file is an image or a non-image raw file.
In order to convert the uploaded document using the Aspose add-on, the 'raw_convert' parameter should be set to 'aspose'.
Cloudinary::Uploader.upload("my_file_name.docx", :public_id => "sample_document.docx", :resource_type => 'raw', :raw_convert => 'aspose')
\Cloudinary\Uploader::upload("my_file_name.docx", array( "public_id" => "sample_document.docx", "resource_type" => "raw", "raw_convert" => "aspose" ));
cloudinary.uploader.upload("my_file_name.docx", public_id = "sample_document.docx", resource_type = "raw", raw_convert = "aspose")
cloudinary.uploader.upload("my_file_name.docx", function(result) { console.log(result); }, { public_id: "sample_document.docx", resource_type: "raw", raw_convert: "aspose" });
cloudinary.uploader().upload("my_file_name.docx", ObjectUtils.asMap( "public_id", "sample_document.docx", "resource_type", "raw", "raw_convert", "aspose"));
Document conversion using the Aspose add-on is performed asynchronously in the background after the upload call is completed. Therefore, the response of the uploaded request mentions that the Aspose raw convert process is in the pending status.
{
"public_id" => "sample_document.docx",
"version" => 1393687686,
"resource_type" => "raw",
"type" => "upload",
"url" =>
"http://res.cloudinary.com/demo/raw/upload/v1393687686/sample_document.docx"
"info" => { "raw_convert" => { "aspose" => { "status" => "pending" }}},
...
}array(11) { ["public_id"]=> string(25) "sample_document.docx" ["version"]=> int(1393687686) ["resource_type"]=> string(3) "raw" ["type"]=> string(6) "upload" ["info"]=> array(1) { ["raw_convert"]=> array(1) { ["aspose"]=> array(1) { ["status"]=> string(9) "pending" } } } ["url"]=> string(79) "http://res.cloudinary.com/demo/raw/upload/v1393687686/sample_document.docx" ... }
{ u'info': { u'raw_convert': { u'aspose': { u'status': u'pending'}}},
u'public_id': u'sample_document.docx',
u'resource_type': u'raw',
u'type': u'upload',
u'url': u'http://res.cloudinary.com/demo/raw/upload/v1393687686/sample_document.docx',
u'version': 1393687686 }{
public_id: "sample_document.docx",
version: 1393687686,
resource_type: "raw",
type: "upload",
url:
"http://res.cloudinary.com/demo/raw/upload/v1393687686/sample_document.docx"
info: { raw_convert: { aspose: { status: "pending" }}},
...
}{
"public_id":"sample_document.docx",
"version":1393687686,
"resource_type":"raw",
"type":"upload",
"url":"http:\/\/res.cloudinary.com\/demo\/raw\/upload\/v1399208539\/sample_document.docx",
"info":{"raw_convert":{"aspose":{"status":"pending"}}},
...
}As a result of the upload example above, the uploaded raw document with the public ID of 'sample_document.docx', is immediately available for delivery as-is using the following CDN URL:
When the Aspose document conversion is completed for the uploaded image, an image resource is also created in your Cloudinary account. The image resource shares the same public ID of the uploaded raw document, 'sample_document.docx' in this case. From now on, you will be able to manipulate and deliver the generated image resource in the same way you manipulate any standard image that is uploaded to Cloudinary.
The following sample code creates an HTML tag with a Cloudinary URL that generates a PNG image of the uploaded Word document.
cl_image_tag("sample_document.docx.png")<?php echo cl_image_tag("sample_document.docx.png" ); ?>
cloudinary.CloudinaryImage("sample_document.docx.png").image()cloudinary.image("sample_document.docx.png");cloudinary.url().imageTag("sample_document.docx.png");Below you can see a scaled down version of the PNG image generated for the original raw document:
Status notification
The Aspose add-on converts documents asynchronously. The conversion usually takes a few seconds but the conversion time is highly dependant on the size and complexity of the converted document. As a result, you may want to get notified when the conversion process is completed.
When calling the upload API with Aspose document conversion, you can set the 'notification_url' to a public HTTP or HTTPS URL of your online web application. Cloudinary sends a POST request to the specified endpoint when a document conversion completes.
Cloudinary::Uploader.upload("my_file_name.docx", :public_id => "sample_document.docx", :resource_type => 'raw', :raw_convert => 'aspose', :notification_url => "http://mysite.example.com/hooks")
\Cloudinary\Uploader::upload("my_file_name.docx", array( "public_id" => "sample_document.docx", "resource_type" => "raw", "raw_convert" => "aspose", "notification_url" => "http://mysite.example.com/hooks" ));
cloudinary.uploader.upload("my_file_name.docx", public_id = "sample_document.docx", resource_type = "raw", raw_convert = "aspose", notification_url = "http://mysite.example.com/hooks")
cloudinary.uploader.upload("my_file_name.docx", function(result) { console.log(result); }, { public_id: "sample_document.docx", resource_type: "raw", raw_convert: "aspose", notification_url: "http://mysite.example.com/hooks" });
cloudinary.uploader().upload("my_file_name.docx", ObjectUtils.asMap( "public_id", "sample_document.docx", "resource_type", "raw", "raw_convert", "aspose", "notification_url", "http://mysite.example.com/hooks"));
The following JSON snippet is an example of a POST request sent to the notification URL when the document conversion is completed:
{
"notification_type": "info",
"info_kind": "aspose",
"info_status": "complete",
"public_id": "sample_document.docx",
"uploaded_at": "2014-03-01T15:43:08Z",
"version": 1393688588,
"url":
"http://res.cloudinary.com/demo/raw/upload/v1393688588/sample_document.docx",
"secure_url":
"https://res.cloudinary.com/demo/raw/upload/v1393688588/sample_document.docx",
"etag": "c558a878b3b309d42b8d97c82c6f924d"
}
The JSON content is signed using the API Secret of your Cloudinary account. For more details regarding Cloudinary's notifications and webhooks, see this blog post.
Generate images from Office documents
Raw documents are converted by the Aspose add-on to PDF files. You can download the converted PDF using Cloudinary's CDN delivery URLs. The following code example returns the PDF delivery URL of the converted Word document.
cloudinary_url("sample_document.docx.pdf")<?php echo cloudinary_url("sample_document.docx.pdf" ); ?>
cloudinary.CloudinaryImage("sample_document.docx.pdf").build_url()cloudinary.url("sample_document.docx.pdf");cloudinary.url().generate("sample_document.docx.pdf");Cloudinary supports converting and manipulating PDF documents. Therefore, the generated PDF version of the Word document can be further manipulated by Cloudinary. The following code creates an HTML image tag with a dynamic manipulation URL that generates a JPG image with a width of 300 pixels of the second page of the document.
cl_image_tag("sample_document.docx.jpg", :crop => "scale", :width => 300, :page => 2)
<?php echo cl_image_tag("sample_document.docx.jpg", array("crop" => "scale", "width" => 300, :page => 2)); ?>
cloudinary.CloudinaryImage("sample_document.docx.jpg").image( crop = "scale", width = 300, :page => 2)
cloudinary.image("sample_document.docx.jpg", { crop: "scale", width: 300, :page => 2 });
cloudinary.url().transformation( new Transformation().crop("scale").width(300).page(2)).imageTag("sample_document.docx.jpg");
Below you can see the generated 300 pixels thumbnail of page two of the document:
Using the Aspose add-on, Cloudinary can convert previously uploaded Office documents. You can use Cloudinary's 'update' Admin API while specifying the public ID of a previously uploaded raw file and setting the 'raw_convert' to 'aspose'.
Cloudinary::Api.update("sample_spreadsheet.xls", :raw_convert => "aspose", :resource_type => :raw)
$api = new \Cloudinary\Api(); $api->update("sample_spreadsheet.xls", array("raw_convert" => "aspose", "resource_type" => "raw"));
cloudinary.api.update("sample_spreadsheet.xls", raw_convert = "aspose", resource_type = "raw")
cloudinary.api.update("sample_spreadsheet.xls", function(result) { console.log(result); }, { raw_convert: "aspose", resource_type: "raw" });
cloudinary.api().update("sample_spreadsheet.xls", ObjectUtils.asMap( "raw_convert", "aspose", "resource_type", "raw"));
Below you can see a PNG image that is dynamically generated for the converted Excel spreadsheet:
Further image manipulations
Office document conversion using the Aspose add-on can be mixed with any of Cloudinary's rich set of image manipulation capabilities.
For example, the following code first scales down the fourth page of the processed Word document to a width of 300 pixels while rounding its corners, applying the sepia effect and adding a gray background. Then another uploaded image named aspose_cloud_logo is added as an overlay. The overlay is resized to a relative width of 90% of the underlying image, positioned 20 pixels from the bottom of the containing image and is made 70% semi transparent.
cl_image_tag("sample_document.docx.jpg", :transformation => [ { :width => 300, :crop => :scale, :page => 4, :radius => 50, :border => "2px_solid_rgb:999", :effect => "sepia" }, { :overlay => "aspose_cloud_logo", :width => 0.9, :flags => :relative, :opacity => 70, :gravity => :south, :y => 20 }])
<?php echo cl_image_tag("sample_document.docx.jpg", array( "transformation" => array( array( "width" => 300, "crop" => "scale", "page" => 4, "radius" => 50, "border" => "2px_solid_rgb:999", "effect" => "sepia"), array( "overlay" => "aspose_cloud_logo", "width" => 0.9, "flags" => "relative", "opacity" => 70, "gravity" => "south", "y" => 20 )) )); ?>
cloudinary.CloudinaryImage("sample_document.docx.jpg").image( transformation = [ { 'width': 300, 'crop': "scale", 'page': 4, 'radius': 50, 'border': "2px_solid_rgb:999", 'effect': "sepia" }, { 'overlay': "aspose_cloud_logo", 'width': 0.9, 'flags': 'relative', 'opacity': 70, 'gravity': "south", 'y': 20 }])
cloudinary.image("sample_document.docx.jpg", { transformation: [ { width: 300, crop: "scale", page: 4, radius: 50, border: "2px_solid_rgb:999", effect: "sepia" }, { overlay: "aspose_cloud_logo", width: 0.9, flags: 'relative', opacity: 70, gravity: "south", y: 20 }], });
cloudinary.url().transformation( new Transformation().width(300).crop("scale").page(4).radius(50). border("2px_solid_rgb:999").effect("sepia"). chain().overlay("aspose_cloud_logo").width(0.9).flags("relative").opacity(70). gravity("south").y(20)).imageTag("sample_document.docx.jpg");
Here's the dynamic Cloudinary manipulation URL and the generated image thumbnail:
For a full list of additional Cloudinary's image manipulation options, see Image transformations.