Tutorial:

Introduction

Modals is a powerful Joomla! system plugin (that also comes with editor button plugin).

With Modals you can easily create cool modal popups on your site, like this!.
Modal popup windows are fancy popups also known as Lightboxes.

You can make modals / lightboxes for whatever you want: text, articles, other internal pages, external pages, images, videos, and even full-blown Modal Image Galleries & Slideshows with thumbnail creation.

Modals gives you full control over the display of your modal content, with plenty of styling options and customization available at your disposal.

You can create your custom modals with the Modal Tag, automatically convert certain links or images to modal popups, open Menu Items in a modal, automatically generate thumbnail images, and much more. In this tutorial we will go through everything in detail.

Modal Tag

This is how the custom Modal plugin tags syntax works:

You place a starting {modal} tag and a closing {/modal} tag in your content (in an article, module, anywhere you want).

The modal tag supports several attributes and modal types, which we'll see below. Between these plugin tags you can place anything you want to use as a link to open the modal popup.

Example: Click here!

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

The clickable link can be text, or a custom image, or basically anything you want. Anything you place between the modal tags will be used as link to open the modal.

For example, to open a modal via a a custom image, simply have the {modal} tags surround your desired image:

Example:

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

Modals also comes with a handy editor button to help you insert the code you need.

Title & Description

You can add a title to be shown on top of the modal popup, by adding a title attribute to the {modal} tag:

Example: Modal with Title

{modal url="https://goo.gl/5r5faj" title="That's my place!"}Modal with Title{/modal}

You can also place an additional description under the title, with a description attribute:

Example: Modal with Title & Description

{modal url="https://goo.gl/5r5faj" title="That's my place!" description="Here is where I live"}Modal with Title & Description{/modal}

Dimensions

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: 500px 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}

Thanks to the Modals Maximum Width and Maximum Height features (set to 95% by default), every modal window created by Modals will be responsive: if the browser window is smaller or gets resized to dimensions smaller than the ones of the modal window, the modal window will adapt to not exceed the size of the container.

Positioning Pro only

The Pro version of Modals allows you to control the modal's vertical and horizontal positioning instead of the default position of being centered in the viewport.

You can adjust the default behavior via the Modals plugin settings, or individually determine the positioning of each modal tag by using the top, bottom, left, and right attributes. You can also choose to disable the overlay of the modal to make the underlying text still fully visible and accessible.

For example, to position the modal popup in the lower-right corner of the page with a margin of 20px, and with no overlay covering the underlying content:

Example: Modal positioned on bottom right

{modal url="images/fruit/bananas.jpg" bottom="20" right="20" overlay="false"}Modal positioned on bottom right{/modal}

To display the modal in a fixed position within the visitor's viewport (unlike the default absolute positioning relative to the document) you can achieve so by adding a fixed="true" attribute.

Content

Internal URLs

All you have to do to create a link is place the url inside the {modal} opening tag. Place the text 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}

Full Page

By default, Modals will generate internal pages so that only the content (component) part of the page is displayed. So without any side and menu modules.

If you want to load an the page as a full page (including all module positions), just add fullpage="true" to the tag.

Example: Internal full page

{modal url="index.php/123-my-article" fullpage="true"}Internal full page{/modal}

External URLs

Just like with internal urls, simply place the external url in the tag.

Example: External url

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

Please note that you cannot open non-SSL (http) urls inside a SSL (https) website, and you cannot open SSL (https) urls inside a non-SSL (http) website.

Articles

As explained before, you can simply link to a url. So, 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, with 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}

Inline Content Pro only

Using the Modal Tag

For short and simple text content, you can 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}

Using a separate Content Tag

To place entire content blocks inside a modal without the need of creating separate articles/urls, you can use the content attribute in combination with modalcontent tags.

You are completely free to place whatever custom content you want to open inside the modal.

All you need to do is choose an alias for the modalcontent tag and place that alias as value for the content attribute in the modal tag. In this example, our alias will be: mycontent.

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;
}

