For Webkit browsers, a similar effect can be used with CSS Masks, but perhaps you need slightly wider browser support, or you want to use the masked image in Canvas somewhere else.

This function is just a base and should really be tailored to your use case, but it shows how easy it is to read the alpha data from one image, and apply it to another. Using getImageData, a 4-chunk CanvasPixelArray is returned with each pixels’ R, G, B, and A values. The result is achieved reading and ‘merging’ the RGB values from the base image, and the A values from the mask.

That’s all it does, but having it wrapped up into a single function is sometimes easier to work with (again, depending on your use case). The function creates a couple of Canvas elements on the DOM and uses them to mash the pixels together. You just pass in the base and mask images, and get back the single masked image either as a CanvasPixelArray, or as a Base-64 encoded data URL.

To give you an idea of what the images can be, here are the raw images I’m using for the utterly useless demo.

• Base JPEG: http://playground.benbarnett.net/canvas-mask/img/octagon.jpg
• Mask PNG-24: http://playground.benbarnett.net/canvas-mask/img/alpha.png

Feel free to head over to the Github repo for further docs.

Here’s some dummy code:

There’s not really much more I can say about this. Its unobtrusive, light weight and will simply hand over to the native jQuery.get() method if no selector is supplied.

Further Resources

• Playground & Demo page
• Github for Issues and Source

So it seems that the YouTube Player API doesn’t offer any support for the HTML5 video player, while the standard Embed code does. It kinds of makes sense with the way they’ve implemented their player API as ultimately it’s just embedding a SWF with a few paramaters, but its still annoying. Its clear that the major players are working towards something, but for now we’re left with finding our own way through.

The reason its annoying is that the only way to truly skin the YouTube player (without its hideous & pointless background colour customization) is to use the Chromeless player and then overlay your own controls. This is relatively easy to do, and a there’s a reasonable demonstration on the YouTube Player Demo page.

What’s the point?

The point is so that you can have a custom YouTube player, and have it work on mobile devices without Flash. It also means that you get the benefits of YouTube’s encoding lair and that the number of ‘Views’ will be counted both on YouTube and from your site.

Making it work

As we need SWFObject on the page in order to embed the Chromeless player for our custom skin, we can use a handy method in its API:

swfobject.hasFlashPlayerVersion(versionStr) // e.g. "8.0.0"

With that, we can do a simple if statement, and hand the logic back to the standard YouTube embed code should that function return false. We do this because the basic embed code will use the HTML5 player where it can, giving us native iPad/iPhone/iWhatever support. You can grab this simply by going to YouTube, clicking Embed, and copying the code it gives you.

Either way, we palm off to YouTube at this point, allowing them to make the correct decision in a non-Flash environment, the logic behind which will probably change quite regularly.

Note: it’s not possible to skin the HTML5 Video Player on Mobile Safari, because it uses the native video player. Not a biggie though, it looks awesome.

Here’s a basic code example:

Demo

This is ugly, rudimentary and not for production. But it demonstrates the technique. Try the link below out on any browser, and on an iPad/iPhone:

http://clients.brushfiredesign.net/playground/youtube/youtube.html

You’ll see that with some basic styling, you can fairly easily create a completely custom player design using the elements on that page, which also works on your iPad.

The way I’ve seen it done before (and I have in fact done it myself) is to simply stick a PNG with alpha transparency on top of the text in question. Granted, this technique does work but it felt like a bit of a cludge. It also means you can’t highlight the text underneath it. Annoying and bad for usability.

I then cast my mind back to the stunning Kaleidoscope App website. Using a Webkit browser, look closely at the colour wheel triangle thingy and you’ll notice it’s spinning. Dig deeper in the CSS and you’ll see they’re using a really nice masking technique to achieve that.

Simple enough, but I wanted this effect to appear on all browsers rather than just Webkit.

Detecting Webkit Masking Support

Feature detection is the best way to implement this technique. Rather than just seeing if “browser = Chrome or Webkit”, you can either use the Modernizr library to do this for you, or simply grab the following line of Javascript and insert it above your CSS.

