Modals

Make modal popups in Joomla!

  • Last updated: 23-May-2018
  • Version: 9.11.1
  • Type: System plugin
  • Joomla rating: 100%
Joomla rating: 100%

Do you like Modals?

Rate it!

Tutorial for Modals

There is a Free and a Pro version of Modals.
The parts in this tutorial that only concern the Pro version will be marked with: Pro only

Introduction

Modals is a Joomla plugin extension to help you create cool modal popup, like this!

Simple Modals

All you have to do to create a link is place the url inside the {modal} opening tag. Place the text of the 'link' you want people to click on between the {modal} opening and {/modal} closing tag.

{modal url="my/url"}Click on me!{/modal}

Example: Internal url

{modal url="index.php/123-my-article"}Internal url{/modal}

Example: External url

{modal url="https://goo.gl/5r5faj"}External url{/modal}

Add a Title

You can add a title by adding a title attribute in the {modal} opening tag, like:

Example: I've got a title

{modal url="https://goo.gl/5r5faj" title="That's my place :)"}I've got a title{/modal}

Link to an Article

As explained before, you can simply link to a url.
To open an article in the modal window, you can use the url of the article, like:

{modal url="index.php?option=com_content&view=article&catid=1&id=123"}Link to an article{/modal}

Change the catid and id values to your actual category and article id.

Quick links Pro only

However, with the pro version of Modals you can link directly to a Joomla article without having to know the exact url. You can simply place the article's title, alias or id after the article attribute.

Examples:
Link using article title
Link using article alias
Link using article id

{modal article="My Article"}Link using article title{/modal}
{modal article="my-article"}Link using article alias{/modal}
{modal article="123"}Link using article id{/modal}

Link to an Image

You can also link to images. Modals will recognise links to images and adjust the styling of the modal window a bit to accommodate this.

Example: Image

{modal url="images/fruit/bananas.jpg" title="Totally bananas"}Image{/modal}

Add link to an Image

To add a modal link to an image, simply place the {modal} tags around the image.

Example:

{modal url="index.php/123-my-article"}{/modal}

Link to a Video

Example: Youtube video

{modal url="https://www.youtube.com/embed/tENZDoj5MTg" width="560" height="315" title="Learn all about What? Nothing!"}Youtube video{/modal}

Example: Vimeo video

{modal url="https://player.vimeo.com/video/163836607" width="500" height="281" title="Modals Tutorial"}Vimeo video{/modal}

Quick links Pro only

Just like with the articles, the pro version of Modals provides you with the ability to create links to videos with a shorter syntax. You can simply place the youtube / vimeo video id after a youtube= / vimeo attribute.

Example: Youtube video

{modal youtube="tENZDoj5MTg" width="560" height="315" title="Learn all about What? Nothing!"}Youtube video{/modal}

Example: Vimeo video

{modal vimeo="163836607" width="500" height="281" title="Modals Tutorial"}Vimeo video{/modal}

Width & Height

By default the modal window will auto size for internal urls and will open in the maximum size for external urls.

You can overrule the width and/or height by setting these to a fixed pixel or percentage value.

Example: 500 x 500px

{modal url="index.php/123-my-article" width="500" height="500"}500 x 500px{/modal}

Example: 60% x 40%

{modal url="index.php/123-my-article" width="60%" height="40%"}60% x 40%{/modal}

Open menu items in modals

To make a menu item open in a modal popup, simply surround the menu title in {modal} tags.

So if your menu item title is Click here!, change it to {modal}Click here!{/modal}.

You can also pass extra variables in the tag as described earlier, like: {modal title="My Page"}Click here!{/modal} or {modal width="600" height="400"}Click here!{/modal}.

If for some reason you don't want to use the {modal} tags (or it doesn't work), you can also give the menu item a custom classname (works with most menu modules) and set Modals up to convert by that classname.

Open modules in modals

To make a module open in a modal popup, you can use any of these techniques.

You will need to use Modules Anywhere to accomplish this.

Via a new article

Create a new article and place the Modules Anywhere tag in that article, like: {module My Module}.

The simply link to that new article using Modals.