Example: A lot more inline content

{modalcontent mycontent}
... your fully styled content...
{/modalcontent}

{modal content="mycontent" title="Fully styled inline content"}A lot more inline content{/modal}

Note: The modalcontent tag can be placed anywhere on the page. You can also have multiple modal links opening the same modalcontent content.

Modules Pro only

You can also make a module open in a modal by using the inline Content Tag described above, and then simply embedding the module inside those tags.

You can do so by using the core "Load Modules" plugin:

{modalcontent mymodule}
{loadmodule mod_custom My Module Title}
{/modalcontent}

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

Or you can also use Modules Anywhere to accomplish this:

{modalcontent mymodule}
{module My Module Title}
{/modalcontent}

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

Some modules that rely on scripts and external styles may not work using the inline method. In that case you might need to use the alternative method below:

Via a new article

An alternative way to open a module in a popup window, is to first create a new article and embed the module in that article.

Then, simply link to that new article using Modals.

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

Menu Items

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 class name (works with most menu modules) and set Modals up to convert by that class name.

Media

Images

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

By default Modals will convert the image filename to a Title, and show it on top of the modal popup. But you can of course override it with your custom one:

Example: This is an Image

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

Thumbnail link Pro only

In addition, the Pro version of Modals provides you with the ability to display a thumbnail as clickable link to the image modal.

You can do so by using the image attribute and without placing any text between the {modal} tags, like:

Example: Totally bananas

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

By default, the dimensions of the automatically created thumbnail will be based on your default settings. However, you can also individually customize the width and height of the thumbnail for each specific image modal, by using the thumbnail-width and thumbnail-height attributes:

Example: Bananas

{modal image="images/fruit/bananas.jpg" thumbnail-width="100" thumbnail-height="100"}{/modal}

Galleries & Slideshows Pro only

The Pro version of Modals also allows you to a create and open a full-blown images gallery with arrow navigation.

You can achieve this by simply using a single modal tag with a gallery attribute holding the folder that contains your images.

Example: Apples

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

By default, *all* the images found in the specified folder will be displayed in the modal gallery in alphabetical order, and the first image found will be shown in the content as a thumbnail. But you have several options to control the displayed images and thumbnails.

Limit/Order Images

If you only want certain images from the folder to show in the modal gallery, you can define them by using the images attribute.

Range of images

You can show a range of images by specifying the number of the first and last image you want to show. For example, to show only the first three:

Example: Apples

{modal gallery="images/gallery" images="1-3"}{/modal}

Specific images

To show a selection of specific images only, simply list them separated by a comma. The modal gallery will also keep the order in which you list the images:

Example: Bananas

{modal gallery="images/gallery" images="bananas.jpg,strawberries.jpg,apples.jpg"}{/modal}

Random order

You can decide to show all images from the folder with a random order instead of alphabetical. This will also make thumbnails show in random order:

Example: Strawberries

{modal gallery="images/gallery" images="random"}{/modal}
Advanced Filtering

For a more advanced control over the images shown, you can use the filter attribute, which allows you to filter images by matching part of the filenames.

This example only shows images from folder images/gallery that contain "berries":

Example: Blueberries Strawberries

{modal gallery="images/gallery" filter="berries" thumbnails="all"}{/modal}

The Filter attribute supports Regular Expressions. For example, to only show images from folder images/staff that start with 'team-accountancy-' or 'team-finance-':

{modal gallery="images/staff" filter="^team-(accountancy|finance)-"}{/modal}

For more info on Regular Expressions: http://www.regular-expressions.info/reference.html

Thumbnails

Modals, by default, will automatically create and display thumbnail images as clickable links to the gallery.

To control number of displayed thumbnails, you can add a thumbnails attribute. Note that if you limited the images output by the gallery with the images or filter attributes, you will of course only be able to display thumbnails from that selection of images.

All thumbnails

To have thumbnails for all images included in the gallery in alphabetical order:

Example: Apples Bananas Blueberries Limes Oranges Strawberries

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