document.documentElement.className = document.documentElement.style.WebkitMask!==undefined?"masking":"nomasking";

That will add a class of ‘masking’ to your HTML tag should the feature be supported. And, by including this pre-CSS, you’ll get no flickering of content. You can then just add the .masking prefix to styles that use it.

Creating the Mask

Basic Photoshop skills should be enough to create pretty much any type of mask. The key point to remember is that they’re unlike Photoshop masks in that they rely on Alpha transparency rather than black or white.

Webkit masks require a PNG with an alpha channel, i.e. a 24 or 32 bit PNG.

Areas of the mask with 0% opacity will hide that section of the element the mask is being applied to. Areas with 100% will render as usual. Then, as you’d expect, you can use anything in-between for partial transparency.

Here’s the mask I’m using. I’ve dropped it in a green container so you can see where the transparency lies.

The CSS

This is the easy bit. For non ‘.masking’ browsers, implement the same ‘overlay’ technique as you’ve no doubt done before.

For browsers that do support Webkit Masking, just override the element (for example, an h1 tag) to set it.

.masking h1 { -webkit-mask-image: url(../img/bg/text-effect-mask.png); }

You can then play with the positioning and things should you need to;

• -webkit-mask-position-y
• -webkit-mask-position-x
• -webkit-mask-repeat

Here’s a screenshot of the output.

A nice, selectable, accessible, progressively enhanced text overlay effect.

Simple right?

This is a rudimentary use of the Webkit mask. As you can see from the Made by Sofa guys (creators of Kaleidoscope App), you can create some amazing effects and choose either to implement a technique for non-supporting browsers, or just degrade gracefully to a static version, as they’ve done.

You can also use them on pretty much any DOM element there is, as the comments on the Surfin’ Safari docs explain.

This is where my jquery-animate-enhanced plugin comes in. The idea was to have a one hundred percent seamless integration, and backwards compatibility with older browsers. For this reason, it just extends $.animate() which we all know and love and detects if you’re trying to animate something that would be better off done with a CSS3 transition. Absolutely zero effort required.

The plugin.

Extend $.animate() to detect CSS transitions for Webkit, Mozilla and Opera and convert animations automatically. Compatible with IE6+

Properties supported: (more to come)

• left : using translate(x, y) or translate3d(x, y, z)
• top : using translate(x, y) or translate3d(x, y, z)
• opacity

Note that any properties not mentioned above will simply be handled by the standard jQuery $.animate() method. This plugin adds new functionality without taking any away.

Demo

What it does

The plugin will analyse the properties you’re animating on, and select the most appropriate method for the browser in use. This means your transitions on left, top and opacity will convert to a CSS3 transition on Webkit & Mozilla agents that support it, and Opera 10.50+. If the user is on a browser that has no CSS3 transitions, this plugin knows about it and won’t get involved. Silent degradation

Multiple callback mechanisms are created internally to monitor for DOM manipulation and for all ‘transitionend‘ CSS3 events to be picked up. This means you have one neat callback() for the whole animation regardless on whether the plugin is using CSS3, DOM, or both for its animations.

Progressively enhanced CSS3 animations without having to do any browser detection or special CSS, therefore using the same Javascript across your applications and websites.

As this plugin uses CSS3 translate where available, there is an internal callback mechanism to reset the ‘left’ and/or ‘top’ properties so that your layout is unaffected.

Usage

Usage is identical to the jQuery animate() function, but it comes with 3 new paramaters, which are totally optional and safe to leave untouched for general use:

• avoidTransforms: (Boolean)By default the plugin will convert left and top animations to the CSS3 style -webkit-transform (or equivalent) to aid hardware acceleration. This functionality can be disabled by setting this to true.
• useTranslate3d: (Boolean)By default the plugin will use 2d translations due to wider browser support. Set this to true to use translate3d instead. Recommended for iPhone/iPad development (here’s why).
• leaveTransforms: (Boolean)By default if the plugin is animating a left or a top property, the translate (2d or 3d depending on setting above) CSS3 transformation will be used. To preserve other layout dependencies, once the transition is complete, these transitions are removed and converted back to the real left and top values. Set this to true to skip this functionality.

