Listing 10-4 shows the install hook for our weather information module.

function weather_info_install() {
  global $user;
  // Insert a default weather_info category.
  db_insert('weather_info')
    ->fields(array(
        'location' => 'Manchester, NH',
        'units' => 'F',
        'language' => 'en',
        'uid' => $user->uid,
        'timestamp' => REQUEST_TIME,
        ))
    ->execute();
  drupal_set_message(st('Weather information table has been created.'));
}

First, an initial record in the database is inserted using the database API function, db_insert(). Recall that the schema array is read first by the installer program, so the table or tables should exist by the time the installer gets to the install hook. This means we are safe to insert our record. If this fails, it usually means there was a problem creating the tables from the schema. If that was the case, however, the error handler would probably prevent us from getting to this point.

The fact that we've gotten this far should mean that everything is good so far.

Next, we need to create the fields that our program depends on. The weather information module depends on certain fields that will be managed as part of the user's profile information. Back in Chapter 6, we created those fields manually. But we don't want to burden our users with this,

The Fields API has a number of functions that allow us to create, retrieve, update, and delete fields. Like any good API, the Fields CRUD API isolates us from the details of the underlying implementation and allows us to get our job done without worrying about how the tables actually look.

Listing 10-5 shows the API call for the first field, field_weather_location.

// *
// * Weather location field
// *

$field = array(
  'field_name' => 'field_weather_location',
  'type' => 'text',
  'translatable' => TRUE,
  );
$instance = array(

'field_name' => 'field_weather_location',
  'entity_type' => 'user',
  'bundle' => 'user',
  'label' => 'Weather location',
  'widget' => array(
      'type' => 'text_textfield',
      'weight' => '15',
      ),
    'description' => st('Enter a location on earth for which you would like '
      . 'to see weather information presented.'),
    );

// Create the field and instance.
field_create_field($field);
field_create_instance($instance);

We use two arrays. The first, $field, provides the name of the field we are creating and its type. This is the field itself, which can be used in many different places. The second, $instance, is one instantiation of a field, which has particulars concerning the actual instance. This seems redundant for this simple field, but you could have a custom field that contains many different facets of atype of information, such as a color with red, green, and blue components, or an address made up of street, city, state, postal code, etc. Defining this field once and instantiating it for particular purposes is more efficient.

Listing 10-6 shows the remaining two fields we need to create.

// *
// * Weather language field
// *

$field = array(
  'field_name' => 'field_weather_language',
  'type' => 'list_text',
  'translatable' => TRUE,
  'settings' => array(
      'allowed_values' => "en|English
es|Spanish
de|German
tr|Turkish
fr|French
",
      'allowed_values_function' => '',
      ),
    );
$instance = array(
  'field_name' => 'field_weather_language',
  'entity_type' => 'user',
  'bundle' => 'user',
  'label' => 'Weather language',
  'widget' => array(
      'type' => 'options_select',
      'weight' => '16',
      ),
    'description' => st('Enter the language in which you would like to see '
      . 'weather information presented.'),
    'default_value' => array(
      array(
        'value' => 'en',
        ),

),
    );
field_create_field($field);
field_create_instance($instance);

// *
// * Weather units field
// *

$field = array(
  'field_name' => 'field_weather_unit',
  'type' => 'list_text',
  'translatable' => TRUE,
  'settings' => array(
      'allowed_values' => "F|Fahrenheit
C|Celsius
K|Kelvin
R|Rankine",
      'allowed_values_function' => '',
      ),
    );
$instance = array(
  'field_name' => 'field_weather_unit',
  'entity_type' => 'user',
  'bundle' => 'user',
  'label' => 'Weather units',
  'widget' => array(
      'type' => 'options_select',
      'weight' => '17',
      ),
    'description' => st('Enter the measurement unit with which you would like '
      . 'to see weather information presented.'),
    'default_value' => array(
      array(
        'value' => 'F',
        ),
      ),
    );

field_create_field($field);
field_create_instance($instance);

Notice the allowed_values property for the language and unit fields. Since these are list_text field types, the allowed_values field provides a list that will appear in a drop-down select widget or a radio button list. The newline characters ( ) denote the individual values, and the vertical bar (|) separates the value that will be placed in the database from the text that will be shown to the user.

The enable hook is shown in Listing 10-7.

