Theme por defecto de WP Carousel 0.4

Con este título ya os podéis imaginar de qué trata el artículo y cómo va el desarrollo de WP Carousel 0.4. Sobre lo primero, hoy explicaré cómo diseñar un theme para WP Carousel (similar a los de WP Main Menu pero con sus cosas particulares) y acerca de lo segundo, he de decir que va inesperadamente muy bien: ya sólo queda el Widget para la Sidebar, los múltiples carruseles en una (o varias) páginas, las traducciones, el valor por defecto de ciertas variables que se pueden configurar (como anchura de los paneles, mostrar flechas o no, etc), exportar e importar y la búsqueda y arreglo de errores. ¿Previsiones? No, gracias. Seguiré sin dar un fecha exacta, aunque voy bastante bien, prefiero seguir sin presión, aunque si tuviera que dar un porcentaje de lo completado de esta versión, diría que ya he superado el 60%.

Pero volviendo al tema, es hora de explicar cómo crear theme para WP Carousel. Por defecto vendrán un par de themes (tengo hechos 2, aunque puede que añada alguno más especialmente pensado para la sidebar), así que viendo el código de cada uno y comparándolo se podrán ver las principales diferencias, pero explicaré paso a paso cómo se crea un theme.

En cuanto a la composición de archivos, es la misma que los themes de WP Main Menu, totalmente idéntica, aunque eso sí, los themes de uno y de otro no son compatibles para nada. Como mucho, la página de opciones os puede detectar los themes de ambos, pero no son compatibles.

Partiremos de un archivo index.php que almacenará la información del theme, cosas como nombre del autor, versión, descripción y archivos CSS que usará (no se permiten añadir archivos Javascript), en una matriz llamada $theme. A continuación podéis ver el código del archivo index.php del theme Default:

<?php

	// THEME INFORMATION

	$theme['author'] = "Sumolari";
	$theme['author_url']= "http://sumolari.com";
	$theme['name'] = "WP Carousel 0.3 Look";
	$theme['url'] = "http://sumolari.com/wp-carousel";
	$theme['desc'] = __('Use WP Carousel 0.3\'s theme', 'wp_carousel');
	$theme['version'] = '1.0';

	$theme['css'] = array();
	$theme['css'][] = 'style.css';

?>

Otro archivo fundamental en los themes es el archivo theme.php, que mostrará el contenido del carrusel. Lo cierto es que en este punto los themes no son muy flexibles: tienen que tener una estructura bastante fija en el diseño. A continuación podéis ver el código mínimo de un theme de WP Carousel comentado y explicado.

<?php
		echo '<div class="nombre_de_mi_theme">'; // Es recomendable poner al principio una capa que tenga por clase el nombre del theme, así se evitan conflictos relacionados con el CSS de otros themes que estén activados en otros carruseles

		if ($config['ARROWS']): // Comprobamos si están habilitadas las flechas y en cada desplazamiento manual se debe desplazar como mínimo un panel
			echo '<a href="javascript:stepcarousel.stepBy(\'carousel_'.$c_id.'\', '.$config['SLIDE_POSTS'].')">'; // Enlace para adelantar un panel
			printf(__('Forward %s panel', 'wp_carousel'), $config['SLIDE_POSTS']); // Texto del enlace
			echo '</a>'; // Fin del enlace
		endif; // Fin de la comprobación

		if ($config['ARROWS']): // Comprobamos si están habilitadas las flechas y en cada desplazamiento manual se debe desplazar como mínimo un panel
			echo '<a href="javascript:stepcarousel.stepBy(\'carousel_'.$c_id.'\', -'.$config['SLIDE_POSTS'].')">'; // Enlace para retroceder un panel
			printf(__('Back %s panel', 'wp_carousel'), $config['SLIDE_POSTS']); // Texto del enlace
			echo '</a>'; // Fin del enlace
		endif; // Fin de la comprobación