Some modules that rely on scripts and external styles may not work correctly. In that case you will need to use the iframe mode, by adding iframe="true" to the {modal} tag.

Inline module Pro only

If you are using the Pro version of Modals, you can also use the inline content tags for this, like:

{modal content="mymodule"}Click here to open My Module{/modal}
{modalcontent mymodule}
{module My Module}
{/modalcontent}

Some modules that rely on scripts and external styles may not work using the inline method. In that case you will need to use the above 'new article' method.

Open by URL Pro only

You can set Modals up to make all links to certain urls open in modal popups.

You can find the URL matches options under the Convert Existing Links section in the Modals system plugin settings.

If you - for instance - want all links to pages containing the word shop to open in a modal popup, simply enter that in the URL matches field.

Or enter some-other-website.com/ to open all external links to some-other-website.com in your website.

For even more control, you can also create URL matching rules using Regular Expressions.

Auto-convert Images Pro only

With the pro version of Modals you can make images automatically clickable and open in a modal by simply giving the image a class name.

The default class name is modal, but you can change that in the Modals system plugin settings. You can even give a comma-separated list of class names which Modals should handle.

Modals will check if the image in your content is a thumbnail or not. It will make sure the thumbnail is shown in the content (as clickable) and the large image is shown in the modal popup.

A thumbnail is an image with the same filename as the large image, but with the thumbnail suffix.
The thumbnail suffix by default is _t, but can also be changed in the Modals system plugin settings.

To give a few examples:

You place the image apples.png in your content. You resize it to a thumbnail size and give it a class name modal.
Modals will check for the thumbnail. If apples_t.png exists, it will show that image in your content instead. When you click on the thumbnail image, the apples.png image will be openen in the modal popup.

Or, you place the apples_t.png image into your content instead and give it a class name modal.
Modals will output the same as in the previous example: it will show the thumbnail image in your content. When you click on the thumbnail image, the apples.png image will be

Galleries & Slideshows Pro only

Auto galleries

You can very easily create a gallery by a single modal tag with a gallery attribute (which holds the folder containing of your images).

You can tell Modals to show special thumbnails images in your content, by adding image files that have the thumbnail suffix added to them (default: _t).
So the thumbnail for image apples.jpg should be apples_t.jpg.

Example:

{modal gallery="images/gallery"}{/modal}

Custom link

If you place anything between the modal tags, that will be used as link to open the gallery. This can be text or an image or basically anything you want.

Example: Click here

{modal gallery="images/gallery"}Click here{/modal}

Different first image

The first image (thumbnail) in the folder will be shown in the content. If you want to show a different image instead, add a first attribute.

Example:

{modal gallery="images/gallery" first="bananas.jpg"}{/modal}

Show all thumbnails

By default only the thumbnail of the first found image in the folder will show (you can change this default setting).
To make the thumbnails of all the images show,add showall="true" to the modal tag.

Example:

{modal gallery="images/gallery" showall="true"}{/modal}

Slideshow

To create a slideshow, simply add slideshow="true" to the modal tag.

Example:

{modal gallery="images/gallery" slideshow="true"}{/modal}

Filtered

You can overrule the default filter with your own. This example only shows images from folder images/fruit that end in _x (just before the file extension).

Example:

{modal gallery="images/fruit" filter="_x\."}{/modal}

Custom images and thumbnails

You might want to define your own specific images, because they are not in the same folder, or because you don't want all images in the folder to show.
To create a gallery with custom image paths, create a modal tag for every image and add a group attribute to the modal tags.

Example:

{modal url="images/fruit/bananas_x.jpg" group="mygallery"}{/modal} {modal url="images/fruit/limes_x.jpg" group="mygallery"}{/modal} {modal url="images/fruit/strawberries_x.jpg" group="mygallery"}{/modal}

Slideshow

To create a slideshow on these custom galleries, you need to add slideshow="true" to every modal tag in the group.

Example:

{modal url="images/fruit/bananas_x.jpg" group="mygallery2" slideshow="true"}{/modal} {modal url="images/fruit/limes_x.jpg" group="mygallery2" slideshow="true"}{/modal} {modal url="images/fruit/strawberries_x.jpg" group="mygallery2" slideshow="true"}{/modal}

