Dottoro Theme Documentation

Tutorial to get your theme to work

PrologueFirst StepsFront PageCreating a custom front pageBlog, News and Portfolio post typesPost Type specific settingsGeneral settingsSingle post settingsCategory / Tag / Date archive page settingsPermalink settingsOptions on single post pagesGeneral page optionsImage optionsGallery settingsPage Templates and PagesPage SettingsPage TemplatesPages created from page templatesGeneral page settingsGallery settingsBlog page settingsNews page settingsPortfolio and Imagefolio page settingsContact page settingsArchives page settingsAuthors page settingsBoomarks page settingsSitemap page settingsSpecial pagesCategory and tag page settingsArchive and date page settingsSearch page settingsAuthor page settings404 page settingsHeader and MenuSubheadersSubheader specific shortcodesPredefined SubheadersCreating SubheadersAssigning subheaders to pagesFooterWidgets in the FooterCopyright and other notices in the FooterSidebarWidgets on the SidebarWidth and alignment of the sidebarWidget AreasWidgetsBreadcrumbShortcodesShortcodes In Alphabetical OrderShortcodes By CategoriesNested ShortcodesPost TemplatesOverlaysMedia and External MediaOverview of galleries, gallery listings and slideshowsGalleries and Gallery ListingsAbout Galleries In GeneralCreating And Managing Galleries[gallery_list] shortcodeSlideshows and Popup SlideshowsSlideshowsPopup SlideshowsSlideshow SettingsMost Often Used Slideshow OptionsAll Slideshow OptionsSlideshow Templates - Slideshow Specific ShortcodesStyling Guide For SlideshowsStyling Of Slideshow and Post TemplatesSlidesPopupsSelectorsWeb FontsGeneral Theme SettingsUser RolesExport / Import SettingsCreating theme designsLocalizationHeadingsChild ThemesCSS ClassesResponsive DesignCSS Extension JavaScript ToolkitJavaScript LibraryAction HooksFilter HooksCompatibility Issues
<

19. Popups

In the Dottoro theme, there are basically two types of popups: "normal" popups and gallery popups. Normal popups can be created and managed under Popups » Popups, while gallery popups under Popups » Gallery Popups.
Gallery popups have been designed to display galleries as popup slideshows while normal popups give you full control over the content of popup windows like pages and posts do. In the following sections, the normal popups will be described. For details about gallery popups, please see the Popup Slideshows section.

Dottoro Theme provides a flexible environment for creating and displaying popup windows. The contents of popups can be edited the same way as the contents of pages and posts, and you can also use shortcodes in them. You can set whether a popup window should be modal or modeless, draggable or not and much more. You can specify the default settings for all popup windows under Popups » 'Popup Settings' and any of these settings can be overridden for each individual popup (Popup Options on single popup pages).

In addition, you have full control over not just the contents but also the main components of popup windows. With the help of popup templates you can specify where and how you want to display the close and fullscreen buttons and the title bar.

Finally, to make the use of popup windows more comfortable, the look of popup windows can be customized in the Theme Editor (Components » Popup Window).

Table of contents

19.1 Creating Popups

Popups can be created and managed under Popups » Popups. To create a new Popup, click 'Add New' on the top of the page, give it a title and enter text, then click Publish. You can also use shortcodes in the content of popups. In addition, the theme supports a shortcode, the [popup_arg] shortcode that allows you to display the values passed to the popup. For details, please see the Displaying Popups section.

There is a 'Popup Options' box below the content editor. Here you can specify the settings of the popup window. It is also possible to change the default settings of popups ('Popup Settings' menu), so you don't need to change the same setting every time you create a new popup.

19.2 Popup Settings

You can specify the default settings for all popup windows under Popups » 'Popup Settings' and any of these settings can be overridden for each individual popup (Popup Options on single popup pages).

Settings
Content Here you can select what you want to display in the popup.
  • The "Own" option means that the popup will display its own content specified above in the WordPress content editor.
  • The "URL" option allows you to specify the URL of the web page you want to display. It is mostly useful when you want to display an external web page in the popup.
  • The other values allow you to display a page or post of your website in the popup.
