WP Carousel – Documentación (Docs)

This post was published 8 years ago. It may be exremely outdated.

Español

En WP Carousel 1.0 hay dos tipos de Addons disponibles: los Extras y los Themes. La diferencia entre ambos es que los Extras están destinados a extender el contenido que se puede añadir al carrusel (por ejemplo, un Extra te puede permitir añadir artículos con una determinada taxonomía personalizada) mientras que los Themes tienen por objetivo darle un aspecto diferente al carrusel.

Comenzaré explicando el funcionamiento de los Extras y la parte compartida entre ambos tipos de Addons.

Extras

index.php

Los Addons se dividen en varios archivos. El archivo index.php contiene información acerca del Addon y la configuración básica (cosas como qué funciones devuelven qué información acerca del elemento, qué características soporta y qué se puede configurar). En los Extras el archivo extra.php es el que contiene las funciones que usa el Addon, mientras que en los Themes es el archivo como theme.php y su hermano theme-jcarousel.php, los que definen el diseño, pero los explicaré más adelante.

El archivo index.php se descompone en dos partes: al inicio se debe declarar la matriz $extra, que contiene la información sobre el Extra (en los themes esta matriz se almacena en la variable $theme). Información como el nombre del autor y la versión, así como una descripción y el nombre de las funciones que usa para obtener el contenido. También se declara el tipo de Extra, algo muy importante, añadido en WP Carousel 1.0.

La segunda parte es la declaración de la matriz $custom_settings, que contiene las opciones que el usuario puede modificar.

La matriz $extra tiene los siguientes índices:

Índice Valor
author Nombre del autor. Simplemente para que se sepa quién ha hecho el Extra
author_url URL de la página web del autor
name Nombre del Extra
url URL de la página del Extra. Puede ser la misma que la del autor o distinta. Puede usarse para dar soporte al Extra, por ejemplo
desc Una descripción de la función del Extra
version Número de versión del Extra, puede ser un número, una palabra, etc. Aunque lo mejor sería usar una numeración lógica (1.0, 1.1, 2.0, etc)
type Importantísimo: Hay dos tipos de Extras: los que permiten añadir elementos individuales y los que añaden una serie de contenidos (grupales). Los veremos más adelante. Para indicar un extra individual, se usa el valor “single“, para unos grupal, “group“. Los Extras grupales requieren más configuración – lo veremos más adelante.
js Es una matriz. Los índices de esta nueva matriz no son importantes. Cada elemento de la matriz deberá ser la ruta relativa a la carpeta contenedora del archivo index.php del Extra a un archivo Javascript que deba ser cargado para el funcionamiento del Extra.
image_url_function Es el nombre de la función que devolverá la URL de la imagen del elemento para el carrusel. Esta función acepta un único parámetro, en forma de matriz, que contiene los campos contenidos en la matriz $custom_settings con los valores asignados por el usuario. Explicaré más adelante esto en detalle.
link_url_function El nombre de la función que devuelve la URL del enlace del elemento para el carrusel. Acepta los mismos parámetros que la función anterior.
video_url_function El nombre de la función que devuelve la URL del vídeo del elemento para el carrusel. Acepta los mismos parámetros que la función anterior.
title_function Igual que las anteriores, sólo que devuelve el título del elemento.
desc_function Igual que las anteriores, sólo que devuelve el contenido del elemento.
item_function Función especial: Esta función sólo es necesaria si es Extra es de tipo group. En ese caso es necesaria una función que a partir de la configuración del usuario, sea capaz de devolver una matriz de elementos con sus correspondientes títulos, descripciones y URLs. La explicaré más adelante.

Nota: Si el Extra va a devolver un elemento que carece de algunas de las características nombradas antes, como por ejemplo, vídeos, la función debe definirse de todos modos, aunque deberá devolver directamente una cadena de texto vacía.

Nota 2: En cualquier futura referencia a la URL del vídeo, se trata de la URL que interpretará el sistema de embebido de vídeos de WordPress, oEmbed. Es decir, si queremos mostrar un vídeo de Youtube bastará con usar como URL del vídeo la URL de la página de Youtube del vídeo. Si el vídeo está alojado en un servidor no soportado por WordPress, no se mostrará.

La matriz $custom_settings es la forma de interactuar con WP Carousel y permitir al usuario personalizar y especificar el contenido. El funcionamiento es sencillo: en esta matriz se sigue una estructura determinada, que WP Carousel analiza y convierte en un formulario que muestra al usuario. El usuario rellena dicho formulario al añadir el contenido al carrusel y WP Carousel se encarga de almacenar la configuración. Cuando es necesario mostrar el elemento, se envía la configuración del elemento a la función correspondiente dependiendo de si se quiere mostrar la imagen, la URL, la descripción, etc.

