Image carousels are often the first thing people see when they visit sites.
Carousels provide an interactive way of cycling through visual elements and are
an effective means of communicating information to users. AlloyUI’s
aui-carousel
module makes it very easy to get an image carousel up and running
in no time flat.
Here is an example of a Carousel being used in a portlet:
Figure 1: Image carousels can be a very handy tool to communicate information to users. Here is an example of the carousel in a portlet.
Now that you can see the appeal of adding a carousel to your design, it’s time to get down to business!
In order to get the carousel running in a portlet you have to do a few things:
- Step 1: Add Images to Your Portlet for Displaying in Your Carousel
- Step 2: Add a Carousel to Your View JSP
- Step 3: Write CSS Code to Configure Your Carousel and to Map Images to the Carousel
Walk through each of these steps to get a carousel up and running in your portlet.
Step 1: Add Images to Your Portlet for Displaying in Your Carousel
Create a location in your portlet to store your carousel’s images and then copy
the images into that folder. For example, you could create a folder named img
in your portlet’s docroot
folder and then put your image files in it.
Step 2: Add a Carousel to Your View JSP
-
Open your view JSP. Create one if you don’t already have one in your portlet.
-
Add a directive to reference the
aui
taglib:<%@ taglib prefix="aui" uri="http://liferay.com/tld/aui" %>
-
Add a
<div>
element to reference all of the images that you want to include in your carousel. Within this<div>
, nest a<div>
for each of the carousel images. Make sure to assign a unique ID to the outer<div>
element and each of the nested<div>
elements.For example, the following HTML specifies an
<div>
named myCarousel that holds references to an images named image1 and image2:<div id="myCarousel"> <div id="image1"></div> <div id="image2"></div> </div>
-
To create a Carousel in which to display your images, you first add
<aui:script>...</aui:script>
tags at the bottom of your JSP. Within those tags, add code that instantiates the Carousel, passing a reference to the outer<div>
as the value for Carousel’scontentBox
element.For example, the following code creates a Carousel for a
<div>
named myCarousel:<aui:script> AUI().use( 'aui-carousel', function(Y) { new Y.Carousel( { contentBox: '#myCarousel', height: 250, width: 700 } ).render(); } ); </aui:script>
To create the Carousel, you get the
AUI
object to use theaui-carousel
module to create a Carousel component. You specify values for the new Carousel’scontentBox
,height
, andwidth
attributes.The Carousel that AlloyUI creates automatically adjusts to the number of images in the
contentBox
element, letting you add as many as images as you like. -
Save the JSP file.
If you were to deploy your JSP’s changes right now, however, no images would be displayed. This is because the display of the carousel’s items is not configured and the carousel has no reference to the image files. Don’t worry; you can use CSS to configure the items and map the image files to your JSP. The next step shows you how to take care of these requirements.
Step 3: Write CSS Code to Configure Your Carousel and to Map Images to the Carousel
This step’s instructions demonstrate using CSS to configure the carousel’s items.
-
Create a
main.css
file in your portlet’s/docroot/css/
folder, if it does not exist. Then, open themain.css
file. -
Specify the dimensions and opacity to use for each carousel item’s
div
. The following example CSS specifies basic width, height, and opacity information for the divs using a class namedcarousel-item
. As you use classes, make sure to keep the class names consistent between your JSP and themain.css
file.div.carousel-item { width: 700px; height: 250px; opacity: 100; }
If you wish, you can add more styling to the carousel items via the
div.carousel-item
class. -
Select the ID of each of your JSP’s image
<div>
elements and apply a background image to each one.For example, if you have
<div>
elements with IDs image1 and image2, then you could map them to their respective image source files with code that looks like this:#image1 { background-image: url("../img/YourImageFile1.jpg"); } #image2 { background-image: url("../img/YourImageFile2.jpg"); }
Of course, you can style each image
<div>
here as well. -
Save the CSS file.
Now that you’ve written code to display your carousel, you can deploy your
plugin and see your images in the carousel. Give yourself a pat on the back.
You’ve just successfully used the aui-carousel
in your portlet!