Carousel allows you to add user-configurable rotating banners to any section of a Plone site.
Project description
Introduction
Carousel is a tool for featuring a rotating set of banner images in any section of your Plone site. Features:
Different sets of banners can be used in different sections of the site.
Banners can link to another page in the site, or an external URL.
Carousel provides options to customize the appearance of the banner as well as the length and type of transition.
An optional pager provides navigation among the banners.
Transition effects are implemented using the jQuery javascript library which is included with Plone, so they are pretty lightweight.
Banners do not rotate while the mouse cursor is hovering over the Carousel.
Banner and pager templates can be registered to customize the appearance of the Carousel.
Carousel implements jQuery events, allowing for integration with custom javascripts.
Compatibility
Carousel requires Plone 3.0 or greater, mainly because it renders itself in a viewlet.
Installation
Add Products.Carousel to your buildout’s list of eggs, and re-run buildout. If you get version conflicts while running buildout, you can use a known good version set to find versions compatible with plone.app.z3cform:
http://good-py.appspot.com/release/plone.app.z3cform/0.5.0-1?plone=4.0.2
Start Zope, go to Site Setup -> Add-on Products in your Plone site and install the Carousel product.
Using Carousel
A detailed guide to using Carousel is available.
Detailed overview and tests
Customizing Carousel
It is possible to customize presentation of the Carousel by registering custom templates for the banner and pager. To simplify the registration of Carousel templates and their associated menu items, Carousel includes special ZCML directives. To begin, define the Carousel XML namespace in your product’s configure.zcml:
xmlns:carousel="http://namespaces.plone.org/carousel"
Then load the ZCML for Carousel:
<include package="Products.Carousel" />
Finally, register your templates:
<carousel:banner
name="banner-example"
template="banner-example.pt"
title="Default"
/>
<carousel:pager
name="pager-classic"
template="templates/pager-classic.pt"
title="Title and Text"
/>
Both the banner and pager directives can also accept a layer attribute to restrict the availability of the template to a particular browser layer.
To make the development of banner and pager templates less repetitive, Carousel includes macros in the banner-base and pager-base templates. See banner-default.pt and pager-titles.pt for examples of how to use these macros.
Carousel Events
Carousel triggers jQuery events at key points in its operation, making it possible to integrate Carousel with other interactive elements on the page. These events are triggered on the Carousel container element:
- afterAnimate
Triggered immediately before animation begins. It passes as parameters the Carousel object, the index of the previous banner and the index of the current banner.
- beforeAnimate
Triggered immediately before animation begins. It passes as parameters the Carousel object, the index of the current banner and the index of the banner that will be active at the end of the animation.
- pause
Triggered when animation is paused, such as when the user mouses over the Carousel. It passes as its parameter the Carousel object.
- play
Triggered when animation begins or resumes. It passes as its parameter the Carousel object.
The Carousel object, which is passed as the first optional parameter to event handlers, is a Javascript object that encapsulates the current state of the Carousel. See carousel.js for details of the Carousel object.
To bind a callback to one of the Carousel events, select the Carousel container element and call the jQuery bind method on it:
(function ($) {
$('.carousel').bind('afterAnimate',
function (event, carousel, old_index, new_index) {
console.log(carousel);
console.log(old_index);
console.log(new_index);
});
})(jQuery);
Change history
2.1b2 (2010-12-08)
Fixed javascript error on Plone 3. [yomatters]
2.1b1 (2010-12-06)
Fixed known good versions set link. [yomatters]
Made instructions for adding and modifying banners more prominent. [yomatters]
Added option for setting the ID of the Carousel. [yomatters]
2.0 (2010-11-19)
Split plugin into functions, making it easier to override parts of the Carousel behavior. [yomatters]
2.0b1 (2010-09-30)
Added slide as a possible transition type. [yomatters]
Refactored javascript as a jQuery plugin that triggers jQuery events on transitions. [yomatters]
Added settings to customize the appearance of the banner and pager and the length and type of transition. [yomatters]
Added an optional pager for navigation among banners. [yomatters]
Replaced description field on Carousel banners with a rich-text body field. [yomatters]
Remove the browser layer to help with use in Plone 2.5. [davisagli]
1.1 (2010-03-26)
In Plone 4, add viewlet to the abovecontent viewlet manager by default, to avoid weird styles. [davisagli]
Added Spanish translation. [tzicatl]
Only show published banners in the Carousel, even for users who have permission to see others. [davisagli]
1.0 (2009-03-31)
Changed behavior of text links to swap banner on mouseover. [davisagli]
1.0b3 (2009-02-07)
Add ‘Carousel Banner’ to types not searched. [davisagli]
Locate carousel folder correctly on containers used as default pages (e.g. a Topic) [davisagli]
Apply proper security declarations to the getSize and tag methods of the banner type so that the view works okay when customized TTW. [davisagli]
Only display the carousel on default view; not any of the other tabs. [davisagli]
Fix viewlet removal on uninstallation. [davisagli]
Fix duplicate entries in quick installer. [davisagli]
1.0b2 (2009-02-04)
Declare dependency of our custom GS import step on the viewlets step. [davisagli]
Separate the (globally-registered) template from the (locally-registered) viewlet, so that the former can be customized using portal_view_customizations. [davisagli]
Added banner description to the template. Changed the ‘carousel-title’ class to ‘carousel-button’ so I could split out ‘carousel-title’ and ‘carousel-description’. [davisagli]
Handle non-structural folders correctly. [davisagli]
1.0b1 (2009-02-03)
Initial release. [davisagli]
Contributors
David Glick [davisagli], Groundwire, Author
Matt Yoder [yomatters], Groundwire
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
