Usando Campos de BBDD y Filtros de Listado, Personalizados, para Clips | Personalización Avanzada | Documentación WS.WebTV | WebTV Solutions

Imprimir

Campos de base de datos y filtros, personalizados, para Clips

Desde WS.WebTV 3.0.2pf1 es posible utilizar campos (en la base de datos) así como filtros de listado, personalizados, para Clips. Esto permite un mayor grado de personalización que resultará de gran utilidad para aquellos usuarios que necesiten manejar estructuras de datos adicionales para los Clips, específicas para ciertos proyectos.

Una vez que el/los nuevo(s) campo(s) se han añadido a la tabla "clips" de la base de datos (leer el punto 1 antes de añadirlos!), es necesario especificarlo(s) -y definir los filtros de listado correspondientes- en la WebTV (principalmente) añadiendo variables en el archivo de configuración (config/Config.inc.php) y editando archivos de plantilla.

A continuación, vamos a proceder con la explicación utilizando un ejemplo práctico.

1: Modificación de la base de datos

Supongamos que se desea añadir un campo personalizado "country" (país) a la tabla clips de la base de datos. Independientemente del nombre que se desee dar al nuevo campo, recomendamos que siempre se utilice un prefijo de seguridad (Ej. "x_") para evitar "colisiones" con futuras versiones de la WebTV. Así pues, el nuevo campo personalizado a añadir, con el prefijo de seguridad, se llamaría "x_country".

2: Especificando el Campo en la WebTV

Una vez añadido el campo personalizado a la tabla "clips", hay que indicarle al sistema que debe manejar ese campo cuando opere en la BBDD. Esto se hace a través de la variable (arreglo asociativo) $CUSTOM_DB_FIELDS["clips"], añadiendo un arreglo asociativo con el nombre del campo como índice y un arreglo con datos descriptivos como valor.

Ejemplo:
Supongamos que a la tabla "clips" se añadió un campo de texto/string (CHAR, VARCHAR, TEXT, etc.) con nombre "x_country". Habría que especificarlo de la siguiente manera en el archivo config/Config.inc.php:

$CUSTOM_DB_FIELDS["clips"]["x_country"] = array (
	"data_type"   => "plain_text", // Tipo de datos almacenado en el campo. Ops: "number" (si almacena números), "plain_text" (si almacena texto normal), "html" (si almacena texto en formato HTML) , "timestamp" (si es un número que es corresponde con una estampa de tiempo Unix)
	"default_val" => "",           // Valor por defecto (puede ser "NULL" si se requiere), cuando no el campo no está definido o cuando no se suministra el dato al crear/leer/actualizar los "clips". Necesario para insertar datos en la BBDD.
	"output_formatting" => "no",   // Aquí se especifica si se requiere formato (según ajustes regionales) cuando se imprima en las plantillas. Ops: "no" (se imprime tal cual), "date" (fecha sin tiempo/hora), "number" (número no decimal), "decimal" (número decimal), "time" (parte de tiempo/hora de una fecha), "datetime" (fecha + tiempo/hora) 
);

Vale la pena destacar que una vez definido el nuevo campo éste será accesible (por su nombre) en la página/plantilla de edición de Clip (Back-End) y en la página/plantilla utilizada para mostrar un Clip (Front-End), usando las siguientes etiquetas:

Adicionalmente a lo anterior, el nuevo campo también será incluido (por su nombre) en los resultados de la función clips > get del API.

3: Mostrando el campo+valor en la página de edición de Clip (Back-End / Formulario)

Con lo anterior, ya se puede modificar la plantilla de edición de Clip (Back-End) para almacenar/leer el nuevo campo, añadiendo nuevos elementos al formulario.

Ejemplo:
Supongamos que se va a añadir un desplegable para seleccionar el país, y dicho desplegable aparecerá encima del campo de descripción de Clip... editar el archivo de plantilla public/backend/admin_clip_edit.tpl y añadir lo siguiente (color azul y rojo) antes del div con clase "formRow" que envuelve al campo "item_description" (en verde):

IMPORTANTE: Validando los componentes de formulario añadidos
Los campos que Ud. añada manualmente no serán validados por las funciones internas Javascript de validación; por lo tanto, necesita validar la entrada del Usuario usando sus propias funciones de Javascript que deben estar definidas en la misma plantilla. Tenga presente que si necesita realizar una validación final cuando el Usuario haga click en el botón "Guardar" y detener el envío si los nuevos campos no son validados entonces puede definir una función Javascript con nombre validateCustomFields() que debe devolver true (si la validación es exitosa) o false y, basado en ese valor de retorno, se continuará con el envío del formulario o se detendrá.
Complementario a lo anterior, tenga presente que su función de validación puede añadir la clase CSS "error" a los elementos del formulario (input, textarea, select...) que no sean validados; esa clase hará que los elementos del formulario se resalten en color rojo. Adicionalmente, si necesita mostrar un mensaje de error puede utilizar la función interna showResultMessage() - ver ejemplo.