Give it a go

More information is available either on the GitHub repository, or on the plugin homepage. Thoughts very much welcome.

I’m a believer of the “write once, deploy anywhere” attitude. I’m also a big fan of things like WhitherApps; James has done a great job taking the (native) BBC News app and rebuilding it using just HTML and CSS to prove out this very concept.

BUT… people would be lying if they told you it’s exactly the same as writing CSS for desktop browsers. It just isn’t.

No support for the CSS fixed position

You could be forgiven for thinking that it just reverts back to absolute positioning like it does in IE6, but in fact it is not same as explicitly setting an element to absolute. The behaviour is subtly different, and I found that running any CSS3 style webkit transitions were much more performant, and less ‘flickery’ on an element with fixed position, over one with absolute even though the layout was identical.

Very strange considering there’s no support for fixed position. Couldn’t find that one in the specs anywhere either, so I remain baffled. My solution was to try both position attributes and see which performs better.

Usually though, Cubiq’s iScroll will do the trick as it’s more than likely the reason for needing fixed positioning anyway. That plugin genuinely works well by the way. Use it.

Hardware accelerated CSS transformations… but are they, really?

This one took me a good few hours to work out when I could have been quite happily doing far more productive things with my day. I knew already that the ‘-webkit-transform’ and ‘opacity’ attributes were hardware accelerated for webkit transitions. If you’re experiencing a flicker with css3 transitions, this is how to fix it.

It is true that opacity is hardware accelerated. It is also true that -webkit-transform is hardware accelerated, but, if you’re using translateX, translateY or translateZ, you don’t get that luxury. Take a typical CSS transition;

#element {
    -webkit-transition: -webkit-transform 1s linear;
    -webkit-transform: translateX(0);
}

#element.transformed {
    -webkit-transform: translateX(300px);
}

In any webkit browser, you’ll get whatever #element is to move 300 pixels to the right, in a linear 1 second animation. On Mobile Safari, it will likely ‘flicker’ before/during/after the transition. The key is to use translate3d(x, y, z). The simple change shown below makes all the difference.

#element.transformed {
    -webkit-transform: translate3d(300px, 0, 0);
}

It’s ridiculously simple, but honestly why would that be hardware accelerated and not the shorter hand, translateX property?

Avoid Javascript Libraries

You’ll notice that the Javascript engine on the iPhone is incredibly slow. The iPad is greatly improved but its still advisable to minimise Javascript, particularly for things like animations. Always use a translate transition over animating the left or top properties. The CSS3 transitions are perfectly smooth and look great. Arguably you don’t need jQuery for mobile apps as a lot of ‘weight’ comes from dealing with cross browser differences; obviously not being an issue if we’re focussing solely on mobile webkit. With the new CSS selector engine, document.querySelectorAll(); you still get lightening fast ‘jQuery style’ DOM selections. Time to brush off the raw Javascript skills (or just be lazy and wait for jQuery mobile).

Am I being impatient?

There’s only a handful of cases that have proved to be quite time consuming during development, but the point here is a bigger one.

The whole idea of unifying standards across all devices is the way forward. The thing is though that I can’t help feeling that we’re harking back to the “Are you using Netscape or Internet Explorer?” days. I wish we didn’t have to know about these tricks. It means that without position fixed, we need to use (and write) Javascript extensions to help us out, but then we add weight and potential bugs to the desktop side of things. Do we really have to start detecting whether we’re on an iPad and serve up specialised code? What about sites that we wrote before all this came about?

I’m still behind the idea of using HTML powered apps with simple Objective-C wrappers to encase everything into a native application. With a bit of reading up, and more than one or two stabs in the dark, its definitely not impossible to make an HTML driven app “feel” just as native as any other.

