Jakarta Project: Image Tag library

Version: 1.0

Table of Contents

Overview

This JSP tag library generates and transforms images dynamically. It exposes the imaging capability available in Java2D, Java Advanced Imaging, ImageIO, etc., as a set of tags.

One of the design objectives was to keep it as simple as possible. It does not require the user to have an in-depth knowledge of the underlying imaging APIs. Currently it includes the basic Java2D and Java Advanced Imaging based implementations. The Java2D implementation uses ImageIO if it is available or else defaults to AWT.

Requirements

This custom tag library can use optional software such as Java Advanced Imaging (JAI), ImageIO, etc., other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.

Configuration

Follow these steps to configure your web application with this tag library:

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/image-1.0" prefix="img" %>

where "img" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

Image Tags
image The parent tag that loads, saves and prints the HTML img tag. It also serves as the nested tag for other tags such as overlay tag that required to load images.
resize This tag scales/ resizes an image loaded by an enclosing parent tag. This can be used to generate thumbnails or to zoom into an image.
overlay This tag overlays an image on the parent image. It can paint transparent images. A color can be specified to make those pixels appear transparent.
transparency This tag makes the image translucent. It supports 255 levels of tranparency.
rotate This tag rotates the image through a certain degrees. The output image dimensions are changed to accommodate the entire image.
border This tag adds a border to an existing image. The thickness and color of the border can be specified.
grayscale This tag converts a color image to grayscale, i.e., only shades on gray.
crop This tag can crop or cut-out a subImage of a bigger image.
text This tag can write or paint a text/a string on the image.
 

Tag Reference

image Availability: 1.0

Image tag loads an image from a URL and lets its nested tags to do transformations on it. The read is based on the available Imaging capability. If Java Advanced Imaging classes or ImageIO classes are available, numerous image formats can be read. If not, the default Java-1.2 AWT supports only reading JPEG or GIF. Encoding the output in the GIF format is not supported. It avoids throwing errors whenever possible. If it is used as a nested tag, it just loads and passes it to the parent tag for immediate use and does not save it.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 src  No   Yes  1.0
 

An absolute or relative URL of the an image. The image is loaded from this URL if the image file specified in the image attribute is not available OR if the refresh option is set to true.

 name  No   Yes  1.0
 

The file name for the output image. The format/ encoding of the output image is decided from the extension on this name. The extention can be jpeg, jpg, png, gif, etc. The default is the same as the src image. Java2d supports only jpeg. JAI supports jpeg, png, tiff, bmp, etc. but not gif. For gif encoding pja-tools.jar must be included in the classpath. The tag searches for an image file with this name and loads it if it exists UNLESS the refresh attribute is set to true. Just the output filename without the path is expected.

 usingImageNameInSession  No   No  1.0
 

Indicates that the servlet uses the name of the image stored in the session.

 dir  No   Yes  1.0
 

The output file is generated in and reloaded from this directory. If specified it is expected to be relative to the context path. The generated images are saved into this directory and the img url is set appropriately. If the dir attribute is not set, the images are saved to the context temp directory and a servlet is used to serve them later. The servlet name/ mapping can be specified as a context parameter in the web.xml (see the web.xml in the image-examples.war)

 refresh  No   Yes  1.0
 

If this value is set to true, the image is generated on every access. If it is set to false (default) the dynamic image is generated only when the output image (already generated) is absent (first access).

 display  No   Yes  1.0
 

If this attribute is set to true, the HTML img tag is not generated, eventhough the image is generated and saved.

 attributes  No   Yes  1.0
 

All the attributes that needs to be included in the HTML img tag can be included in this attribute. It is just a direct copy of the String specified here. If this value does not contain the width and height attributes, they are added by the tag.

 imagingType  No   Yes  1.0
 

The imaging library used is specified by this attribute. It could be JAVA2D or JAI. By default it will look for JAI and if those classes are not available it will load Java2D imaging support.

 quality  No   Yes  1.0
 

The quality of the output image file. The value must be between 0.0 and 1.0. The default is 0.6.

VariablesNone
Examples This just loads an image and displays it. It does not do anything else unless nested transformation tags (give below) are included. This will print an img tag with the width and height attributes as well, like <img src="http://yourdomain.com/generated/splash-new.jpg" width="300" height="200" alt='A sample image' />  
 


			    	
<img:image 
	src="/images/splash.jpg" 
	dir="generated" 
	name="splash-new.jpg" 
	attributes="alt='A sample image'"
	refresh="false"
	quality="0.8">
</img:image>			    	
					 
			    

resize Availability: 1.0