Some notes:
  • If you select an option other than "Own", the content will be loaded into an iframe. The size of the iframe must always be set. See the "Popup CSS Class" option for details.
  • If you select the "URL" option and specify an external URL, leave the "external" checkbox checked to avoid JavaScript warnings.
JavaScript is supported in popups from version 1.39.
Popup CSS Class One or more CSS classes to add to the outer element of the popup window, separated by a single space. Custom CSS classes allow you to set the position, the size and other properties of the popup window.
Some notes:
  • If the popup content is loaded into an iframe (see the Content option), the size of the iframe must be set.
    CSS Example: .my_popup iframe {width: 400px; height: 300px;}
  • If the popup displays its own content, it is advisable to set the size of popup\'s body not the entire popup window. Its main advantage is that the content will be scrollable when the popup is resized (see the "Size Limit" option).
    CSS Example: .my_popup .popup_body {width: 400px; height: 300px;}
* replace my_popup with your own CSS class specified in the Popup CSS Class input field
Template Select a template for the popup. The popup template specifies where and how to display the close and fullscreen buttons, the title bar and more.
Popup templates can be created under Templates » Popup Templates. More on Popup Templates.
Close Button Select whether you want to display the popup close button or not and you can also select an icon for the close button.
Technically, these settings change the way the [popup_button type="close"] shortcode works in the popup template.
Fullscreen Button Select whether you want to display the popup fullscreen button or not and you can also select an icon for the "go fullscreen" and "exit fullscreen" buttons.
Technically, these settings change the way the [popup_button type="go_fullscreen"] and [popup_button type="exit_fullscreen"] shortcodes work in the popup template.
Please note that the fullscreen button is only supported in modern browsers (in IE, version 11 or above). In older browsers, the button will be hidden.
Auto Close Specifies the amount of time in milliseconds that the popup should remain visible before it hides. The value of 0 means that there is no time limit.
Window Type Select whether the popup window should be modal or modeless. While a modal window is open the user cannot interact with the main window.
Position Set the position of the popup window.
  • The "centered" value means that the popup window will be centered in the browser window.
  • The "horizontally centered"/"vertically centered" value means that the popup window will be horizontally/vertically centered and you should specify its vertical/horizontal position.
  • Finally, the "custom" value allows you to specify both the vertical and horizontal positions.
To specify the position of popup windows, you have the following possibilities:
  • If you want to specify the default position for all popup windows, use the ".popup" CSS class.
    CSS Example: .popup {right: 0px; bottom: 0px;}
  • The Popup CSS Class option on individual popup pages allows you to add custom CSS classes to a popup. Use these CSS classes to specify different positions for different popups.
    CSS Example: .my_popup {right: 0px; bottom: 0px;} - where my_popup is your own CSS class specified in the Popup CSS Class input field
  • If you want to display a popup with an animation, the Show Animation - Properties option allows you to specify the properties to animate.
