How to create an install script

Hi this is Chris Shattuck with Build a Module dot Com. I'm going to talk a little but about what happens when someone installs your Module, and typically, if your Module has some data that it needs to store, there's some places to do that inside of Drupal, but sometimes you need to setup your own tables, so we'll go over some examples of how other Modules are doing that. Plus, when the Module installation Script is triggered, a lot of things can happen, basically anything; you can do anything in Drupal.

So we'll talk a little bit about all that stuff. First of all, when you create a table inside of Drupal, there is a particular way that you do it, and the reason why we don't use just basic vanilla SQL, is that it's not a cross-database compatible, so in previous versions of Drupal, people had to create a different versions of their installation's Script, based on the type of database that they're trying to support. Also, it's easy to make mistakes inside a basic SQL Statement, and not everybody knows all the little tricks and tips, and how to use it and how to format it and Syntax stuff like that.

So in Drupal, it has a built-in system called a Schema API which allows you to create a table by just defining an Array Key Value pairs. It's pretty simple to use, the only trick is knowing what keys to use for what type of column or Function that you need inside of the table. There's some benefits in doing this.

For one, you just have to create an Array to generate a table. Second, its easier look at other people's examples of how they are creating their tables and it's easier to generate it, because you are just dealing with an Array, you're not dealing with a funky SQL Syntax. Finally, there's a lot of cool little API Functions you can use to Hook in to the Schema API, to change your table columns to update them, to add new columns and a couple of other things too.

So, all of that functionality is in there, sort of built-in; so if you use a Schema API, you get some benefits. When you're setting up, what happens when your Module is installed, all of your Code is going to go to your dot Install file. So that's going to be named with your Module Name, and then ending in the dot Install Function.

You're going to be using a few basic Hooks. The first is hook install, and this is where we stick anything that's going to happen when our Module is installed. We will use hook schema in order to define the database tables that we're going to be adding for our Modules.

We'll use 'Hook uninstall' to use this Scheme API to pull out our tables after our Module's been Uninstalled, and to run any tasks that we need to when that's Uninstalled. So, a common thing would be unsetting any Variables that your Module will have set. Finally, we're going to look at 'Hook update N' which is how a Module can add new changes to a database table, after the Module has been installed; in the structure here the 'N' just stands for a number, so a Module can provide multiple Update Functions in sequential order, and those will all be run on a Module Install, or in a when a Module is updated it will just run the updates from that version that it was last installed at.

Before we go over some examples, I want to point you to some useful documentation on this. The first page I want to point you to is a good tutorial page on writing dot Install files in Drupal 6, on Drupal dot org. This is part of the Module's Developers Guide and it takes you through the basics of what you need for dot Install file; it's pretty good.

Secondly, I want to point you to Hooks, at the Hooks documentation at API dot Drupal dot org; that's API slash group slash Hooks slash 6. This page lists all of the Hooks that you would use in Drupal, and includes the four that we are going to cover; Hook Install, Hook Schema, Hook uninstall, and Hook update N. You can find those in alphabetical order, or you can use your Browser's search functionality to find the one you are looking for.

On Drupal dot org, there's some documentation on the Scheme API, how it came to be, how you can use it to do some crafty cool little things. The basics are pretty much all you need to get a functioning Module that's using a database table, but you can do some other good stuff if you need more complex functionality out of your table. Finally, I want to point you to the Deadwood Module that's project slash deadwood on Drupal dot org; what this Module will do is automatically convert an older version of a Module to a newer version.

It does a really good job on the dot Install file, so it will take vanilla SQL Query that we would use in older versions of Drupal and convert that into the Schema API. This can be pretty handy, so if you want to see how your Script might convert into the Schema API, you can run it through Deadwood. Ultimately, it will probably be easier to just look at some other Modules Install files, and draw from those for inspiration.

Let's go ahead and do that, and take a look at couple of popular Modules in Drupal to see how they craft Install files. The first Module we're going to look at is Twitter; the Twitter Module. You can see that the dot Install file, even though it doesn't have a PHP extension, its syntax colored in my editor to look like PHP.

One thing I wanted to point out is that in virtually, in any integrated development environment, or IDE, and many text editors you can associate the extension with a particular type of syntax coloring. So in this case, I've associated the Install extension with the PHP syntax coloring. It can be useful especially when you're looking at bigger Arrays, and things like that, and a little difficult to part visually without the colors.

So what we have here at the very top is an implementation of Hooks Schema, so that's the Name of the Module, underscore Scheme. It starts out with a Key Value pair and it looks like because we're defining an Array here, this allows us to add more items later. Each table in your Module is going to be an item in this Scheme Array.

So, we're defining this Schema for this Twitter table here. We're starting off with the description of the table; which is just kind of nice. I don't even know how to do that in my SQL, so this is a good little addition there that slow overhead for me, but add some description to the table that I wouldn't normally be able to do in just basic SQL.

Next, is a definition of the fields; so the field is an Array, and each field is an Array in itself. There's a lot of nested Arrays, and with a structured like this, it's a little easier to read because we can see through the indents where each column is and what the Values are for them. In other examples, they boil it down to just a single line, an ...

Read the last half of the transcript