You can also make all thumbnails show by default in all your modal galleries by enabling the "Show All Gallery Thumbnails" setting.

Range of thumbnails

To show only a certain amount of thumbnails, simply specify the number. For example, to show the first 3 thumbnails:

Example: Apples Bananas Blueberries

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

You can also have a range of thumbnails not starting from the start, by specifying the number of the first and last image you want to show. For example, to show from the 2nd to the 5th thumbnail:

Example: Bananas Blueberries Limes Oranges

{modal gallery="images/gallery" thumbnails="2-5"}{/modal}

Specific thumbnails

To have a specific image as a thumbnail, you can simply specify the desired image name:

Example: Strawberries

{modal gallery="images/gallery" thumbnails="strawberries.jpg"}{/modal}

Or for multple images, a comma separated list of image names or thumbnail numbers:

Example: Apples Strawberries

{modal gallery="images/gallery" thumbnails="apples.jpg,strawberries.jpg"}{/modal}

Example: Apples Blueberries Oranges

{modal gallery="images/gallery" thumbnails="1,3,5"}{/modal}

Random thumbnail

To have a random image as a thumbnail:

Example: Oranges

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

All thumbnails in random order

You can show all thumbnails in a random order by combining the thumbnails attribute with the images attribute.

Example: Apples Bananas Oranges Blueberries Strawberries Limes

{modal gallery="images/gallery" images="random" thumbnails="all"}{/modal}
Thumbnail dimensions

By default, the dimensions of the automatically created thumbnails will be based on your default settings. However, you can individually customize the width and height of the thumbnails for each specific gallery modal, by using the thumbnail-width and thumbnail-height attributes.

You don't need to specify both width and height attributes - you can also just specify one, and all thumbnails will be created maintaining its aspect ratio.

Example: Apples

{modal gallery="images/gallery" thumbnail-height="100"}{/modal}


When you specify both width and height attributes, all thumbnails will be created with the exact width and height, meaning that if proportions are different, the image will be cropped to fill the specified dimensions.

Example: Apples

{modal gallery="images/gallery" thumbnail-width="100" thumbnail-height="100"}{/modal}
Custom link (no thumbnail)

If you place anything between the modal tags, that content will be used as a link to open the gallery instead of a thumbnail. This can be text, or a custom image, or basically anything you want.

Example: Click here

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

Start on different image

By default, when opening the gallery via a text link (no thumbnail), it will start on the first image found in the gallery in alphabetical order.

If you want the gallery to start on a different image instead of the first image, add a first attribute to specify the desired image:

Example: Click here

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


To start on a random image, set the first attribute to random:

Example: Click here

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

Slideshow

To make the gallery act like a slideshow that cycles through the images automatically, simply add slideshow="true" to the modal tag.

Example: Apples

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

The Slideshow Speed can be set in the Modals plugin settings.

Images from different folders

What if you want to create a gallery modal but your images are not all in the same folder? You can do this as well, thanks to the "Grouping" feature that allows you to group multiple modals.

To create a gallery with your own specific images, create a modal tag for every image and then group the modals together by adding a group attribute to all modal tags.

Example: Bananas X Limes X Strawberries X

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


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

Example: Bananas X Limes X Strawberries X

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

Titles & Descriptions

By default Modals will convert the image filenames to Titles, and show them on top of the modal popup for each image.

But you can override image titles with your custom ones, as well as additional descriptions that will display under the title, by placing a data.txt file in the same folder where images reside. You can also specifiy additional information such as alternate text or different attributes specific for the thumbnail images.

Here is an example of a data.txt file showing you the different possibilities:

title_apples=My special title for Apples image
description_apples=Description specific for Apples image
alt_apples=Separate alternate text for Apples image
thumbnail_title_apples=The title of the thumbnail for Apples image
thumbnail_alt_apples=The alternate text of the thumbnail for Apples image

description=Base description that will show for all other images in the gallery

Thumbnail System Pro only