Move Into View Select whether the popup window should be automatically moved into the viewport (browser window) or not.
Size Limit Select whether the popup window should be automatically resized when it is larger than the browser window (view) or not (none). It is advisable to select the view option, otherwise it can happen that the popup will be larger than the viewport and cannot be closed. Also see the Popup CSS Class option above.
Margin Here you can add some extra space around the popup window, in pixels. This is not the same thing as the CSS margin but they are very similar. This option affects the way the Move Into View and Size Limit options work. This margin is included in the boundary box of the popup window when its size and/or position is being calculated. It is mostly useful when the close button is placed outside the popup window. For example, if the close button is placed at the top-right, outside of the popup window, then add some space on the top and right sides of the popup and the close button remains visible even if the popup needs to be moved and/or resized on small screen devices.
Action On Close Select whether the popup window should be destroyed or hidden when closed. The contents of popup windows are loaded with AJAX (SEO optimization). The destroy option ensures that the contents are reloaded every time the popup is shown while hidden popups only reopen without refreshing their content. Always destroy a popup if parameters are passed to the popup.
Close On Outside Click Select whether modal popup windows should be closed when clicking outside the popup or not. This setting only affects modal popup windows.
Draggable Select whether you want popup windows to be draggable or not. Since a popup window can be only dragged by clicking on its title bar, popup windows without a title are never draggable.
Show Animation - Properties Specify the properties to animate when the popup appears and disappears. The value must be given in JavaScript object literal format.
The supported properties are:
  • CSS properties that take length values (width, height, left, top, right, bottom, font-size, etc.)
    Examples:
    • {top: {from: -200, to: 0}} - the top position of the popup is -200 pixels at the start of the show animation and 0 pixels at the end.
    • {right: {from: -500, to: 0}, bottom: {from: -200, to: 0}} - move from right-bottom (-500, -200) to (0, 0).
    Units can also be specified:
    • {top: {from: '-10%', to: '0%'}}
  • opacity (values between 0 and 1)
    • {opacity: {from: 0, to: 1}}
    • {opacity: {from: 0.2, to: 0.8}}
  • clip - animates the clip CSS property.
    • {clip: {right: {from: 0, to: 'auto'}}}
    • {clip: {right: {from: 0, to: 'auto'}, bottom: {from: 0, to: 'auto'}}}
    • {clip: {left: {from: -1, to: 'auto'}}} - if 'left' is negative, it means the right side of the popup
    • {clip: {left: {from: -1, to: 'auto'}, top: {from: -1, to: 'auto'}}} - if 'top' is negative, it means the bottom side of the popup
  • trafo - two-dimensional linear transformation, supported functions: moveX, moveY, scaleX, scaleY, rotate, originX, originY
    • {trafo: {moveX: {from: 0, to: 100}}}
    • {trafo: {scaleX: {from: 0, to: 1}, scaleY: {from: 0, to: 1}}}
    • {trafo: {rotate: {from: 3.14, to: 0}}}
    • {trafo: {rotate: {from: 3.14, to: 0}, originX: '100%', originY: '100%'}}
Show Animation - Duration Specify the duration of the show/hide animation, in milliseconds.
Show Animation - Easing Specifies the easing function for the show/hide animation. Easing functions (timing functions) specify how the intermediate values are calculated during the animation. It allows for a transition to change speed over its duration. See Live Demo.
Media Preload Select whether media (images, videos and iframes) should be preloaded before opening the popup, or not.

19.3 Popup Templates

Popup templates give you control over the main components of popup windows. You can specify where and how you want to display the close and fullscreen buttons, the title bar and for instance, if you want to add a copyright line at the bottom of the popup windows on your site, just add it to a popup template so you don't need to add it to the content every time you create a new popup.

You can select a default popup template with the Template option under Popups » 'Popup Settings' and this setting can be overridden for each single popup with the Template option on the Edit Popup Screen.

Popup templates can be created and managed under Templates » Popup Templates. The theme comes with a couple of predefined templates that are designed to meet the most common needs, and you can always create custom ones. Predefined templates give you a good basis to create your own popup templates.

Shortcodes for Popup Templates

There are a couple of shortcodes that are designed for popup templates. They display the titlebar, close and fullscreen buttons and the body of a popup window. They can be used in popup templates and also in slideshow templates used for gallery popups.

19.4 Displaying Popups

There are basically two ways to display a popup:

Regardless of whether you choose the [popup_opener] shortcode or the DottoroWP.OpenPopup JavaScript function to open a popup, you will need the identifier of the popup. To get the identifier of a popup, open the edit popup page and look at the URL in the location bar of your browser. The URL contains a 'post=number' substring, where the number is the identifier.

19.4.1 Examples for the popup_opener shortcode

Example 1
This example shows how to add some text to the content of a page/post that opens a popup?

[popup_opener popup_id="23"]Open Popup[/popup_opener]

Example 2
This example shows how to create a button with the [button] shortcode that opens a popup.

[popup_opener nested_shortcode="button"][button skin="coral"]Open popup[/button][/popup_opener]

For further details and examples, please see [popup_opener] shortcode.

19.4.2 Examples for the DottoroWP.OpenPopup function

Example 3
This example displays a link that opens a popup with the id of 2365. The return false; is required to cancel the onclick event (if the click event is canceled the browser does not navigate to the URL of the link).
<a href="#" onclick="DottoroWP.OpenPopup (2365); return false;">Open Popup</a>

