Dottoro Theme Documentation

Tutorial to get your theme to work

31. CSS Extension JavaScript Toolkit

The Dottoro CSSEx JavaScript Toolkit is intended to handle cases in which CSS does not provide enough flexibility. For performance reasons, the features of the toolkit are only available in sliders and popup windows except the Aspect Ratio feature that is available everywhere on your site. To use a function of the toolkit, you don't need to do anything else, just add the corresponding CSS class to a HTML element.

• Flexible height

  CSS classes:

  • js-flex-height: Marks the current element as a flexible height element.
  • js-flex-height-media-on: Marks every media element which is descendant of the current element as a flexible height element. Media elements are: img, video, emebed, objct and iframe
  • js-flex-height-layer: Marks the current element as a flexible height layer.

  This feature has been designed to handle cases when the CSS "height:100%" and "max-height:100%" properties cannot or hardly be used. The flexible height feature allows you to mark the HTML elements whose height should be reduced when there is no enough vertical space for them. Every time when the size of the viewport (browser window) changes (and initially), it will be checked whether the slideshow's/popup's content is higher than the slideshow/popup window itself. In other words, whether the content overflows or not. If the content overflows, the height of the flexible height elements will be reduced to eliminate the overflow.
  For instance, let's assume that there is a 400 pixels high image in a slideshow and the image is marked as a flexible height element. If the height of the slideshow is set to 300 pixels on small screen sizes, than the height of the image will be reduced to eliminate the overflow:

  <div class="slideshow" style="height: 300px">
  ....
  <img width="600" height="400" class="js-flex-height" />
  ....
  </div>

  Additionally, flexible height elements can be nested into each other. For instance, if there are two flexible height elements in a slideshow: F1 and F2, and F2 is a descendant of F1 in the DOM, then

  • if the content of the slideshow overflows, the height of F1 will be reduced
  • if the content of F1 overflows, the height of F2 will be reduced

  There is one more thing that is worth mentioning. There are cases, when the height of a flexible height element should be reduced, but the content of a slidehow/popup does not overflow. This typically occurs when the height of an element in the slideshow depends on the height of its parent element.
  Example 1:

  <div class="slideshow" style="height: 300px">
  <div style="height: 100%" class="js-flex-height-layer">
  	....
  	<img width="600" height="400" class="js-flex-height" />
  	....
  </div>
  </div>

  Example 2:

  <div class="slideshow" style="height: 300px; position: relative;">
  <div style="position: absolute; top: 0; bottom: 0; left: 20;" class="js-flex-height-layer">
  	....
  	<img width="600" height="400" class="js-flex-height" />
  	....
  </div>
  </div>

  The two examples are quite similar. There is a 400 pixels high image marked as flexible height in both ones and a div whose height depends on the height of the slideshow. If the height of the slideshow is set to 300 pixels on small screen sizes, the height of the image should be reduced. But since the height of the div depends on the height of the slideshow, the content of the slideshow will not overflow on small screen sizes. In these cases, the overflow of the div's content should be checked not the overflow of the whole slideshow's content. The "js-flex-height-layer" class has been intended for this purpose. If an element is marked as a flexible height layer, then every time the size of the viewport changes, the overflow of its content will be checked, and if the content overflows, the height of the descendant flexible height elements will be reduced.

  Finally, about the "js-flex-height-media-on" class. There are cases when you cannot add the "js-flex-height" class to a media element. For instance, when a post_thumbnail shortcode creates the content. Since the post_thumbnail shortcode often puts the image into a link tag, adding the "js-flex-height" class to the post_thumbnail shortcode ([post_thumbnail class="js-flex-height"]) adds the "js-flex-height" class to the link not to the image. The "js-flex-height-media-on" class has been designed for these cases. If the "js-flex-height-media-on" class is added to an element, every descendant media element will be marked as a flexible height element.

  How to use the flex-height classes in your own templates

  There are two important things you should be aware of:

  • If you want the height of media to be reduced, add the "js-flex-height-media-on" class to the shortcode that displays the media: [post_media class="js-flex-height-media-on" /] or [post_thumbnail class="js-flex-height-media-on" /]
  • If the height of an element depends on the height of the parent (height:100%, max-height: 100%, or when the element is absolute positioned and its top and bottom positions are set), and the element has a flexible height descendant element, add the "js-flex-height-layer" class to the element.
  You will find examples for both cases among the predefined slideshow and post templates (Templates » Slideshow/Post Templates).

  It may seem strange at first sight, that the "js-flex-height" class is not used in the predefined templates at all. This is because the "js-flex-height" class should be set on an element only if the height is specified for the element. The height of images and other media are mostly specified, this is why it is important to add the "js-flex-height-media-on" class to their holder elements (as mentioned above). Additionally, if you set the height of a slideshow (Slideshow Height option), you can also select whether you want the slideshow to have flexible height or not (Flexible Height option). The same is true for the Inner View Height and Inner View Flexible Height options.

