Creating content of a particular type is just a matter of navigating to the appropriate place in the administrative section. Let's start with an About Us page.

From the front page, click on "Add new content". You'll get a list of all of the content types that are currently available on your system. (See Figure 6-1.)

Figure 6.1. Content types available

This page will contain all of the content types that are currently installed and enabled on your system.

Clicking "Basic page" presents the screen shown in Figure 6-2, where you'll see two fields, "Title" and "Body."

Figure 6.2. Form to create a basic page

The Title and Body fields are standard Drupal features for most content types. Notice the orange asterisk next to the Title field. This indicates that the field is required to contain content.

Notice as well the small number of HTML tags that can be placed inline. These will be interpreted according to the input filters listed just below the body field.

Drupal comes with two filters: Filtered HTML and Full HTML. You can create more filters if you like, and some contributed modules create their own filters for specific purposes.

To understand why filters are necessary, you need to think about the different types of content you create. For example, if your module is designed to send e-mail to your subscribers, you might want a filter that only allows HTML tags that are e-mail-friendly, or one that allows no HTML tags at all for text-only messages.

At the bottom of the page, you'll see some buttons, Save and Preview. Clicking the Preview button lets you see the content before actually publishing it. This is a good idea, particularly as you are learning how the system works, because posting something—especially if you are hand-coding your HTML tags—could result in exposing information publicly before you can check for errors.

Because previewing is so important, it is possible to define content types such that the user will not be able to see the Save button until the post has been previewed first. (See Figure 6-3.)

Figure 6.3. Preview of a basic page

Notice that the HTML tags have been interpreted to format the text. That is, the title has turned into an HTML header and the <ul> and <li> tags have been turned into a list. Notice, also, that there are two versions, "trimmed" and "full." Drupal saves both versions and uses each where appropriate. For example, if a number of articles are to appear on the front page of a site, the trimmed version will be shown. This is also called a teaser. Whenever a teaser is shown, there is usually a "Read more..." button to get to the entire entry.

Drupal makes a guess at where you want the teaser separated from the rest of the content, but if you'd like to indicate, for example, just the first couple paragraphs, you can insert an XML processing instruction, <!--break-->, at the point where you'd like to separate the teaser from the body of the content.

If you'd rather have different text displayed as the teaser, you can click the "Edit summary" link, which will give you another box for entering this text.

Notice the area near the bottom of the page that lists a number of settings you can add for this particular page. The menu settings allow you to add the page to a particular menu hierarchy. In this case, let's add it to our primary links menu so we can display it on every page. (See Figure 6-4.)

Figure 6.4. Creating a Main menu entry

The revision information area indicates whether you want to keep revisions for this page. Since this is a new page, the only version is the original. In other words, no revision. But if you were to come back and modify this page and click the "Create new revision" box, the original version of the page would be saved, as well as a new revision. If you need to revert back to the original, it thus becomes trivial.

By default, a page is accessed by its node number. If we were to save this page right now, we would access it with the URL http://mysite.com/node/1. While that might be sufficient for accessing forum topic number 60,456, we would like to see something more appropriate for a page used as often as the "About us" page. That's where the URL path settings page comes in. Clicking that link displays a text box where you can type an alias for the path that's more appropriate for the content. (See Figure 6-5)

Figure 6.5. Setting the URL path

The text is what your user will type after http://mysite.com/. The text can also have paths, so if you set the URL alias field to content/about/marketing, you could publish the URL as http://mysite.com/content/about/marketing.

Drupal's comment framework provides a way for users to post comments on virtually any piece of content on the site. Commenting is turned off by default for pages, but can be turned on for any page.

The role-based permissions engine allows you to specify which types of users have the ability to create, delete, edit, or even view comments. For example, anonymous users might be given the ability to read comments that have been posted, but only authenticated users who have created an account can add new comments. And only administrators or authors are able modify or delete comments. I'll cover the permissions framework later.

The authoring information block allows you to specify the person who created the content. By default, this is the currently logged-in user.

Given the proper permissions, you can change this to any user on the site. You can also indicate when the post was authored. Leaving it blank specifies the current time, but you can change this if you'd like.

