Converting a URL with additional parameters

All our services offer the possibility of passing a URL as a parameter so that specific URL will be converted to a PDF. We see a lot of our users struggle the first time they want to pass a URL that contains additional parameters separated by an ampersand (&) sign.

Most of the time you’ll see usage examples in the documentation describing how you can convert the Google website or another straightforward site with a simple URL like http://www.google.com or http://www.nytimes.com. The reasoning behind this is that all URLs will work and there’s not so much that’s difficult about URLs.

Today we’ll talk about an exception: additional parameters passed to the URL with the ampersand (&) character. These URLs will look like:

http://www.example.com/news?author=peter&date=20130316

Usage of the ampersand in our services

You can pass URLs with additional parameters in all our services. In two of them you have to escape the ampersand in the URL you’re passing to %26. This is because you’re already passing other parameters (your apikey, width, height etc) with the ampersand sign as well.

Let’s look at the syntax:

1. Our Save as PDF functionality
   Here you put a link to http://www.htm2pdf.co.uk/display on your page and if you want to convert a different URL containing an ampersand you would put the following link up:

   http://www.htm2pdf.co.uk/display?url=http://www.example.com/news?author=peter%26date=20130316

2. Our HTML to PDF API
   With the API you’d do pretty much the same as with the save as PDF functionality. You use HTTP GET to call it, which means you send a HTTP request and that means you have to escape the ampersand in the same way. So if you want to convert the example URL you’d have send a request to:

   https://api.htm2pdf.co.uk/urltopdf?apikey=yourapikey&url=http://www.example.com/news?author=peter%26date=20130316

   Note – only the ampersand in the URL you’re passing is translated to %26!

3. Our HTML to PDF SDK
   With our PHP library you don’t have to worry about escaping anything. Since you’re calling a predefined function that we programmed and is included in your library file, we’ll make sure everything works fine without you thinking about anything. You just pass whichever URL you’d normally type in the browser and we’ll convert  that one.
   So you’d just go and do:

   $pdf->ConvertFromURL('http://www.example.com/news?author=peter&date=20130316');

Translation of the ampersand in coding

For most of you who got this far it’s probably just a matter of ‘AHA!’ and you already know what to do. You’ve been passing the wrong URL a couple of times, took a look at the documentation and are on your way.

Now if you’re still reading you may want to learn what the easiest way is to add the %26 to the URL. I’ll give you a few pointers in PHP and invite all others to give a shout out in the comment box to do the same in C#, Java, Ruby or whatever programming language they’re fluent in.

Example 1
Suppose you already have the URL in parameter $url. You could then just go and do:

$url = str_replace('&','%26', $url);

Example 2
Suppose you have the building blocks of the URL and you were previously doing something like:

$url='http://www.example.com/news?author=' . $author . '&date=' . $date;

Then now you’d go and do the following:

$url='http://www.example.com/news?author=' . $author . '%26date=' . $date;

Now these are just basic examples. I hope you get the idea. If not – scream in the comment box and I’ll try to improve on this.