• Aspect Ratio CSS classes: js-keep-aspect-ratio

  This feature is intended to handle resizing of those elements for which CSS does not provide enough flexibility. Although this feature can be used for any elements, but since HTML image and video elements always keep aspect ratio (CSS), it is the most useful for iframe, embed and object elements. Especially for iframe, embed and object elements displaying videos.

  Since keeping aspect ratio of videos and other elements can be useful not just in popups and slideshows but also in the content of your pages and posts, this feature is available everywhere on your site. And to make it more easily usable, theme options on the admin screen (in the Aspect ration section under Theme Options » General) allow you to specify the media elements you want this feature to apply. For details, please see Aspect Ratio options.

  In case of the theme options on the admin screen do not provide enough flexibility, you can always add the "js-keep-aspect-ratio" CSS class to any element manually.

• Further Features

  CSS classes
  js-fill-avail-horiz-space	Sets the width of the element to fill the available space. This function is useful for multicolumn layouts when you want a column to fill all the available space. You will find an example for its use in the content of the "Popup - Vertical Navigation" predefined slideshow template (Templates » Slideshow Templates). Its structure looks like this: [row] [col class="js-fill-avail-horiz-space"] [slider_slides /] [/col] [col] [slider_navigation /] [/col] [/row] As you can see the "js-fill-avail-horiz-space" class is set on the left column. The slides are displayed on the left, the navigation on the right. This template has been designed for full size popup slideshows. The width of the right column is determined by the width of the navigation, while the left column always fills the available horizontal space. For instance, if the navigation is 300 pixels wide and the width of the browser window is 1920 pixels, the left column will be 1620 pixels wide (perhaps somewhat less, margins and paddings). If a 400 pixels wide slide is being displayed, it will be centered in the 1620 pixels wide column ("margin: auto" is set for the slides in CSS).
  js-set-parent-width	Sets the width of the parent element to the width of the current element. This is the opposite of the "width:100%" CSS style. The "width:100%" CSS style sets the width of the child element to the width of parent element, while the "js-set-parent-width" function sets the width of the parent element to the width of the child element. This function is useful if you have two or more rows in one column and you want the width of the column to be determined by one of the rows. For instance, if you take a look at the content of the "Slider - Retro" post template (Templates » Post Templates), you will see something like this: <div> <div class="js-set-parent-width"> [post_media /] </div> <div style="overflow: hidden; max-width:100%;"> [post_title /] </div> </div> This template displays the post thumbnail at the top, the post title below it and the title cannot be wider than the thumbnail. This was necessary because if the post title is wider than the thumbnail, it looks better if the title is wrapped to multiple lines. As you can see the "js-set-parent-width" class is set on the div containing the thumbnail. Since in most cases, the width of the "js-set-parent-width" elements must be determined by their content, the theme sets the "display: inline-block" style for the "js-set-parent-width" elements. Therefore the div containing the thumbnail will have the same width as the thumbnail. Since the "js-set-parent-width" class is set on the div, its parent div also has the same width. Finally, since the "max-width:100%;" style is set for the lower div containing the title, it cannot be wider than the parent div so it cannot be wider than the thumbnail.
  js-set-parent-height	Sets the height of the parent element to the height of the current element. This is the opposite of the "height:100%" CSS style (but does not have the same limitations as "height:100%" has - "height:100%" only works if the height of the parent element is set). The "height:100%" CSS style sets the height of the child element to the height of parent element, while the "js-set-parent-height" function sets the height of the parent element to the height of the child element. This function is useful if you have two or more columns in one row and you want the height of the row to be determined by one of the columns. For instance, if you take a look at the content of the "Vertical Navigation On The Right" predefined slideshow template (Templates » Slideshow Templates), you will see something like this: [row] [col class="js-set-parent-height"] [slider_slides /] [/col] [col class="js-flex-height-layer vertical_navigation_wrapper"] [slider_navigation /] [/col] [/row] This template displays the slides on the left and the navigation on the right. Additionally, the navigation cannot be higher than the slides. If it were higher, the slideshow would not look good. How it works? Since the "js-set-parent-height" class is set on the first column, the height of the row will be the same as the height of the first column. Which is not shown in this example is that the maximum height of the second column is set to 100% with CSS (max-height: 100%). The "max-height:100%" works only if the height of the parent element is set, but in this case it is not a problem because the "js-set-parent-height" in the first column guarantees that the height of the parent element will be set. Therefore, the second column will have the same height as the row that has the same height as the first column. So the navigation on the right cannot be higher than the slides on the left.
  js-vert-center	Centers the element vertically within its parent. You will find many examples of this in the predefined slideshow templates. Typically, the slider_slides shortcode has a "js-vert-center" class. It guarantees that the slides will be centered vertically within their parents. It is mostly needed in full size popup slideshows.