This nested/ child tag of the <image> tag can be used to scale an image to a percentage (both width and height) or can be scaled to a specific width and height. If either width or height is present while the other is missing, the other value is calculated keeping the aspect-ratio. Either scale OR width OR height OR both width and height can be specified.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 scale  No   Yes  1.0
 

The scale is specified as a percentage of the image's dimensions, for eg., "50%" means that the width and height of the image will be reduced to half its current values. This also means that the aspect-ratio of the image is maintained in this case. The scale percentage cannot be zero or less. When this attribute is specified, the width and height attributes, if specified, are ignored.

 width  No   Yes  1.0
 

The width of the output image can be specified as number of pixels wide OR as a percentage of the current width. In either case, if the height attribute is not specified, it is calculated keeping the aspect ratio. However if the scale attribute is specified, this attribute is ignored.

 height  No   Yes  1.0
 

The height of the output image can be specified as number of pixels high OR as a percentage of the current height. In either case, if the width attribute is not specified, it is calculated keeping the aspect ratio. However if the scale attribute is specified, this attribute is ignored.

 bestfit  No   Yes  1.0
 

The image is scaled within the rectangled specified by the width and height keeping the aspect ratio of the original image if this option is true. The width and height MUST be specified if this option is set true.

VariablesNone
Examples This example loads an image, resizes it to 100 pixels. Since only the width is specified the appropriate height is calculated by the tag itself. The img tag it prints out after generating the image is like <img src="http://yourdomain.com/gen-images/splash-thumb.jpg" width="100" height="67" alt='A thumbnail' />. The width or height may also be specified as a percentage "40%"  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" 
	attributes="alt='A thumbnail'">
	
	<img:resize width="100" />
	
</img:image>			    	
					 
			    

This example loads an image, scales the total image to 50%. The scale is specified in percentage. The <img> tag it prints out after generating the image is like <img src="http://yourdomain.com/generated/splash-thumb.jpg" width="150" height="100" alt='A thumbnail' />  
 


			    	
<img:image 
	src="/images/splash.jpg" 
	dir="generated" 
	name="splash-thumb.jpg" 
	attributes="alt='A thumbnail'">
	
	<img:resize scale="50%" />
	
</img:image>			    	
					 
			    

overlay Availability: 1.0

This nested/ child tag of the <image> tag can paint another image on the parent image. The new image is specified by a nested <image> tag. This image itself can undergo a set of imaging operations before it is used. It can also refer to an existing dynamically generated image (by a previous tag). Since this image is not encoded but only used to overlay, even GIF images can be used.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 x  No   Yes  1.0
 

The horizontal distance from the top-left corner of the current image to the point where the new image is painted (the top-left corner of the new image). The value can be in the number of pixels OR as a percentage of the current width.

 y  No   Yes  1.0
 

The vertical distance from the top-left corner of the current image to the point where the new image is painted (the top-left corner of the new image). The value can be in the number of pixels OR as a percentage of the current height.

 color  No   Yes  1.0
 

A color can be specified to be made transparent. This is particularly useful to remove/ignore the black/ white background of images that does not support transparency. The color can be specified as an integer, for e.g., "0xff0000" for red. This will be decoded to obtain the color. There is no default color.

 tolerance  No   Yes  1.0
 

The tolerance value is used to specify the amount of variation in the color components allowed of the color specified as transparent, i.e., if the difference of the "red", "green" and "blue" components of the specified "color" and a pixel on the overlaid image is within this tolerance value, that pixel is considered transparent.

VariablesNone
Examples This example loads an image "splash.jpg". It then loads another image "asf-logo", resizes it to "60%" and overlays it on the parent image. The color "white" ("0xffffff") in the "asf-logo.jpg" is treated as transparent while overlaying.  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:overlay x="10%" y="60%" color="0xffffff" tolerance="35">	
		<img:image src="/images/asf-logo.jpg">
			<img:resize scale = "60%" />
		</img:image>	  
	</img:overlay>
	
</img:image>			    	
					 
			    

transparency Availability: 1.0

This nested/ child tag of the <image> tag can add transparency to an image. This is usually useful if you want an overlaid image to be translucent.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 level  No   Yes  1.0
 

The level value is used to specify the amount of transparency to be added. It can range from 0 (no change) to 255 (fully transparent). Note that the transparent pixels and semi-transparent will also be affected.

VariablesNone
Examples This example loads an image "splash.jpg". It then loads another image "asf-logo", adds transparency of "125" (half opaque/ transparent) and overlays it on the parent image. The color "white" ("0xffffff") in the "asf-logo.jpg" is treated as transparent while overlaying.  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:overlay x="10%" y="60%" color="0xffffff" tolerance="35">	
		<img:image src="/images/asf-logo.jpg">
			<img:transparency level="125" />
		</img:image>	  
	</img:overlay>
	
