Dottoro Theme Documentation

Tutorial to get your theme to work

14. Overlays

Overlays make it possible to display any HTML content over post thumbnails, images and media. You can display image titles and descriptions, post meta data (titles, teasers, categories, etc.), buttons that open popup slideshows and more. There are predefined overlays to choose from and you can create custom ones. The contents of overlays can be edited the same way as the contents of pages and posts, and you can also use shortcodes in them. Thanks for the [layer] shortcode, any part of an overlay can appear and disappear with an animation. Thus you have the possibility to create a wide variety of overlay animations.

• 14.1 Displaying Overlays
• 14.2 Built-in Overlays
• 14.3 Creating Overlays
• 14.4 Overlay Specific Shortcodes

14.1 Displaying Overlays

There are several ways to display overlays in the theme:

• Overlays over post thumbnails on single pages:
  • The Thumbnail Overlay option under Posts » Post Settings / News » News Settings / Portfolio » Portfolio Settings allows you to select an overlay for post thumbnails on single pages.
  • This setting can be overridden for each single post with the Thumbnail Overlay option on the Edit Post Screen.
• Overlays over "single" images in the content:
  The Overlay option under Attachment Display Settings in the WordPress media dialog allows you to select an overlay for every image inserted into a page or post with the "Add Media" button above the WordPress content editor.
• Overlays over any media (self hosted and external, post and media thumbnails) in listings and slideshows:
  • The Thumbnail Overlay option for post list pages allows you to select an overlay for post thumbnails appearing in the list.
  • The Media Overlay option for slideshows allows you to select an overlay for any media appearing in the slideshow.
  • Finally, the media_overlay attribute of the [item_settings] shortcode allows you to select an overlay for any media in listings and slideshows displayed by shortcodes (Post List shortcodes, [gallery_list] shortcode, [slideshow] shortcode).
• Overlays over Flickr images:
  The Thumbnail Overlay option for the Flickr Photos widget allows you to set an overlay to appear over the photos.

14.2 Built-in Overlays

Built-in overlays give you a good basis to create your own overlays. In the following, the content and working mechanism of built-in overlays are discussed in detail to help you in creating your own overlays.

The source and description of a built-in overlay can be viewed by clicking on the overlay under under Templates » Overlays. As you can see, each overlay contains a list of layers.

• The first layer displays a semi-transparent gray background with a fade in-out effect in each overlay.
• The last layer displays a gallery button (and a read more and visit site buttons in post overlays) in each overlay.
• The other layers display image and post titles and descriptions.

There are a few things worth mentioning:

