Implement New Features

An Imageboard Feature
Ready Your Development Environment
Dependent Modules
Build The Feature Components
Export the Feature
Install The Feature
Update Your Feature To Store Configuration and Componenets In Code
Export any necessary user permissions
What Else Is Exportable - Permissions, Variables, Views, Node types, and much more
Strongarm - Export Variables To Code
Set up a context and add a Boxes block
Add help text for your Feature
Skip The UI
Conclusion
See also

This section covers how to build a new Feature. It assumes that you have a good understanding of using the Drupal user interface, including specifically CCK and Views. Read here for more information on Features. Understanding how Features work will allow you to make configuration changes portable and version controlled.

An Imageboard Feature

To demonstrate how to create a new feature, we will build an Imageboard which provides the following functionality:

There is a site-wide gallery
Administrators can upload photos to the gallery
Selected photos show up in the site-wide gallery
Administrators can select whether to show image titles and descriptions for the gallery
A boxes block is made available for the dashboard

Ready Your Development Environment

To make Feature development easier, we suggest installing Drush, and the Devel module. Drush will allow you to easily update your Feature once it is built and you want to make changes to it and export those changes to code. Devel will help in general with debugging. Neither are required to complete this tutorial, though there are some steps where Drush alternatives are suggested.

Dependent Modules

The Imageboard will depend on a few other contributed modules. You will need to install the following modules in order to continue:

Build The Feature Components

Features (learn more about Features here) often consist of several components created with other building-block modules in Drupal. The Imageboard Feature consists of a few different components. Start off by building the following components:

An image content type built with the Content Construction Kit which consists of the following fields admin/content/types:
- Title - the default title field
- Body/description - the default body field
- Image - which should be a field type of File and use the Image display widget
Create a new imagecache preset on Administer > Site Building > Imagecache (admin/build/imagecache). You will need to make sure the Imagecache UI module is enabled in order to build this. The new imagecache preset should have the following settings:
- You can call the new preset "imageboard-thumb"
- Add a Scale action and set the width to 180px and leave the height blank
Go to Administer > Site Building > Views (admin/build/views) and create a new view called imageboard using node as the base table. The view should have the following properties:
- Filter by node type of 'image'
- Node body and node title fields, without labels. Optionally link the node title to the node.
- Field image field, which should say something like Content: Image (field_image_image) next to it in the list of fields to choose from. The exact name will vary based on how you named it on the content type.
- The format for the image field on the view should be set imageboard-thumb image linked to node and set the label to none.
- Change the order of the fields so that title is first, the image field second, and the body last.
- Under the Basic settings of the view, set the style to grid and set to have 3 columns.
- Choose to use a pager
- Add a display of type "page", give it a title, like "Images"
- Under page settings, set the url to imageboard and set the menu to Normal menu entry with a title of Imageboard the the Menu set to Features.
- These are the main, important features for the view. You can adjust other settings on the view later, like sort order, etc. We'll also come back to this view to set the Access plugin once our Feature is more complete.
- Save the View

These are the main components that comprise our Feature. There's still a lot of missing functionality, but we'll get to that shortly. The next step is to get these basic components exported to code in what will become our Feature module.

Export the Feature

In order to export the Feature to code, go to Administer > Site Building > Features (admin/build/features) and click on the Create feature tab. Give the Feature the name Imageboard and a short description. You can ignore Version and URL of Update XML for now. Next, from the Add components drop down we need to select all of the components which pertain to our Feature. These include:

Content types
- image
Imagecache presets
- imageboard-thumb
Menu items
- imageboard
Views
- imageboard

Then, click Download feature. This will provide you with an archive of the Feature module. Later, we'll need to add a few more components, like permissions and context, but we'll do that using Drush.

Install The Feature

Take the archive of the Imageboard Feature module you just downloaded and extract it in your sites/all/modules directory so that it's located at /sites/all/modules/imageboard. You could create a directory in the sites/all/modules directory called features and put the imageboard folder in the features directory. This will help keep your modules separate from your Feature modules, possibly improving organization, but not required.