</img:image>			    	
					 
			    

rotate Availability: 1.0

This nested/ child tag of the <image> tag can rotate an image through a specified degrees. The background of the new image after rotation may depend on the type of image such as transparent or otherwise. The new image is made large enough to accommodate the entire image without any cropping.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 degrees  Yes   Yes  1.0
 

The degrees through which the image is rotated. A negative value rotates the image in the anti-clockwise direction.

VariablesNone
Examples This example loads an image "splash.jpg". Then it is rotated in the anti-clockwise direction by 30 degrees. The resultant image dimensions are larger so that no part of the rotated image is cropped off.  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:rotate degrees="-30" />
	
</img:image>			    	
					 
			    

border Availability: 1.0

This nested/ child tag of the <image> tag adds a border to the image. The color of the border can also be specified. The thickness of the border at the sides and at the top and bottom of the image is specified separately.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 width  Yes   Yes  1.0
 

The width of the border on the left and right sides of the image can be specified as number of pixels wide. If no value s specified, no border on the left and right side is added.

 height  Yes   Yes  1.0
 

The height of the border on the top and bottom sides of the image can be specified as number of pixels wide. If no value s specified, no border on the top and bottom is added.

 color  No   Yes  1.0
 

The color of the border can be specified as an integer, for e.g., "0xff0000" for red. This will be decoded to obtain the color. The default color is black.

VariablesNone
Examples This example loads an image "splash.jpg". Then it adds a border that has a thickness of 5 pixels on the sides and 3 pixels on the top and bottom in the color whose RGB values are specified in hex values.  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:border width="5" height="3" color="0x44dd44"/>
	
</img:image>			    	
					 
			    

grayscale Availability: 1.0

This nested/ child tag of the <image> tag converts a color image to a grayscale image.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 brightness  No   Yes  1.0
 

This value between "0.00" and "9.99" specifies the brightness factor of the grayscale image generated.

VariablesNone
Examples This example loads an image "splash.jpg". Then it is converted to grayscale.  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:grayscale brightness="30" />
	
</img:image>			    	
					 
			    

crop Availability: 1.0

This nested/ child tag of the <image> tag can crop or cut-out a subImage of a bigger image. The sub-image area is always specified as a rectangular area whose top-left point and the width and height can be specified.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 x  No   Yes  1.0
 

The horizontal distance from the top-left corner of the current image to the point where the cropping begins. The value can be in the number of pixels OR as a percentage of the current width.

 y  No   Yes  1.0
 

The vertical distance from the top-left corner of the current image to the point where the cropping begins. The value can be in the number of pixels OR as a percentage of the current height.

 width  Yes   Yes  1.0
 

The width of the output sub-image is specified relative to the "x" attribute. The value can be in the number of pixels OR as a percentage of the current width.

 height  Yes   Yes  1.0
 

The height of the output sub-image is specified relative to the "y" attribute. The value can be in the number of pixels OR as a percentage of the current height.

VariablesNone
Examples This example loads an image "splash.jpg". Then it crops off (removes) all the portions except a horizontal band at the center of the image. The cropping starts from "25%" below the top edge and continues till "75%" (= 25% + 50%).  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:crop x="0%" y="25%" width="100%" height="50%"/>
	
</img:image>			    	
					 
			    

text Availability: 1.0

This nested/ child tag of the <image> tag can add a line of text on the image. It can be written from a point specified. The color and font can also be specified.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 x  No   Yes  1.0
 

The horizontal distance from the top-left corner of the current image to the point where the text begins. The value can be in the number of pixels OR as a percentage of the current width. The default value is "2"

 y  No   Yes  1.0
 

The vertical distance from the top-left corner of the current image to the point of the where the text begins. This point is the BASE of the font/text and hence the text is painted above this point. If this value if zero, the text is painted outside the bounds and hence is not visible. The value can be in the number of pixels OR as a percentage of the current height. The default value is "98%"

 text  No   Yes  1.0
 

The String value that should be written/painted on the image. This may also be specified in the body. If the text attribute is specified the body is ignored.

 font  No   Yes  1.0
 

The name of the font in which the text has to appear. Make sure that this font is available. The default font is "SanSerif"

 size  No   Yes  1.0
 

The size of the font in which the text has to appear.The default size is "10"

 color  No   Yes  1.0
 

The color of the font (as an RGB integer) in which the text has to appear. The default color value is "0x000000" (black)

 bold  No   Yes  1.0
 