The Pro version of Modals comes packed with the ability to automatically create thumbnail images, used as clickable links to open modal popups for Image Modals, Galleries & Slideshows and Auto-Converted Images (all Pro features).

The "Create Thumbnails" feature is enabled by default. If you disable it (via the Modals plugin settings) Modals will fallback to displaying the large original image as clickable link to open the modal, unless you manually create a custom thumbnail for that image yourself (see below).

Automatically generated thumbnails

In the Modal plugin settings you can customize the default width and height that Modals will use to create thumbnails (default is set to 80x60), set the quality of the thumbnails, select the filetypes to create thumbnails of (gif, jpg, png), and decide whether you want the thumbnail images to be cropped or not.

With the "Crop" option enabled, all thumbnails will be created with the exact width and height, meaning that if proportions are different, the image will be cropped to fill the specified dimensions. With the option disabled, the thumbnails will be created to the maximum width or height, maintaing its aspect ratio.

As we've seen previously, you can also individually override/customize the width and height for the thumbnails in each specific image modal or gallery modal tag, by using the thumbnail-width and thumbnail-height attributes.

All thumbnails are stored inside a subfolder of the location containing your original image, with the same filename of the original image appendend by the dimensions. By default, the folder name is resized (so the thumbnail for image gallery/apples.jpg would be gallery/resized/apples_80x60.jpg), but you can customize the folder however you want.

Note that thumbnails will only be created for internal images hosted on your website. Thumbnails will not be generated for external images, which will be used regardless of the settings.

Custom thumbnails

As mentioned, thumbnails will be automatically generated based on the original image. But you also have the ability to manually create your own custom thumbnails.

Obviously, you can individually overwrite an automatically generated thumbnail of a specific size with a custom one by simply replacing that file.

Thumbnail base

Even cooler, you can upload your own special image that Modals will use (instead of the original) as a base to create all thumbnails of the various possible sizes. This can be useful for example if you want all thumbnails for your image be in grayscale, or zoomed-in on a particular area, or in any way different from the original image.

You can do so by inserting your custom image in the thumbnails folder, with the same filename of the original image (with no dimensions appended to the filename). For example, your custom thumbnail for gallery/apples.jpg would be gallery/resized/apples.jpg.

Manual thumbnails

If you turn off the "Create Thumbnails" feature, thumbnails will not be automatically created, but you can manually upload your custom thumbnail, which will be displayed with the dimensions you uploaded it with (it will not be resized).

To do so, the path and name of your custom thumbnail file for gallery/apples.jpg would be gallery/resized/apples.jpg.

Legacy Suffix Support

Older versions of Modals used a fixed suffix (by default: _t) to identify and store thumbnail images, instead of storing them in a subfolder.

In the Modal plugin settings you can enable support for this previous naming method. With this option turned on, Modals will first look for thumbnails stored with a suffix (for example the thumbnail for image gallery/apples.jpg would be gallery/apples_t.jpg) before looking for thumbnails stored in the specified subfolder.

Note: This option will be automatically set to on by default when updating from older versions, while it will be set to off for new installs.

Videos

Example: Youtube video

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

Example: Vimeo video

{modal url="https://player.vimeo.com/video/163836607" width="500" height="281" title="Modals Tutorial"}This is a 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!"}This is a Youtube video{/modal}

Example: Vimeo video

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

Please note that you can only use this feature if your website is running in SSL (https) mode.

Grouping Pro only

You can group different types of modals by adding a group attribute to multiple modal tags.

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?option=com_content&view=article&id=123" 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 image="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 a default time of 5 seconds, 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 off the "Enable Countdown Bar" setting in the Modals plugin settings.

Open 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 modal link in the content of your page, then simply don't place any text between the {modal} tags, like:

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

The syntax for the 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}

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}

Show only once

To make a modal popup only show once, you can instead use the attribute 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 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 plugin settings. You can also choose to base the count on the site wide session count instead.

Auto-Convert

In addition to manually creating modals with modal plugin tags, Modals also allows you to automatically open certain links or images in modal popups, thanks to the "Auto-Convert" options in the Modals plugin settings.

