Snippets en MODX Revolution: cómo funcionan, creación, métodos de llamada, paso de parámetros

En MODX Revolution CMF, un snippet es un código PHP que se puede llamar en campos de recursos, chunks, plantillas, plugins u otros snippets. Un snippet se utiliza para realizar una función específica: extracción de datos, cálculos, modificación de datos, etc.

Normalmente, los extras de MODX que se encargan de crear la funcionalidad del sitio utilizan snippets para llamar a plantillas: phpthumb, pdoResources y otros.

Es la herramienta principal para añadir contenido dinámico de la base de datos a tus páginas, manipular datos en la base de datos o realizar operaciones complejas.

Crear snippet

Abre el menú contextual haciendo clic con el botón derecho del ratón en el árbol de elementos de la pestaña Snippets del panel Elementos. Puedes utilizar el botón Crear snippet; se abrirá el formulario de creación de snippets en una nueva página.

Si haces clic en Creación rápida de snippet, el formulario aparecerá en una ventana emergente.

También puede utilizar el botón situado a la derecha del encabezado del panel Snippets en el árbol de elementos. El formulario de creación se abrirá en una página separada.

Si tiene instalado el paquete tagElementPlugin, puede crear snippets cuando se abre la ventana de edición rápida. Para ello, seleccione el nombre del snippet en el editor y pulse las teclas Ctrl+Enter.

Si el script no encuentra un snippet con este nombre, el sistema ofrecerá crear uno nuevo.

Para evitar confusiones al nombrar otros elementos (chunks, plugins, TV), puedes usar php al principio del nombre, así será fácil entender que estás llamando a un snippet.

phpArticleGetTags php.Article.GetTags php-Article-GetTags php_Article_GetTags

También es útil crear una estructura en los nombres de los snippets que se parezca a un modelo orientado a objetos, por ejemplo:

php.Article.GetTags php.Article.UpdateHitsCount php.Article.GetRating php.Article.Articles.GetPopular php.Tags.GetList php.Author.GetRating

A continuación, los elementos del árbol de snippet se ordenan convenientemente. Además, en el código, en los lugares donde se llama al snippet, se comprende mejor qué funcionalidad tiene. 

Uso

Un snippet siempre debe devolver algún valor. Si realmente devuelve un valor vacío, puede utilizar return true.

Por ejemplo, ha creado el snippet php.snippetName y ha escrito código que muestra la fecha y la hora actuales:

return date("F j, Y, g:i a");

Puedes llamarlo en una página, plantilla u otro chunks utilizando la sintaxis:

[[php.snippetName]]

Cuando se genera la página, el resultado de la ejecución del snippet se insertará en la ubicación de la etiqueta si el script devuelve un resultado.

Hay casos en los que un snippet no devuelve el resultado en sí, sino que lo escribe en placeholder; en ese caso, primero debe llamar al snippet y, a continuación, especificar un placeholder en el lugar donde desea que se muestre el resultado. Creemos el placeholder date:

$modx->setPlaceholder('date', date("F j, Y, g:i a"));

Ahora puedes llamarlo después del snippet:

[[php.snippetName]] <p>Fecha actual: [[+date]]</p>

Caché

Los snippets se pueden llamar en forma almacenada en caché y no almacenada en caché.

<!-- cashing --> [[php.snippetName]] <!-- non-cashing --> [[!php.snippetName]]

El snippet almacenado en caché se guarda en un archivo durante la primera generación. Durante las siguientes llamadas, se recuperará del archivo. Esto es necesario para reducir el tiempo de ejecución del script y la carga de la base de datos. Hasta que se borre la caché de una página, un snippet o todo el sitio, por ejemplo, al guardar un snippet o borrar la caché del sitio.

El snippet no almacenable en caché se ejecutará cada vez que se cargue la página.

La regla es sencilla: utilice llamadas en caché siempre que pueda. Llame a las no almacenables en caché solo cuando necesite constantemente datos reales o realice una acción en el momento de la carga de la página (obtener parámetros $_GET; aumentar el recuento de visitas a la página; comprobar la autorización del usuario, etc.).