function weather_info_enable() {
  variable_set('default_location', 'Manchester, NH'),
  variable_set('default_units', 'F'),
  variable_set('default_language', 'en'),

variable_set('current_location', variable_get('default_location'));
  drupal_set_message(st('Weather information default variables have been set.'));
}

The only task of the enable hook, in our case, is to set up the four system variables the module depends on. Recall that this hook is called after the install hook, so if there are any tasks you need to do that depend on tables that were created or modified, it's safe to do them in this hook.

That wraps up the tasks necessary for setting up our installer to be ready for our weather information module. Here are some other common tasks you might want to take care of in your install hook:

Of course, there are myriad other things you might want to do to set the system up for your module.

Now that we've created the weather information history table, we'll want to add some functionality to our module that takes advantage of the new table. To start, we will insert a record every time a user changes his profile information inhis user profile. The function to insert the record is shown in Listing 10-8.

function weather_info_insert_history($location, $language, $unit, $weather) {
  global $user;
    $fields = array(

'location' => $location,
      'language' => substr($language, 0, 2),
      'units' => substr($unit, 0, 1),
      'uid' => $user->uid,
      'timestamp' => REQUEST_TIME,
      );
    $options = array('return' => Database::RETURN_STATEMENT);
    $returned = db_insert('weather_info', $options)
      ->fields($fields)
      ->execute();
}

We will call this function from the validate function of the form where the user enters information on the profile page. The code is shown in Listing 10-9.

function weather_info_profile_weather_location_validate($element, &$form_state) {
  $location = $form_state['values']['field_weather_location']['und'][0]['value'];
  $language = $form_state['values']['field_weather_language']['und'][0]['value'];
  $unit = $form_state['values']['field_weather_unit']['und'][0]['value'];
  if (variable_get('default_location') != $location) {
    $weather = weather_info_get_weather($location, 'en'),
    if ($weather) {
      weather_info_insert_history($location, $language, $unit, $weather);
    }
    else {
      form_set_error('field_weather_location[und][0][value]', t('Cannot get weather for %location.',
        array('%location' => $location)));
    }
  }
}

This stores the appropriate information into the history table whenever the user makes a change.

The disable hook is executed when a module is unchecked on the Modules page and the page is submitted, as shown in Figure 10-4.

Figure 10.4. The disable hook

The disable hook, then, should be used only to put the system in a state where other functions are not affected by its presence. Listing 10-10 shows the weather information disable hook.

function weather_info_disable() {
  variable_del('default_location'),
  variable_del('default_units'),
  variable_del('default_language'),
  variable_del('current_location'),
}

This function merely deletes the system variables from the variables table. This is probably not necessary because it's unlikely that any other module will be using them, but it is good manners to clean up after yourself. Remember that the disable hook is optional. If you don't include it, your module will still be removed from the list of enabled modules, and its functionality will be unavailable.

The uninstall hook is executed when the module is checked on the uninstall page and the page is submitted, as shown in Figure 10-5.

Figure 10.5. The Uninstall Hook

The uninstall hook is where you really clean up all traces of your module—any directories you've created on the site-managed store, or any configuration changes made to the system table, or any number of things you may have done to prepare the system for your module. Listing 10-11 shows the weather information uninstall hook.

function weather_info_uninstall() {
  field_delete_field('field_weather_location'),
  field_delete_field('field_weather_language'),

field_delete_field('field_weather_unit'),

  // Flush the cache to get rid of the user profile page entry
  drupal_flush_all_caches();
}

During the install phase, we created three attached fields that entered information into the database tables that the Field module managed. When we uninstall the module, our uninstall hook function needs to delete all traces of our activities. This is done by deleting the fields, which removes all of the information from the system.

There's one last taskto perform before we deliver our module. We need to add the .install file to our .info file so Drupal knows about it. Listing 10-12 shows the new .info file.

; $Id$
name = Weather information
description = A block that shows current weather for a particular location.
package = Cool stuff from Brian
core = 7.x
files[] = weather_info.module
files[] = weather_info.inc
files[] = weather_info.install
files[] = tests/weather_info.test
dependencies[] = blocks
configure = /admin/config/weather_info/settings
version = 7.x-1.x

That covers the installing and uninstalling of modules. Now, what happens if you need to make changes to existing modules and you don't want to require your users to rebuild everything? You can give them the tools to perform an update.

The project for this book, the weather information block, saves location, language, and unit information in the database table we created with the .install script. As a new revision, I'd like to also save the XML stream that's returned whenever a user selects a new location. Plus, I'd like to make the name of the database table more descriptive.