The Free version of Modals only supports converting links by class names. All the other options below are features exclusive to the Pro version.

Links

Class names

By enabling this option, all links with one of the given class names will be converted to modal popups.

The default class name that will be auto-converted is modal, but you can change that and give a comma-separated list of class names which Modals should handle and convert to modal popups.

Example: Link automatically converted

<a href="/index.php/123-my-article" class="modal">Link automatically converted</a>

External Links Pro only

By enabling this option, all links to external sites will be converted to modal popups.

Example: Link automatically converted

<a href="https://goo.gl/5r5faj">Link automatically converted</a>

Target Blank Pro only

By enabling this option, all links that are set to open in a new window (with a target="_blank" attribute), will be opened in a modal popup instead.

Example: Link automatically converted

<a href="/index.php/123-my-article" target="_blank">Link automatically converted</a>

Filetypes Pro only

By enabling this option, all links to files that match one of the given filetypes will be converted to modal popups.

You can give a comma-separated list of filetypes which Modals should handle and convert to modal popups.

URL matches Pro only

By enabling this option, all links that match certain URLs will be converted to modal popups.

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.

Use a new line for each different match. For even more control, you can also create URL matching rules using Regular Expressions.

Images Pro only

With the Pro version of Modals you can also automatically convert certain images to modal popups, by simply giving one of your specified class names to the img tag.

The default class name that will be auto-converted is modal, but you can change that in the Modals plugin settings and give a comma-separated list of class names which Modals should handle and convert to modal popups.

When auto-converting an image to a modal popup, Modals will display a thumbnail as clickable link to the image modal.

Thumbnail dimensions

By default, the dimensions of the automatically created thumbnail will be based on your default settings. However, you can also individually customize the width and height of the thumbnail for each specific image, by using the width and height attributes in the img tag:

Example: Bananas

<img src="/images/fruit/bananas.jpg" class="modal" width="100" height="100" />

Note: Modals will also check if the image you placed in the content is already a thumbnail of an image, instead of the actual image. If so, Modals will still work as expected and will ouput the same result, with the thumbnail shown in the content (as clickable) and the large original image shown in the modal popup.

Title & Description

By default Modals will convert the image filename to a Title, and show it on top of the modal popup.

But you can override the image title with your custom one, as well as an additional description that will display under the title, by using the data-modal-title and data-modal-description attributes in the img tag.

Example: Bananas

<img src="/images/fruit/bananas.jpg" class="modal" data-modal-title="My title for Bananas image" data-modal-description="Description for Bananas image" />

You can also make Modals use title or alt attributes as a Modal Title & Description, if you enable those options in the Modals plugin settings.

Javascript Events Pro only

There are different events during the opening and closing of modals on which you can attach javascript actions.
So if you need to trigger some custom javascript function or something in a 3rd party plugin, you can do that.

The available events are:

  • onOpen Event that fires right before the modal begins to open.
  • onLoad Event that fires right before attempting to load the target content.
  • onComplete Event that fires right after loaded content is displayed.
  • onCleanup Event that fires at the start of the close process.
  • onClosed Event that fires once the modal is closed.

Example: Alert when opening

{modal article="My Article" onOpen="alert('The modal is opening!');"}Alert when opening{/modal}

Example: Alert when closed

{modal article="My Article" onClosed="alert('The modal just closed!');"}Alert when closed{/modal}

Example: See the browsers console

{modal article="My Article" onOpen="console.log('onOpen');" onLoad="console.log('onLoad');" onComplete="console.log('onComplete');" onCleanup="console.log('onCleanup');" onClosed="console.log('onClosed');"}See the browsers console{/modal}

Editor Button

You can enter the {modal} tags directly into your content. However, to save time typing and remembering what the exact syntax is, Modals also comes with a handy editor button.

You can use this editor button (located below the text input area) to place a {modal} tag with the desired attributes into your article (or other editor fields).

