UPDATE: Since the posting of this article there has been dramatic improvements by the community and now this is no longer the best way to implement this feature. We now use the "Views Slideshow," found at: http://drupal.org/project/views_slideshow. We have used this method to create the various slideshows for the City of South Bend at www.SouthBendOn.com.

---

One of the more common design elements of modern webpage design is a large content area on the landing page of a website. Though there are some Drupal 7 themes that have this feature already (Marinelli comes to mind), what if you want to use a different base theme (like Zen)? In this How-To I will discuss how to create a simple slideshow that can be used in any theme.

The first thing that needs to be done is to ensure that your Drupal 7 environment is set up to support the slideshow. The following Drupal 7 modules need to be installed:

• Chaos Tools (http://drupal.org/project/ctools)
• Views (http://drupal.org/project/views)

The WYSIWYG module (http://drupal.org/project/wysiwyg) also can be installed to make editing the content easier, but it is not necessary.

Theme ".info" and supporting files

In order to incorporate the slideshow into your theme you will need to reference some external resources in your theme.info file. You will need to add a stylesheet that defines the UI and the JavaScript libraries necessary to make it work. First obtain the following jQuery libraries and place them in the "js" directory of your theme (or other directory that holds the themes external JavaScript files):

• jquery.cycle.all.min.js
• jquery.easing.1.3.js

Once you have those files where they need to be, then create a new JavaScript file in the "js" directory. For the purpose of this article, we will name it utility.js. In that file place the following code:

jQuery(document).ready(function() {
jQuery('.slides').cycle({
fx: 'fade',
   speed:       500, 
            timeout:     6000, 
            pager:      '.slidenav', 
   pagerEvent: 'click', 
   pauseOnPagerHover: true,
pause:true
})
});

Once those files have been placed where they need to go, add the following to your themes ".info" file (assuming the files are in the "js" directory):

scripts[] = js/jquery.cycle.all.min.js
scripts[] = js/jquery.easing.1.3.js
scripts[] = js/utility.js

Now that you have the necessary JavaScript linked, you need to define the visual appearance and structure of the slideshow. The following is in the file slides.css that is located in my theme's css directory.

@charset "UTF-8";
/* CSS Document */

.slideshow-container {
height: 340px;
}

.slides {
width: 970px;
height: 340px;
overflow: hidden;
position: absolute;
background: white;
}

.slides .slide {
height: 340px;
}

.sdw-l, .sdw-r {
background-repeat: no-repeat;
width: 30px;
height: 485px;
position: absolute;
z-index: 99;
}

.sdw-r {
background-image: url(../images/sdw-r.png);
margin: -155px 0 0 978px;
}

.sdw-l {
background-image: url(../images/sdw-l.png);
margin: -155px 0 0 -30px;
}

.slides .slide .text {
float: left;
width: 450px;
padding: 10px 15px;
}

.slides .slide .text p {
line-height: 1.5em;
}

.slides .slide .text p a {
color: #4a64aa;
text-decoration: none;
}

.slides .slide .text p a:hover {
text-decoration: underline;
}

.slides .slide .photo {
overflow: hidden;
width: 480px;
height: 280px;
text-align: center;
vertical-align: middle;
float: right;
}

.slides .slide .photo img {
margin: 20px auto;
}

.slideshow-container .slidenav {
position: relative;
margin: 280px 55px 0 0;
z-index: 100;
float: right;
}

.slideshow-container .slidenav a {
display: block;
height: 30px;
width: 30px;
text-align: center;
margin: 0 8px;
float: left;
background-color: #e5e2df;
color: #a1988c;
text-decoration: none;
line-height: 30px;
}

.slideshow-container .slidenav a:hover {
background-color: #4a64aa;
color: white;
}

.slideshow-container .slidenav a.activeSlide {
color: #4a64aa;
}

.slideshow-container .slidenav a.activeSlide:hover {
color: white;
}

Of course the colors and other design related items will be changed to match the visual look and feel of the theme that you are creating. Once the CSS file is created and in the necessary directory, the theme needs to be informed of its existence. Simply add the following line to your themes ".info" file.

stylesheets[all][]        = css/slides.css

One last item needs to be added to the themes ".info" file. The region needs to be defined for the location of the slideshow. I have created a region named "slideshow". To add this add the following in the regions section of the .info file.

regions[slideshow]      = Slideshow

The final structural item that needs to be modified is the page.tpl.php template file. The template needs to be modified to render the slideshow content. Below is a snippet of the template that is necessary. Notice that the only thing necessary to display the slideshow contents in the  print render... call for the slideshow region.

Slide Show Content type

Once the structural elements are taken care of now you need to create a "Slide Show Content" content type so that the items can be easily added.

1. In the "Content Types" section of the Drupal administrative interface create the type. In this type a 3 fields:
   • Title
   • Body Text
   • Slide Image
2. In the "Manage Display" tab move both "Body Text" and "Slide Image" to be hidden. Also, the comments for this content type should be disabled.
3. Once you have the content type, you can create a new slide using the "Add Content" links and populating the form fields.

Creating the Slideshow View

Much of the power of this approach comes from the View module. In order to correctly gather the slides that are to be displayed and then render them on the properly a new view needs to be created. In the administrative interface select Structure->Views and create a new view. I named mine "Front Page Slide Show Content". Do the following to create the view block:

1. Create a "Block" display for the view
2. Under Format, select "Unformatted list"
3. Under Format -> Settings, select "None" for the Grouping Field, and enter "slide" for the Row Class
4. Under Show->Settings check all "Content: Title", "Content: Body", and "Content: Slide Image" as inline fields
5. In order for the correct XHTML to be generated the output of the fields needs to be added and then modified. User the Views admin UI to add the Title, Body, and Slide Image fields within the "FIELDS" section. Once you have done so make the following changes to the fields.
   • Content: Title=> Under "Rewrite Results," check the "Rewrite the output" box and use the following in the text:

     [title]
     Content: Body=>Under "Rewrite Results," check the "Rewrite the output" box and use the following in the text:
     
     [body]

   • Content: Slide Image=>Under "Style Settings," check the box for "Wrap field in HTML," choose "DIV" for the HTML element. Check the "Create a CSS class" box and enter "photo" for the CSS class.
6. Add "Content: Type = Slide Show Conent" to the View's filter criteria.
7. Under Block Name enter a name that you will reference when you add the block to the page's structure
8. Save the view

View Block Template File

Now that we have the view and the content type for the slideshow, we need to make sure that the block will render properly within the page. To do that I have a custom template file for this view's block. For this article the name of this file is views-view--slide-show-content.tpl.php. Below is the contents of the file:

Adding the Slideshow and wrapping up

The final step is adding the block to the page design. To do that, go to the Structure->Blocks section of the Administrative interface. From there add the View Block that you just created to the "Slideshow" region that you defined earlier. Now once you refresh your cache and look at your page you will see the slideshow.

We at Force 5 are always looking for ways to improve, so I welcome any comments or suggestions that you might have. Since Drupal 7 is so new and there is little documentation on many of the features I look forward to hearing the community's voice for suggestions. If you would like to hear more about Force 5 Drupal development, feel free to Contact us and we would be happy to discuss them with you. In the meantime feel free to read our blog or read other How-Tos