Esquema de la matriz $custom_settings de WP Carousel 1.0Cada elemento de la matriz es una matriz que representa a un campo del formulario. El índice de la matriz $custom_settings que almacena la matriz del campo es el identificador que se usará en el formulario y a través del cual se podrá proceder a obtener la información sobre la configuración. En la tabla que muestro a continuación podéis ver los índices que la matriz de cada campo y una explicación de su valor. En la imagen de la izquierda podéis ver un esquema de la estructura.

Índice Valor
type Admite sólo uno de los siguientes valores: 

Valor Explicación
textarea El campo es una área de texto
text El campo es un campo de texto estándar
password El campo es un campo de texto con el contenido oculto
select El campo es un menú desplegable
checkbox El campo es una casilla de verificación. Este tipo de campo no funciona correctamente de momento, así que es mejor usar select en su lugar.
group No es un campo propiamente dicho, sino el valor del índice title con un tamaño más grande y centrado, de modo que sirve de separador en el caso de que hayan muchos campos y se quiera estructurar un poco el contenido.
default_value Si el tipo es group, no es necesario.Si el tipo es select, es el índice de la matriz de valores que corresponde al valor por defecto.Si el tipo es textarea, text o password, es una cadena de texto.
values Sólo es necesario si el tipo es select. Es una matriz donde cada índce sirve como ID de la opción y cada valor de la matriz es el texto visible para el usuario. Debe tenerse en cuenta que el valor que se almacenará es la ID, no el valor visible por el usuario, y esta ID es la que recibirán las funciones del Extra a la hora de obtener la información de los elementos.
title Es el texto que aparece junto al campo y le explica al usuario qué se le pide en el campo. En el caso de que el tipo sea group, es el texto que sirve de encabezamiento a los siguientes campos del formulario.

Se pueden añadir tantos campos como sean necesarios, aunque se ha de intentar usar los mínimos posibles para no confundir al usuario con demasiadas opciones.

El funcionamiento de esta matriz y su estructura es idéntica en Themes y en Extras.

Con esto está completo el archivo index.php del Extra.

extra.php

El archivo extra.php no es más complicado. Tan sólo deben definirse las funciones que hemos indicado anteriormente. Estas funciones reciben como parámetro una matriz, a la que llamaremos $extra_config. Esta matriz tiene por índices los identificadores de los campos que hemos definido en la matriz $custom_settings y por valores la cadena de texto que haya introducido el usuario o el ID del valor que haya seleccionado en un select.

Atención: La matriz $extra_config es recibida por las funciones serializada y codificada en base64. Es decir, para poder utilizarla como una matriz deberemos decodificarla y desserializarla. A continuación tenéis un ejemplo en código.

$extra_config = unserialize(base64_decode($extra_config));
echo 'El valor del campo mi_campo es: '.$extra_config['mi_campo'];

Sin embargo, se puede complicar algo más si estamos tratando con un Extra de tipo grupal. Cuando el Extra es de tipo individual, se llama una sola vez a las funciones para obtener la imagen, el título, la URL y la descripción y se pasa como parámetro la matriz $extra_config. Cuando el Extra es grupal, se llama a la función de elementos (item_function) y es a ésta a quien se le pasa como parémtro la matriz $extra_config. Esta función devuelve una matriz con los elementos ya procesados, es decir, una matriz lista para que WP Carousel la muestre en el carrusel.

Esquema de la matriz $elementos_procesadosEsta matriz, a la que llamaremos $elementos_procesados, se compone de tantos índices como elementos vayan a ser mostrados en el carrusel, correspondiéndole a cada índice una matriz que sigue la estructura de la siguiente tabla. En la imagen de la izquierda tenéis un esquema de la matriz.

Índice Valor
ID Identificador del elemento. Si es un contenido generador por WordPress, es preferible que este valor sea el mismo que utiliza WordPress para gestionarlo, de modo que el usuario puede obtener más información del elemento a través de las funciones estándar de WordPress.
TITLE El título del elemento.
DESC El contenido, descripción o extracto del elemento.
IMAGE_URL La URL de la imagen que debe ser mostrada por el elemento.
LINK_URL La URL que se carga al hacer clic en el elemento.
VIDEO La URL del vídeo del elemento.
TYPE Identificador interno del tipo de contenido. Es una forma de hacer que WP Carousel pueda distinguir entre los diferentes tipos de contenido. No hay que seguir ninguna regla específica para completar este campo, tan sólo intentar usar un nombre descriptivo que no haya sido usado por ningún otro Extra.El nombre debe ser una cadena de texto con valores alfanuméricos. El contenido estándar de WP Carousel utiliza tipos numéricos, de modo que la única forma de distinguir un Extra de un contenido estándar es viendo si el tipo es numérico o no. Si se usan tipos numéricos pueden darse anomalías en el comportamiento del plugin, al igual que si varios Extras diferentes usan el mismo tipo.