Ejemplo de función de validación:

<script>
function validateCustomFields()
{
    $("#x_country").removeClass("error");
    if($("#x_country").val()=="")
    {
      $("#x_country").addClass("error");
      showResultMessage("Oops, debe seleccionar un país","error",5000); // 5000 es el tiempo en milisegundos que el mensaje permanecerá en la página
      return false;
    }

return true;
}
</script>

NOTAS
- 1: Vale la pena destacar que, para imprimir el valor en la página/plantilla, como se está haciendo dentro de una cadena de texto (string) Javascript, es mejor utilizar la etiqueta {k.html.x_country_escaped} por seguridad.
- 2: Si algún caracter especial, con tilde, etc. no se muestra correctamente, será necesario convertir (con el editor de texto) la codificación del archivo de plantilla de ANSI a UTF-8.
- 3: Hay repetir el procedimiento anterior con la plantilla public/backend/admin_clip_edit_auto_encoding.tpl (que aplica únicamente a los Clips Auto-Compresión).

...Listo: Ya se puede editar los Clips y asignar el país.

4: Mostrando el valor del campo en la página de un Clip (Front-End)

El siguiente paso es modificar la plantilla del Front-End que muestra el Clip a los visitantes, para que imprima el valor del nuevo campo (si es que se desea mostrarlo...).

Ejemplo:
Supongamos que se desea mostrar el país debajo de la descripción del Clip, pero encima de las categorías del mismo... editar el archivo de plantilla -utilizado por defecto para los Clips cuando el tema V2 está seleccionado- public/frontend/v2/clip.tpl y añadir lo siguiente (color azul y rojo) antes de <div class="itemCategoriesTitle" ...:

NOTAS
- 1: La etiqueta {k.lang.fe.country} imprime la palabra "País" según el idioma seleccionado para el Front-End.
- 2: Vale la pena destacar que, como normal general, y si el valor del campo no se va a utilizar dentro de código HTML/Javascript entrecomillado, para imprimirlo se debe utilizar la etiqueta _formatted.

5: Mostrando el valor del campo en listados (Front-End)

5.1: Especificando el campo para que el sistema lo maneje

Si se desea que el/los nuevo(s) campo(s) esté(n) disponible(s) para ser impreso(s) en los listados de Clips (búsquedas, etc.) entonces primero hay que especificarlo(s) en el archivo de configuración (config/Config.inc.php) a través de la variable (arreglo asociativo) $CUSTOM_DB_FIELDS_LIST_INCLUSION["clips"] asignando un arreglo con el listado de campo(s) personalizado(s) a incluir:

$CUSTOM_DB_FIELDS_LIST_INCLUSION["clips"] = array("x_country"); // Campos personalizados que se van a incluir en los listados de Clips (uno o varios)

5.2: Mostrando el valor del campo

Después de lo anterior, el valor del campo ya se puede imprimir en los listados, para ello, hay que incluir la etiqueta correspondiente a las estructuras de "loop" (bucle) de las plantillas del Front-End.

Ejemplo:
Supongamos que se desea incluir el valor del nuevo campo de país en los listados de Clip de los resultados de búsqueda, debajo de los "visionados". Editar el archivo de plantilla -utilizado por defecto para los listados de Clips, Canales y Páginas cuando está seleccionado el tema V2 - public/frontend/v2/search_results.tpl y añadir lo siguiente (color azul y rojo) después de <div class="views...:

NOTA:Como la plantilla anterior es válida para listar tanto Clips como Canales como Páginas entonces hay que añadir un código JS y CSS al encabezado de la Web para que sólo muestre el nuevo div en el caso de los Clips. Añadir lo siguiente en Configuración > Código HTML Adicional / Sección <head> :

<script>
if ( 
  window.location.href.indexOf("/searchChannel/")>1 ||
  window.location.href.indexOf("portal/channels")>1 ||
  window.location.href.indexOf("/channels/")>1 ||
  window.location.href.indexOf("/searchPage/")>1 ||
  window.location.href.indexOf("portal/pages")>1 ||
  window.location.href.indexOf("/pages/")>1
)
{ $("html").addClass("channels"); }
</script>
<style>
.channels .xCountry { display:none; }
</style>

6: Filtros de búsqueda