• Every layer is absolute positioned. For example, if you take a look at the first layer of the Gallery overlay, you will see that its left, top, right and bottom positions are zero so it fills the whole overlay. And since its background color is black (#000), start opacity 0 and the 'on' opacity is 0.5, it will display a black (that seems to be gray) semi-transparent background with a fade in-out effect.
• If you take a look again at the first layer you will notice an allow_empty="true" attribute. Empty layers (layers without content) are not displayed by default, but with the allow_empty attribute you can change this behavior. Since this layer has no content but needs to be displayed, the allow_empty attribute must be set to true.
• The second layer in the Gallery overlay displays a button ([gallery_button] shortcode) that opens a popup slideshow. As you can see its 'required' attribute is set to true. If an overlay has required layers, then at least one of the required layers must be displayed otherwise the overlay won't be shown. If this overlay should appear over a post thumbnail and the post has no gallery, the gallery_button shortcode does not display anything. That's why the second layer won't be displayed (empty layers are displayed only if their allow_empty attribute is set to true). Since this overlay has only one required layer, if the post has no gallery, the overlay will not appear.
• Another important thing in the second layer is the '-50%W' and '-50%H' values of the marginLeft and marginTop CSS properties. The value of the 'start', 'on' and 'end' attributes can contain a comma separated list of CSS property-value pairs in JavaScript syntax. It means that the JavaScript CSS property names must be used (camelcase names, e.g. marginLeft instead of margin-left) and string values (such as '10px' and '20%') must be quoted.

  But what do the '-50%W' and '-50%H' values mean?
  The %W and %H are special length units supported by the layer shortcode. The W identifies the width, the H identifies the height of the layer. The '50%W' means the half width, the '50%H' means the half height of the layer, in pixels. So they are actually pixel units. The JavaScript library of the theme replaces the '50%W' and '50%H' values with the half width and height of the layer when animates it.

  But what are they good for?
  Unfortunately CSS does not make it easy to center an absolute positioned element within its parent element. If the left and top CSS properties of an element are set to '50%', then the top-left corner of the element will be placed in the middle of its parent element. But what can you do if you want the center point of an element to be placed in the middle of its parent element? If you know the exact width and height of the element (let's say 200 pixels), then set its margin-left and margin-top CSS property to the negative half width and height (-100px). If you don't know the size of the element, you need to use JavaScript to get the width and height and to set the margins dynamically (the margin-left: 50% sets the left margin to the half width of the parent element not the half width of the current element).
  
  That's why it was necessary to extend the list of CSS length units with the %W and %H units. Since the left and top positions of the second layer is set to '50%' and the marginLeft and marginTop properties are set to '-50%W' and '-50%H' in the 'on' attribute, the layer will always be centered in the overlay regardless of the size of the layer. And since the marginLeft property is set to '-50%W' and the marginTop property is set to 0 in the 'start' attribute, the show animation moves the layer upward.

• The overlay 'Gallery - follow mouse' is very similar to the overlay 'Gallery'. The first layer is the same, but the second layer is different in the two overlays. The second layer displays a gallery button in both overlay, but its animation is different. The start_left, start_top, start_right and start_bottom attributes allow you to specify the start state of a layer depending on the direction the mouse pointer has been moved into the area of the overlay. Similarly, the end_left, end_top, end_right and end_bottom attributes allow you to specify the end state of a layer depending on the direction the mouse pointer has been moved out of the area of the overlay. The end, end_left, end_top, etc. attributes are not specified in this layer because they don't need to be specified if they are the same as the start, start_left, etc. attributes. The gallery button in this overlay moves in the same direction as the mouse pointer when it appears and disappears.
• Another attribute we need to talk about is the breakanim attribute. Every layer has a show and hide animation. The show animations of layers start (maybe with some delay - depending on the starttime attribute of the layer) when the mouse pointer moves into the area of the overlay and the hide animations start when the mouse pointer moves out of the area of the overlay. If the show animation of a layer runs when the layer should start to hide, the show animation turns back instead of beginning the hide animation, but this behavior can be changed with the breakanim attribute. If the breakanim attribute is set to true, the show animation stops and the hide animation starts.
  Since the breakanim attribue is set to true in the second layer of the overlay 'Gallery - follow mouse', the gallery button moves out of the overlay in the same direction as the mouse pointer did even if the show animation of layer is running when the mouse leaves the area of the overlay element.
• Finally, the last thing worth mentioning is the 'Post Complex' overlay. It is quite similar to the overlay 'Post title, excerpt, gallery and read more'. Both display the post title and excerpt at the top, the gallery, read more and visit site buttons at the bottom. But there is an important difference. If the post title and excerpt are turned off (the Hover meta info option on portfolio pages allows you to set what meta information should be displayed when hovering over thumbnails), the 'Post Complex' overlay displays the gallery, read more and visit site buttons vertically centered not at the bottom. This is why it was necessary to use the do_action shortcode, because this feature requires some PHP coding.

For further details and examples, please see the [layer] shortcode and the overlay specific shortcodes section.

14.3 Creating Overlays

Overlays can be created and managed under Templates » Overlays. The theme comes with a few predefined overlays to choose from and you can create custom ones. The predefined overlays give you a good basis to create your own overlays. More on Built-in Overlays.

To create your own overlay:

• select a built-in overlay that fits your needs most
• copy its content to the clipboard
• click on "Add New" at the top of the page
• give your new overlay a name
• paste the clipboard content into the content editor below the title field
• make the required modifications in the content of your overlay
• finally, click "Save Template"

You are done, your custom overlay is ready to use. For example, if you want to use this overlay on a portfolio page, select your new overlay in the Thumbnail Overlay option on the Edit page, then click Save Changes. If you take a look at the portfolio page now, you will see the changes.

As you can see the contents of overlays can be edited the same way as the contents of pages and posts, and you can also use shortcodes in them. In addition to the common shortcodes, the post template specific shortcodes and the overlay specific shortcodes can also be used in the content of overlays.

Overlay options

You will find an "Overlay Settings" box below the WordPress content editor. In this section, these options will be described.

Overlay options
Visibility	Select whether the overlay element should be always visible or only on hover. If this option is set to 'always', the start and end attributes determine how a layer looks like when the mouse is not over the covered element.
Clicking	Select what you would like to happen when the user clicks on the overlay. The 'auto' value means that if there is only one clickable element in the overlay, then the whole overlay is clickable, otherwise the overlay is not clickable.
Placement	Select whether the overlay should cover only the content box, the padding box (content and padding), or the border box (content, padding and border) of the associated element.
CSS Class	CSS class or classes that are added to the overlay wrapper element.
Small Width	Specifies the width of the overlay (in pixels) below the 'small' CSS class should be added to the overlay. Since an overlay can appear over different elements and the size of the overlay depends on the size of the covered element, the same overlay can have different sizes. The 'small' class allows you to apply additional CSS rules to an overlay when its width is below a certain size. For example, you can make buttons smaller and so on.
Small Height	Specifies the height of the overlay (in pixels) below the 'small' CSS class should be added to the overlay. Since an overlay can appear over different elements and the size of the overlay depends on the size of the covered element, the same overlay can have different sizes. The 'small' class allows you to apply additional CSS rules to an overlay when its height is below a certain size. For example, you can make buttons smaller and so on.

14.4 Overlay Specific Shortcodes

These shortcodes can only be used in overlays.

[image_title]

Displays the image title. The image title can be set on the Edit Media page under Media » Library.

Attributes:
target	Specifies the target window where the document should be opened when clicking on the title. Default is '_blank'. This attribute is the same as the target attribute of the anchor tag in HTML. This attribute has effect only if the show_as_link attribute is set to true.
show_as_link	Specifies whether the title should appear as a link or plain text (true | false). Default is false.
image_target	Specifies whether clicking on the title should open the attachment page or a page that only contains the image in its original size (attachment | image). Default is attachment. Has effect only if the show_as_link attribute is set to true. Please note that if the overlay appears over a Flickr image, this attribute is omitted and clicking on the title opens the Flickr page of the image.

[image_description]

Displays the image description. The image description can be set on the Edit Media page under Media » Library.

[gallery_button]

Displays a button that opens a popup window. For details, please see the Shortcodes for popup windows section.

[read_more_button]

Displays a read more button.

Attributes:
icon	Specifies an icon for the button (magnifier | photo | player | vimeo | youtube | flash | readmore | external). Default is 'readmore'. An empty string means no icon will be used. Please note that if the [read_more_button] shortcode has HTML content, no icon will be shown.
target	Specifies the target window where the post should be opened. Default is '_self'. This attribute is the same as the target attribute of the anchor tag in HTML.

[visit_site_button]

Displays a button that opens the page specified by:

• for self hosted and external media: the Target URL option
• for slides: the Slide Link option
• for portfolio posts: the External URL option
• for other types of posts, this shortcode is not supported.

If the URL is not specified or not supported, the button will not be displayed.

Attributes:
icon	Specifies an icon for the button (magnifier | photo | player | vimeo | youtube | flash | readmore | external). Default is 'external'. An empty string means no icon will be used. Please note that if the [visit_site_button] shortcode has HTML content, no icon will be shown.
target	Specifies the target window where the post should be opened. Default is '_blank'. This attribute is the same as the target attribute of the anchor tag in HTML.