Proceso de carga del contenido generado con ExtrasAtención: Si el tipo de elemento es grupal, la función de elementos (item_function) es la que debe encargarse de generar toda la matriz, de modo que WP Carousel no llama a ninguna de las otras funciones. Sin embargo, si el tipo es individual, WP Carousel llamará a cada una de las funciones para obtener la información correspondiente. En la imagen de la derecha tenéis un esquema del proceso que sigue WP Carousel para cargar la información.

Themes

Los Themes de WP Carousel se dividen en tres archivos principales: index.php, theme.php y theme-jcarousel.php. Como en los Extras, el archivo index.php almacena la información general del Theme. La estructura del archivo es muy similar a la del Extra, pero tiene algunas diferencias importantes, así que voy a explicar estas diferencias y las partes en común.

index.php

Lo primero que debemos definir en el archivo index.php es la matrix $theme. Su estructura es casi idéntica a la de los Extras. Las diferencias radican en que en los Themes no se usan los índices *_function (no es necesario definir ninguna función para obtener imágenes ni nada similar) ni el índice type y al índice js se le suma el índice css, cuya utilidad es añadir más archivos CSS al Theme, además del índice supports, que indica a WP Carousel qué características soporta el theme. En la tabla que tenéis a continuación están los índices y sus descripciones.

Índice Valor
author Nombre del autor. Simplemente para que se sepa quién ha hecho el Theme
author_url URL de la página web del autor
name Nombre del Theme
url URL de la página del Theme. Puede ser la misma que la del autor o distinta. Puede usarse para dar soporte al Theme, por ejemplo
desc Una descripción del Theme
version Número de versión del Theme, puede ser un número, una palabra, etc. Aunque lo mejor sería usar una numeración lógica (1.0, 1.1, 2.0, etc)
css Es una matriz. Los índices de esta nueva matriz no son importantes. Cada elemento de la matriz deberá ser la ruta relativa a la carpeta contenedora del archivo index.php del Theme a un archivo CSS que deba ser cargado para el funcionamiento del Theme.
js Es una matriz. Los índices de esta nueva matriz no son importantes. Cada elemento de la matriz deberá ser la ruta relativa a la carpeta contenedora del archivo index.php del Theme a un archivo Javascript que deba ser cargado para el funcionamiento del Theme.
supports Es una matriz donde se indican qué características soporta el Theme. Hay una serie de características que se presuponen soportadas (están indicadas en la tabla que hay a continuació) y otras que se presuponen no soportadas (WP Carousel no puede detectar por sí mismo si una característica está soportada o no, debe indicarlo el autor del Theme a través de esta matriz). Si el Theme soporta una característica, el valor del índice debe ser true. Si no la soporta, debe ser false. Aunque no se soporte una característica, es recomendable indicarlo en esta matriz. 

Índice Descripción
stepcarousel Por defecto soportado. Indica si se soporta o no el script StepCarousel, el motor del carrusel usado hasta WP Carousel 0.5 (a partir de WP Carousel 1.0 es sólo una de las opciones posibles).
arrows Por defecto soportadas. Indica si se soportan o no las flechas para el desplazamiento manual.
panel_size Por defecto soportado. Indica si se soporta o no personalizar el tamaño del panel.
image_size Por defecto soportado. Indica si se soporta o no personalizar el tamaño de las imágenes.
pagination Por defecto soportada. Indica si se soporta o no la paginación (el indicador que permite saltar de un panel a otro directamente).
jcarousel Por defecto no soportado. Indica si se soporta o no jCarousel, el motor para carruseles añadido en WP Carousel 1.0.
carousel_size Por defecto no soportado. Indica si se soporta o no ajustar el tamaño del carrusel (en general, no específicamente imágenes o paneles).
vertical_mode Por defecto no soportado. Indica si se soporta o no el modo vertical de jCarousel. StepCarousel no soporta modo vertical.

El archivo index.php también admite una matriz $custom_settings, que es totalmente idéntica a la de los Extras, y su finalidad es la misma: permitir que los Themes sean mucho más personalizables y no sea necesario modificar ningún archivo para cambiar cosas básicas del Theme. Cada autor es libre de hacer más o menos personalizable sus Themes, no hay ninguna limitación por parte de WP Carousel.

theme.php y theme-jcarousel.php

Los archivos theme.php y theme-jcarousel.php son respectivamente, los que contienen el código HTML del carrusel si se usa StepCarousel o jCarousel (opción escogida por el usuario). WP Carousel carga automáticamente el archivo necesario, aunque deben usarse clases CSS distintas en cada archivo, preferiblemente el mismo nombre con el añadido -stepcarousel o -jcarousel.