You can customize the default tag settings in the Modals plugin settings.

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
Transition The transition type. Can be set to "elastic"or "none".
Speed Sets the speed of the transitions, in milliseconds. Default: 300
Return Focus If selected, focus will be returned when the modal exits to the element it was launched from.
Fast Iframe If deselected, the loading graphic removal and onComplete event will be delayed until iframe's content has completely loaded.
Enable Overlay If selected, an overlay will cover the rest of the website, behind the modal.
Overlay Opacity The overlay opacity level. Range: 0 to 1. Default: 0.8.
Overlay Close If selected, enables closing the modal by clicking on the background overlay.
Close Button If selected, enables the close button.
Enable Countdown Bar If selected, there will be a countdown bar at the top of the modal when using the autoclose feature.
Enable ESC Key If selected, enables closing the modal on 'esc' key press.
Enable Arrow Keys If selected, enables 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%). Leave empty to attempt auto-sizing.
Height Set the fixed dimension. In pixels (ie 500) or percentage (ie 80%). Leave empty to attempt auto-sizing.
Width External Pages Set the fixed dimension for external URLs. In pixels (ie 500) or percentage (ie 80%).
Height External Pages Set the fixed dimension for external URLs. In pixels (ie 500) or percentage (ie 80%).
Initial Width Set the initial dimension, prior to any content being loaded. In pixels (ie 500) or percentage (ie 80%). Default: 600.
Initial Height Set the initial dimension, prior to any content being loaded. In pixels (ie 500) or percentage (ie 80%). Default: 450.
Maximum Width Set the maximum dimension for loaded content. In pixels (ie 500) or percentage (ie 80%). Set to 0 for no maximum. Default: 95%.
Maximum Height Set the maximum dimension for loaded content. In pixels (ie 500) or percentage (ie 80%). Set to 0 for no maximum. Default: 95%.
Auto-Correct Resize If selected, the modal popup will do an extra resize after the content in the modal is loaded. This will fix sizing issues with certain types of content.
Auto-Resizing Delay (ms) The Delay (in milliseconds) after which the modal should do the auto-correct resize. Increase this value if you have (slower) scripts causing changes in the modal content dimentions.

Positioning Pro only

Fixed If selected, 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 Repositions the modal if the window's resize event is fired.
Top Controls the modal's vertical positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%").
Bottom Controls the modal's vertical positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%").
Left Controls the modal's horizontal positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%").
Right Controls the modal's horizontal positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%").

Media

Images

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.
Default: a,the,to,at,in,with,and,but,or
Scale Images If selected, and if maxWidth, maxHeight, width or height have been defined, the modal will scale images to fit within the those values.
Retina Image If selected, the modal will scale down the current photo to match the screen's pixel ratio
Retina URL If selected and the device has a high resolution display, the modal will replace the current photo's file extension with the Retina Suffix + extension
Retina Suffix When "retinaUrl" is set to yes:
If the device has a high resolution display, the href value will have it's extension extended with this suffix. For example, the default value would change my-photo.jpg to

Thumbnails Pro only

Create Thumbnails If selected, thumbnails will be automatically created for images if they do not exist yet. The thumbnails will be created using below settings.
Crop Select to make the resized image crop the original image.
If selected, the resized image will always have the set width and height.
If not selected, the resized image will be resized to the maximum width or height maintaining its aspect ratio.
Set When "Crop" is set to no:
Select whether to resize images using the maximum width or height. The other dimension will be calculated based on the aspect ratio of the original image.
Width Set the width of the resized image in pixels.
Height Set the height of the resized image in pixels.
Only on Filetypes Select the filetypes to do resizing on.
Options: GIF, JPG, PNG
JPG Quality The quality of the resized images. Choose from Low, Medium or High. The higher the quality, the larger the resulting files. This only affects jpeg images.
Options: Low, Medium, High
Folder The folder containing the resized images. This will be a subfolder of the folder containing your original images. Default: resized.
Legacy Suffix Support Switch on to let Modals use images with the defined suffix as the thumbnail.
Thumbnail Suffix When "Thumbnail Suffix" is set to yes:
Set the suffix used for the thumbnail images.