Changing the name of a table in the database will break all kinds of things that depend on it. In our case, we have encapsulated the access to that table ina single function, so we don't need to make many changes. Listing 10-13 shows the modified function to write to the table and insert the new information.

function weather_info_insert_history($location, $language, $unit, $weather) {
  global $user;
  $fields = array(
    'location' => $location,
    'language' => substr($language, 0, 2),
    'units' => substr($unit, 0, 1),
    'uid' => $user->uid,
    'timestamp' => REQUEST_TIME,
    'xml' => $weather->asXML(),
    );
  db_insert('weather_info _history')
    ->fields($fields)
    ->execute();
}

Notice the asXML() method on the weather object. This is a way to serialize the XML weather object so it can be stored as a text field. We have also changed the name of the table on the db_insert() function to reflect our new table name.

This code works on our system, because we have manually changed the name of the table in our database and added the field. But we don't want our users to have to go through that effort. Plus, we want to take all of the existing data and populate the new field with the XML for the previously stored locations.

Listing 10-14 shows the update function that will do all of that.

/**
 * Rename {weather_info} table to {weather_info_history} and add a field to capture
 * raw XML data from the weather service.
 */
function weather_info_update_7100() {
  ... update logic goes here.
}

First, notice the Doxygen-style comment before the function declaration. We'll see that a bit later when the module is updated.

Next, see the carefully crafted function name, weather_info_update_7100(). This is a hook that will be found and executed by the update program. It is the name of our module, followed by _update_, followed by a number that indicates information about the particular update. That number is created according to the following rules:

The following are examples of update hook names:

Listing 10-15 shows the complete function that will be updating our module.

/**
 * Rename {weather_info} table to {weather_info_history} and add a field to capture
 * raw XML data from the weather service.
 */
function weather_info_update_7100() {
  db_rename_table('weather_info', 'weather_info_history'),
  db_add_field('weather_info_history', 'xml',
    array(
      'type' => 'text',
      'size' => 'normal',
      'description' => 'Raw weather XML returned.',
    )
  );

  // update all existing records
  $result = db_select('weather_info_history', 'h')
    ->fields('h', array('hid', 'location', 'language'))
    ->execute();
  foreach ($result as $record) {
    $weather = weather_info_get_weather($record->location, $record->language);
    if ($weather) {
      db_update('weather_info_history')
        ->fields(array(
            'xml' => $weather->asXML())
            )
        ->condition('hid', $record->hid, '=')
        ->execute();
    }
  }
}

The first two functions rename the table and add a new field. Then, the rest of the code reads the existing records and updates each record with the XML generated by a call to the weather service.

Now that the .install file is ready, let's deliver our package to the users. We just need to modify the .info file first. Since we have a new version of our program, we should update the version number. In this case, the new version number will be 7.x-1.0. Our new .info file is shown in Listing 10-16.

; $Id$
name = Weather information
description = A block that shows current weather for a particular location.
package = Cool stuff from Brian
core = 7.x
files[] = weather_info.module
files[] = weather_info.inc
files[] = weather_info.install
files[] = tests/weather_info.test
dependencies[] = profile

configure = /admin/config/weather_info/settings
version = 7.x-1.0

After we place the new module files in our directory and go to the Configuration page, we'll see the error shown in Figure 10-6.

Figure 10.6. The update manager detected a new version.

The error message is displayed by the update manager, which noticed that there is at least one new version of an installed module. Clicking on "status report" provides more information, as shown in Figure 10-7.

Figure 10.7. The update manager has detected new updates.

Clicking on "database update script" launches the update program, which starts the wizard shown in Figure 10-8.

Figure 10.8. The database update wizard

Clicking "Continue" shows all of the updates that are available. (See Figure 10-9.)

Figure 10.9. Information on a pending update

You'll notice that the information in our .install file is shown here. You can see the information contained in the comment that was entered just before the update function definition. Also, you can see the number of the update, 7100. Clicking "Apply pending updates" causes the updater to run all of the update functions available (in this case, just one). The throbberdisplays while the process is executing. (See Figure 10-10.)

Figure 10.10. The module update screen indicates updates in progress.

Finally, the update happy screen is shown in Figure 10-11.

Figure 10.11. A status screen is displayed once the updates are complete.

There are some important things to keep in mind about the .install file and updates:

Now that you have your module described and instructions for installation, let's talk about the process of delivering your module to your users.