También puede utilizar una llamada no almacenable en caché durante la fase de desarrollo de un sitio web para evitar errores, pero no es una buena idea. Una vez que el sitio esté listo, tendrá que comprobar cuidadosamente una gran cantidad de código. Es mejor desactivar el almacenamiento en caché de elementos en la configuración del sistema MODX. Vaya a Configuración del Sistema, busque cache_scripts y establezca el valor en No.

Hay un matiz desagradable: el mismo snippet en una página llamado varias veces devolverá el mismo resultado. Por ejemplo, has llamado a un snippet que debería seleccionar un banner publicitario aleatorio. El mismo banner se mostrará en todas partes de la página. Para evitarlo, puedes pasar diferentes parámetros a los snippets al llamarlos, de modo que se ejecuten por separado.

Modificadores

Un snippet se puede utilizar como modificador de salida. En resumen, podemos añadir un modificador a una etiqueta (un chunk o un campo de recurso, por ejemplo), y este modificador cambiará el valor de salida.  MODX tiene modificadores y filtros integrados, pero si queremos crear los nuestros propios, necesitamos utilizar snippets. Por ejemplo, creemos un script phpH1 que muestre el título de la página en la etiqueta h1:

$input = $modx->getOption('input', $scriptProperties, ''); $output = $input; if ($output != '') { $output = '<h1>' . $output . '</h1>'; } return $output;

Y utilízalo en la plantilla:

[[*pagetitle:phpH1]]

Como habrás adivinado, devolverá el título de la página en la etiqueta h1. Pero puedes escribir una lógica más compleja. Puedes acceder a toda la potencia de PHP dentro del snippet.

xPDO y MODX API

MODX API es un modelo orientado a objetos de nuestro sistema MODX. Te permite realizar todas las mismas acciones que haces manualmente dentro del panel de administración, solo que en forma de código php. Y además hay muchas acciones útiles. En un snippet que utiliza MODX API puedes obtener campos y campos de variables de plantilla del recurso actual:

// resource field $pagetitle = $modx->resource->get('pagetitle'); // TV value by TV name $tvValue = $modx->resource->getTVValue('tvName'); // TV value by TV id $tvValue = $modx->resource->getTVValue(1);

O otro recurso por ID:

$resource = $modx->getObject('modResource', 1); $pagetitle = $resource->get('pagetitle'); $tvValue = $resource->getTVValue('tvName');

También podemos crear consultas SQL avanzadas en la base de datos utilizando xPDO. xPDO es un modelo de base de datos orientado a objetos que nos ofrece la comodidad y la seguridad de las consultas SQL. xPDO está incluido en el objeto $modx. Es similar a PHP PDO, pero es una versión mejorada escrita por los desarrolladores de MODX.

Por ejemplo, obtener recursos con el identificador de plantilla id=2 y mostrar sus títulos en la página:

// Crear una nueva consulta SQL. $q = $modx->newQuery('modResource'); // Añadir una condición WHERE a la consulta SQL. $q->where(array( 'template' => '2' )); // Establecer campos para SELECT $q->select(array( 'id', 'pagetitle' )); // obtener una lista de recursos que se ajusten a nuestra condición $res = $modx->getCollection('modResource', $q); // Mostrar el campo pagetitle de estos recursos. foreach ($res as $r) { echo $r->get('pagetitle'); }

Pero normalmente necesitamos algo más que mostrar una lista de encabezados: queremos utilizar alguna plantilla HTML. Normalmente, los chunks se utilizan para crear plantillas de elementos en snippets.

getChunk

La base de un desarrollo competente en PHP y MODX es la separación de la lógica y la presentación. Debes separar el código PHP y el diseño HTML. Como probablemente ya sabes, MODX utiliza chunks para el diseño. Puedes obtener un chunk en un snippet de esta manera:

$html = $modx->getChunk('tplSomeChunk');

También podemos pasar al chunk una matriz de parámetros que estarán disponibles en el chunk como placeholders.

$html = $modx->getChunk('tplSomeChunk', array( 'placeholderName' => 'Oleg', 'placeholderAge' => 23 ) );