Example 4
This example is similar to the previous one but it uses the button shortcode not an anchor tag.
[button onclick="DottoroWP.OpenPopup (2365); return false;"]Open Popup[/button]

Example 5
It is also possible to pass arguments to a popup. The second argument of the DottoroWP.OpenPopup function allows you to pass name/value pairs to a popup. This argument must be a JavaScript object!

This example shows how to pass values to a popup (name: John, age: 53).

[button onclick="DottoroWP.OpenPopup (2365, {'name': 'John', 'age': 53}); return false;"]Open Popup[/button]

But how to access the passed arguments in the popup? The [popup_arg] shortcode allows you to display the passed arguments. Additionally, make sure that the Action On Close option of the popup is set to destroy to ensure that the contents are reloaded every time the popup is shown. For example, if the content of a popup looks like this:

<h1>Hello [popup_arg name="name" /]!</h1>
<div>You are [popup_arg name="age" /] years old.</div>

then the following popup will appear:

Hello John!

You are 53 years old.

Example 6
There are cases when the [popup_arg] shortcode does not provide enough flexibility. For instance, when a popup should display a button ([button] shortcode) pointing to the URL passed as an argument named 'url'. Shortcodes are not processed within shortcode attributes:
[button href="[popup_arg name='url']"]Visit Site[/button] does not work.

Fortunately, the [do_action] shortcode provides a solution for these cases. Just insert a [do_action] shortcode into the content of the popup where you want to display the button and execute a custom hook (e.g. popup_link) with the [do_action] shortcode:
[do_action action="popup_link" /]
Then hook a function to the popup_link action that displays the button. You can use the Dottoro_Popup::get_popup_arg PHP function to get the value of a passed argument. Insert the following lines into the functions.php file of your child theme:
add_action ('popup_link', 'display_popup_link');
function display_popup_link () {
    $url = Dottoro_Popup::get_popup_arg ('url');
    echo (do_shortcode ('[button href="'. $url .'"]Visit Site[/button]'));
}
and the popup will display a button pointing the target URL of the clicked link.
See also the next example.

Example 7
How to open a popup window when the visitor clicks on certain automatically generated links, for example, menu items?

Since you cannot specify the onclick attribute for automatically generated links directly, you should use JavaScript to collect these menu items when the document has been loaded and to listen the onclick event on them.
But how to find these menu items? A possible solution is to add the same CSS class (for example popup_link) to these menu items: And now, write some lines of JavaScript code. The Dottoro JavaScript library provides everything you need: The code should look like this (opens the popup with the id of 2365 and passes the target URL of the clicked anchor as a parameter named 'url'):
<script>
    Dottoro.Ready (PopupForExternalMenus);
    function PopupForExternalMenus() {
        var items = Dottoro.GetElemsByClass ('popup_link');
        for (var i = 0; i < items.length; i++) {
            var item = items[i];
                // the css classes are added to the parent element of menu links
            var link = item.getElementsByTagName ('a')[0];
            if (link) {
                Dottoro.AddListener ('click', OnClickExternalMenu, link);
            }
        }
    }
    function OnClickExternalMenu (event, link) {
        DottoroWP.OpenPopup (2365, {'url': link.href});
        return Dottoro.PreventDefault (event);
    }
</script>
If you want to use this script on multiple pages, it is advisable to insert it (without the opening and closing script tags!) into a custom js file.
If you have already a custom js file, just add this code to it and you are done.
Otherwise create a new file, add this code to it and save it (such as script.js). Create a folder named 'js' under the root directory of your child theme and upload the script.js file to it. Finally, use the dottoro_scripts action to import the script.js file (insert these lines into the functions.php file of your child theme):
add_action ( 'dottoro_scripts', 'custom_scripts' );
function custom_scripts ( ) {
	$mtime = @filemtime ( FOLDER_CHILD_THEME . 'js/script.js' );
	Dottoro_Theme::print_script ( URL_CHILD_THEME . '/js/script.js', $mtime );
}
The main advantage of this solution is that the URL pointing to the script.js file will end with the last modified timestamp of the file. So you don't need to worry about browser caching issues when you modify the content of your script.js file.