La estructura HTML de estos archivos puede verse en las páginas de documentación de StepCarousel y de jCarousel, así que no me detendré a explicarlas.

Además, entre los Themes que vienen por defecto se incluye el Theme Skinless, un Theme con el código mínimo para hacer funcionar los carruseles con todas las nuevas características de WP Carousel. También recomiendo revisar los demás Themes incluidos por defecto. En ellos se hace uso de todas las nuevas características y se puede ver sin mucha dificultad cómo funcionan los Themes y como crear un Theme complejo con múltiples opciones.

Los nombres de las variables son bastante descriptivos y no creo que haya ningún problema a la hora de entender qué hace cada cosa y de dónde sale cada variable, aunque a continuación tenéis una tabla de los valores de la matriz $config, que define la configuración del carrusel (es recomendable comprobar que los índices están establecidos antes de ponerse a ver su valor):

Índice Valor
THEME Nombre del Theme activado para el carrusel actual.
SHOW_ARROWS 1 si se deben mostrar, 0 si están desactivadas.
SLIDE_POSTS Número de paneles a mover en cada movimiento manual (al hacer clic en las flechas).
ENABLE_PAGINATION 1 si la paginación (iconos para saltar de un panel a otro) está activada. 0 en caso contrario.
AUTOSLIDE_TIME Tiempo entre cada desplazamiento automático (en milisegundos). 0 si está desactivado.
AUTOSLIDE_POSTS Paneles desplazados en cada movimiento automático.
IMG_WIDTH Anchura de las imágenes.
IMG_HEIGHT Altura de las imágenes.
PANEL_WIDTH Ancho del panel.
PANEL_HEIGHT Altura del panel.
LOOP_MODE 1 si está activado el modo bucle (al terminar los paneles comienzan de nuevo). 0 si no.
CAROUSEL_NAME Nombre del carrusel.
USE_JCAROUSEL Si se debe usar StepCarousel (0) o jCarousel (1).
VERTICAL_MODE Si está habilitado el modo vertical (sólo jCarousel – 1) o no (0).
THEME_SETTINGS Matriz con las opciones personalizadas del theme. Cada índice se corresponde con el identificador de un campo de la matriz $custom_settings del Theme, y el valor es lo que el usuario haya escrito en el campo de texto correspondiente o el identificador de la opción seleccionada si se trata de un menú desplegable.
Hay más índices, pero estos son los más importantes.

Integrar WP Carousel en Themes de WordPress

WP Carousel admite una vuelta de tuerca más: mostrar carruseles usando Themes integrados en Themes de WordPress. Básicamente el procedimiento consiste en llamar a la función wp_carousel(), pero enviándole como segundo parámetro el valor ‘array’. Esto hará que WP Carousel devuelva una matriz con todo el contenido procesado y ordenado, una matriz con la misma información que reciben los Themes de WP Carousel. Tras esto, simplemente se cambian los nombres de las variables y se puede utilizar el mismo código que en cualquier otro Theme de WP Carousel.

Por ejemplo, a continuación tenéis una versión de la función que muestra el carrusel de la página de inicio de Sumolari.com (sí, yo tengo integrado WP Carousel en mi Theme de WordPress, no uso un Theme para WP Carousel).

function sumolari_carousel($c_id) {
 $carousel_array = wp_carousel($c_id, 'array');
 $carousel_config = $carousel_array['CONFIG'];
 $carousel_items = $carousel_array['ITEMS'];
 ?>
<div class="carousel_stick stick-blue">
		<a class="carousel-next" href="javascript:stepcarousel.stepBy('carousel_<?php echo $c_id; ?>', <?php echo $carousel_config['SLIDE_POSTS']; ?>)"><span class="hide">Avanza <?php echo $carousel_config['SLIDE_POSTS']; ?> panel</span></a></div>
<div class="carousel_stick_next stick-blue">
		<a class="carousel-back" href="javascript:stepcarousel.stepBy('carousel_<?php echo $c_id; ?>', -<?php echo $carousel_config['SLIDE_POSTS']; ?>)"><span class="hide">Retrocede <?php echo $carousel_config['SLIDE_POSTS']; ?> panel</span></a></div>
<div id="carousel_<?php echo $c_id; ?><br />" class="stepcarousel">
<div class="belt">
			<?php foreach ($carousel_items as $i_id => $item): ?>
<div class="panel">
<div class="image">
					<a href="<?php echo $item['LINK_URL']; ?>">
						<img title="<?php echo $item['TITLE']; ?>" src="<?php echo $item['IMAGE_URL']; ?>" alt="<?php echo $item['TITLE']; ?>" width="888" height="500" />
						<span class="hide"><?php echo $item['TITLE']; ?></span>
					</a></div>
</div>
			<?php endforeach; ?></div>
</div>
<div id="carousel_<?php echo $c_id; ?>-paginate" class="sumocarousel_pagination">
		<img src="<?php bloginfo('template_directory'); ?>/img/opencircle.png" alt="" /></div>
<?php }
sumolari_carousel(3);