Finally, the Publishing options block will allow you to specify how the content is to be treated when you save it.

By default, pages are not promoted to the front page, but stories and blog entries have that box checked by default. Publishing content allows it to be read by your users (based on permissions).

Unchecking the Published box lets you save the content, but it will be marked as a draft and users won't be able to see it. This is handy, for example, if you are working on a post but you are not ready to give it to users.

Making a post sticky causes it to appear at the top of any list of content where it would otherwise appear in reverse chronological order. This is useful when you have content that all users should see, like site policies or frequently asked questions.

Pressing the Save button publishes the page and it will appear in the browser, as shown in Figure 6-6.

Figure 6.6. The create page happy screen

Notice at the very top of the page that the "About Us" link appears in the upper left. That's because we added the page to our Main menu. This is a quick way to create several important pages that your users will probably expect to see on your site. Plus, you can access the page with the URL, http://mysite.com/about directly.

Working hand-in-hand with the permissions framework is the concept of user roles. Every user who accesses your site will have one or more roles. Each user has a unique user id, or uid, which is an integer that increments with each new user.

There are two special uids on your site, 0 and 1. When you first configured your site, you entered the username and password of the administrator, who automatically became uid 1. The administrator has access to every single aspect of your site, and does not require any permissions to be set.

At the other end of the spectrum is a user when he first comes to the site. This user is considered "anonymous" and will have a uid of zero.

All other users are considered "authenticated" once they create an account and, optionally, depending on how you configure your site, authenticate that they have a valid e-mail address. Users can create an account by clicking the "Create new account" link under the Log in button.

This will take them to the registration screen, which will only ask for a username and a e-mail address by default. This is shown in Figure 6-28.

Figure 6.28. New user registration screen

By default, only a username and e-mail address are required, but you can add more required fields, as we will shortly. By default, the system will send an e-mail to the user requesting her to click on a link. This will verify that the person has entered a valid e-mail address and that the user has access to that e-mail address. This helps to avoid spambots from creating bogus accounts.

Note

if you want more protection against bots, there are a number of bot-fighting modules you can employ, such as CAPTCHA, as shown below:

The CAPTCHA module is quick to install in your Drupal enviroment and provides instant discouragement to bots.

The user will see a confirmation that the account was created (see Figure 6-29).

Figure 6.29. The confirmation shown to the user will depend on site approval settings.

As an administrator, you can specify more information that is required on the form at Configuration

Figure 6.30. In the account settings screen you can craft emails for various purposes.

You can, for example, require that the user respond to an e-mail in order to be authenticated, or that all users be approved by an administrator before being granted access to the system.

On this page, you can also craft e-mail templates for various user management functions:

These messages have variables available so you can personalize the message to the user. Once a user registers, he or she will get assigned the next available uid. An example e-mail message is shown in Figure 6-31.

Figure 6.31. An message generated to assure a valid e-mail address

In the case of the site allowing visitors to create their own accounts, the e-mail sent will have the standard link to verify that the e-mail address is correct. It also gives the new user the ability to set a password, as shown in Figure 6-32.

Figure 6.32. Initial user login screen

Once authenticated, either by administrative approval or e-mail verification (or immediately if user authentication is turned off), the user can access the system.

The site administrator can also manually authenticate a user by changing Status from Blocked to Active.

Adding a Role

Your site can have as many different roles as necessary. Let's create a new role for authenticated users on our site whom we have chosen to write blog entries. Let's call the role "blogger." Before doing this, make sure the Blog module is enabled (from the Modules menu).

Access the roles page by navigating to People

Figure 6.33. Adding a new role

Type "blogger" and click "Add role". Once the screen comes back, click "edit permissions" to get to the permissions page shown in Figure 6-34.

Figure 6.34. Permissions page for new user

When you go to the user permissions page you'll see the new role with nothing checked. Check the appropriate permissions and click "Save permissions".