Now, go to Administer > Site Building > Features (admin/build/features) and under the Features section, click the checkbox next to Imageboard and then click Save settings to enable the imageboard Feature. Once you enable the Imageboard Feature you should notice a new item appears in the main navigation.

Update Your Feature To Store Configuration and Componenets In Code

When you change an element of the Feature - say by adding a sort to the View - it is not yet saved to code. If we take the code of the Imageboard Feature as-is and put it in the codebase of another site, any changes we made to the view will not be included.

Each time you change, add, or remove components that are part of your Feature you should update your Feature module code because Features are not portable if some components are in code and others remain in the database. You also will have no history of your changes unless you continuously put the changes into code in your Feature module and use version control.

There's an easy way and a lesser easy way. Use Drush for the easy way, or use the UI for the lesser easy way.

Update your Feature with Drush

Assuming you have Drush installed, open a terminal shell and cd to the directory of your site.
Run drush features-update imageboard which will update the code of your module.
If you are using a version control system you can now diff and you'll see the changes the Features module made
In the case that you want to update the Feature to add a whole new view, variable, etc., see the Skip The UI section below.

Update your Feature using the user interface

Go to Administer > Site Building > Features (admin/build/features) and click on the Features tab
Next to the Imageboard Feature, click on "Recreate"
Go through and select any new components you'd like to add to the Feature, then click "Download feature"

The Drush method saves you the hassle of having to download, uncompress, and place the Feature in the correct directory since it does everything for you, in-place.

Export any necessary user permissions