Es una versión simplificada del potencial de esta característica. Realmente se puede hacer mucho más, pero para mi carrusel he dejado de lado integrar todas las posiblidades ya que realmente yo no las necesito. El modo de integrarlas es análogo a como se haría en cualquier Theme de WP Carousel. Como antes, os recomiendo revisar los Themes por defecto, ya que os pueden servir de punto de partida y ahorraros mucho trabajo.

Integrar WP Carousel en los plugins de WordPress

WP Carousel también se puede integrar en los plugins de WordPress, esta vez a través de Extras que se definen fuera de WP Carousel. Al cargar los Extras, WP Carousel revisa si hay algún Extra añadido a la matriz contenida en la variable de sesión $_SESSION[‘WP_CAROUSEL_CUSTOM_EXTRAS’] y añade cualquier Extra que encuentre en esa matriz a la página de opciones de cada carrusel.

El procedimiento a seguir para integrar WP Carousel en un plugin de WordPress es el siguiente:

  1. Comprobamos si existe o no la variable de sesión $_SESSION[‘WP_CAROUSEL_CUSTOM_EXTRAS’].
  2. Si no existe o si no es una matriz, la creamos como matriz.
  3. Definimos una matriz $extra, que sigue la misma estructura (idéntica) que cualquier otro Extra de WP Carousel.
  4. Añadimos la matriz $extra a la matriz contenida en la variable de sesión anterior.

Como Extras de ejemplo añadí soporte para el plugin TheCartPress. Pues bien, como ejemplo para integrar un plugin de WordPress con WP Carousel os pongo a continuación el código que se debe añadir a TheCartPress para hacerlo compatible con WP Carousel.

Nota: Las funciones definidas como funciones del Extra (item_function, desc_function, etc) no están definidas en este fragmento de código. Son las mismas funciones que aparecen en los Extras por defecto. Cuando se integra un plugin de WordPress con WP Carousel deben definirse también esas funciones en algún lado. Como en los Extras de ejemplo se definen esas funciones, yo no las he puesto aquí, pero recordad, sin definir esas funciones la integración no funcionaría.