Galleries Pro only

Show All Gallery Thumbnails If selected, all thumbnails in the given gallery folder will be automatically shown.
Image Separator Set the separator html for the images in the gallery. By default this is a space. Enter {none} to have no spacing between images.
File Filter The filter (Regular Expression) used to find the image files in the given gallery folder.

Groups / Slideshows Pro only

Auto Group Select to automatically group certain filetypes to create series / galleries.
URL/File Filter When "Auto Group" is set to yes:
The filter (Regular Expression) used to define which URLs/file types to group automatically.
Preloading If selected, the 'Next' and 'Previous' content in a group will get preloaded after the current content has finished loading.
Loop If selected, enables the ability to loop back to the beginning of the group when on the last element.
Slideshow If selected, adds an automatic slideshow to a content group / gallery.
Slideshow Speed Sets the speed of the slideshow, in milliseconds.
Slideshow Auto If selected, the slideshow will automatically start to play.

Auto-Convert

Class names

Auto-Convert If selected, all links with one of the given class names will be converted to modal popups.
Class names A comma separated list of class names. Links that have any of the defined class names will be converted to modal popups. Default: modal

External Links Pro only

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

Target Blank Pro only

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

Filetypes Pro only

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

URL matches Pro only

Auto-Convert If selected, all links that match the URL selection will be converted to modal popups.
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

Auto-Convert If selected, all images with one of the given class names will be converted to modal popups.
Class names A comma separated list of class names. Images that have any of the defined class names will be converted to a modal popup gallery. Default: modal
Use Title Attribute Select to use the title attribute in the image tag as the title or description of the modal popup.
Use Alt Attribute Select to use the alt attribute in the image tag as the title or description of the modal popup.

Editor Button Options

Button Text This text will be shown in the Editor Button.
Default: "Modal"
Enable in frontend If enabled, it will also be available in the frontend.

Tag Syntax

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.
Default: modal
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.
Default: modalcontent
Tag Characters The surrounding characters of the tag syntax.
Note: If you change this, all existing tags will not work anymore.
Options: {...}, [...], {{...}}, [[...]], [:...:], [%...%]

Advanced

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.
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.
Cookie ID Option to set a unique cookie ID for the open count
Disable Background Scrolling Select to disable the main window from scrolling along when the modal is opened.
Disable on Mobile Select to open links normally (not in modal windows) on narrow screens.
Disable Pageload Popups on Mobile Select to disable modal popups entirely for modals set to open on pageload.
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 system plugins syntax will remain intact.
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.
Place HTML comments By default HTML comments are placed around the output of this extension. These comments can help you troubleshoot when you don't get the output you expect. If you prefer to not have these comments in your HTML output, turn this option off.
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 Select to load the core jQuery script. You can disable this if you experience conflicts if your template or other extensions load their own version of jQuery.
FAQs:

The {modal} tags are not being converted

The Modals plugin is not published

Check if the Modals plugin is published. Go to Extensions >> Plugin manager and search for the system plugin System - Regular Labs - Modals. Then publish it.

There is markup on the {modal} tags

If you have copy/pasted code directly into your editor, you might also have copied along hidden HTML tags. So this will also cause the {modal} tags to break:

{<span>modal</span> ...}

Remove the extra styling or other html tags around and in the {modal} tags that might cause problems.

The modal redirects to a white page with an email address

This is caused by the Joomla core "Content - Email Cloaking" plugin.

I recommend you use Email Protector instead, or disable the core plugin.

The modal does not have the correct styling

Modals uses the sub-template modal by default (which you can change in the Modals plugin settings).

This means that Modals will tell Joomla to show the page using the modal template view.
Joomla will look in your templates folder for a modal.php file, and if there is none, it will use the modal.php file from the system template.

If you want to customize this sub-template, you can copy that modal.php file to your templates folder, or copy your templates component.php (if available) and name it to modal.php.
Then you can change it to how you want, like adding stylesheets.