Titles and Descriptions

By default Modals will convert the image name to a title.

But you can override image titles and give them separate descriptions via a data.txt file which you place in the gallery folder.

Here is an example of such a file showing you the different possibilities:

description=Description for all images in the gallery

title_apples=My special title for Apples
description_apples=Description especially for Apples

title_bananas=My special title for Bananas

Inline content Pro only

Content in separate content tag

You can use the content attribute in combination with modalcontent tags to open your custom content inside a modal.
This is great for when you don't want to create a separate article just for one link.

All you need to do is choose an alias for the modalcontent tag and place that alias as value in for the content attribute.

Example: A lot more inline content

{modal content="mycontent" title="Fully styled inline content"}A lot more inline content{/modal}
{modalcontent mycontent}
... your fully styled content...
{/modalcontent}

By using the modalcontent tags, you can place entire content blocks into the modal without the need of creating separate articles/urls.

You are also completely free to place whatever style and type of content you want in here:

Lorem Ipsum

applesPellentesque habitant morbi tristiquesenectus et netus et malesuadafames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. Ut felis.

Header Level 2

  1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  2. Aliquam tincidunt mauris eu risus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus magna. Cras in mi at felis aliquet congue. Ut a est eget ligula molestie gravida. Curabitur massa. Donec eleifend, libero at sagittis mollis, tellus est malesuada tellus, at luctus turpis elit sit amet quam. Vivamus pretium ornare est.

Header Level 3

  • Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  • Aliquam tincidunt mauris eu risus.
#header h1 a { 
	display: block; 
	width: 300px; 
	height: 80px; 
}

Content in tag

For short and simple content, you can also place the content straight into the modal tag by using the html attribute:

Example: Show some inline text

{modal html="This text is entered right inside the modal tag." title="Hello!"}Show some inline text{/modal}

Grouped mixed content Pro only

You can group different types of links by adding a group attribute to the modal tag.
This will give you arrow navigation to the different links inside the modal popup.

  1. Internal url
  2. External url
  3. Inline content
  4. Image
  5. Video
{modal url="index.php/123-my-article" group="mygroup"}Internal url{/modal}
{modal url="https://goo.gl/5r5faj" group="mygroup"}External url{/modal}
{modal html="This text is entered right inside the modal tag." group="mygroup"}Inline content{/modal}
{modal url="images/fruit/bananas.jpg" group="mygroup"}Image{/modal}
{modal url="https://www.youtube.com/embed/tENZDoj5MTg" width="560" height="315" title="Learn all about What? Nothing!" group="mygroup"}Video{/modal}

Auto-close Pro only

You can make a modal window auto-close after a given amount of time using the autoclose attribute.

To make the modal close after the default amount of time set in the Modals plugin settings, simply add the autoclose="true" attribute:

Example

{modal url="my/url" autoclose="true"}...{/modal}

But you can also set a different time in milliseconds. So if you want to auto-close the modal after only 2 seconds, do:

Example

{modal url="my/url" autoclose="2000"}...{/modal}

As you can see in above examples, Modals shows a countdown bar (blue line) at the top of the modal popup.

If you don't want that countdown to show, you can switch of the Enable Countdown Bar setting in the Modals system plugin settings.

Splash pages : Open modal on pageload Pro only

To make modal popup on pageload, simply add the open="true" to the {modal} tag, like:

{modal url="my/url" open="true"}...{/modal}

If you do not want to show the actual link to the page, then simply don't place any text between the {modal} tags, like:

{modal url="my/url" open="true"}{/modal}

The syntax for modal popup you can see on the demo page looks like:

{modal html="Yes, you can also make modal popups show on page load!" title="Welcome to the Modals Demo" open="true" autoclose="5000"}{/modal}

Show only once

To make a modal popup only show once, you can use open=once, like:

{modal html="This modal will only show once" open="once"}{/modal}

By default, Modals will keep track of the count via a site wide cookie. If you want this count to be based on the individual page visits, then you can change that in the Modals system plugin settings. You can also choose to base the count on the site wide session count instead.

Show on specific page loads

You can also tell Modals to show the modal on specific pageloads or a specified range of visits, using the open attributes. For instance, to show a modal on the second, third and fourth page load, you can do:

