Issuu is a document sharing and publishing service that allows users to convert any type of publication file (PDF, word, ...) to a visually appealing media viewer, which presents the content like a real book with an unique "page flip" effect.

Today I am going to explain the basics of the Issuu API to learn how to upload and delete publications in Ruby.

First of all, we need to get the public and private API keys, which can be obtained by registering at the same issuu.com site.

To exchange information with Issuu using this API we will have to sign every petition we make.

Signing data

According to Issuu API specification (July 2010), the steps involved in signing an HTTP request are as follows:

  1. Sort request parameters alphabetically
      (e.g. foo=1, bar=2 sorts to bar=2, foo=1)
  2. Concatenate in order your API secret key and request name-value pairs (e.g. SECRETbar2baz3foo1)
  3. Calculate the signature as the MD5 hash of this string
  4. Include the signature parameter in the request encoded as lowercase HEX (e.g. signature=7431d31140cf412ab5caa73586d6324a)

Here is the representation of this algorithm in Ruby:

Where params contains all the parameters defined as a key/value hash. eg {access => private, :action => issuu.document.upload, ... }, and API_SECRET is the api secret key defined somewhere as a constant.

Uploading a document

Because of the cumbersome way that binary file upload works in Net::HTTP library (you have to implement it all yourself), we decided to use a gem called "Multipart" which allowed us to mix the binary file with the rest of the parameters.

Let's take a look at the code:

To upload a publication to Issuu each request must be sent to http://upload.issuu.com/1_0? using the POST method. First we prepare the file with the Multipart's object UploadIO. 

Then we set the parameters that specifies the type of petition we will make. The most important fields are action, format and name:

• action: the upload action. This field will change when deleting a file.
• format: specifies the language of the response (JSON or XML).
• name: is the unique url of our publication.

Now we can sent the POST request using another Multipart gem method joining the "file" and "signature" parameters.

After sending the request, we can easily get the response status by decoding the JSON text returned by Issuu. If all goes well, we should receive an "ok" status followed by a limited number of response parameters, with information about the document which has been created.

Now it's a good idea to store the documentID so we can delete it later on.

Deleting a publication

Deleting a publication is fairly easy, we can use GET or POST method. We will use the second.

Here it is the code:

Note that we changed the url to http://api.issuu.com/1_0? and the action to issuu.document.delete

We can set the files to be deleted in the names field.

Other considerations

Because Issuu does not support file overwriting, we will have to delete each file before trying to upload it. You may be asking we could also make a request to check if the file is uploaded, but surprisingly you cannot make a request by documentID nor document name.

Loading mentions Retweet

In ubiquo_categories, there are mainly two ways to filter instances by the category name.

The first one is the built-in named scope. Let's say we have the following

Now we can use the automatically generated "with_genres_in" named scope to filter by this field:

Pretty handy. The second option to filter, is to retrieve the condition hash and then use it at our discretion. For example, in ubiquo models we usually have the filtered_search method, if we want to integrate this filter it would be done with:

Where "value" can be a single element or an array of strings or Category instances.

Hope you find this useful!

Loading mentions Retweet

Currently in ubiquo, when we have so many tabs to display all them in a single row, the approach to follow is to group them under a new group name, and then, use that name as a link to have a sub-menu with links to each single resource display. This approach is hard to maintain, because each time we add / remove / change any of that resources, we must update several files (one for each resource that appear in list).

Another approach has been taken in one of out projects. By now, is a custom change for that single project, but it can be leveraged to a template system easily.

The approach is similar to the previous one, except that we only maintain one single file (_main_navtabs) for all ubiquo navigation. The navigation now will have only two parts for each menu item:
- The first one will be the title, and it's use can be either as an informative resource and a link to one of those resources grouped under that name
- The second, will be a list (<ul> / <li>). Each row in the list will be a link to a resource.

The clever idea in this approach is the interaction between both parts of menu items:

Items list will be a hidden element in DOM, that only appear when mouse is over group name. In this way, those lists can co-exist without being displayed together at any time. The effect applied to show each list is a SlideDown effect from scripaculous.

The following snipped of code will display a group with all resources under it.

Loading mentions Retweet

We are designing a new version of Ubiquo's logo.

We are working on two lines: a completely new logo and a new interpretation of the current one.

Today I'll talk a little about the completely new logo version.

In this new version we want to introduce the concept of "golden ratio".

Mathematicians, architects,... have studied the golden ratio because of its unique and interesting properties, and it seems that "golden ratio" is in the majority of elements that surround us and is considered as "the perfect proportions".
We want you to find it in Ubiquo too.

Ok, for me there is not perfection, but golden ratio approximates my own sense of good proportions.

Here I show some of the tests I've done so far. I'll upload more.

In my opinion, "golden ratio" as a logo, aesthetically is a figure too classic for what it means Ubiquo, but we are trying to re-interpret it.

What do you think about it?

               

Click here to download:

ubiquo-logo-the-golden-ratio-nxmfEnFHFAunvAFbDfyk.zip (1606 KB)

Loading mentions Retweet

Do you work regularly with Ubiquo? How was your experience programming with Ubiquo? Do you collaborate in any way with the CMS framework?

Welcome to Ubiquo Planet! In this space you can explain anything that might be of interest to Ubiquo's community.

Loading mentions Retweet