Specifies if the font needs to be bold. The default is "false"

 italic  No   Yes  1.0
 

Specifies if the font needs to be italic. The default is "false"

VariablesNone
Examples This example loads an image "splash.jpg". Then it writes/paints the given text/string on the image in bold "Arial". font with size "12". The text is written "30%" towards the right and "15" pixels towards the bottom from the top left corner of the image.  
 


			    	
<img:image 
	src="images/splash.jpg"  
	name="splash-thumb.jpg" >
	
	<img:text 
		text="A part of the Jakarta Tag library" 
		x="30%" 
		y="15" 
		font="Arial" 
		bold="true" 
		size="12" 
		color="0xff0000"
	/>  
	
</img:image>			    	
					 
			    

The "Mother" <image> tag

Tag structure and image loading
The <image> tag is the parent tag that can take any number of child (transformation) tags. The <image> tag loads the image from a URL src or from a previously generated image referenced by its name. Each child tag does one transformation on the image referenced by the parent <image> tag. The transformations are done in the order of the child tags specified. The <image> tag adds width and height attributes if it is not specified already. All attributes and JavaScript required for the final HTML <img> tag can be specified in the attributes attribute. If the dynamic image (parameters) need not change for each request, the image needn't be generated for each request. Hence the dynamic image is generated only once (and saved) if the refresh attribute is "false" (saving a lot of processing and memory). If the refresh is set to "true" the image is re-generated for each request. The default for the refresh attribute is "false". The dir attribute lets you specify a directory to save the generated images within the context. The generated images are saved into this directory and the img url is set appropriately. If the dir attribute is not set, the images are saved to the context temp directory and a servlet is used to serve them later. The servlet name/ mapping can be specified as a context parameter in the web.xml (see the web.xml in the image-examples.war). The context param to be set is "ImageServletMapping". The quality of the final image can be specified as a float (0.0 to 1.0 - default 0.6) by the quality attribute.
Encoding, HTML generation and access of the images
After completing all the transformations, the <image> tag saves the image to a file by the name attribute (explicitly specified) OR a file generated using the source image filename/ URL. The image type/ encoding is determined from the file's extension. However writing of "GIF" files is supported ONLY if the pjatools.jar is available in the classpath (instead of throwing an error, it writes a JPEG image and changes the extension). Then an HTML <image> tag pointing to the newly created image is printed on to the page (As we know, the image is accessed by a separate request sometime later).

Image Operations

The children of the <image> tag can be a set of transformation tags such as: - These tags can be combined and used in any order to get the desired effect. The overlay is useful to add tags like "SOLD", "NEW", etc., to a product image. Text can be used to add copyright information to images. Grayscale and Resize can be used to generate thumbnail images. There are numerous ways to use them in combination. Take a look at the example.

A Sample

Overlay a Rotated transparent image on a Grayscaled image and then Resize it (GIF on JPEG).
<img:image src="/images/splash.jpg"
        dir="generated"
        name="splash-new-gray.jpg"
        refresh="true"
        attributes="border='0' alt='a sample dynamic image'">
    <img:grayscale/>
    <img:overlay x="55%" y="60%">
        <img:image src="/images/new.gif" >
            <img:rotate degrees="-30" />
            <img:resize scale="80%" />
            <img:transparency level="125" />            
        </img:image>        
    </img:overlay>
    <img:border width="5" height="3" 
            color="0x005d00"/>
    <img:resize bestfit="true" width="200" height="400"/>
</img:image>
		
The output image of the tag given above:

The sequence of operations to generate the output image: -
  1. The image file "splash.jpg" is loaded (each time since the "refresh" is set to "true"). Otherwise it checks for "splash-new-gray.jpg" in the "generated" directory and loads it.
  2. The image is converted to grayscale.
  3. The "new.gif" is overlaid/ painted on the base image at location 5% right and 60% below (percentages of base image's current "width" and "height" respectively) the top-left corner. The image for overlay is generated by the following steps: -
    1. The nested image tag loads the "new.gif"
    2. The image is rotated by "-30" degrees
    3. The resulting image is resize/scaled to its "80%"
  4. A colored border with "5" pixels thickness at the sides and "3" pixels at the top and bottom is added.
  5. The whole image is resized/ scaled to fit within a "200" x "400" rectangle.
  6. The image is saved as "splash-new-gray.jpg" in the "generated" directory.
  7. An <img> tag similar to <img border='0' alt='a sample dynamic image' src="/generated/splash-new-gray.jpg" width="200" height="132"> is written. The "width" and "height" are that of the resulting image.

On the radar

Examples

See the example application image-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.