uso Protocarrusel

Documentación y ejemplos de uso de Protocarrusel.


requisitos

Para usar Protocarrusel necesitamos incluir en nuestro documento el framework JavaScript Prototype, la librería de efectos Script.aculo.us , Usefull y por último Protocarrusel. El código sería algo como esto:

       
 <head>
   .
   .
  <script type="text/javascript" src="ruta/a/prototype.js"></script>
  <script type="text/javascript" src="ruta/a/scriptaculous.js?load=effects"></script>
  <script type="text/javascript" src="ruta/a/usefull.js"></script>
  <script type="text/javascript" src="ruta/a/protocarrusel.js"></script>
   .
   .
 </head>
       
      

uso

Vamos a la faena. Para utilizar Protocarrusel necesitamos una estructura mínima en nuestro documento HTML: un elemento 'div' contenedor y el contenido formado por otros elementos que conformarán los paneles del carrusel a los que se les aplicará la clase 'carousel-slide' (veremos, más adelante, que no es obligatorio que la clase se llame de esta forma). Un ejemplo:

       
 <div id="contenedor-carrusel">
  <div class="carousel-slide">contenido 1</div>
  <div class="carousel-slide">contenido 2</div>
   .
   .
  <div class="carousel-slide">contenido n</div>
 </div>
       
      

Ahora necesitamos unos controles para manejar nuestro carrusel. Este sería el código básico:

       
 <div id="controles">
  <a href="#" class="carousel-control" rel="first">primero</a>
  <a href="#" class="carousel-control" rel="prev">anterior</a>
  <a href="#" class="carousel-control" rel="startStop">iniciar/parar</a>
  <a href="#" class="carousel-control" rel="next">siguiente</a>
  <a href="#" class="carousel-control" rel="last">último</a>
 </div>
       
      

Tal como se ve en el código de arriba, para definir los controles utilizamos la clase 'carousel-control' y especificamos la función de cada uno en el atributo 'rel': 'first', 'prev', 'startStop'(1.0.3+) , 'next' o 'last'.

Podemos también definir otro tipo de controles que nos van a permitir saltar a cada uno de los elementos del carrusel individualmente:

       
 <div id="jumpers">
  <ul>
   <li><a href="#" class="carousel-jumper">contenido del control</a></li>
  </ul>
 </div>
       
      

En los controles tipo 'jumper' se puede 'apuntar' con el atributo 'href' al elemento al que queremos saltar (href="#idElemento"). Si no apuntamos a ningún elemento (href="#") el 'jumper' salta al elemento del carrusel que guarda la misma posición que el control dentro de la colección de controles jumpers.

Si este tipo de controles van a tener todos el mismo contenido bastará con definir sólo uno y Protocarrusel se encargará de crear el resto. Es importante resaltar también que podemos aplicar estilos a los contenedores de los controles, sean del tipo que sean, para que estos no se vean en el supuesto de que Javascript estuviese deshabilitado: Protocarrusel se encargará de mostrarlos. De esta forma evitamos desbaratar el diseño del documento mostrando unos controles que no sirven para nada.

Una vez que tenemos nuestra estructura bien definida sólo tenemos que instanciar un objeto Protocarrusel en nuestro documento:

       
 <script type="text/javascript">
 /* <![CDATA[ */
 
  var miCarrusel = new ProtoCarrusel('contenedor-carrusel', {
   visibleSlides: 3,
   controlsContainer: 'controles',
   jumpersContainer: 'jumpers'
  });
 
 /* ]]> */
 </script>
       
      

El primer argumento del constructor es el 'id' del contenedor del carrusel y el segundo argumento es una lista de opciones en formato JSON (un objeto con las opciones).

En la base de Protocarrusel esta la idea de hacer, con su uso, los sitios web más usables y nunca inaccesibles. Esto quiere decir que la información que contenga y muestre el carrusel se debería poder acceder aun cuando Javascript estuviera dehabilitado. Un ejemplo.

1
2
3
4
5
6
7
8
9
10

Arriba podemos ver el contenido del carrusel tal como se mostraría (en este caso interesa que sea así) si JavaScript estuviese deshabilitado. Abajo con Protocarrusel funcionando.


