Working with images

Last updated on
29 December 2023

This documentation needs review. See "Help improve this page" in the sidebar.

The Image module allows you to display and manipulate images on your website. It exposes a setting for using the Image toolkit, allows you to configure image styles that can be used for resizing or adjusting images on display, and provides an image field (using the Field API) for attaching images to content.

Usage

Adding an image field to a content type

In a default installation, only Articles have an image field, but this type of field can be added to other content types (e.g. Basic page or custom content types) as well. An image field can also be added to a user profile, a comment, or a taxonomy term. An unlimited number of image fields can be added, each with a variety of settings such as allowed extensions, maximum file size and default directory for storing the images.

To control the way the image is displayed you must define styles (see below).

To add an image field to a content type:

  1. Choose the content type via Administration > Structure > Content types.
  2. Choose "Manage fields".
  3. Enter a label for the field, e.g. "Product picture", define a field name and choose "Image".
  4. Decide if there should be a limit on how many images can be attached (defaults to 1).
  5. Choose a default image for this field (optional).
  6. Define further settings, such as allowed extensions, maximum file size and default directory for storing the image files.
  7. Save the settings.

Add images to content

To add images to content:

  1. Choose Administration > Add content > [Content type].
  2. The image field will be displayed in the list of fields once you've added it to the content type (see above). Click 'Browse', then select and upload the desired image.
  3. Enter alternate text to improve accessibility and optimize it for search engines.
  4. Save the article.

Images can be added and removed from the node's Edit tab. If the node is deleted, all associated images are deleted with it.

Adding images inline

To use images attached to nodes via the Image module inline (ie. in your node body text) you can use the Insert module. It provides a button to easily add an img tag with the path to the image in the src attribute and styles of your choosing. Creating image styles (see below) with inline images in mind, combined with some CSS to set the float property, can give users the option to easily set content to display to the left or right of the document text.

You'll want to go to "Manage display" for your content type to ensure the image is set to hidden, otherwise it will be displayed twice.

Adding and changing styles

Using image styles you can scale, crop, resize, convert image type, rotate and desaturate images without affecting the original image. By default three sizes are defined: 'thumbnail,' 'medium', and 'large'. The thumbnail style, for example, is shown with the teaser for image posts and when browsing image galleries.

When you change an image style, the module automatically refreshes all created images. Every image style must have a name, which will be used in the URL of the generated images.

To create or change image styles:

  1. Choose Administration > Configuration > Media > Image styles.
  2. Add or select a style to edit its settings.
  3. When configuring styles you can add effects: crop, scale, resize, rotate, and desaturate (other contributed modules provide additional effects). For example, by combining effects as crop, scale, and desaturate, you can create square, grayscale thumbnails.
  4. Save the settings.

To start using the defined styles they must be assigned to the display of a content type. For each display (e.g. "default" or "teaser"), a different style can chosen.

To assign a style:

  1. Choose Administer > Structure > Content types > Manage display.
  2. Choose the display (e.g. "default" or "teaser") via the tab buttons.
  3. Click the gear wheel button to choose an image style; you are also able to link the image to the node.
  4. Save the settings.
  5. Check the content that contains the image style in question to see your new styles at work.

Setting image quality

You can specifically define the image quality on your site. Take into account that better image quality means bigger files.

  1. Navigate to Administration > Configuration > Media > Image toolkit.
  2. Enter the desired quality in the field JPEG quality.
  3. Save the settings.

Troubleshooting

To know more about your problem, log into your site as an administrator and go to Reports → "Recent log messages" (/admin/reports/dblog).

The image doesn't show up

This may be a directory permission problem. When everything works fine, images seem to be generated when uploaded, when the node is saved or when a new image style is created. If you have a multisite installation and your website directory is sites/example.com/ , Drupal generates subdirectories and files inside sites/example.com/files/styles/ , for instance sites/example.com/files/styles/medium/public/field/image/landscape.jpg . (In a single site installation, it would be sites/default/files/styles/medium/public/field/image/landscape.jpg ). So check whether sites/example.com/files/styles belongs to the web server user and whether this user has all permissions on it. In Mageia 3, the webserver user is called "apache". Other typical names for it are "_www" and "www-data", depending on your operating system and distribution. To ensure that the directory "styles" is owned by the user apache and that the latter has all permissions on it, you can go to sites/example.com/files directory and run, in Linux:

$ su
# chown apache styles
# chmod u+rwx styles

(Or use "sudo".)

In some cases, you might have trouble with tokens. See Drupal 7.20's release notes, especially the last paragraph "Overall mitigation steps".

In some circumstances, functions like adding images to galleries don't work unless Clean URLs are activated. (You get no result from attempting to add to galleries) More info on Clean URLs. [Related bug report]

Flushing or Rebuilding the Image styles

Just resaving your image style will flush the image cache. If you need to flush all image styles (eg. after adjusting the JPEG quality), you can execute drush image-flush, use the Image style flush module, or run the following code (for instance using Devel):

// Flush all image styles in Drupal 7.
foreach (image_styles() as $style) {
  image_style_flush($style);
}

If images are not generated at all, check that HTTP error 404 is handled by Drupal. This is set by default in Drupal's provided .htaccess.

Help improve this page

Page status: Needs review

You can: