4. For Joomla 1.5 sites, the extension requires Mootools 1.2.4. If you have not already you need to enable the extension named System – Mootools Upgrade. For Joomla 1.6 or greater sites, there is no need to upgrade MooTools.

5. It is also important that the Mootools Upgrade plugin appear in order before the Nice Slide Show extension. And that the numerical order values (located in the center column of the plugin list) reflect the order of the plugins. For example Mootools' order = 1 and Nice Slide Show's order = 2. To change the order number values, simply enter the appropriate numerical value in the order text field and click the small disk icon at the top of the column to submit your changes.

Now, the extension is set and ready to go. Let's add a tag to an article and see it in action. Add the following tag to a new Joomla article and click save. Make sure to replace the image URLs with your own values.

*Important, if you are coping and pasting the example tag to your article, you should paste it into a simple text editor (such as Notepad) first. Then copy it from the text editor to Joomla. This process will clean any hidden HTML code, used for formating, out of the tag. Hidden HTML code can cause the tags to be unrecognizable to the extension and/or cause unexpected results. The best safeguard is to manually type the tag.

After you have placed your tag, take a look at the page on the front end. You should see a nice Mootools slide show looking back at you.

Basic Usage

The most basic way to use the Nice Slide Show extension is to simply provide a list of image urls that you want to use and rely on the default settings that are designated in the plugin's parameters.

It will probably be easiest for you to organize your images into slide show sub-folders on your site. For example, http://yoursite.com/images/slideshows/bmw or
http://yoursite.com/images/slideshows/mercedes. This is purely optional, you may organize your images how ever you like, there are no restrictions imposed by this extension.

After you have assembled the list of images, you can create slide show with a simple tag following this syntax.

Notice how all of the images are separated by the pipe symbol "|". You may add as many image URLs as you like as long as they are separated by a pipe symbol. It is important to point out that it is required to include a leading pipe symbol at the beginning of the list. This leading pipe separates the image list from additional parameters that can be optioanlly specifed at the beginning of the tag. For now, we will leave these parameters unspecified, which automatically invokes the default parameters set in the Plugin Manager.

Syntax
{niceslides:parameters|image URL|image URL|image URL}

It is not desirable to include a trailing pipe symbol at the end of the list. This would result in the extension believing there was a missing image.

A Bit Beyond Basic Usage

Now that you are a little more familiar with the tag syntax, lets take it a step further. For each image that you specify, there are additional parameters you can set. This additional information includes an image title, image byline or description, image hyperlink and hyperlink target window. So, if you want to take advantage of the caption feature or have the slide image link to some page you will need to include some of this additional information. Here is how the syntax works.