I guess one just has to accept that the concept of using exactly the same code on mobile and desktop devices still isn’t quite there.

Is there an easy way to convert this increasingly mammoth tube map into a clean, cross browser, interactive map?

The short answer is…. no, but here’s how anyway.

Allow me to explain why. I’m sure someone will find this post and tell me straight away that I could’ve done this using a much simpler approach, but this is how I tackled it.

Firstly, get the right Tube Map

Ok, it sounds obvious but this is quite important as it can drastically affect how much work we have to do. I’m not implying that I downloaded the map for New York Metro, but the starting format for this key.

The first part is that we need a vector based tube map, i.e. the PDF or even better an SVG version to start with. I tried both formats, in “normal” and large print. After popping them all into Adobe Illustrator, I clicked around to find the version which had the most amount of clean separation between layers. Turned out the PDF Large Print tube map was a reasonable starting point. I use that adjective loosely.

Spring cleaning

This is probably the most laborious part, but equally the most important to make this thing actually any use. Unfortunately with compressed PDFs, text fields are nearly always seperation in order to preserve the display of the typography as accurately as possible, making lines split into words, and words split into meaningless 1 or 2 letter “phrases”. This is great for the human eye, but for actually ‘querying’ the document, it’s useless as we need clean labels for each tube station.

Essentially the job was a manual one. I’m no Illustrator expert so there may well have been easier way, but it surpassed me if so. Here’s a demonstration example of what I did:

Oxford Circus -> Oxford Circus

Do you see? To start with, we had 5 different (and meaningless) labels, “Ox”, “for”, “d C”, “irc” and “us.” Do you also see how I used the Tube line colours for my demo?

By now I’m sure you’ve figured out how I spent that evening…

Seperate the Tube lines

Now we have the station names cleaned up and ready for conversion (I’ll explain how in a minute), it’d make it even more interactive if we could distinguish between the Tube lines themselves as well. Filtering just on the Central and Picadilly Lines, for example.

This part is a bit simpler and is actually a really simple technique of getting complex paths into Raphael JS.

I simply selected each line in Illustrator, and copied into a new standalone document. I then Saved a Copy, selected SVG 1.1 as the document format and clicked Show SVG Code. I was presented with this little beauty for the Central Line:

<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 13.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 14948)  -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
width="400px" height="400px" viewBox="0 0 400 400" enable-background="new 0 0 400 400" xml:space="preserve">
<path fill="none" stroke="#ED3024" stroke-width="6.65" stroke-linejoin="round" stroke-miterlimit="3.994" d="M973.98,129.223
H773.97c-4.87,0-11.67,2.823-15.12,6.269L629.99,264.364c-3.45,3.44-10.25,6.258-15.12,6.258h-79.49
c-4.87,0-11.66-2.817-15.11-6.258l-33.239-33.236c-3.44-3.448-10.24-6.264-15.11-6.264H-572.959"/>
</svg>

I’ve highlighted the bit we need. This can then be used as simply as:

var c = paper.path("<<< PATH CONTENTS HERE >>>");

…and so on for each line.

Getting the stations into Raphael JS

This is the final stage really. Unfortunately there’s no such easy technique for getting text labels into Raphael type code. After a bit of playing around, I wrote a PHP script to help me with this.

All you need to do as save the stations, and the stations only into a document. This does mean a lot of copying and pasting, or a lot of deleting of tube lines and artifcats, whichever your preference. However, with this done you should just have a document with a bunch of text labels which you save as an SVG 1.1 file somewhere.

Running this PHP script on it will loop through every SVG text node, extract the text and the x and y coordinates for you; making it super easy to plot all the hundreds of stations exactly where they were in SVG, using Raphael.

header("Content Type: text/plain");
$xml = simplexml_load_file("stations.svg");