function add_extras_to_wpcarousel()
{
	global $_SESSION;
	if (!isset($_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS']))
	{
		$_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS'] = array(); // No creada. La creamos.
	}
	elseif (!is_array($_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS']))
	{
		$_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS'] = array(); // No es una matriz. La creamos.
	}
	//  Información del Extra
	$extra['author'] = "Sumolari";
	$extra['author_url']= "http://sumolari.com";
	$extra['name'] = __('Products', 'wp_carousel');
	$extra['url'] = "http://sumolari.com/wp-carousel";
	$extra['desc'] = __('Show products created with TheCartPress WordPress plugin', 'wp_carousel');
	$extra['version'] = '1.0';
	$extra['type'] = 'single';
	// Funciones definidas en otro archivo
	$extra['image_url_function'] = 'wpc_tcp_image_url';
	$extra['link_url_function'] = 'wpc_tcp_link_url';
	$extra['title_function'] = 'wpc_tcp_title';
	$extra['desc_function'] = 'wpc_tcp_desc';
	// En este modo NO se pueden añadir archivos Javascript
	/* Añadimos las opciones para configurar este elemento */
	$products = get_posts('numberposts=-1&post_type=tcp_product&post_status=publish&orderby=post_date&order=DESC');
	$products_array = array();
	foreach ($products as $product)
	{
		$products_array[$product->ID] = $product->post_title;
	}
	$extra['custom_settings'] = array(
		'id' => array(
			'type' => 'select',
			'default_value' => '',
			'title' => 'Product',
			'values' => $products_array
		)
	);
	/*
		Fin de la información del Extra
	*/
	$_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS'][] = $extra; // Extra añadido a la matriz
}
add_extras_to_wpcarousel();

Con esto hacemos que si el plugin está activo aparezca un nuevo Extra en WP Carousel. Cuando el plugin se desactiva ese Extra desaparece. De este modo hacemos que nuestros plugins se integren con WP Carousel.

English

There are two kind of Addons available in WP Carousel 1.0: Extras and Themes. Extras’s purpose is to extend content suitable for the carousel (for instance, an Extra that can add posts from a specific custom taxonomy) while Themes’s purpose is to give the carousel a different look.

Extras

index.php

Addons are divided into different files. File index.php stores information about the Addon and the basic configuration (things such as what functions return what information about an element, which features are supported and what can be customized).

File index.php is broken down into two parts: at the start array $extra, containing information about the Extra (in Themes this array is stored in variable $theme) is declared. Information such as author’s name, version, description and functions’s names. It is also declared the type of the Extra, something really important in WP Carousel 1.0.

The second part is declaration of array $custom_settings, which contains the options the user can customize.

Array $extra has the following keys:

Key Value
author Author’s name. Just to know who has done the Extra.
author_url Author’s URL.
name Extra’s name.
url Extra’s URL.
desc A brief description of the Extra.
version Extra’s version number.
type Really important: There are two kinds of Extras: those allowing the addition of single element (“single”) and those that add a group of elements (“group”).
js It’s an array. Its keys are not important. Each item in the array has to be the relative path from Extra’s index.php file to the folder which contains the Javascript file to be loaded.
image_url_function It’s the name of the function that will return the URL of the image that will be shown in the carousel. This functions accepts only one argument: an array which stores custom fields of array $custom_settings with values assigned by the user. I’ll explain this later.
link_url_function It’s the name of the function that will return the URL of the link that will be shown in the carousel. Same arguments that previous one.
video_url_function It’s the name of the function that will return the URL of the video that will be shown in the carousel. Same arguments that previous one.
title_function It’s the name of the function that will return the title link that will be shown in the carousel. Same arguments that previous one.
desc_function It’s the name of the function that will return the text that will be shown in the carousel. Same arguments that previous one.
item_function Special function: This function in only needed if the Extra is a group Extra. In that case it’s needed a function which returns an array of items to show in the carousel from the configuration the user set up before. I’ll explain this later.

Note: If the Extra does not support some of the features we have mentioned before, you have to define them anyway, although it will simply return an empty string.

Note 2: In any future reference to video URL, it’s the URL which will be parsed by WordPress embedding system (oEmbed). If we want to show a Youtube video, we just copy the URL of the Youtube page. If the video is hosted in an unsupported site, it can not be displayed.

Array $custom_settings is an easy way to interact with WP Carousel and it allows users to customize and specify contents. It is easy: this array follows a specific structure that WP Carousel analyzes and transform into a form which is shown to the user. The user fills up that form when content is added to the carousel and WP Carousel handles configuration storage. When showing an item is needed, the element settings are sent to the proper function depending on wether an image, a URL or a description is to be shown.

$custom_settingsEach item of the array is an array which represents a field of the form. The key of the array $custom_settings that stores the array of the field is the identifier that will be used in the form and will be used to refer to the content that user has filled up. The following table shows the keys of the array of each field and a description of its values. In image at left you can see an scheme of the structure.

Key Value
type Admits just one of the following values: 

Value Description
textarea This field is a text area
text The field is a text field
password The field is a text field with hidden value
select The field is a dropdown menu
checkbox The field is a check box. It does not work yet.
group It is not a proper field, but a heading that shows the value of key title with a bigger font.
default_value If type is group it is not needed. If type is select, is the key of the array of values that corresponds to the default value. If type is textarea, text or password, it is a string.
values It is only needed if type is select. Is an array where each key is used as ID of the option and each value of the array is the text visible to the user. The value stored is the ID, not the visible value. This ID will be received by functions to obtain item’s information.
title Is the text that appears next to the field and explains what is supposed to do the Extra with the value of the field. If type is group, is the text that is used as heading of the following form fields.

You can add as fields as needed, but you should use the least to avoid confusing the user.

The use of this array and its structure is exactly the same in Themes and Extras.

With this Extra’s file index.php is completed.

extra.php

File extra.php is not more complex.We just have to define the functions we have already mentioned. These functions receive as argument an array which we will call $extra_config. This array has as keys the ID of the fields we have defined in array $custom_settings and as values of that keys, the text the user had written down or the ID of the option the user had selected (if the field was a dropdown list).

Warning: Array $extra_config is received by the functions serialized and base64 codified. We have to unserialize and decodify it to use it as a normal array:

$extra_config = unserialize(base64_decode($extra_config));
echo 'Value of field my_test_field is: '.$extra_config['my_test_field'];

This process is a bit more complicated for group Extras. When the Extra is a single Extra, each function is called just once and array $extra_config is passed as argument. When the Extra is a group Extra, function item_function is called and array $extra_config is passed as argument. Function item_function has to call any other function to get item’s information and then return an array with all the items processed.

Array $processed_itemsWe will call this array of processed items $processed_items. Each item of $processed_items array is an array (processed item array) which follows a fixed structure. In the image at left you can see an example of $processed_items array. A processed item array has the following keys:

Key Value
ID Item’s identifier. If it is an item generated by WordPress, it is better to use the same value that uses WordPress as ID.
TITLE Item’s title.
DESC Item’s content or description.
IMAGE_URL Item’s image’s URL.
LINK_URL URL which is loaded when users click on the item.
VIDEO Item’s video URL.
TYPE Iternal kind of content identifier. It is a way to allow WP Carousel to discriminate between different kinds of content. There is no a specific rule to fill this field. Just try to use a descriptive name which has not been used by other Extra. The name must be a string with alphanumeric characters. WP Carousel default content use numbers as type identifier, so the only way to discriminate between default content and Extras is to check if the type is a number or not.

Loading an Extra

Warning: If the type of the item is group, item_function has to generate the whole array so WP Carousel does not call any other functions. Nevertheless, if the type is single, WP Carousel will call each function to get the information about the item. In the image at right, you can see a diagram of the process WP Carousel follows.

Themes

WP Carousel Themes are divided into three main files: index.php, themes.php and theme-jcarousel.php. As with Extras, file index.php stores general information about the Theme. File structure is very similar to that of the Extra, but it has some important differences.

index.php

First of all, we have to define array $theme. Its structure is almost identical to that of the Extras. The differences are that Themes do not use key *_function (there is no need to define any function) nor type key and keys css and supports are added. In the following table all the keys are explained.

Key Value
author Author’s name. Just to know who has done the Theme.
author_url Author’s URL.
name Theme’s name.
url Theme’s URL.
desc A brief description of the Theme.
version Theme’s version number.
css It’s an array. Its keys are not important. Each item in the array has to be the relative path from Theme’s index.php file to the folder which contains the CSS file to be loaded.
js It’s an array. Its keys are not important. Each item in the array has to be the relative path from Theme’s index.php file to the folder which contains the Javascript file to be loaded.
supports It is an array where developers specify which features are supported by the Theme. There are some features that are presupossed as supported while others are presupossed not supported (WP Carousel can’t detect by itself if a feature is supported or not). If the Theme supports a feature, the value of the key has to be true, while if it is not supported, value has to be false. These are the supportable features: 

Key Description
stepcarousel Supported by default. Shows if Theme supports StepCarousel.
arrows Supported by default. Shows if arrows for manual sliding are supported.
panel_size Supported by default. Shows if user can customize panel size.
image_size Supported by default. Shows if user can customize image size.
pagination Supported by default. Shows if pagination is supported.
jcarousel Not supported by default. Shows if jCarousel is supported.
carousel_size Not supported by default. Shows if user can customize carousel size.
vertical_mode Not supported by default. Shows if jCarousel vertical mode is supported (StepCarousel does not support vertical mode).

File index.php allows also an array $custom_settings, which is completely identical to the Extras one, and it is used for the same purpose.

theme.php and theme-jcarousel.php

theme.php and theme-jcarousel.php files contain respectively the HTML code of the carousels depending on our using StepCarousel or jCarousel (option selected by the user). WP Carousel automatically loads the required file, but differents CSS clasess should be used for each file, I suggest using the same name adding -stepcarousel or -jcarousel.

HMTL structure of these files can be seen in StepCarousel and jCarousel documentation, so I won’t explain them.

With WP Carousel 1.0 is included a Theme called Skinless that has been done specifically to be used as a template to create new Themes.

Array $config stores the carousel config. Its keys are quite descriptive, but there is a table with their description.

Key Value
THEME Theme’s name.
SHOW_ARROWS 1 is arrows should be done, 0 is they are disabled.
SLIDE_POSTS Number of panels to move in each manual movement (or when user click on the arrows).
ENABLE_PAGINATION 1 is pagination is enabled. o otherwise.
AUTOSLIDE_TIME Time between each autoslide (in miliseconds). 0 is autosliding is disabled.
AUTOSLIDE_POSTS Panels to move in each automatic movement.
IMG_WIDTH Images width.
IMG_HEIGHT Images height.
PANEL_WIDTH Panel width.
PANEL_HEIGHT Panel height.
LOOP_MODE 1 if loop mode is enabled (when carousel finishes, it starts again). 0 otherwise.
CAROUSEL_NAME Carousel’s name.
USE_JCAROUSEL If StepCarousel should be used, value is 0. If jCarousel should be used, value is 1.
VERTICAL_MODE If vertical mode is enabled (only jCarousel) value is 1. 0 otherwise.
THEME_SETTINGS Array with theme’s custom options. Each key refers to the identifier of a field of Theme’s array $custom_settings, and the value is what the user has written or selected.
There are more keys, but these are the most important.

Integrating WP Carousel in WordPress Themes

To show a carousel with a custom design we can use WP Carousel in array mode. Function wp_carousel supportsa second argument which sets how should be returned the carousel. If this second argument is ‘array’, WP Carousel will return an array with processed items, the same array that use standard Themes to show the carousel.

There a simplified version of the functions that shows the carousel in Sumolari.com:

function sumolari_carousel($c_id) {
 $carousel_array = wp_carousel($c_id, 'array');
 $carousel_config = $carousel_array['CONFIG'];
 $carousel_items = $carousel_array['ITEMS'];
 ?>
<div class="carousel_stick stick-blue">
		<a class="carousel-next" href="javascript:stepcarousel.stepBy('carousel_<?php echo $c_id; ?>', <?php echo $carousel_config['SLIDE_POSTS']; ?>)"><span class="hide">Avanza <?php echo $carousel_config['SLIDE_POSTS']; ?> panel</span></a></div>
<div class="carousel_stick_next stick-blue">
		<a class="carousel-back" href="javascript:stepcarousel.stepBy('carousel_<?php echo $c_id; ?>', -<?php echo $carousel_config['SLIDE_POSTS']; ?>)"><span class="hide">Retrocede <!?php echo $carousel_config['SLIDE_POSTS']; ?> panel</span></a></div>
<div id="carousel_<?php echo $c_id; ?><br />" class="stepcarousel">
<div class="belt">
			<?php foreach ($carousel_items as $i_id => $item): ?>
<div class="panel">
<div class="image">
					<a href="<?php echo $item['LINK_URL']; ?>">
						<img title="<?php echo $item['TITLE']; ?>" src="<?php echo $item['IMAGE_URL']; ?>" alt="<?php echo $item['TITLE']; ?>" width="888" height="500" />
						<span class="hide"><?php echo $item['TITLE']; ?></span>
					</a></div>
</div>
			<?php endforeach; ?></div>
</div>
<div id="carousel_<?php echo $c_id; ?>-paginate" class="sumocarousel_pagination">
		<img src="<?php bloginfo('template_directory'); ?>/img/opencircle.png" alt="" /></div>
<?php }
sumolari_carousel(3);

It is a very simplified version of the potential of this feature. You can do much more than that, you are only limited by your creativity.

Integrating WP Carousel in WordPress plugins

WP Carousel can also be integrated in WordPress plugins, this time through Extras that are define outside of WP Carousel. When WP Carousel loads the Extras, it checks if there is any Extra added to the array stored in session variable $_SESSION[‘WP_CAROUSEL_CUSTOM_EXTRAS’] and adds any Extra that finds in that array in the carousel options page.

The process is as follows:

  1. We check if there is defined or not session variable $_SESSION[‘WP_CAROUSEL_CUSTOM_EXTRAS’].
  2. If it does not exists or if it is not an array, we create it as an array
  3. We define an array $extra, which follows the same structure that any other WP Carousel Extra.
  4. We add that array to the array stored in the variable session we were working with before.

As default Extras I added support to the plugin TheCartPress. Here is the code that has to be added to TheCartPress to integrate this plugin with WP Carousel by default.

Note: Functions defined as Extras functions (item_function, desc_function, etc) are not defined in this code. They are the same that appear in the default Extras. When a WordPress plugin is integrated with WP Carousel, these functions must be define in some place. As the default Extras define these functions, I haven’t written them here, but remember, without defining these function, integration won’t work.

function add_extras_to_wpcarousel()
{
	global $_SESSION;
	if (!isset($_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS']))
	{
		$_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS'] = array(); // Not created. We create it.
	}
	elseif (!is_array($_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS']))
	{
		$_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS'] = array(); // Not an array. We create it.
	}
	//  Extra's information
	$extra['author'] = "Sumolari";
	$extra['author_url']= "http://sumolari.com";
	$extra['name'] = __('Products', 'wp_carousel');
	$extra['url'] = "http://sumolari.com/wp-carousel";
	$extra['desc'] = __('Show products created with TheCartPress WordPress plugin', 'wp_carousel');
	$extra['version'] = '1.0';
	$extra['type'] = 'single';
	// Functions defined in other file
	$extra['image_url_function'] = 'wpc_tcp_image_url';
	$extra['link_url_function'] = 'wpc_tcp_link_url';
	$extra['title_function'] = 'wpc_tcp_title';
	$extra['desc_function'] = 'wpc_tcp_desc';
	// Javascript files can't be added in this mode
	/* Options to set up this item */
	$products = get_posts('numberposts=-1&post_type=tcp_product&post_status=publish&orderby=post_date&order=DESC');
	$products_array = array();
	foreach ($products as $product)
	{
		$products_array[$product->ID] = $product->post_title;
	}
	$extra['custom_settings'] = array(
		'id' => array(
			'type' => 'select',
			'default_value' => '',
			'title' => 'Product',
			'values' => $products_array
		)
	);
	/*
		End of Extra's information
	*/
	$_SESSION['WP_CAROUSEL_CUSTOM_EXTRAS'][] = $extra; // Extra added to array
}
add_extras_to_wpcarousel();