Now that you see how to export configuration and components to code for your Feature (if you're using Drush, you should have read Skip The UI section below) there are a few more configuration changes we should first make in the UI and then update our Feature code to include those changes. We need to configure Imageboard to have sensible permissions out of the box. Managing News comes with 3 different user roles and Features should try to stay away from adding additional roles if possible:

anonymous user (viewing access only)
authenticated user (ability to add feeds, channels and searches and edit one's own content)
admin (has access to sitewide configuration, maintenance)

You need to give the correct roles permission to add/edit/delete images. You can access the permissions administration page by visiting Administer > User Management > Permissions (admin/user/permissions).

In the case of the Imageboard Feature, authenticated users should be able to add, edit, and delete their own images, while administrators should be able to do all the same, but to any images created by any user. Find the permissions that read Create image content, Delete own image content, and Edit own image content and check the box for the authenticated user role. Next, for the admin role, check the permissions Create image content, Delete any image content, and Edit any image content. Now that these permissions are set, repeat the above step on updating a feature in order to include these changes in the code.

What Else Is Exportable - Permissions, Variables, Views, Node types, and much more

The drop down on the Feature creation page at Administer > Site Building > Features > Create Feature (admin/build/features/create) shows several different components which you can export to code. These include:

Strongarm
Menu items
Content types
Permissions
Boxes
Contexts
Feeds
Imagecache presets
Views
Dependencies

Strongarm deals with exporting variables to code and is further discussed in the next section. If there is a component you find that is not exportable but would like to make it so, you can read the API.txt file in the Features module for how to go about making a component exportable.

Strongarm - Export Variables To Code

Strongarm makes it possible to store variable settings in code. Your Feature is likely to use at least a few variable settings. Some of the most common variables you'll want to export are these node type settings. You can look at all the variables that might relate to your node type using the following drush command:

$ drush variable-get | grep _image

node_options_image: Array
upload_image: "1"
simpleshare_enabled_image: "0"
form_build_id_image: "form-5e3cc6bf8d7335c4134cee395368477b"
content_extra_weights_image: Array

To find out the value of a variable, you can use

$ drush variable-get node_options_image

node_options_image: Array
(
    [0] => status
    [1] => promote
)

In order to update our Feature module to include these settings, follow the steps discussed in the update section above.

Set up a context and add a Boxes block

When on the Imageboard page view, we want a Boxes block to show up in the left sidebar of the page, below the navigation. In order to accomplish this we need to first create a new Boxes block and then create a new context and add the Boxes block to the context. Go to Administer > Site Building > Blocks (admin/build/block) and click on the Add box tab. You will see four fields, into which you should enter the following:

Box description - "Imageboard welcome box"
Block title - "Welcome To The Gallery"
Box body - "Welcome to the Imageboard Gallery. Here you can find photos submitted by users."
Machine name - "imageboard_welcome"

Click save to save the box to the database. Later, we'll export the box code to our Feature module.

Next, we need to create a Context for our module. Go to Administer > Site Building > Context (admin/build/context) and click the Add tab. In the fields and options, do the following:

For name, enter "feature-imageboard"
For tag, enter "Imageboard"
For description, enter "Imageboard main view context"
From the conditions dropdown, select Views then scroll down the list of views and check the box next to "Imageboard"
Also from the conditions dropdown, select Node and then check the box next to Image
From the reactions dropdown, select Blocks then scroll down the list of blocks and check the box next to Imageboard welcome box (it's under the Boxes header in the list) and then in the list of regions on the left side, click +Add next to "Left sidebar"
Click Save to save the context.

I'll bet you can guess the next step. Put it in code!

Now if you go to the imageboard, you should see that the Boxes block now shows up in the left sidebar.

Add help text for your Feature

You may have noticed in certain areas of your Managing News site there is a question mark icon that appears near the top-right area of the screen, which when clicked, opens a help popup box. You can provide help text for your module which will appear in this popup by using Drupal's own hook_help. You can use hook_help combined with testing the current context to set help messages. See the following code which should live in imageboard.module for how to do this:

/**
 * Implementation of hook_help().
 */
function imageboard_help($path) {
  // Central help page content.
  if ($path == 'admin/help#imageboard') {
    $help = '<h3>'. t('Imageboard') .'</h3>';
    $help .= '<p>'. t("The imageboard lets you post photos which will show up in a gallery.") .'</p>';
    return $help;
  }

  // Contextual help content.
  if (context_isset('context', 'feature-imageboard')) {
     $help = '<h3>'. t('Image') .'</h3>';
     $help .= '<p>'. t("The imageboard lets you post photos in a group.") .'</p>';
     return $help;
  }
}

Skip The UI

When we first exported our Feature we used the UI to select the components that belong to the Feature. It's actually possible to not use the UI at all, even for the initial creation of the Feature module. If you inspect the imageboard.info file you should now see something like:

core = "6.x"
dependencies[] = "features"
dependencies[] = "imagefield"
dependencies[] = "strongarm"
dependencies[] = "views"
description = "Short description"
features[content][] = "image-field_image"
features[ctools][] = "variable"
features[imagecache][] = "imageboard-thumb"
features[menu][] = "imageboard"
features[node][] = "image"
features[variable][] = "content_extra_weights_image"
features[views][] = "imageboard"
name = "Imageboard"
package = "Features"
project = "imageboard"

and if you look at the top of the imageboard.module file, you'll see:

include_once('imageboard.features.inc');

To not use the UI at all, you can just create an empty .module file and .info file. Then, you can add different components to your .info file using the formatting you see above. You'll need to add the include_once line to your .module file and run drush features-update imageboard provided that your feature/module is called imageboard which will build out the exported code and place it in the appropriate files for your Feature module. Then, as you go along adding more components and need to add these to your module, just add more lines to your .info file like:

features[node][] = "some_other_nodetype"
features[variable][] = "some_new_variable1"
features[variable][] = "some_new_variable2"

and run drush features-update imageboard again to write these components and configuration to code.

Conclusion

You should now have a basic, working Imageboard Feature. Not all of these steps are required to build a Feature, but understanding them all will let you know what most of your options are.