img element

This article explains the how to use the "img" element.

Overview

The "img" element allows to show an image specified by its id. The attributes of this element are:

• "id": The image id, if the image refers to an Image definition. See image files for the specification of image ids
• "href": The relative path of the image, if the image do not refer to an Image definition
• "width": The optional image width: can be specified in pixels or in % of the HTML page width
• "maxWidth": Same as "width", but the width can not exceed the native image reference width
• "height": The optional image height: can be specified in pixels, in % of the HTML page width, or with the "text" value specifying that the image will have the same height as the enclosing text
• "maxHeight": Same as "height", but the width can not exceed the native image reference height
• "caption": The optional image caption
• "border": Optionally, the property specifying that we should add a border around the image. This attribute can have the following values:
• "true" or "simple": the image will be bordered by simple line
• "shadow" or "softShadow" : the image will have a soft shadowed border
• "strongShadow": the image will have a strong shadowed border
• "false" or "noBorder" : (the default) no border
• "margin": Optionally, the property specifying the margin around the image. See also image margins for more information
• "package": The optional package attribute allows to reference an image in another package
• "position" or "align": Optionally the alignment of the image. Can be "left", "right", or "center"
• "valign": Optionally the vertical alignment of the image relative to the text. Can be "middle", or "baseline". This can be useful if you want to add an icon in a line of text
• "float": Optional, true if the image should have the "float" attribute (which means that there will be text around the image)

Default usage

The following attributes allow to specify the image reference:

• "id": The image id. See image files for the specification of image ids
• "package": The optional package attribute allows to reference an image in another package

For example:

   <img id="image1" />

   An SVG image:<img id="svgLogo" width="60" />

Result:


An SVG image:

Using the href attribute

If you specify the "href" attribute, the image points to a relative image file, which must be under a doc-files directory in the same directory as the article which uses the img element.



For example, suppose the following file structure:

      wiki
      -- doc-files
      ---- ball.jpg
      -- article.xml
      -- index.xml

And the following content for the article:

   <article desc="My article">
     <img href="ball.jpg" />
   </article>

The img will point to the ball.jpg Jpeg file.

Specifying the size of the image

By default the image will have the native width and height of the image reference. The following attributes allow to specify the width or height of the image:

• "width": The optional image width: can be specified in pixels or in % of the HTML page width
• "maxWidth": Same as "width", but the width can not exceed the native image reference width
• "height": The optional image height: can be specified in pixels, in % of the HTML page width, or with the "text" value specifying that the image will have the same height as the enclosing text
• "maxHeight": Same as "height", but the width can not exceed the native image reference height

For example:

   <img id="image1" width="20%" />

Result:

Enclosing the image in text with the same height:

  The <img id="image1" height="text" /> image

Result:

The image

Specifying the position of the image

The following attributes allow to specify the position of the image:

• "position": Optionally the alignment of the image. Can be "left", "right", or "center"
• "valign": Optionally the vertical alignment of the image relative to the text. Can be "middle", or "baseline". THis can be useful if you want to add an icon in a line of text
• "float": Optional, true if the image should have the "float" attribute (which means that there will be text around the image)

The alignment of an image can be set through the "position" attribute, which can have the values "center", "left", or "right".

For example:

  An image:<img id="image1" valign="middle" width="40" />

  The image aligned on the left:
  <img id="image1" width="40" position="left"/>

Result:

An image:
The image aligned on the left:

Adding a border or a caption

The following attributes allow to add a border an a caption to the image:

• "border": Optionally, the property specifying that we should add a border around the image. This attribute can have the following values:
• "true" or "simple": the image will be bordered by simple line
• "shadow" or "softShadow" : the image will have a soft shadowed border
• "strongShadow": the image will have a strong shadowed border
• "false" or "noBorder" : (the default) no border
• "caption": The optional image caption

For example:

   An image with a border:
   <img id="image1" width="20%" border="true" />

   The same image with a border and a caption:
   <img id="image1" width="20%" border="true" caption="the caption" />

   The same image with a shadowed border:
   <img id="image1" width="20%" border="shadow" />

Result:

An image with a border:

The same image with a border and a caption:

Adding a lightbox

A Lightbox effect is a JavaScript mechanism that displays images and videos by filling the screen, and dimming out the rest of the web page, when the image is clicked on.

It is possible for images to have a Lightbox effect if the lightbox property is set on the command line or the configuration properties.

Unresolved references

By default unresolved images will emit an error during the generation, but it is possible to set the packages dependencies to specify that unresolved images from one package to another will not emit an error.

Linking on images

It is possible to link on an image by adding inside the img element:

• A list of areaRef elements to link on portions of the image
• A ref element to link on an internal wiki element
• A catRef element to link on a category
• An a element to link on an external file

Linking on areaRef elements

It is possible to add internal wiki links on portions of images using the "areaRef" element inside an "img" element. The attributes of the "areaRef" elements which specify each area are:

• "type": the type of the active area ("rect", "circle", or "poly")
• "coords": the coordinates of the active area. The coordinates are separated by "," (commas)
• "id": the id of the inter-wiki reference, specified exactly as for the ref element
• "desc": the optional alternate text for the inter-wiki reference, specified exactly as for the ref element
• "package": the optional package for the inter-wiki reference, specified exactly as for the ref element

For example:

   <img id="image1" width="200" >
     <areaRef id="img element#Linking on images" coords="0,0,200,100" />
     <areaRef id="syntax#img" coords="0,100,200,200" />
   </img>

Linking on an internal wiki element

It is possible to add an internal wiki link on the image using a "ref" element inside the "img" element.

For example:

  <img id="image1" width="200" >
    <ref id="the reference" />
  </img>

Linking on a category

It is possible to add an internal category link on the image using a "catRef" element inside the "img" element.

For example:

  <img id="image1" width="200" >
    <catRef id="general" />
  </img>

Linking on an external file

It is possible to add a link on an external file on the image using an "a" element inside the "img" element.

For example:

  <img id="image1" width="200" >
    <a href="http://docs.oracle.com/javase/8/docs/api/index.html" />
  </img>