?>

		<div id="carousel_<?php echo $c_id; ?>" class="stepcarousel"> <?php // Esta capa (div) debe tener esa ID y no otra, ya que StepCarousel (el script en el que está basado WP Carousel) crea los carruseles mediante las IDs de los elementos que los contienen ?>

			<div class="belt"> <?php // Otra capa necesaria para el correcto funcionamiento de StepCarousel. No se debe modificar la clase, puede hacer que falle el script ?>
				<?php foreach ($items as $i_id => $item): // Iniciamos el bucle que mostrará los elementos del carrusel, donde $i_id es la ID INTERNA de los elementos del carrusel (la ID que utiliza WP Carousel) y el índice ID de la matriz $item es la ID que tiene el elemento dentro de WordPress. En este ejemplo están todos los índices importantes de $item, hay más, pero no merecen ser explicados ya que no son usados mas que internamente por WP Carousel ?>
				<div class="panel" <?php if ($config['HAS_PANEL_WIDTH']) echo 'style="width:'.$config['PANEL_WIDTH'].';"'; ?>><?php // Esta es otra capa que debe tener de clase panel. El índice HAS_PANEL_WIDTH comprueba que el valor de la anchura personalizada del panel no esté en blanco y si es un valor aceptable, lo usa como anchura ?>
					<a href="<?php echo $item['LINK_URL']; ?>" title="<?php echo $item['TITLE']; ?>"><?php // Enlace hacia la URL del elemento el carrusel. Ojo, es la URL a la que debe dirigir el elemento, no la URL del elemento dentro de WordPress, así que un artículo que tenga por permalink /post, no tiene por qué llevar a /post, sino que puede llevar a http://sumolari.com (por ejemplo). El índice LINK_URL almacena la URL del enlace mientras que el índice TITLE almacena el título del contenido. Como podréis suponer, la matriz $items no contiene ninguna categoría, sino que anteriormente WP Carousel ha reemplazado las categorías por los artículos que hay en ellas ?>
						<img src="<?php echo $item['IMAGE_URL']; ?>" alt="<?php echo $item['TITLE']; ?>" title="<?php echo $item['TITLE']; ?>" width="<?php if ($config['HAS_IMG_WIDTH']) { echo $config['IMG_WIDTH']; } else { echo '100px'; } ?>" height="<?php if ($config['HAS_IMG_HEIGHT']) { echo $config['IMG_HEIGHT']; } else { echo '100px'; } ?>" /><?php // Ahora mostramos la imagen que hemos establecido para este elemento. El índice IMAGE_URL se corresponde a la URL de la imagen, el índice TITLE lo hemos comentado antes, el índice HAS_IMG_WIDTH es true si la anchura personalizada de las imágenes del carrusel es un valor aceptable, mientras que el índice IMG_WIDTH es el valor anteriormente comprobado. El índice HAS_IMG_HEIGHT e IMG_HEIGHT devuelven lo mismo que los anteriores pero sobre la altura. Podéis ver que la altura y la anchura por defecto es de 100px.  ?>
					</a><?php // Cerramos el link ?>
					<div class="panel-text"><?php // Esto es opcional, y es la capa en la que se mostrará la descripción de cada elemento. Se pueden hacer themes que no muestren la descripción y themes que no muestren el título, al igual que themes que no muestren ninguno o que muestren ambos ?>
					<?php echo $item['DESC']; // El índice DESC se corresponde con el extracto del artículo o el campo personalizado wp_carousel_carousel_text ?>
					</div><?php // Cerramos la capa de la descripción ?>
				</div><?php // Cerramos la capa del panel ?>
				<?php endforeach; // Finaliza el bucle ?>
			</div> <?php // Cerramos la capa con clase belt ?>
		</div><?php // Cerramos la capa del carrusel ?>

		<?php if ($config['ENABLE_PAGINATION']): // El índice ENABLE_PAGINATION devuelve true si se deben mostrar los iconos indicadores del panel en el que nos situamos ?>
		<div id="carousel_<?php echo $c_id; ?>-paginate" class="wp_carousel_default_pagination"><?php // La ID de esta capa no se puede modificar, pero la clase sí ?>
			<img src="<?php echo $path[6]; ?>/img/opencircle.png" data-over="<?php echo $path[6]; ?>/img/graycircle.png" data-select="<?php echo $path[6]; ?>/img/closedcircle.png" data-moveby="1" /><?php // Mostramos la imagen de carga e indicamos la URL a los iconos de la paginación. El índice 6 de $path devuelve la URL hasta la carpeta del plugin. Para cargar la carpeta del theme, deberíamos usar el siguiente código: $path[6].'/themes/'.$config['THEME'].'/imagen.png ?>
		</div><?php // Cerramos la capa de la paginación
		endif;

	echo '</div>'; // Cerramos la capa con la clase especial para evitar conflictos CSS

?>

Con esto ya tenemos dos tercios del trabajo hecho, pero nos queda el CSS, que también es algo restrictivo, ya que tenemos que partir de un código CSS básico que es:

.nombre_de_mi_theme .stepcarousel {
position: relative;
overflow: scroll;
}

.nombre_de_mi_theme .stepcarousel .belt {
position: absolute;
left: 0;
top: 0;
}

.nombre_de_mi_theme .stepcarousel .panel {
float: left;
overflow: hidden;
}

Os recomiendo que diseñéis teniendo en cuenta que hay otros themes y que puede que haya dos themes en uso a la vez, así que hay que procurar una máxima compatibilidad entre los themes.

Y esto es todo, así se crea un theme para WP Carousel. ¿Fácil? ¿Difícil? ¿Flexible? ¿Estricto? Puede que no sea el mejor sistema de creación de themes, pero es el que habrá en la próxima versión de WP Carousel, y seguramente en las posteriores.