En el primer parámetro del método $modx->getChunk() escribimos el nombre del chunk, en el segundo parámetro, una matriz de datos que se pueden utilizar como marcadores de posición en el propio chunk, por ejemplo:

<p>Hola, me llamo [[+placeholderName]], tengo [[+placeholderAge]] años.</p>

Cuando obtenemos datos de una base de datos, cada fila (si obtenemos recursos, una fila equivale a un recurso) es una matriz de datos. El conjunto de sus campos depende de los que hayamos especificado al crear la consulta xPDO.

[ 0 => [ 'id' => 1, 'pagetitle' => 'value', ... ], 1 => [ 'id' => 2, 'pagetitle' => 'value2', ... ] ]

Así que podemos pasar esta matriz de datos directamente al segundo parámetro de la llamada al chunk. En este snippet de código de ejemplo, obtenemos los recursos utilizando el método getCollection() y los mostramos como un chunk tplSomeChunk:

$output = ''; $q = $modx->newQuery('modResource'); $q->select(array( 'id', 'pagetitle' )); $resources = $modx->getCollection('modResource', $q); if ($resources) { foreach ($resources as $res) { $resArr = $res->toArray(); // Convertimos el objeto en una matriz normal $output .= $modx->getChunk('tplSomeChunk', $resArr); } } return $output;

Utilizamos el método toArray() para convertir el objeto modResource en una matriz php y utilizarlo como argumento.

Esto se debe a que cuando utilizamos getCollection(), getObject() y métodos similares, obtenemos una matriz de objetos MODX, no una matriz php normal. Cuando seleccionamos una lista de recursos utilizando getCollection(), obtenemos una matriz de objetos modResource. Si seleccionamos usuarios, obtendríamos una matriz de objetos modUsers con sus métodos disponibles.

En el ejemplo con recursos, necesitamos obtener exactamente los objetos, de modo que los métodos get(), getTVValue() y otros métodos de recursos estén disponibles en nuestro código.

Pero si solo necesitamos obtener una matriz de la base de datos y mostrarla en la página, podemos obtener una matriz de datos en lugar de objetos. Para ello, cree una consulta xPDO de la misma manera, pero no la pase a getCollection(), sino que ejecútela como una consulta SQL normal.

$output = ''; // Crear nueva consulta xPDO $q = $modx->newQuery('modResource'); $q->select(array( 'id', 'pagetitle' )); // Realizar una consulta SQL como PHP PDO $q->prepare(); $q->stmt->execute(); $resources = $q->stmt->fetchAll(PDO::FETCH_ASSOC); foreach ($resources as $resource) { $output = $modx->getChunk('tplSomeChunk', $resource); } return $output;

Este método aumenta la velocidad del snippet porque no se crean objetos MODX, sino que utilizamos las matrices PHP habituales.

Parámetros

Los snippets también pueden aceptar parámetros de entrada. Esto le permite configurar diferentes escenarios de comportamiento del script. Es similar a los parámetros de las URL. Para pasar parámetros, utilice esta sintaxis:

[[snippetName? &parameter1=`value1` &parameter2=`[[*pagetitle]]` &parameter3=`[[php.My.Snippet]]` &parameter4=`[[+placeholder]]` &parameter4=`[[++systemVar]]` ]]

No solo se pueden pasar valores estáticos, sino también otros snippets, placeholders, campos de recursos y variables del sistema a los valores de los parámetros.

Dentro del código del snippet, puedes acceder a los valores de los parámetros utilizando el método $modx->getOption(). Al hacerlo, puedes establecer un valor predeterminado. Por ejemplo:

$parameter1 = $modx->getOption('parameter1', $scriptProperties); // establecer valor predeterminado $parameter2 = $modx->getOption('parameter2', $scriptProperties, 'Привет');

Creo que hemos aclarado todos los matices básicos. Los Snippets te ayudan a llevar tus sitios MODX Revolution al siguiente nivel y a no experimentar limitaciones en el desarrollo. Por lo tanto, te aconsejo que los aprendas.