{modal html="This modal will show on visit 2, 3 and 4" open="2,3,4"}{/modal}

or:

{modal html="This modal will show on visit 2, 3 and 4" open="2-4"}{/modal}

If you want a modal to pop up on the first 5 visits and on visit 10, 15 and 20, you can do:

{modal html="This modal will show on visits, 1-5, 10, 15 and 20" open="1-5,10,15,20"}{/modal}

By default, Modals will keep track of the count via a site wide cookie. If you want this count to be based on the individual page visits, then you can change that in the Modals system plugin settings. You can also choose to base the count on the site wide session count instead.

Open with a delay

Maybe you want the modal popup to open after a few seconds.

No problem, Modals can do that too.

Simply add a delay attribute to the tag and give the time value in milliseconds.

So to open a modal popup 7.5 seconds after the page has loaded, do:

{modal url="my/url" open="true" delay="7500"}{/modal}

Settings

Styling

Load Stylesheet Select to load the extensions stylesheet. You can disable this if you place all your own styles in some other stylesheet, like the templates stylesheet.
Style Select a style to use for the modal popup windows

Convert Existing Links

Classnames

Auto-Convert If selected, all links with one of the given classnames will be converted to modal popup links.
Classnames A comma separated list of classnames. Links that have any of the defined classnames will be converted to modal popup links.

External Links Pro only

Auto-Convert If selected, all links to external sites will be converted to modal popup links.

Target Blank Pro only

Auto-Convert If selected, all links that have a target="_blank" will be converted to modal popup links.
Internal Links If selected, all links to internal sites will be converted to modal popup links.
External Links If selected, all links to external sites will be converted to modal popup links.

Filetypes Pro only

Auto-Convert If selected, all links to files that match one of the given filetypes will be converted to modal popup links.
Filetypes A comma separated list of filetypes. Links that point to any of the defined filetypes will be converted to modal popup links.

URL matches Pro only

Auto-Convert If selected, all links that match the URL selection will be converted to modal popup links.
URL matches Enter (part of) the URLs to match.
Use a new line for each different match.
Use Regular Expressions Url parts will be matched using regular expressions. So make sure the string uses valid regex syntax.

Images Pro only

Classnames

Auto-Convert If selected, all images with one of the given classnames will be converted to modal popup links.
Classnames A comma separated list of classnames. Images that have any of the defined classnames will be converted to a modal popup gallery.

Default Settings

These options that can be overrules inside the {modal} tag like you can see in above examples.

So the syntax for overruling settings in the {modal} tag is:

{modal url="my/url" setting_name="setting_value" setting_name="setting_value"}...{/modal}

The settings marked with a * can be set to a different default value in the Modals system plugin settings.

The Free version ONLY allows these settings: url, title, width, height, iframe.

