This submodule exposes the data from the Goodreads module (and optionally the Goodreads OAuth module) to Drupal via an input filter.

To use the Goodreads filter submodule:

1. Make sure you have the main Goodreads module installed and configured.
2. Enable the Goodreads filter submodule on your site’s module page (Administer >> Site building >> Modules).
3. The Goodreads filter submodule needs to be added to one or more existing input filters, such as the full HTML input filter (Administer > Site configuration > Input formats), select the Goodreads filter checkbox, and save your settings:

Once you’ve configured the an input filter to include the Goodreads filter, you can insert Goodreads data using the general format

[goodreads_function_name selector parameters]

Square brackets are used to delimit a Goodreads token, like many other contributed module input filters.

After the opening square bracket insert the Goodreads API function name you want to access. All the Goodreads API PHP functions start with “goodreads_” and are listed alphabetically. As an example, to get information about a book using its ISBN, the corresponding Goodreads API function would be:

goodreads_get_isbn_reviews($isbn, $rating = '', $text_only = '')

The input filter for that function would start:

[goodreads_get_isbn_reviews ….]

After the function name is the data selector for the data element you want. Each Goodreads API function will return a different multi-dimensional array with the data returned by that Goodreads API call. You will need to use the sample XML displays from the Goodreads API or the sample selector list contained in GOODREADS_FILTER_LIST.txt in the Goodreads Filter folder to pick the selector you need.

Selector notation changes the format of standard PHP array notation to avoid conflicting with the square brackets used by many token input filters, including the Goodreads filter submodule. To convert from standard PHP array notation, remove the square brackets and any quotations from the associative array and separate the elements with hyphens. In the continuing example of the goodreads_get_isbn_reviews function, if the result is returned in a multi-dimensional array $reviews, to represent the first author of a book, found at

$reviews[‘authors’][‘author’][0][‘name’]

You would use the selector authors-author-0-name, separated from the function name by a space like:

[goodreads_get_isbn_reviews authors-author-0-name …]

In the selector list, a number of selectors have a 0 shown. When a Goodreads API can return more than one result for a given element, they are contained in an indexed array selected by their number: 0, 1, 2, etc. So to get the primary author for a book use the above example, to get the second author of a book use:

[goodreads_get_isbn_reviews authors-author-1-name …]

While getting a single value of the group might work for many applications, if you would like to get all the values, separated by commas, substitute an asterisk for the index number like:

[goodreads_get_isbn_reviews authors-author-*-name …]

The last parts of the Goodreads filter module token are any parameters that are to be passed to the function. They are separated from the selector with a space. Continuing our example in the simplest case, the goodreads_get_isbn_reviews function needs the ISBN of the book. For this example we’ll use 1430209895, the ISBN of Pro Drupal Development:

[goodreads_get_isbn_reviews authors-author-0-name 1430209895]

Which would insert

John K. VanDyk

into the content you put this token into. If you see the token and not the result, the most likely cause is you haven’t selected the proper input format, or that format doesn’t have the Goodreads filter enabled.

Many functions have multiple parameters, separate them with commas. Any blank parameter can be skipped when needed. For the goodreads_get_isbn_reviews function if we only want to return reviews that contain text, therefore excluding any review that is just a five star rating, for Pro Drupal Development, the token to for the reviews iFrame widget would be

[goodreads_get_isbn_reviews reviews_widget 1430209895,,true]

A more complex example that returns the first page members of a Goodreads group, the Goodreads developer group, sorted by number of posts/comments would be

[goodreads_get_group_members group_user-*-user-first_name 62646,1,num_comments,d]

Spaces following a comma are ignored. Strings can be enclosed in single or double quotes, or not at all, as shown in the above example.

To review, the general format for a Goodreads filter token is function, selector and parameters:

[goodreads_function_name selector parameters]

In theory any of the Goodreads API functions can be used in a Goodreads filter token, including the OAuth API’s if the Goodreads OAuth submodule is enabled. While that suggests it would be possible to insert a Goodreads filter token that would change something on the Goodreads site, such as posting a review to a book, it is not suggested. I can’t think of a use case and worry about submitting the same change multiple times as a page gets loaded over and over.

Also it is sort of possible to pass the results of one Goodreads filter token as the last parameter of another Goodreads filter token. It wasn’t in the original design but appears to be possible, with some limitations, because the filter can be called recursively. However, at least as currently implemented, the nested token must be the last parameter of the outer token because of the way the parameter string is parsed by the regex expression in the filter. In addition, for the same reason, the syntax is slightly off; only one closing square bracket is used. To get the names of all the groups the current user belongs to you could use

[goodreads_get_user_groups list-group-*-title [goodreads_oauth_get_user_id id]

This has some use as it is implemented but really needs a patch contributed to make it work in a more general and symmetrical manner.