foreach($xml->children() as $child) {
	if ($child->getName() == "text") {
		$matrix = $child->attributes();
		$matrix = str_replace(array("matrix(1 0 0 1 ", ")"), "", $matrix);
		$matrix = explode(" ", $matrix);

		// here we go
		$stationName = trim(str_replace(array("%%", '’'), array('\n', "'"), $child), " ");
		$x = $matrix[0];
		$y = $matrix[1];

		// your business logic here
                // echo($stationName);
} }

One last thing to note is that it seems line breaks (which are essential to mirror the layout of the Tube Map) are converted into seperate text fields when saving down to SVG. For this reason, and its not the cleanest solution I admit, I tokenised the strings with “%%” to represent a line break, which were then converted into line breaks using the code above.

Using that script I printed out the exact Javascript variables I needed for the project I was working on for this at the time, looped through them all and created them as text fields:

var stations = { "Oxford Circus" : { x: 100, y: 100 } };

for (p in stations) {
	var station = stations[p];
	var t = paper.text(station.x, station.y, p);
	t.attr({font: 'Arial', 'font-size': 13.5, fill: '#1C3F94'});
}

SVG and Illustrator file references

As a farewell I will leave you with the 2 SVG files which took the most time to produce and will do most of the work for you. I’m sure they could be cleaned up even further, and I’m open to any suggestions on how to do so.

SVG Source for Tube Stations
SVG Source for Tube Lines

All should be labelled clearly for ease of use. Good luck!

To see an example app, check out the free online baby book creator, which has just launched and is written using pretty much the exact code in my post.

Anyway, the updated Rails/Lulu API howto is just a click away.

I’m very pleased to be able to say that Jonathan Spies has taken the roots of this blog post and produced a fully fledged plugin. I’ve used it on a couple of projects already. Oh how I love the web sometimes.

http://github.com/jspies/raphael.serialize

Introduction

I’ve been playing around with RaphaelJS recently (if you haven’t seen it, check it out) for an ‘avatar builder’ type project to avoid the use of Flash. It’s a really fun bit of kit to use, but I needed a way to actually save the results of the avatar to a bitmap to avoid having heavy javascript libraries every time the avatar is displayed on a page. After a bit of poking around on forums/blogs I thought I’d tie up all the key pieces in one blog post in case anyone else was in the same boat.

The output is essentially a PNG-24 alpha channel bitmap image, which can then be treated as normal with the likes of ImageMagick (I’ve been adding drop shadows to the avatars for example).

Extracting SVG data from Raphael

Unfortunately this isn’t as easy as could be. In browsers that support SVG, we can simply extract all the data from the DOM itself to reproduce it, but as Raphael uses VML on non-SVG browsers (namely, IE) that idea won’t work.

However, the Raphael Javascript object does store the data we need in order to re-produce the SVG. This requires a little bit of Javascript, and for demonstration purposes I’m using PHP.

The Javascript

So the first thing I do build up a JSON object describing the data needed to produce the SVG file, with a little help from jQuery. I’ve put the code for this on this gist. It essentially loops through the ‘paper’ variable that RaphaelJS is using to build up our own array. In mine I was using just paths and images, so that was the only data I needed, however this could easily be expanded to include all the other properties as well.

The Server Side Code (PHP)

All this file does is decode the JSON data into an associative array for use in PHP, loop through the properties and outputs an SVN file. I’ve put the PHP I’m using below as there’s not much to it:

    $json = json_decode($_GET['json'], true);

    $output = '<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="'.$json[0]['width'].'" height="'.$json[0]['height'].'" xml:space="preserve"><desc>Created with Raphael</desc><defs></defs>';

    for ($i=1; $i &lt; count($json); $i++) {
        if ($json[$i]['type'] == "image") {
            $base64 = base64_encode(file_get_contents($json[$i]['src']));

            $output .= '<image overflow="visible" x="'.$json[$i]["x"].'" y="'.$json[$i]["y"].'" width="'.$json[$i]["width"].'" height="'.$json[$i]["height"].'" transform="'.$json[$i]["transform"].'" preserveAspectRatio="none" xlink:href="data:image/png;base64,'.$base64.'"></image>';
        }

        if ($json[$i]['type'] == "path") {
            $output .= '<path fill="'.$json[$i]['fill'].'" stroke="'.$json[$i]['stroke'].'" d="'.$json[$i]['path'].'" style="opacity: '.$json[$i]['opacity'].';" opacity="'.$json[$i]['opacity'].'" transform="'.$json[$i]['transform'].'"></path>';
        }
    }

    $output .= '</svg>';