Si se necesita crear filtros de búsqueda para campos personalizados, estos hay que definirlos en el archivo de configuración (config/Config.inc.php). Primero hay que especificar el nombre de los filtros y luego crear las funciones correspondientes a cada uno.

6.1: Creando los filtros (especificando los nombres)

El nombre de los filtros se especifica a través de la variable (arreglo asociativo) $CUSTOM_DB_FIELDS_LIST_FILTERS["clips"], asignando un arreglo con el listado de filtros (nombres) que estarán disponibles:

$CUSTOM_DB_FIELDS_LIST_FILTERS["clips"] = array("xCountryFilter"); // Arreglo con la lista de nombres de los nuevos filtros. Estos nombres son los que se pasarán como variables POST o GET

6.2: Creando los filtros (definiendo las funciones)

Una vez especificados los nombres, es necesario definir la función de filtrado para cada uno de ellos. Las funciones de los filtros serán las encargadas de generar las cláusulas SQL adicionales que se incluirán en la consulta SQL que lista los Clips. Las funciones se definen como se muestra a continuación (también en el archivo config/Config.inc.php) - Ejemplo con el campo de país:
NOTA: Las funciones son nombradas de la siguiente manera: prefijo "custom_db_fields_list_filter_clips_" + nombre del filtro.

function custom_db_fields_list_filter_clips_xCountryFilter()
{
  // Para este ejemplo, el filtro restringirá el listado de Clips en función del valor de país   

  // El valor de entrada se encontrará en una variable GET o POST
  // NOTA: Las variables GET y POST son "saneadas" por el sistema automáticamente
  $input_value = "";
  if ( isset($_POST["xCountryFilter"])) $input_value = $_POST["xCountryFilter"];
  else if ( isset($_GET["xCountryFilter"])) $input_value = $_GET["xCountryFilter"];

  // Preparar el arreglo de retorno con valores por defecto (todo en blanco)
  $clauses=array(
                  "query_select_field" => "", // Ej. "otra_tabla.x_nombre_otro_campo" -> Dejar en blanco si no se necesita seleccionar datos de otra(s) tabla(s) diferentes a "clips"
                  "query_select_from" => "",  // Ej. "otra_tabla" -> Dejar en blanco si no se necesita operar en otra(s) tabla(s) diferentes a "clips" 
                  "query_select_where" => ""  // Ej. "clips.xCountryFilter = '%$input_value%'"
              );

  // validar el valor de entrada y generar las cláusulas de consulta (SQL) adicionales
  if ($input_value!='')
  {
    $clauses["query_select_where"]= " clips.x_country LIKE '%$input_value%' ";
  }
  
  return $clauses;
}  

Listo: Ahora el filtro está creado y cuando se pase la variable POST o GET "xCountryFilter" (en el formulario de búsqueda o en la función clips > list del API) el filtro se aplicará en la función de listado.

6.3: Usando el filtro con el API

Para usar el filtro con la función de listado de Clips, del API (clips > list), simplemente hay que pasar el nombre del filtro como variable POST.

6.4: Añadiendo el filtro a los filtros de búsqueda de Clip existentes, en el Front-End

Ejemplo:
Supongamos que se desea incluir el nuevo filtro de país en la página de búsqueda de Clips (en área de Filtros). Editar el archivo de plantilla - utilizado por defecto para incluir los filtros de búsqueda de Clips cuando el tema V2 está seleccionado- public/frontend/v2/inc_search_filters_clips.tpl y añadir lo siguiente (color azul y rojo) después de <form name="filterForm"... en el lugar deseado:

NOTAS
- 1: Vale la pena destacar que, para imprimir el valor en la página/plantilla, como se está haciendo dentro de una cadena de texto (string) Javascript, es mejor utilizar la etiqueta {k.html.xCountryFilter_escaped} por seguridad.
- 2: Si algún caracter especial, con tilde, etc. no se muestra correctamente, será necesario convertir (con el editor de texto) la codificación del archivo de plantilla de ANSI a UTF-8.
- 3: Las etiquetas {k.lang.fe....} muestran un texto según el idioma del Front-End: {k.lang.fe.country} = "País", {k.lang.fe.filter_any} = "Cualquiera"

7: Campos Asociativos/Combinados

Los campos asociativos/combinados son aquellos resultantes de un "JOIN" entre un campo de la tabla "clips" y el campo de otra tabla. Para explicarlo con un ejemplo: Supongamos que el campo "x_country" de los ejemplos, en vez de almacenar el nombre de los países, lo que almacena es el código de país (ES, FR, GB, etc.), y el nombre del país se encuentra en otra tabla de la base de datos. Pues bien, eso también es posible. Contactar para más información sobre cómo añadir las cláusulas SQL adicionales.