WImage

WImage is a component for adding content images to an application. WImage outputs a HTML img element and may be placed in the content of any other container WComponent.

• Creating WImage
  • Attaching an image
  • Caching
• Accessibility
  • Text equivalent
  • Size
• Accessing the image
• Dimensions
  • Size overrides considered harmful
• Hiding
• Related components
• Further information

Creating WImage

WImage has three constructors. The default constructor creates a WImage which has no actual image. A WImage may be created using an ImageResource or with a String path to a resource on the classpath and a String description.

// Create an empty WImage
WImage img = new WImage(); // useless at this stage
// Create a WImage using an existing
// ImageResource `imgResource`
img = new WImage(imgResource);
// Create a WImage based on an application resource
img = new WImage("/path/to/image/file", "description of image");

Attaching an image

An image may be added to a WImage after construction. This is done using an ImageResource (or an instance of any class which implements Image).

// given WImage dynamicImage and ImageResource res:
dynamicImage.setImage(res);

// or ...
// string IMAGE_RESOURCE_PATH points at the local resource path,
// string IMAGE_DESCRIPTION describes the image:
dynamicImage.setImage(
    new ImageResource(IMAGE_RESOURCE_PATH, IMAGE_DESCRIPTION));

A WImage can use an external image accessed through a URL.

// given WImage dynamicImage and URL 'URL'
dynamicImage.setImageUrl(URL);

Caching

WImage will output an image which is not cacheable unless a cache-key is set. If an image is not limited to a particular state or otherwise restricted (e.g. a particular user's portrait photograph) then a cache key should be set and the image will be cached.

If a cache key is set the image will be cached "permanently" i.e. no expiry will be set and the cached image used until it falls out of the user's cache or the cache-key is changed.

// set a cache key which is `permanent`
wImage.setCacheKey("some-key");

// A cache key could include a timestamp component to,
// for example, cache for a day:
Calendar cal = Calendar.getInstance();
cal.add(Calendar.DATE, 1);
SimpleDateFormat format1 = new SimpleDateFormat("yyyy-MM-dd");
wImage.setCacheKey(format1.format(cal.getTime()));

// If your application have a build number then it could
// be used to cache per release
// given the current release reported by string `VERSION`
wImage.setCacheKey(VERSION);

Accessibility

The main accessibility issues surrounding WImage are those which apply to non-text content. Most simply the image description must be appropriate for the image and its use-case. For example, where a WImage is used as a decorative icon on a WButton which also has a text label the most appropriate description is probably an empty string. For more information see Understanding WCAG 2.0 - text equivalent.

Text equivalent

The WImage description sets the HTML img element's alt attribute. This is a mandatory attribute in the HTML5 specification for all images with a content implication and is required to provide a text alternative to indicate the content and purpose of the image (see the HTML5 specification and WCAG 2.0 guidelines).

If the image is part of the page content (such as an identification photograph) then the alt property must be specified and specified appropriately. The alt property is expected to provide a text equivalent for the image, not a complete description. The text equivalent should be as brief as possible whilst still supplying the information needed so that the page's meaning does not change if the image is replaced by its text equivalent.

What constitutes an appropriate text equivalent is dependent upon context. The important factor is that your users must not lose any information or meaning if they are not able to view the image. So for the identification photograph example mentioned above an appropriate text alternative may be something along the lines of 'a full face identification photograph of person's name'. Complex images and charts may require more detailed information. For an image with significant content implications, such as a graph or chart, it may be more appropriate to provide a visible caption for the image and supply a short pointer to the caption in the alt property. For this you should use WFigure.

As mentioned before if your image is purely decorative (with no content implication at all) then it must have its alt property explicitly specified as "" (an empty string).

If a WImage is created without a description it may be added using setAlternativeText(String).

// with WImage image and String DESCRIPTION:
wImage.setAlternativeText(DESCRIPTION);

// for a decorative image
wImage.setAlternativeText("");

For more information about image descriptions see the WCAG 2.0 guidelines for text equivalence.

Size

Another issue which is often overlooked is the use of images of an inappropriate size. If a WImage is used as the only visible content of a Wlink, for example, then it should be large enough to both be easily discernible and make the link hit zone a reasonable size; it should not, however, be so big that it causes wrapping or overflow issues on small screened devices.

Accessing the image

If one needs to access the raw image from a WImage it is done by getImage

// given WImage wImage:
Image theImage = wImage.getImage();

Dimensions

The image may have its default size and proportions modified using the width and/or height properties. These properties are usually determined by inspection of the image but may be over-ridden. If you require an override of the image size you must specify width and /or height explicitly and provide a reason why the image cannot be supplied in the desired size.

// with WImage wImage, int WIDTH and int HEIGHT
wImage.setSize(new Dimension(WIDTH, HEIGHT));

One would not normally set an image's dimensions to their native/original dimensions as this would be redundant. The only use case for this is if resetting the dimensions after setting them to a different size.

Size overrides considered harmful

NOTE custom dimensions may change the appearance of the image. In the following examples a sample image is used which in its unaltered state (or default state as it was itself implemented using WImage) is as shown below:

There are no circumstances where it is not better to have an image of the correct size rather than resizing an existing image in the browser. User agents may choose to ignore image size overrides or may give the user the option to rescale the image to the original size. If exactly one of the height or width are set then the image will scale proportionally.

• Making the image larger may result in a visible reduction in quality:

  

• Making the image smaller results in wasted network use and may result in a visible reduction in quality:

  

• If the width and height are both set, and the proportion of width to the image's original width is not exactly the same as height to its original height then the image will be distorted.

  

Hiding

A WImage may be hidden on page load. When hidden the WImage is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl.

Related components

• WFigure

Further information

• JavaDoc;
• HTML Specification;
• Understanding WCAG 2.0 - text equivalent;
• List of WComponents.