Save the SVG and send to Apache Batik for Rasterization

So this part is fairly simple. I recommend using Apache Batik for the SVG rasterization as it seemed to have better results compared to ImageMagick. The first part is simply to write the ‘SVG string’ to a file.

file_put_contents('generated/avatar.svg', $output);

Now, just send it across to Apache Batik with the exec() command, and we have a PNG!

exec("java -jar batik-rasterizer.jar /path/to/avatar.svg");

Just the beginning

So this was just a basic introduction to exporting an SVG from Raphael, and will need more work for more complex shapes and transformations. I’m planning on writing a RaphaelJS extension to make all this a bit easier, and perhaps offer out the server side code on a public domain so there’s no need to write it out…

So stay tuned. Or, if you’re already doing this, I’d be more than happy to help out.

To get the communication between your site and the Lulu Publication API the main libraries we need are;

require 'net/https'
require 'uri'
require 'curb'

…and 4 URLs, along with the API Key (free to create one) which should be defined as constants (perhaps in config/environment.rb);

LULU_AUTHENTICATE = "https://www.lulu.com/account/endpoints/authenticator.php"
LULU_UPLOAD_TOKEN = "http://apps.lulu.com/api/publish/v1/request_upload_token"
LULU_UPLOAD = "https://pubapp.lulu.com/api/publish/v1/upload"
LULU_PUBLISH = "http://apps.lulu.com/api/publish/v1/create"
API_KEY = "ABCDEF123" # replace this with your api key

Curb is simply a hook into the brilliant cURL utility and can be installed as a gem. It’s used here as it makes it dead easy to do a multipart form post, which is required for the ‘upload’ phase of the integration.

[sudo] gem install curb

Step 1 – Obtain your authToken from the Lulu API

To use the Lulu API, all you need is a normal Lulu account, which is free. You’ll need those details to get the ‘authToken’ from the Lulu API which simply authenticates all the requests. We also need to be using https for every call to the API. Anyway, here’s the code you need for step 1 (I’ve defined my LULU_AUTH_USER and LULU_AUTH_PASS in config/environment.rb for neatness).

require 'net/https'
require 'uri'
require 'curb'

# LULU_AUTHENTICATE WITH LULU TO GET OUR auth_token
url = URI.parse(LULU_AUTHENTICATE+'?api_key='+LULU_API_KEY)
auth_args = {
'username' => LULU_AUTH_USER,
'password' => LULU_AUTH_PASS,
'responseType' => 'json'
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.path)
request.set_form_data(auth_args)

response = http.start {|http| http.request(request) }
json = ActiveSupport::JSON.decode(response.body)

Now all we need to do is deal with that response. The last line of the code above simply gives us a decoded JSON object, which can be used like this:

if json['authenticated'] == true
  # we're logged in!
  auth_token = json['authToken']
else
 # something went wrong, let's review what came back and try again
 puts response.body
end

Step 2 – Upload the PDFs

This bit probably took me the longest to work out, but as I mentioned earlier, the Curb gem came to the rescue. Make sure you’ve installed that and then we can form a new request to send our cover PDF and the book PDF. Remember that this will only work if you’ve successfully received an authToken from the authentication stage of the Lulu API.

UPDATE: Since June 2010, you now need to request an Upload Token before being able to upload files:-

url = URI.parse(LULU_UPLOAD_TOKEN+'?api_key='+LULU_API_KEY)

publish_args = {
  'auth_user' => LULU_AUTH_USER,
  'auth_token' => auth_token,
  'api_key' => LULU_API_KEY
}
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path)
request.set_form_data(publish_args)