CSS del ejemplo:

       
 //carrusel
 #contenedor-carrusel .carousel-slide{
  float:left;
  width:30px;
  height:30px;
  margin:10px 30px;
  padding:6px;
  font-size:22px;
  text-align:center;
  border:10px solid #D18656;
 }

 #contenedor-carrusel{
  float:left;
  overflow:hidden;
  width:100%;
  margin-bottom:10px;
 }
 
 //controles
 #controles{
  float:left;
  width:30%;
  margin:10px 30px;
  font-size:13px;
  letter-spacing:-2px;
 }
 
 #controles .carousel-control{
  margin:0 5px;
  font-weight:bolder;
 }
 
 #controles .carousel-control:hover{
  text-decoration:none;
  color:#333;
 }
 
 #controles .carousel-disabled{
  color:#CFD1BC;
 }
 
 #controles .carousel-disabled:hover{
  color:#CFD1BC;
 }
       
      


opciones de configuración

En la siguiente tabla se describen las opciones de configuración de Protocarrusel.

opción
(tipo)
(valor por defecto)
Descripción
auto
(boolean)
(false)

Determina si el carrusel funciona en modo automático.

afterMove
(función)
(null)

Función a ejecutar después de que el carrusel se ha movido.

amountToMove
(entero)
(1)

Cantidad de paneles a mover con los controles anterior y siguiente y cuando el carrusel se mueve en modo automático. Esta limitado por la opción visibleSlides y en modo circular la cantidad máxima es 1.

beforeMove
(función)
(null)

Función a ejecutar antes de que el carrusel se mueva.

circular
(boolean)
(false)

Determina si el carrusel funciona en modo circular.

controlClassName
(cadena)
(carousel-control)

Clase CSS que se les aplica a los controles principales.

controlsContainer
(cadena)
(null)

'Id' del contenedor de los controles. Si creamos controles es imprescindible para evitar conflictos en caso de crear más de un carrusel en el mismo documento.

disabledClassName
(cadena)
(carousel-disabled)

Clase CSS que se les aplica a los controles principales cuando están deshabilitados.

duration
(flotante)
(1)

Duración del efecto aplicado al carrusel en segundos.

effect
(cadena)
(scroll)

Efecto a aplicar al carrusel: 'fade' o 'scroll'.

frequency
(flotante)
(6)

Frecuencia con la que el carrusel se mueve cuando está en modo auto. En segundos.

initial
(entero o cadena)
(0)

Permite indicar qué elemento del carrusel se mostrará al inicio: puede ser el 'id' del elemento o su posición con respecto a los demás elementos del carrusel empezando por cero.

jumperClassName
(cadena)
(carousel-jumper)

Clase CSS que se les aplica a los controles tipo 'jumper'.

jumpersContainer
(cadena)
(null)

'Id' del contenedor de los controles tipo 'jumper'. Si creamos controles es imprescindible para evitar conflictos en caso de crear más de un carrusel en el mismo documento.

lapseInterval
(flotante)
(5)
obsoleto

Es el lapso de tiempo que transcurre desde que se interrumpe el carrusel cuando está en modo auto (por ejemplo pulsando algún control) hasta que este reanuda el modo automático. En segundos.

marginZero
(boolean)
(false)

Quita los márgenes de los elementos del carrusel.

next
(boolean)
(true)

Determina el sentido del movimiento del carrusel cuando está en modo auto.

panelClassName
(cadena)
(carousel-slide)

Clase CSS que se les aplica a los elementos del carrusel.

selectedClassName
(cadena)
(carousel-selected)

Clase CSS que se le aplica al control 'jumper' seleccionado.

transition
(cadena)
(sinoidal)

Transición a aplicar al efecto scroll: 'spring' o 'sinoidal'.

vertical
(boolean)
(false)

Determina si el carrusel funciona en vertical o en horizontal.

visibleSlides
(entero)
(1)

Cantidad de elementos del carrusel a mostrar al mismo tiempo. Está limitado por el ancho del contenedor y el ancho de los elementos.

wheel
(boolean)
(false)

Permite el control del carrusel con la ruedad del ratón.