NameDefault valueDescription
url / href   The url or element to open in the modal. You do not have to use the setting name in the {modal} tag if the url is defined as first parameter. So these all work:
{modal my/url}...{/modal}
{modal url="my/url"}...{/modal}
{modal href="/my/url"}...{/modal}
content   The id of the content (set by the {modalcontent} tag) to open in the modal:
{modal content="mycontent"}...{/modal}
{modalcontent mycontent}This text appears inside the modal!{/modalcontent}
html   For displaying a string of HTML or text:
{modal html="This text appears inside the modal!"}...{/modal}
title   This can be used as an anchor title alternative for the modal.
className   Adds a given class to the modal and the overlay.
iframe false If true, specifies that content should be displayed in an iFrame. For external urls this is automatically set to true.
photo false If true, this setting forces the modal to display a link as a photo. Use this when automatic photo detection fails (such as using a url like 'photo.php' instead of 'photo.jpg')
scrolling true If false, the modal will hide scrollbars for overflowing content. This could be used on conjunction with the resize method (see below) for a smoother transition if you are appending content to an already open instance of the modal.
open true If true, the modal will immediately open on pageload.
transition * elastic The transition type. Can be set to "elastic"or "none".
speed * 350 Sets the speed of elastic transitions, in milliseconds.
scalePhotos * true If true, and if maxWidth, maxHeight, width, or height have been defined, the modal will scale photos to fit within the those values.
returnFocus * true If true, focus will be returned when the modal exits to the element it was launched from.
fastIframe * true If false, the loading graphic removal and onComplete event will be delayed until iframe's content has completely loaded.
opacity * 0.8 The overlay opacity level. Range: 0 to 1.
overlayClose * true If false, disables closing the modal by clicking on the background overlay.
closeButton * true If false, removes the close button.
escKey * true If false, will disable closing the modal on 'esc' key press.
arrowKey * true If false, will disable the left and right arrow keys from navigating between the items in a group.
Dimensions
width *   Set the fixed dimension. In pixels (ie 500) or percentage (ie 80%).
height *   Set the fixed dimension. In pixels (ie 500) or percentage (ie 80%).
externalWidth *   Set the fixed dimension for external urls. In pixels (ie 500) or percentage (ie 80%).
externalHeight *   Set the fixed dimension for external urls. In pixels (ie 500) or percentage (ie 80%)./td>
initialWidth * 600 Set the initial dimension, prior to any content being loaded. In pixels (ie 500) or percentage (ie 80%).
initialHeight * 450 Set the initial dimension, prior to any content being loaded. In pixels (ie 500) or percentage (ie 80%).
maxWidth * 95% Set the maximum dimension for loaded content. In pixels (ie 500) or percentage (ie 80%). Set to 0 for no maximum.
maxHeight * 95% Set the maximum dimension for loaded content. In pixels (ie 500) or percentage (ie 80%). Set to 0 for no maximum.
Positioning
fixed * false If true, the modal will be displayed in a fixed position within the visitor's viewport. This is unlike the default absolute positioning relative to the document.
reposition * true Repositions the modal if the window's resize event is fired.
top *   Accepts a pixel or percent value (50, "50px", "10%"). Controls the modal's vertical positioning instead of using the default position of being centered in the viewport.
bottom *   Accepts a pixel or percent value (50, "50px", "10%"). Controls the modal's vertical positioning instead of using the default position of being centered in the viewport.
left *   Accepts a pixel or percent value (50, "50px", "10%"). Controls the modal's horizontal positioning instead of using the default position of being centered in the viewport.
right *   Accepts a pixel or percent value (50, "50px", "10%"). Controls the modal's horizontal positioning instead of using the default position of being centered in the viewport.
Groups / Slideshows
group / gallery   This allows the user to group any combination of elements together for a gallery.
preloading * true Allows for preloading of 'Next' and 'Previous' content in a group, after the current content has finished loading. Set to false to disable.
loop * true If false, will disable the ability to loop back to the beginning of the group when on the last element.
slideshow * false If true, adds an automatic slideshow to a content group / gallery.
slideshowSpeed * 2500 Sets the speed of the slideshow, in milliseconds.
slideshowAuto * true If true, the slideshow will automatically start to play.
Auto-Gallery
showall * false If selected, all thumbnails in the given gallery folder will be automatically shown.
thumbSuffix * _t The suffix to identify the thumbnail to show as the link. Example with default value '_t': if the main image is 'apple.jpg', then the thumbnail image is 'apple_t.jpg'.
thumbWidth *   Set the thumbnail dimension in pixels (ie 80). Leave empty to not force a specific size.
thumbHeight *   Set the thumbnail dimension in pixels (ie 80). Leave empty to not force a specific size.
separator * (space) Set the separator html for the images in the gallery. By default this is a space. Enter {none} to have no spacing between images.
filter * \.(png|jpg|gif|eps) The filter (Regular Expression) used to find the image files in the given gallery folder.
Retina Images
retinaImage * false If true, the modal will scale down the current photo to match the screen's pixel ratio
retinaUrl * false If true and the device has a high resolution display, the modal will replace the current photo's file extention with the retinaSuffix+extension
retinaSuffix * @2x.$1 If retinaUrl is true and the device has a high resolution display, the href value will have it's extention extended with this suffix. For example, the default value would change 'my-photo.jpg' to ''

Advanced Settings

Modal Tag The word used for the modal tags.

You can change the word if you are using another plugin that uses this tag syntax.
Modal Content Tag The word used for the modal content tags used to define content for modal links that open by id.

