In this article we explain how to use Ruby to convert MS-Word, Excel, PowerPoint, HTML and other common file formats to PDF as well as to other formats. Read on to learn more about the Muhimbi PDF Converter and how it can assist with the Conversion, Merging, Watermarking, Splitting and Securing of documents.
We previously discussed how to use the popular Muhimbi PDF Converter API and Server Platform in combination with PHP, Java (Axis2 and wsimport) as well as Microsoft .NET based environments. Today we will discuss a similar example using the increasingly popular Ruby on Rails (ROR) platform.
For those not familiar with the product, the Muhimbi PDF Converter API and Server Platform is a server based SDK that allows software developers to convert and manipulate typical Office files, including MS-Word, Excel, PowerPoint, Visio, Publisher, AutoCAD, HTML, emails and InfoPath, to PDF and other formats using a robust, scalable but friendly Web Services interface from Java, PHP, Ruby and .NET based solutions. If you have any questions or need more information then please let us know.
Update for 2019: Please note that this example was written in the Ruby 1.8.7 / Rails 3.2.12 (2013) time-frame. Things have moved on since that time and you may find that for more recent Ruby versions you need a different Web Services Framework. However, the concept remains the same, you use a tool to generate proxy classes for the web service, then invoke those proxy classes from your Ruby code. You can find some additional details in our GitHub repository. Talk to us if you get stuck , we love to help.
Installing the base ROR environment
If you are reading this then you probably already have a full ROR environment set up. If that is the case then please take into account that this example has been tested with Ruby 1.8.7-p370 and Rails 3.2.12. You may want to use RVM to select the exact same Ruby version as the
soap4r gem used in this example may not be compatible with all ruby versions.
If you don’t have a full Rails environment installed then you may want to follow the instructions below to install it. For the sake of this example we used Ubuntu 12.10.
- Download and Install Ubuntu 12.10. We set it up to run inside Hyper-V, but that is naturally not a requirement.
- Install Ruby and Rails as described here. However, rather than using the
rvm install 1.9.3command use
rvm install ruby-1.8.7-p370and set that to the default using
rvm use ruby-1.8.7-p370 –default.
- When deploying to a clean Ubuntu 12.10 system the
ExecJSdependency is missing. The easiest way to install this is to issue the following command:
That is it as far as the base ROR environment is concerned. You may want to consider installing a decent text editor. For testing purposes we use Sublime-Text.
Creating the Rails application
The Muhimbi PDF Converter exposes a comprehensive API via a standards based Web Services interface (Full Documentation). A number of Web Service frameworks are available for Ruby (Savon, Handsoap), but in this example we use
Soap4R to pre-generate Ruby proxies as it is simple, and it works.
In the example below we will create a basic PDF Conversion Rails application. If you are looking to add PDF Conversion to an existing Rails application then I am sure you’ll know how to modify the various steps.
Use a terminal application of your choice to navigate to the location where you wish to create the Rails application. We use
Execute the following command to create the skeleton for the application:
Gemfileusing a text editor of your choice and add the following line:
Execute the following command to pull in the applicable gems (Make sure you are still in the
The quickest way (also from a performance perspective) to interact with a Web Service is to generate proxy classes. This can be achieved easily using
soap4r, which has already been added to the application as described above.
Before we can generate the proxies we need to make sure that the Muhimbi Conversion Service has been installed and is running ( Yes, this requires one or more Windows Based Servers. Sorry Linux/Apple experts, there is just no way to achieve a decent conversion fidelity on other platforms. Rest assured that your Ruby application can continue to run on non-Windows systems).
- Download and Install the Muhimbi PDF Converter API and Server Platform as described in Chapter 2 of the Administration guide.
Muhimbi.DocumentConverter.Service.exe.configin your favourite text editor (notepad works as well). A handy shortcut to the configuration/installation folder can be found in the Windows Start Menu Group.
- Search for
localhostto the DNS name or IP address of the server running the Conversion Service.
- Restart the Conversion Service as follows:
Back on your Ruby system carry out the following steps to generate the proxies:
- Navigate to
- Execute the following command. Please replace
localhostwith the name or ip address of the server that runs the Muhimbi PDF Converter API and Server Platform.
This generates four new files and places them in the
lib folder. Note that the generated property and method names follow Ruby’s naming convention and not the convention used in the Muhimbi Developer guide. This mainly impacts the capitalisation of the first letters.
Update: A third party is maintaining a Ruby Gem for our PDF Converter. Although unsupported and untested by our engineers, it may be worth checking out.
Implementing the sample
All prerequisites are in place. Let’s add some code to tie it all together. If you prefer you can download the full example, including generated proxies from our website.
- Start by generating a controller where the form will be posted to:
- Delete the home page that comes with every new Rails application (Execute in the
- If you are using Sublime-Text then this is the moment to execute
_subl ._to open the text editor and display the entire folder structure.
config/routes.rband after the following lineAdd
app/views/home/upload\_file.html.erband add the following HTML
app/controllers/home\_controller.rband replace it with the following:
Please update the
url variable with the IP address or DNS name of the server that runs the Muhimbi Conversion Service.
This is a minimum code sample to illustrate how simple it is to convert a file. Our full Developer Guide contains the entire object model, including details about how to Convert, Watermark, Split, Merge and Secure files.
That is it. Start the Rails server as follows:
Open a web browser and point it to
http://localhost:3000. If the browser is opened on a system other than the one that runs the Rails application then replace
localhost with the DNS name or IP number of that server.
The sample application is very simple. Select a file to convert (see this list of supported file types, please make sure that the file extension matches its format). Then select the Output format, e.g. PDF, and click the Convert button.
SOAP / Web Service Debugging
The Muhimbi Conversion Service is a Windows Service based on the Microsoft Windows Communication Foundation (WCF) framework. This comprehensive framework is used to expose a standards based Web Services interface that can be consumed by many different platforms including .NET, Java, PHP, SAP, Ruby, Documentum and many others.
Even though WCF Web Services are standards based, standards are not interpreted the same by everyone so from time to time you may need to do some troubleshooting when programming against the PDF Converter Web Service, especially from non-Microsoft platforms.
For details about how to debug Web Service / SOAP messages, see this Knowledge Base Article.
If you have any questions then leave a comment below or contact us.