response = http.start {|http| http.request(request) }
responsebody = response.body.gsub("'", "\"") # Sadly our JSON parser won't work unless we do this (single quotes aren't valid JSON)

tokendata = ActiveSupport::JSON.decode(responsebody)

# LULU_UPLOAD THEM
pdf_cover = "/tmp/cover.pdf"
pdf_book = "/tmp/book.pdf"

c = Curl::Easy.new(LULU_UPLOAD)
c.multipart_form_post = true
c.http_post(
       Curl::PostField.content('auth_user', LULU_AUTH_USER.to_s),
       Curl::PostField.content('auth_token', auth_token.to_s),
       Curl::PostField.content('api_key', LULU_API_KEY), # note the new API key being sent across
       Curl::PostField.content('upload_token', tokendata['token'].to_s), # add our upload_token to the post fields
       Curl::PostField.file('cover', pdf_cover),
       Curl::PostField.file('book', pdf_book)     )

json = ActiveSupport::JSON.decode(c.body_str)

if json['written_files']
  # the files were uploaded!
  ... business logic here ...
else
  # something went wrong, review the output below
  puts c.body_str
end

It really is as simple as that! Now all we need to do is send the fairly large (but still, easy to interpret) JSON data structure to the final stage of the Lulu API.

Step 3 – Send Publish Data to Lulu Publication API

So this will probably look like the most complicated part, but it’s simply where we configure exactly what sort of book we want; meaning the size, paper/hardback, quality, availability etc etc. Let’s get straight into the data structure.

create_input =
{
  "allow_ratings" => true,
  "project_type" => "hardcover",
  "access" => "direct",

  "bibliography" =>
  {
    "title" => "My First Book",
    "authors" => [
      {
        "first_name" => "Ben",
        "last_name" => "Barnett"
      }
    ],
    "category" => 4,
    "description" => "What a fabulous book!",
    "copyright_year" => "2010",
    "publisher" => "Brushfire Design Ltd",
    "language" => "EN",
    "country_code" => "GB"

  },

  "physical_attributes" =>
  {
    "binding_type" => "casewrap-hardcover",
    "trim_size" => "SIZE_825x1075",
    "paper_type" => "regular",
    "color" => "true"
  },

  "pricing" =>
  [
      {
        "product" => "print",
        "currency_code" => "GBP",
        "total_price" => "34.99"
      }
  ],

  "file_info" =>
  {
    "cover" => [{"mimetype" => "application/pdf", "filename" => "cover.pdf"}],
    "contents" => [{"mimetype" => "application/pdf", "filename" => "book.pdf"}]
  }
}

The only couple of bits to really worry about are to ensure that you provide just the name of your PDFs, i.e. not the full path (mine were /tmp/cover.pdf) and to set the access type. Supported access levels are ‘private’, ‘public’ (available through search/browse), and ‘direct’.

Hopefully the above layout makes it clear how the JSON will be structured. Obviously at this stage we have a standard Object in Ruby, which we need to convert to a JSON and then send to the Publication API:

url = URI.parse(LULU_PUBLISH)
publish_args = {
  'auth_user' => LULU_AUTH_USER,
  'auth_token' => auth_token,
  'project' => create_input.to_json,
  'api_key' => LULU_API_KEY # note the new API key being sent across
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.path)
request.set_form_data(publish_args)

response = http.start {|http| http.request(request) }

json = ActiveSupport::JSON.decode(response.body)

if json['content_id']
  # we have a book!
  ... store the json['content_id'] for reference
else
  # something went wrong
  ... review output in response.body
end

That’s it!

It may look like a lot of code above, but that really is all there is to it. I found the last stage quite fiddly, but it was more to do in terms of getting my PDF to the right DPI and exact sizes etc. You can find some sample PDFs from Lulu’s Book Specifications (at the bottom of the page).

Feel free to get in touch if you need any more help getting up and running.