Example
{niceslides:|images/mercedes-s.jpg;Mercedes S::A powerful expression of individuality.;http://www.mbusa.com/mercedes/vehicles/class/class-S;_blank|images/mercedes-cl.jpg;Mercedes CL::Exclusive in audience and extraordinary in every way.;http://www.mbusa.com/mercedes/vehicles/class/class-CL;_self}

In the example above the following image related parameters have been specified for two slides:

Slide 1

image URL: images/mercedes-s.jpg

image alt & caption title: Mercedes S

caption byline: A powerful expression of individuality.

slide link: http://www.mbusa.com/mercedes/vehicles/class/class-S

link target window: _blank

Slide 2

image URL: images/mercedes-cl.jpg

image alt & caption title: Mercedes CL

caption byline: Exclusive in audience and extraordinary in every way.

slide link: http://www.mbusa.com/mercedes/vehicles/class/class-CL

link target window: _self

Notice in the syntax, that all extra information (with the exception of the title and byline) are separated by a semi-colon ";" . If you wish to exclude a parameter you may do so by leaving the field empty.

In the example below we will exclude the title an byline. Note the double semi-colon after the image URL.

If you wish to exclude paramters at the end of the tag string, you can simply leave them out entirely. In the below example we will exclude the target window parameter. This will invoke the default value set in the Plugin Manager.

Customizing Individual Slide Shows

We have already learned how to manipulate the tag parameters related to the slide images. Now, in this portion of the documentation will will focus on the the parameters used to control the slide show itself.

To maximize control and flexibility over individual slide shows, we need to set the parameters in each tag, as opposed to relying on the Plugin Manager specified defaults.
Here is an example of the basic slide show parameters.

The above syntax is demonstrates the general parameter order for customized Nice Slide Show tags.

As is the case for the image parameters, the some of the slide show parameters can include additional values. Similar to the image parameters, you can exclude values by leaving them blank. This will invoke the default values set in the Plugin Manager. Similarly, if the value is at the end of a value string, you can leave it out entirely.

In the example above, we have set a custom width, height and duration for this instance of the Nice Slide Show. All width and height parameters are in pixels and durations are set in milliseconds (1000 milliseconds = 1 second). So, in our example we have set the slide show to be 320 pixels wide, 240 pixels high and we have set a 5 second delay between slide transitions.

Notice that we have left the remainder of the slide show parameters out entirely. Default values will be used, since we did not include custom values for these fields. Similarly, we can skip values and use their defaults by leaving them blank. In the example below we will exclude the height parameter and use its default.

Duration

The duration controls the amount of time each slide will be displayed before the slide show transitions to the next slide. The duration is set in milliseconds. 1000 milliseconds equals 1 second. For example 3500 milliseconds is 3.5 seconds.

Only numerical values are allowed in this parameter. There are no additional values to be set.

In addition to turning the controls on and off, there are several other properties that you can set in the tag syntax. These properties include the left & right button graphic URLs and the global width & height of the graphics in pixels. Here is the syntax for setting all values for the navigation control parameters.

Captions

The caption is the title and byline caption that appears at the bottom of the slide. It displays slide specific information to the audience.

You can control whether or not the caption is displayed by entering "true" or "false" into the parameter.

Example
{niceslides:320;240;5000;true;true|images/mercedes-s.jpg;Mercedes S::A powerful expression of individuality.|images/mercedes-cl.jpg;Mercedes CL::Exclusive in audience and extraordinary in every way.}

Please keep in mind that in order for the caption feature to operate properly, you need to set the title::byline values for each image in the slide show. The caption title and byline text are pulled from these values.

In addition to turning the caption feature on and off, there are several other properties that you can set in the tag syntax. These properties include caption opacity, background fill color, title text color and byline text color. Here is the syntax for setting all values for the caption parameters.

The opacity is set in terms of a decimal or float value. 1.0 is equal to 100%, where as 0.5 is the equivalent of 50% opacity.

The color values can be designated as hexadecimal or keyword values. When setting a color as a hexadecimal value you must include the number symbol in the value. For example to designate a black value you would enter "#000000". To designate a black value by keyword you would enter "black".

Notice that the additional values are separated by comas. To exclude a value leave it blank. If the value(s) are at the end of the syntax string you can leave them out entirely.

Sidebar & Table of Contents Menu

The sidebar table of content displays a list of all image titles contained in the slide show. In addition, all listed titles are linked to the slides that they represent. When the viewing audience clicks on a title that appears in the sidebar the slide show will display the correlating image.

You can control whether or not the sidebar is displayed by entering "true" or "false" into the parameter.

Please keep in mind that in order for the sidebar table of contents feature to operate properly, you need to set the title values for each image in the slide show. The sidebar table of contents title list text is pulled from these values.

In addition to turning the table of contents feature on and off, there are several other properties that you can set in the tag syntax. These properties include the sidebar width, background color, background image URL, background image repeat pattern, text color and active text color.

It is important to understand that the sidebar width adds to the total slide show width. For example, if you have specified a slide show width of 320 pixels and a sidebar width of 170 pixels, the total width of the slide show will be 490 pixels. This is an important detail to remember when planning your page layout.

Here is the syntax for setting all values for the sidebar table of contents parameters.

The width value is always set in pixels. Only numerical values are allowed in the width field.

The background color values can be designated as hexadecimal or keyword values. When setting a color as a hexadecimal value you must include the number symbol in the value. For example to designate a black value you would enter "#000000". To designate a black value by keyword you would enter "black".

The background image URL must be a valid URL that points to the location of your background image. In addition, you may enter the word "none" to exclude the usage of a background image.

Thumbnails Menu

The thumbnails menu displays a visual menu of thumbnails at the bottom of the slide show. Each image in the slide show is represented by a smaller copy of itself. When the viewing audience clicks on a thumbnail that appears in the menu the slide show will display the correlating image.

You can control whether or not the thumbnail menu is displayed by entering "true" or "false" into the parameter.

In addition to turning the thumbnails menu feature on and off, there are several other property that you can set in the tag syntax. These options include the thumbnails width & height , margin space between thumbnails, an inactive thumbnails opacity.

It is important to understand that the thumbnails menu height adds to the total slide show height. For example, if you have specified a slide show height of 240 pixels and thumbnail height of of 50 pixels, plus a margin of 1 pixel, the total height of the slide show will be 292 pixels.

If you have your thinking cap on, you might be thinking, "Don't you mean 291px." (240+1+50). Actually, no. The margin is automatically doubled between the slide display and the first row of thumbnails. After which, consecutive rows of thumbnails will be spaced by a single margin height. Provided you have enough images in your slide show to create a second row of thumbnails, the total height will be 343 pixels (240+2+50+1+50).

Here is the syntax for setting all values for the sidebar table of contents parameters.

CSS Suffix Override

The CSS suffix override feature provides a method to manually override the default CSS that is generated by the extension. This feature provides the benefit of allowing developers to customize the CSS for individual slide shows.

It very important to understand that this is an advanced feature and should only be used by individuals who have a firm understanding of CSS and HTML coding.

To override the default CSS with a custom CSS, enter the default CSS suffix

Suffix Example
-mysuffix

CSS example
niceslides-wrap-0-mysuffix

The custom CSS needs to be manually included with the template.

There has to be a unique set of CSS definitions for each slide show per page. For example, if you include 2 slide shows on a page then there has to be 2 complete slide show CSS sets, i.e. niceslides-wrap-0-SUFFIX & niceslides-wrap-1-SUFFIX.

Note the numbering in the example, all numbering starts with 0. The dynamic value replacement used by the extension's internal CSS generator ( i.e. %totalWidth% ) will not take effect with this custom CSS technique.

Tinkering with the Default CSS

The default CSS is exposed in the Plugin Manager for the Nice Slide Show. This was done in order to allow for global customization to all slide shows displayed on a site.

For the most part the CSS found in the Nice Slide Shows plugin parameters is standard CSS. However, the extension does a large amount of auto-dynamic layout adjustments. Many of these dynamic values are reflected in the exposed default CSS as keywords. You will see the keywords represented with a specific syntax.

Syntax
%keyword%

Example
%totalWidth%

When making adjustments to the CSS, you have the option to use the keywords or to override them with a static value of your choosing.

Here is a handy list of all the auto-dynamic keywords used and their correlating values.

Keyword = Value

%count% = slide show count, increments with each slide show displayed per page