The basic structure of the file looks like the following:

<?php
// $Id: default.install,v 1.18 2009/11/10 17:27:54 webchick Exp $

/**
 * Implement hook_install().
 *
 * Perform actions to set up the site for this profile.
 */
function default_install() {
  //Actual work happens here!
  ...
}

The file starts out with the opening PHP tag <?php. Then, the Id is again entered automatically by the version control system. If you are developing your own installation module, you should simply enter // $Id$. Do not enter all the remaining information; that will be generated automatically. Next, the file has a comment (the information starting with /** and ending with */) stating what the function does. This is good coding practice and helps other people to understand what you are trying to do. It can also help you understand your own code if it's been a little while since you wrote it. You may even want to include a summary of what the installation will do, and why, to remind yourself after you have been away from the code for a while.

After the comment comes the actual implementation of hook_install. Since this profile is named default, the function is called default_install. The logic of the function is then included and the function ends with a closing curly bracket. By convention, Drupal files do not include the optional closing PHP tag after all functions have been written, so the file ends there.

Now, let's look at the actual logic being performed within the profile. The first section of code begins by defining several blocks which are then added to the default display.

// Enable some standard blocks.
  $values = array(
    array(
      'module' => 'system',
      'delta' => 'main',
      'theme' => 'garland',
      'status' => 1,
      'weight' => 0,
      'region' => 'content',
      'pages' => '',
      'cache' => -1,
    ),
    ...
    array(
      'module' => 'user',
      'delta' => 'new',
      'theme' => 'seven',
      'status' => 1,
      'weight' => 0,
      'region' => 'dashboard_sidebar',
      'pages' => '',
      'cache' => -1,
    ),
  );
  $query = db_insert('block')->fields(array('module', 'delta', 'theme', 'status', 'weight', 'region', 'pages', 'cache'));
  foreach ($values as $record) {
    $query->values($record);
  }
  $query->execute();

Each block is loaded into the $values array. Each module defines the name of the module, which defines the block as well as the delta or unique ID of the block within the module. The theme setting controls which theme the block should be active for and the status variable controls if the block is enabled (1) or disabled (2). The region variable controls where the block should be displayed within the page and weight controls the position within the region. The pages setting controls which pages the block should be shown on. In the case of the default installation profile, they are shown on all pages. If you want to only show the block on some pages, you should also include the visibility parameter. The cache setting controls whether or not the block can be cached to optimize performance. By default, all blocks are set to -1, which means do not cache. You can change this to a variety of values for fine-grained caching control. For a complete list of fields that can be set for a block and their possible values, see:

http://api.drupal.org/api/function/block_schema/7.

The next several lines set up a query to insert the blocks into the database using the new DBTNG layer and then execute the query to save all of the new blocks. We will review the DBTNG layer more in Chapter 6, so don't worry about the actual syntax too much for now.

The next section adds some default node types that editors can use to add content to the site.

  // Insert default user-defined node types into the database. For a complete
  // list of available node type attributes, refer to the node type API
  // documentation at: http://api.drupal.org/api/HEAD/function/hook_node_info.
  $types = array(
    array(
      'type' => 'page',
      'name' => st('Page'),
      'base' => 'node_content',
      'description' => st("Use <em>pages</em> for your static content, such as an 'About us' page."),
      'custom' => 1,
      'modified' => 1,
      'locked' => 0,
    ),
    array(
      'type' => 'article',
      'name' => st('Article'),
      'base' => 'node_content',
      'description' => st('Use <em>articles</em> for time-specific content like news, press releases or blog posts.'),
      'custom' => 1,
      'modified' => 1,
      'locked' => 0,
    ),
  );

  foreach ($types as $type) {
    $type = node_type_set_defaults($type);
    node_type_save($type);
  }

In this case, two node types are being added—a page node type and an article node type. The installation profile defines the type, name, and description for each node type. These are all fairly straightforward. However, note that the st() function is called to provide translations rather than t(). This is done because the install function is called during the install process and the full localization system may not be available yet. The profile also sets the base for the node type, which tells Drupal which module will control the functionality of the node. By setting custom to 1, the installation profile instructs Drupal that this node type should be treated as if it were created by a user and that it is not defined by a module. Setting locked to 0 indicates that the name of the content type can be modified by an administrator.

After basic information has been defined for each node type, the installation profile begins to save each type individually. Before saving the type, it calls node_type_set_defaults, which builds a type object and adds additional default information to it. The new node type is then saved with a call to node_type_save.

The installation profile then uses the same technique of defining an array of information and then saving it to build RDF-mapping information for each type as well as taxonomies and fields. Because these substantially use the same techniques as creating blocks and node types, we will omit a line by line discussion of these.

Between setting up the RDF mappings and creating taxonomies, the installation profile sets the values of some variables in the database using the following lines:

  // Default page to not be promoted and have comments disabled.
  variable_set('node_options_page', array('status'));
  variable_set('comment_page', COMMENT_NODE_HIDDEN);

  // Don't display date and author information for page nodes by default.
  variable_set('node_submitted_page', FALSE);

  // Enable user picture support and set the default to a square thumbnail option.
  variable_set('user_pictures', '1');
  variable_set('user_picture_dimensions', '1024x1024');
  variable_set('user_picture_file_size', '800');
  variable_set('user_picture_style', 'thumbnail');

All of these lines use the variable_set function to change the value of the variables. You can get a list of all variables defined within Drupal using the Devel module (http://drupal.org/project/devel).

Skipping down to the end of the file after all of the fields have been created, the installation profile sets some default permissions for the Anonymous and Authenticated roles using a call to user_role_grant_permissions.

  // Enable default permissions for system roles.
  user_role_grant_permissions(DRUPAL_ANONYMOUS_RID, array('access content', 'use text format 1'));
  user_role_grant_permissions(DRUPAL_AUTHENTICATED_RID, array('access content', 'access comments', 'post comments', 'post comments without approval', 'use text format 1'));

If you are creating your own installation profile, which activates additional modules, you may want to activate additional permissions for these users.

The installation profile also creates a new role for the administrator and sets some default permissions:

  // Create a default role for site administrators, with all available permissions assigned.
  $admin_role = new stdClass();
  $admin_role->name = 'administrator';
  user_role_save($admin_role);
  user_role_grant_permissions($admin_role->rid, array_keys(module_invoke_all('permission')));

The new role is set up by creating an object to store the role and then saving it with a call to user_role_save. The permissions are granted by first calling module_invoke_all('permission'). This loads all available permissions for all modules which have been enabled, thus giving the administrator role all available permissions.

To ensure that the administrator role stays up to date, the installation profile assigns the administrator role as the system admin role by updating the appropriate system variable.

  // Set this as the administrator role.
  variable_set('user_admin_role', $admin_role->rid);

Next the profile rebuilds the menu system to ensure the cache is fresh and that all modules which were installed are correctly updated:

  // Update the menu router information.
  menu_rebuild();

Finally, the installation profile activates the Seven theme and sets it up for use as the administration theme.

  // Enable the admin theme.
  db_update('system')
    ->fields(array('status' => 1))
    ->condition('type', 'theme')
    ->condition('name', 'seven')
    ->execute();
  variable_set('admin_theme', 'seven');
  variable_set('node_admin_theme', '1');

To do this, it again executes a query using the new DBTNG syntax and then sets a couple of variables to finalize the installation. Don't worry about the syntax of the update query too much right now; we will definitely explore this in more detail in Chapter 7.

After the Seven theme has been installed, the installation profile ends and the installation continues. Remember, because the Drupal core has been installed and all of your modules have been activated, when the install function runs, there is a wide range of actions you can perform during this routine.