Finally, we'll need to assign a role to a user. When a user creates an account, she is granted the default role, "Authenticated user." If we want to create a user, let's say a "blogger," we can add a new user, or just have that user create her own account, and then promote her afterwards. That's usually the easiest first step for creating a user with different roles. Once the user account is present, you add it to other roles by accessing the account under the People tab on the administration menu. (See Figure 6-35.)

Figure 6.35. Activating a user and adding roles

The user now has the combined permissions of anyone who is an authenticated user or a blogger. Now that the permissions are in place and the user has been assigned a role, how can we take advantage of them in our modules? You've probably guessed that one of the answers has to be hooks.

To create entries on the permissions page, you need to write a hook function in your module. For this exercise, I'll be using the weather block module we developed in Chapter 5.

Let's say we have three different settings we want to control:

The Permission Hook

First we need to create these permissions so they will appear on the permissions form. We can do this with the permission hook shown in Listing 6-1.

Example 6.1. The Permissions Hook

function weather_info_permission() {
  return array(
    'administer weather info' =>  array(
      'title' => t('Administer weather information'),
      'description' => t('Set global site information for language, units, and location.'),
    ),
    'view weather info' =>  array(
      'title' => t('View weather information'),
      'description' => t('View the site-wide weather information on pages.'),
    ),
    'change weather location' =>  array(

'title' => t('Change weather location'),
      'description' => t('Change the current location for weather information.'),
      ),
    );
}

Once we've created this in our code, we will immediately see it when we go to the permissions page, as Figure 6-36 shows.

Figure 6.36. Permissions screen for weather information

Notice that the entries on the page were generated by the contents of the array in the hook function we just wrote. Also, see that the block title is the same as our module name. And you can see the new role, Blogger, that we just created, as well as the three that were already defined.

In determining who gets access to what, you can see that only the administrator gets the permission to change the site-wide settings, but everyone, even anonymous users, can see the weather for that site-wide location. And authenticated users can change the location, but they can't change the language or units settings.

Also notice that the page knows that the administrator and blogger roles are also authenticated users, so when I check the authenticated user box, the administrator and blogger boxes automatically get set, and they become grayed so I can't uncheck them.

Set the permissions as you see fit and click "Save permissions". Of course, just having those permissions there does absolutely nothing. In order for them to work, we need to incorporate the permissions engine into our module.

Creating roles and assigning permissions doesn't change anything in our module. The task now is to tell our module how to handle access to the information based on roles and permissions. This is done with the access hook.

