Using OpenAmplify with Drupal, Part 1

OpenAmplify provides powerful text analysis tools accessible via an XML-based web service. The ease of use of the web API makes OpenAmplify a fantastic tool for building semantically oriented web applications. When I first encountered OpenAmplify, I was so excited about its potential that I immediately wrote a handful of applications. One such tool gradually solidified into a general purpose Drupal module.

In this three-part series of articles, we will look at using OpenAmplify from within the open source Drupal content management system (http://drupal.org). Drupal is a mature web-based CMS system. Two of its evident advantages are its emphasis on social networking and the ease with which it can be extended. In this article, we are going to look at Drupal's add-on Amplify module, which provides deep integration between Drupal's content system and OpenAmplify's analysis engine.

The first part of this series-the part you are presently reading-introduces the Amplify module and explains how to install and configure it. The remainder of this series will make use of the module to exhibit OpenAmplify in action and to provide practical details about writing code that makes use of the API.

The second part of this series focuses on building a mini-portal using the Amplify module. There, we will look at a little code, but the material will still be high level.

In the third part of the series, we will look at the API exposed by the Amplify module, and we will talk about the details of working with the OpenAmplify service. This part will be code-centered. While much of this series will have a lot to do with Drupal, the principles applied (and even some of the APIs) will be broadly applicable. We will be writing our code in PHP, and even non-Drupal PHP developers will be able to apply the information provided here to other projects.

This article will have three parts:

1.      Getting started with Drupal

2.      Installation the Amplify module and its dependencies

3.      Configuring the module

By the end of this first part, you should be familiar with the Amplify module and how to configure it in Drupal. The later parts will build on this knowledge.

Getting Started with Drupal

For those unfamiliar with Drupal, it is a web-based content management system (CMS) written in the PHP programming language. It uses a relational database (usually MySQL) to store data. The core Drupal system contains a bare-bones set of modules that can be used to build a generic website. But the real power of Drupal comes from the many (5,000+) add-on modules that provide additional features.

The current stable release of Drupal is Drupal 6. We will be using that version throughout this article.

You can get the core version of directly from Drupal.org (http://drupal.org). All of the add-on modules are available there, too, though you will need to download them one at a time.

If this is your first time using Drupal, I suggest grabbing one of the nicely packaged versions of Drupal provided by Acquia (http://acquia.com). These versions include a dozen or so of the most commonly used add-on modules. There are also full development stacks for Windows and Mac OS X which make it easy to get a webserver, database, and Drupal all up-and-running in a matter of minutes. You can install Acquia Drupal by following the directions provided on their site and in the distribution.

Drupal, being a mature product, has many sources of documentation, including the main drupal.org website and numerous published books. If at any point you find yourself stuck during installation, there are many resources to help you get going again. You can get started with the official Drupal handbooks (http://drupal.org/handbooks).

We are going to move on to the installation of the Amplify module.

Installing and Configuring the Amplify Module

As I mentioned above, Drupal has thousands of add-on modules available. One of these is a module that exposes OpenAmplify's web service to Drupal. We will be installing and configuring that module, along with a second module upon which it depends. The Amplify module is developer-oriented. To be able to make use of OpenAmplify's offerings right away, we will also install a third module called QP Services.

All told, we will be downloading and installing three modules:

1.      Amplify: The core API module for accessing OpenAmplify

2.      QueryPath: An XML and HTTP library that we use for interacting with OpenAmplify

3.      QP Services: A demonstration module that makes use of Amplify's capabilities

The Amplify module is maintained as a project on Drupal's official website. You can learn about the module (and download it) at http://drupal.org/project/amplify. You should download the current stable release.

OpenAmplify is an XML-based web service, and the Amplify module uses a helper module to work with the low-level XML. The helper module is the QueryPath Drupal module. This is maintained at http://drupal.org/project/querypath. Download the most recent stable version of this, as well.

In the next part, we will be building a mini-portal based on OpenAmplify's analysis. For that, we will need a third module called QP Services (QP is short for QueryPath). Download the latest release of QP Services from http://drupal.org/project/qpservices.

I have put the QueryPath, Amplify, and QP Services modules both in my home directory on the web server on which I will install them.

Installing the modules

Installing modules in Drupal is a two-step process. First, the module needs to be extracted into the appropriate location on the file system, then its installer must be run through the administration interface.

Add-on modules such as the ones we just downloaded should be installed in Drupal under the directory sites/all/modules. Here is a short series of shell commands for extracting the two modules:

$ cd sites/all

$ mkdir modules

$ cd modules

$ tar -zxvf ~/amplify-6.x*.tgz

$ tar -zxvf ~/querypath-6.x*.tgz

$ tar -zxvf ~/qpservices-6.x*.tgz

Here's what we are doing above. First, we find the sites/all directory of Drupal's installation. If you are using a fresh installation of Drupal, there may not be a modules directory already created. In the example above, we create one, and then change directories into that.

On the last three lines, we untar and unzip the downloaded add-on modules into the sites/all/modules directory. Drupal will look in this directory to find all available modules, so the next time we log into Drupal, it will be aware of our new add-ons.

Log into the Drupal administration interface and go to Administer > Site building > Modules. You should see a large list of modules. Look for Amplify. When you find it, check the Enable checkbox. Do the same for QP Services and QueryPath, and then submit the form.

Once this process is complete, you should now have OpenAmplify's administration pages available to you. The next thing to do is configure the Amplify module.

Configuring the Amplify Module

So far we have installed three modules. The Amplify module is the main one we are interested in right now. The QueryPath module has nothing we need to configure, and the QP Services module will be the subject of our next section.

To configure the Amplify module, go to Administer > Site configuration > Amplify settings. You will see something like this:

There are two main configuration options here:

• Amplify API Key
• Amplified Node Types

The first field is where you will enter the API key issued to you by OpenAmplify. If you do not already have one, you can sign up easily (http://community.openamplify.com/user/CreateUser.aspx). There is no charge for a basic key. This key allows requests from your server to authenticate against OpenAmplify's web service. If you do not enter a key, this module will not function properly.

The second group of fields are checkboxes. There is one check box for every content type you have created in Drupal. By default, you will probably see two: Story and Page. I have already defined several for my site. One of these is called Amplified Page.

Here's what these checkboxes do. Any content type that is checked will be automatically analyzed using OpenAmplify's service. So in the screenshot above, every time I create or update an Amplified Page, the contents of that page will be analyzed, and the results of that analysis will be stored in Drupal. In the next part, we will see how this works. For now, though, it is only important to note that new content will be analyzed if and only if it is of one of the types checked on this screen.

Once you have entered an API key and checked the desired content type checkboxes, save the configuration. That is all there is configure.

Conclusion of Part 1

In this brief article, we have taken the first steps toward working with OpenAmplify in Drupal. We have installed and configured the necessary libraries, and we have configured the core Amplify module to interact with the OpenAmplify web service.

The next part will take us beyond mere configuration. There, we will build a mini-portal which analyzes Drupal content using OpenAmplify, and then uses the analysis to draw in related information from around the web. As we build our site, we will talk about the principles and design driving the Amplify module.

In the final part, we will look beneath the hood and see how the PHP API works. We will write a simple  tool that uses OpenAmplify data to add a new feature to our Drupal site.

 

Matt Butcher is an author and software engineer. He has written six technology books and dozens of articles. He is the Lead Software Developer at Spine-Health, where he works on PHP, Drupal, and various other technologies. He is an active contributor to many Open Source projects, and is the maintainer of the QueryPath PHP library and a handful of Drupal modules (including the Amplify module). He blogs regularly at http://technosophos.com. When not writing code, Matt enjoys exploring Chicago with his wife and daughters. You can friend him on Twitter at http://twitter.com/technosophos.

---

Posted 6 Jan 2010 8:20 AM by DaveW