Highslide JS API Reference : hs.registerOverlay

hs.registerOverlay

Apply custom overlays to image or HTML expanders.

void hs.registerOverlay(Object options)

Highslide has two easily accessable overlays, namely the heading and the caption. If you want to add overlays other than these, you use hs.registerOverlay. See Custom overlays in the documentation for full explanation. When you want to add individual overlays for each expander, hs.Expander.prototype.createOverlay is generally a better option. Or you can use the hs.Expander.prototype.onCreateOverlay event to change the properties of the overlay before it is added to each single expander.

Details

Requires	overlays
Type	function
Returns	void

Parameters

options

An object containing some of the following options:

className (string): Apply a class name for styling the overlay.
fade (mixed): Whether the overlay should fade in and out. Possible values 0/false, 1/true, 2. Fading in and out is problematic in IE if you put alphatransparent PNGs in the overlay, either through AlphaImageLoader or not. In this case, set the fade to 2 to skip fading in IE only. An example can be seen at example-no-border.html.
hideOnMouseOut (bool): Defines whether the overlay should be hidden when the mouse leaves the full-size image.
html (string): A string to use as innerHTML for the overlay. When this is used, you don't need to specify an overlayId.
overlayId (string): The id of the overlay div defined in your page's source code.
offsetX, offsetY (number): The number of pixels to offset the overlay in the horizontal and vertical directions respectively. Can be negative.
opacity (float): Can be a float number between 0 and 1 (fully opaque).
position (string): Specifies where the overlay will appear related to the full-size image. The first word specifies the vertical position and can be top, middle or bottom, and the second word can be left, center, right. In addition, the position can be the single word positions above, below, leftpanel or rightpanel. If you want to put some air between the overlay and the edge of the image, you use regular CSS margins on the overlay div. You can also offset the overlay by using position:relative in it's CSS.
relativeTo (string): Can be 'viewport' or 'expander'. Overlays in most positions can be rendered relative to the viewport rather than the default, which is relative to the expander. When relative to the viewport, the overlays stay fixed on scrolling. This option requires that the 'Viewport overlays' component be activated in the Configurator.
slideshowGroup (string): Refers to a hs.slideshowGroup that will use this overlay.
thumbnailId (string): Either a string specifying the id of the thumbnail, or you can set it to null to apply the overlay on all thumbnails.
width (string): The width of the overlay can be specified either as a pixel value or as a percentage, like 100px or 100%. However, overlays in the leftpanel or rightpanel positions require a fixed pixel width, or they will fall back to the default 200px width.
useOnHtml (bool): By default overlays are not added to HTML content. Set useOnHtml to true to allow this.

Example

Putting some text in an overlay

Please note that in most cases, using a heading or caption is better for this effect.

1. In a script tag in the head section of your page, call the hs.registerOverlay function. In this case thumbnailId is set to null, as we want the overlay to tie to all expanders.

hs.registerOverlay({
	thumbnailId: null,
	overlayId: 'my-overlay',
	position: 'top left',
	hideOnMouseOut: true,
	opacity: 0.8
});

2. A div containing your overlay, with an id corresponding to the overlayId above, is created somewhere in the body of your HTML page. Styles can be set inline or using CSS rules.

<div class="highslide-overlay" id="my-overlay" 
      style="background: black; font-weight: bold; font-size: 150%;
      color: white; margin-top: 2em; padding: 1em">
   This is some text in an overlay
</div>

3. A CSS rule telling the overlay to be initially hidden.

.highslide-overlay {
   display: none;
}

4. The normal expander markup.

<a class="highslide" href="../samples/full3.jpg" onclick="return hs.expand(this)">
   <img src="../samples/thumb3.jpg" alt=""/>
</a>

This is the effect of the above:

This is some text in an overlay

Highslide JS API Reference

Object: hs

Variables

Functions

Events

Object: hs.Expander