You can change the word if you are using another plugin that uses this tag syntax.
Tag Characters The surrounding characters of the tag syntax.

Note: If you change this, all existing tags will not work anymore.

Options: {...}, [...], {{...}}, [[...]], [:...:], [%...%]
Sub Template This is the sub template used for the internal pages in the modal popup windows. There will have to be a php file with this name in your templates folder or otherwise in the system templates folder.
Open as Iframe If selected, modals will be opened as iframe by default. This excludes links lo media files.
Load scripts/styles Select to load the scripts, styles and other document head data in the inline modal content. Only enable when certain functionality/styling isn't working inside the modal windows.
Media File Types A comma separated list of file types to interpret as media files.
Iframe File Types A comma separated list of file types to always open in iframe mode.
Exclude URLs A comma separated list of (part of) URLs to exclude.
Auto Titles If selected, the title will automatically be set based on the file name. This only applies to media files.
Case Auto Titles Select the way the auto title should be cased.

Options: None, lowercase, UPPERCASE, Uppercase first letter, Titlecase (Uppercase All Words), Smart Titlecase (No Uppercasing of Certain Words)
Lowercase Words A comma separated list of words of which the first word should be lowercase in the auto titles.
Open count based on Select whether to base the open count on the visits on entire website or on specific page (url). The open count is used when using the openOnce, openMin and openMax attributes.

Options: Website (Cookies), Page (Cookies), Website (Session)
Cookie Lifetime The of lifetime of the cookie (in minutes) used to determine the open count. Set to 0 to have no expiration time, the browser cookie will then be kept till the user removes it manually.
Disable on Mobile Select to open links normally (not in modal windows) on narrow screens.
Max Width Mobiles The maximum width in pixels for which to disable Modals.
Disable on Components Select in which frontend components NOT to enable the use of this extension.
Remove in Disabled Components If selected, the plugin syntax will get removed from the component. If not, the original plugins syntax will remain in tact.
Enable in administrator If enabled, the plugin will also work in the administrator side of the website.

Normally you will not need this. And it can cause unwanted effects, like slowing down the administrator and the plugin tags being handled in areas you don't want it.
Add Redirect Script If selected, a redirect script will be added to the modal pages that will make the page reload as a normal page when not opened in a modal window.
Use Media Versioning Select to add the extension version number to the end of media (js/css) urls, to make browsers force load the correct file.
Load jQuery Script You have disabled the jQuery script. Modals needs jQuery to function. Make sure your template or other extensions load the necessary scripts to replace the required functionality.

You have disabled the jQuery script. Modals needs jQuery to function. Make sure your template or other extensions load the necessary scripts to replace the required functionality.

Installation

You can either install Modals by using the core extension manager available in the Joomla! Administrator Control Panel, or by using the powerful Regular Labs Extension Manager.

Note: When updating Modals, you do not need to uninstall it first. The package will update all the files automatically.

Keep in mind that when you update to a major new version (or uninstall first), you might lose some configuration settings.

Regular Labs Extension Manager

It is very easy to install/update any Regular Labs Extension using the Regular Labs Extension Manager.

Please see the Tutorial for the Regular Labs Extension Manager for more detailed information...

Joomla! Extension Manager

To install via the Joomla! Extension Manager, just follow these steps:

  1. Log into your Joomla administrator;
  2. In the menu, choose: Extensions >> Extensions;
  3. Choose the tab: Install from Web (or enable it if you haven't done so yet);
  4. Select the search field and enter Modals and hit enter;
  5. Click on the Modals listing;
  6. Click on Install;
  7. Click on Install to confirm.
Joomla! Installer - Install from Web

Or if you need to install the Pro version or cannot install via the 'Install via Web' method for some reason:

  1. Download the extension install file (.zip);
  2. Log into your Joomla administrator;
  3. In the menu, choose: Extensions >> Extensions;
  4. Choose the tab: Upload Package File;
  5. Click on the Choose File button and select the extension zip;
  6. Click on Upload & Install.
Joomla! Installer - Upload Package File

If you have problems installing Modals, please try the manual installation process as described here: docs.joomla.org/Installing_an_extension