The page in the modal window won't load

This could have a few reasons:

  • The url is not correct. Double check if the url loads the page when placed directly in your browser.
  • You are linking to an external site which doesn't allow you to open it inside your site. Some (usually larger) sites have a protection script which prevents it from being opened inside iframes in other sites. Sites like Google, Youtube, Facebook. See if they offer an 'embed' url for the page you are trying to link to.
  • You are trying to open a non-SSL url in an SSL site. If you are running your page in HTTPS mode (SSL), you cannot open any HTTP (non-SSL) pages with Modals. This is a protection on browser level.
Free vs Pro:

Create modals anywhere::Modals gives you the power to create modal popups anywhere you can enter text. So also in modules.
Different modal styles::You have to possibility to choose from different modal styles. You can choose the one that best fits your websites style.
URL modals::Open any article, internal page, or external URL in a modal popup
Image & Video modals::Make your images, videos and other media urls popup in a modal window.
Create Modals by
Modal tag::Use a quick and easy modal tag anywhere in your content to create modal popups. You can even use these to convert your Menu Items to modal popups (with most menu modules).
Class name::Give existing links a user-defined class name and Modals will create a modal popup from it.

Galleries & Slideshows::Create complete image galleries with just 1 tag, with thumbnail creation and even slideshow functionality.
Inline Content::Create modal popups with text that is directly in your content. You do not need to create separate articles/urls. This is especially useful for short pieces of text or even to embed Modules.
Auto-Images::Automatically open existing images in modals simply by adding a class name to the img tag.
Quick links::Easily create modal popups for articles with the article attribute, thumbnailed images with the image attribute, and videos with youtube / vimeo attributes.
Open on pageload::Make splash page modal popups that will show when you first load the page, or with a delay.
Auto-close::Make a modal close after a given amount of seconds.
Positioning::Control the modal's vertical and horizontal positioning.
Group Modals::Group multiple modal popups (via the modal tag) on your page, so you can use the modal navigation to go to the next/previous modal.
Create Modals by
Modal tag::Use a quick and easy modal tag anywhere in your content to create modal popups. You can even use these to convert your Menu Items to modal popups (with most menu modules).
Class name::Give existing links a user-defined class name and Modals will create a modal popup from it.
External Links::Let Modals open all external links in modal popups.
Target blank::Let Modals convert all links with a target=_blank to modal popups.
Filetypes::Want to make all pdf files open in modal popups? No problem with Modals. Or any other file types for that matter.
URL matches::Specify certain urls to always open in modals. You can also use the powerful Regular Expressions to define urls.

Examples:

You can find a multitude of examples on the dedicated Modals Demo Page.

Visit the Demo Page >>>

Modals is a powerful plugin that allows you to easily create cool modal popups on your site, like this!.

Modal popup windows are fancy popups also known as Lightboxes.

You can make modals / lightboxes for whatever you want: text, articles, other internal pages, external pages, images, videos, and even full-blown Modal Image Galleries & Slideshows with thumbnail creation.

Full control

Modals is packed with options to control the modal popups:

  • Full control over styling (via styling options and CSS)
  • Define dimensions
  • Create image popups quickly and easily
  • Make modal image galleries and slideshows automatically Pro only
  • Make popups open on pageload, or with a delay Pro only
  • Open Menu Items in modals
  • And much more...

How to use it:

With Modals you can create your custom modals, and you can also automatically convert certain links or images to modal popups.

Here are all the ways you can activate Modals:

  • Via the special Modal tags {modal ...}...{/modal}
  • By class names (all links with defined class names)
  • All external links Pro only
  • By target="_blank" (all links with a target. Internal and/or external) Pro only
  • By filetypes (all links to given filetypes) Pro only
  • By url matches (also supports regular expressions) Pro only

Modals also comes with a handy editor button to help you insert the code you need.

See the full documentation to find out more!

Colorbox

Modals utilizes the fabulous modal script Colorbox by Jack Moore. Kudos to him!