Example 8
How to create a button in the popup that closes the popup window?

The DottoroWP.GetOwnerPopup JavaScript function retrieves a Popup object from any HTML element of the popup. This Popup object represents the popup window. For example, you can use its Close method to close the popup window:
[button onclick="DottoroWP.GetOwnerPopup (this).Close(); return false;" ]Close[/button]

Example 9
How to display a popup when the document has been loaded?

This example opens a popup with the id of 2365 when the document has been loaded:
<script>
Dottoro.Ready (ShowPopupOnLoad);
function ShowPopupOnLoad () {
    DottoroWP.OpenPopup (2365);
}
</script>

Example 10
How to display a popup when the user scrolls down the page.

The following JavaScript code snippet opens a popup (with the id of 2365) if the position of the vertical scrollbar is greater than the half of the maximum scroll position, otherwise closes the popup. For further details, please see the Dottoro.GetDocScrollTop, Dottoro.GetDocScrollMax and Dottoro.AddListener methods.
<script>
Dottoro.AddListener ('scroll', ShowPopupOnScroll, window);
function ShowPopupOnScroll () {
    var y = Dottoro.GetDocScrollTop ();
    var max = Dottoro.GetDocScrollMax ();
    if (y > max.y / 2) {
        DottoroWP.OpenPopup (2365);
    }
    else {
        DottoroWP.ClosePopup (2365);
    }
}
</script>

Live example

19.5 Preloading Popups

Since the contents of popups rarely need to be indexed by search engines, they are loaded with ajax. This causes a delay in opening popups. If you want to eliminate this delay, you have the following options:

The main difference between the ajax and static preloads is that the staic preload increases the document loading time while ajax preload doesn't. Therefore, it is advisable to choose ajax preloading in the case of large popups.

The main drawback of preloading is that the popup downloads regardless of whether it can or should open.

How to preload
The Dottoro_Popup::preload method allows you to preload popups. You need to pass an array as a parameter, where you can specify the popup id and preloading method.
Example 1
This example preloads the popup with id 2423 dynamically. The script block generated by the Dottoro_Popup::preload method will be inserted before the closing </body> tag.

If you want to preload a single popup on every page, insert the following lines into the functions.php file of your child theme.
add_action( 'dottoro_close_body', 'preload_popups', 5 );
function preload_popups () {
	Dottoro_Popup::preload ( array ('id' => 2423, 'loadtype' => 'ajax') );
}
Example 2
This example is similar to the previous one, but it uses the 'static' preloading method.
add_action( 'dottoro_close_body', 'preload_popups', 5 );
function preload_popups () {
	Dottoro_Popup::preload ( array ('id' => 2423, 'loadtype' => 'static') );
}
Example 3
How to preload a popup on a single page?

You can use the Dottoro_Theme::get_page_id method to retrive the id of the current page/post. This example preloads the popup with id 2423 only on the page with id 23.
add_action( 'dottoro_close_body', 'preload_popups', 5 );
function preload_popups () {
	if ( Dottoro_Theme::get_page_id () == 23 ) {
		Dottoro_Popup::preload ( array ('id' => 2423, 'loadtype' => 'ajax') );
	}
}
Example 4
How to preload multiple popups?

Just create an array and put the popups in it:
add_action( 'dottoro_close_body', 'preload_popups', 5 );
function preload_popups () {
	$popups = array (
		array ('id' => 2415, 'loadtype' => 'static'),
		array ('id' => 2423, 'loadtype' => 'static'),
	);

	Dottoro_Popup::preload ( $popups );
}
Example 5
It is also possible to pass arguments to a preloading popup. The key 'args' allows you to specify the arguments as a PHP array.
add_action( 'dottoro_close_body', 'preload_popups', 5 );
function preload_popups () {
	$popups = array (
		array ('id' => 2415, 'loadtype' => 'ajax', 'args' => array ( 'url' => 'dottoro.com' )),
		array ('id' => 2423, 'loadtype' => 'ajax', 'args' => array ( 'url' => 'dottoro.com', 'color' => 'red' )),
	);

	Dottoro_Popup::preload ( $popups );
}