function weather_info_block_view($delta='') {
  if (!user_access('view weather info')) {
    return null;
  }
  ...

if (user_access('change weather location')) {
    $temp = drupal_get_form('weather_location_form'),
    $block_content .= drupal_render($temp);
  }

'access arguments' => array('administer weather info'),

The weather location can be a valid location, or it could be something that is not acceptable to the weather service we are using. If we have a bad value in that field, it doesn't make sense to load it into the database, as the user would get an error the next time she refreshed the page.

We can use the validate hook to verify that the location is correct before submitting the form. We did this back in Chapter 5, but there's a difference with how we deal with the fields we attached to the user entity. When we hooked into the validate function, we owned the form and named the validate function in a way that the form processor was expecting.

With the way we are adding our fields to the standard user profile screen, however, we don't own the form, Drupal does. With a little investigation, I found that the name of the function that creates the form is user_profile_form(). According to the naming conventions for hooks, we would expect that we just need to create a function called user_profile_form_validate() to be called by the form submission logic, right?

But it's not quite that easy. You see, the user_profile_form() function belongs to the User module, which already has a function called user_profile_form_validate(). If we created a function with that same name, we'd get a PHP error.

So how can we hook into the validate functionality of the user_profile_form() function without violating PHP's rules? We can do this by altering the form before it is displayed, and creating our own validation function.

Let's first create a function that validates the field (see Listing 6-4).

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

This function takes an element, which is a single field on the form, and the same form state structure that is passed to any validation hook. The code grabs the location submitted on the form, and then checks to see if it is different from the one already in our variable store. There's no reason to check for validity if the value is already there.

So how do I know that the name of the field we are interested in is field_weather_location[und][0][value]? The most straightforward way is to have the page render in the browser and then view the source. You'll see something like this:

<input name="field_weather_location[und][0][value]" type="text" .../>

You can also use a browser debugging tool to highlight the field and check out its properties.

This function gets the location from the form and then calls the weather service to see if it will return a valid report. If there's a problem, it sets the form error, which will keep the submit hook from firing.

Now that we have this function, we need to tell the form, which is owned by someone else, that we want our validation function added to the list of functions to be called when the form is submitted. We do this by writing a function that hooks into Drupal's form-alter mechanism.

Our form-alter function will be called after the form that's being altered has been built, but just before it is to be rendered. That way, all of the fields and settings of the form are available to our function, and we can add, delete, or change whatever we want.

The trick in creating a function to alter an existing form is in properly naming the hook function. The format is:

{your module name}_form_{the id of the form you are altering}_alter

Our module name is weather_info. The name of the form we are altering is user_profile_form. So we need to create a function with a mouthful of a name: weather_info_form_user_profile_form_alter(). The function is shown in Listing 6-5.

function weather_info_form_user_profile_form_alter(&$form, &$form_state) {
  $form['profile_weather_location']['#element_validate'][] =
    'weather_info_profile_weather_location_validate';
}

This just adds the name of our validation function to the list of functions the form will have to call before it can be considered valid.

So now that we have the field name, we can set the #element_validate property to the validation function we just created. The #element_validate property is an array of all of the validation functions that are to operate on the element. The field is usually null, since the form validation logic will probably do the validation of all fields on the form as necessary.

Now, after the form function is called, Drupal will look around for functions that alter it. Our alter hook function will be hit, which will add the name of our validate function to the list of functions that must all give their nod that a field is valid before the form will be accepted as validated. Then, when the user enters information and submits the form, our function will be called.

Try it. Enter a bad location into the form and click Save. (See Figure 6-47.)

Figure 6.47. Entering bad information into a form

If you are running in Visual Studio and have the debugger running, you can set breakpoints to see exactly what is happening when.

When we get to the validation function, the weather service will return a null object, which will set the form error and prevent us from saving the information. It will also put our error text at the top of the screen and highlight the offending field. (See Figure 6-48)

Figure 6.48. The error is caught by the element validation function

The form_alter() hook is a very powerful tool to have, as it allows you to customize any form in the system, whether it is part of the Drupal core or a contributed module.

Once the attached field information has been entered for your user, it is accessible as part of the $user object. The code in Listing 6-6 shows how to get the profile information for the user, and then how to get the values.

global $user;
$user_profile = user_load($user->uid);
if (isset($user_profile->field_weather_unit['und'][0]['value'])
  && ($user_profile->field_weather_unit['und'][0]['value'] != '')) {
    $unit = substr($user_profile->field_weather_unit['und'][0]['value'], 0, 1);
  }
  else {
    $unit = variable_get('default_units', 'F'),
  }

The global $user variable does not always contain the attached fields information, so to make sure you get it, just call the user_load() function and load all of the user information, including attached fields, into the new variable. From there, you can access the attached fields.

In this case, we will use the values in the profile information to set the location, language, and units for our weather block if they exist. If they are not in the profile, we will use the site defaults.

Listing 6-7 shows the full version of the weather information block view hook.

function weather_info_block_view($delta='') {
  if (!user_access('view weather info')) {
    return null;
  }

  $block = null;
  $block_content = null;

  global $user;

  $user_profile = user_load($user->uid);
  if (isset($user_profile->field_weather_unit['und'][0]['value'])
    && ($user_profile->field_weather_unit['und'][0]['value'] != '')) {
      $unit = substr($user_profile->field_weather_unit['und'][0]['value'], 0, 1);
    }
    else {
      $unit = variable_get('default_units', 'F'),
    }

    if (isset($user_profile->field_weather_language['und'][0]['value'])
      && ($user_profile->field_weather_language['und'][0]['value'] != '')) {

$language = substr($user_profile->field_weather_language['und'][0]['value'], 0, 2);
    }
    else {
      $language = variable_get('default_language', 'en'),
    }

    if (isset($user_profile->field_weather_location['und'][0]['value'])
      && ($user_profile->field_weather_location['und'][0]['value'] != '')) {
      $location = $user_profile->field_weather_location['und'][0]['value'];
    }
    else {
      $location = variable_get('default_location', null);
    }

    if ($location) {
      $weather = weather_info_get_weather($location, $language);
      if ($weather) {
        $unit_system = $weather->weather->forecast_information->unit_system['data'];
        $current = $weather->weather->current_conditions;

        $block_content .= theme('current',
          array(
            'img' => $current->icon['data'],
            'condition' => $current->condition['data'],
            'temp' => $current->temp_f['data'],
            'unit' => $unit,
            'wind' => $current->wind_condition['data'],
            'humidity' => $current->humidity['data'],
            )
          );

        foreach($weather->weather->forecast_conditions as $new) {
          $block_content .= theme('forecast',
            array(
              'day' => $new->day_of_week['data'],
              'img' => $new->icon['data'],
              'high' => weather_info_temp($new->high['data'], $unit, $unit_system),
              'low' => weather_info_temp($new->low['data'], $unit, $unit_system),
              )
            );
        }
        $block['subject'] = $weather->weather->forecast_information->city['data'];
      }
      else {
        form_set_error('weather_location',
          t('Location @loc not found.', array('@loc' => $location)));
        variable_set('current_location', null);
        $block['subject'] = t('Get Weather'),
      }
    }

    if (user_access('change weather location')) {
      $temp = drupal_get_form('weather_location_form'),
      $block_content .= drupal_render($temp);
    }
    $block['content'] = $block_content;
    return $block;
}

Attached field information is integrated into the Drupal core, making it easy to write functions that require such information.

There's one more topic to cover, and that's the updating of attached field information in the database. As we've seen, the Drupal $user variable contains basic information about the user as defined by the core. But we extended the user by attaching fields to the entity type, which caused Drupal to create some database tables, and entries in some other tables, to hold our field information, and metadata to allow the Field API to access everything.

If we want to update the user information, there's a save_user() function that's pretty straightforward. However, updating the values of attached fields requires a different function.

In the scenario detailed above, the user set the three variables, location, language, and unit, by changing them on the account page. But now, suppose the user is on the move and wants to check the weather for another location. This is done by entering a location on the weather information form (see Figure 6-49), which we placed in the second sidebar region of our page.

Figure 6.49. The weather information block

Let's make the assumption that, if a user enters a new location on the weather information block, the new location becomes the user's preferred location. I know this is a stretch, as it might just be a temporary query, but making that assumption makes it easier to explain what I want to do here.

Currently, when we enter a new location on the weather information form, the data is validated using the weather_location_form_validate() function, and then processed using the weather_location_form_submit() function. The latter is shown in Listing 6-8.

function weather_location_form_submit($form, $form_state) {
  $location = trim($form_state['values']['weather_location']);
  variable_set('current_location', $location);
}

This code not only fails to take into account each user's individual location, but it also sets the global variable to what the user entered. Any user who changes the location will change it for everyone who is currently logged on—not really what we want.

We need to change that logic to update the profile of the current user instead of updating the current location variable for all users. In order to change the user's profile, we use the field_attach_update() function, which is part of the Field Attach API. The code to do that is shown in Listing 6-9.

function weather_location_form_submit($form, $form_state) {
  $location = trim($form_state['values']['weather_location']);
  global $user;
  $user_profile = user_load($user->uid);
  $user_profile->field_weather_location['und'][0]['value'] = $location;
  field_attach_update('user', $user_profile);
}

The field_attach_update() function requires an array containing a list of the attached fields. In order to give this, we grab the user information and convert it into an array. Once we change the weather location, we can pass it to the function and update our fields.

As you can see, it's possible to programmatically change just about any aspect of the system, even if we don't own the data or the code. For this reason, it becomes important to be sure that your code does not adversely affect other modules and has the effect on the system that you intend. A lot of this can be assured by adopting a test-driven development mindset and running tests on your module and the entire system whenever you change something.

Chapter 8 covers test-driven development and Drupal's Simpletest unit and system test environment.