JavierSam: 5. Configuración de las funciones de su Tema

domingo, 14 de julio de 2013

5. Configuración de las funciones de su Tema

(El artículo original y en inglés, fue publicado el 27 de octubre de 2012)

ThemeShaper es el sitio del Equipo de Temas de Automattic, que, en junio de 2009, publicaron una muy popular serie de 11 artículos de Ian Stewart, bajo el título: How To Create a WordPress Theme: The Ultimate WordPress Theme Tutorial (Como crear un Tema de WordPress: el tutorial definitivo).
El año pasado, reflotaron y actualizaron ese tutorial. Esta vez con 16 artículos a cargo de Michelle Langston: The ThemeShaper WordPress Theme Tutorial: 2nd Edition (Tutorial de Temas de WordPress de ThemeShaper. Segunda edición).
Me propongo traducir libremente esas 16 entradas (además de la introducción) e ir publicándolas a medida que las tenga listas.
Al final de cada entrada va el listado con todas las entradas de este tutorial.

Vamos a empezar a agregarle cosas a la estructura de archivos que ya definimos.
Primero, vamos a agregar algunas funciones PHP a nuestro Tema. Estas funciones cumplirán con una variedad de propósitos, incluyendo:

agregar soporte para características de WordPress como fondos y cabeceras personalizados, formatos de entrada, etc.
configurar los valores predefinidos del Tema,
actuar como “contenedores” de código que podremos reutilizar a lo largo del desarrollo del Tema.

Archivos que vamos a editar o crear en esta lección

functions.php
inc/template-tags.php
inc/tweaks.php

Si usted es nuevo en esto de PHP, entonces piense en las funciones como “máquinas” que realizan una tarea específica, cuando sea que la necesitemos. Definimos las funciones de esta manera:

function mi_funcion() {
  ...contenido de la función
}

Después que hemos definido una función, podemos llamarla desde los archivos de nuestro Tema donde sea que necesitemos que ejecuten su magia. El llamado a una función puede ser tan simple como escribir el nombre de la función seguido de punto y coma:

<div>
<?php mi_funcion(); ?>
</div>

Otros llamados a funciones son un poquito más complejos:

<div>
<?php mi_segunda_funcion ( 'parámetro 1', 'parámetro 2' ); ?>
</div>

En el ejemplo precedente, le estamos pasando parámetros a nuestra función. Los parámetros son un tipo de variable que se pueden introducir en, o pasar a, una función. La función los utilizará para producir la salida final. Es algo así como las máquinas elongadoras de monedas de los zoológicos y museos.
¡Vamos a estar llamando a muchas funciones en nuestro Tema!

functions.php

Comencemos, sin demora. Abra el archivo functions.php, ubicado en el directorio theme creado en la lección anterior. Al comienzo del mismo, pegue lo siguiente:

<?php
/**
 * Shape functions and definitions
 *
 * @package Shape
 * @since Shape 1.0
 */

Por si usted es nuevo en esto de PHP: comenzamos el archivo con la etiqueta de apertura de PHP: <?php
A continuación tenemos un bloque de texto comentado con algo de documentación integrada: una pequeña descripción del archivo, seguido por las etiquetas PHPdoc: “@package y @since”. Puede leer más sobre Documentación Integrada en el Codex de WordPress.
Unas palabras sobre los comentarios PHP. Puede que le sean familiares los comentarios en HTML: en PHP, encontrará dos tipos de comentarios, los de una línea y los multilínea. Los comentarios multilínea empiezan con /* y terminan con */, al tiempo que los comentarios de una sola línea comienzan con una doble barra inclinada (//). Los comentarios son perfectos para la documentación integrada, ya que PHP los ignora al procesar el código.

$content_width

$content_width es una variable global que define el ancho máximo del conenido (como el de las imágenes subidas) en su Tema. Evita que grandes imágenes sobresalgan del área del contenido principal. Deberemos definir el valor de $content_width para ajustarse al ancho del área de nuestro contenido principal. Si volvemos a nuestra estructura HTML, esta área es el div con el id #content. Usaremos CSS para definir el ancho del div, sin embargo, todavía no tenemos el CSS. Entonces, por ahora, le diré que el div será de 654px de ancho, y volveremos aquí más adelante, durante la lección sobre CSS.
En functions.php, deje una línea libre después del último */ y pegue el siguiente código:

/**
 * Set the content width based on the theme's design and stylesheet.
 *
 * @since Shape 1.0
 */
if ( ! isset( $content_width ) )
    $content_width = 654; /* pixels */

Así, $content_width queda definida. Las variables en PHP llevan un signo de pesos (“$”) antes de su nombre y un punto y coma (“;”) después del valor asignado.

shape_setup()

A continuación vamos a crear una función que establezca los valores predefinidos del Tema y que registre soporte para varias características de WordPress. Deje una línea en blanco luego de la declaración de $content_width, y agregue esto:

if ( ! function_exists( 'shape_setup' ) ):
/**
 * Sets up theme defaults and registers support for various WordPress features.
 *
 * Note that this function is hooked into the after_setup_theme hook, which runs
 * before the init hook. The init hook is too late for some features, such as indicating
 * support post thumbnails.
 *
 * @since Shape 1.0
 */
function shape_setup() {
 
    /**
     * Custom template tags for this theme.
     */
    require( get_template_directory() . '/inc/template-tags.php' );
 
    /**
     * Custom functions that act independently of the theme templates
     */
    require( get_template_directory() . '/inc/tweaks.php' );
 
    /**
     * Make theme available for translation
     * Translations can be filed in the /languages/ directory
     * If you're building a theme based on Shape, use a find and replace
     * to change 'shape' to the name of your theme in all the template files
     */
    load_theme_textdomain( 'shape', get_template_directory() . '/languages' );
 
    /**
     * Add default posts and comments RSS feed links to head
     */
    add_theme_support( 'automatic-feed-links' );
 
    /**
     * Enable support for the Aside Post Format
     */
    add_theme_support( 'post-formats', array( 'aside' ) );
 
    /**
     * This theme uses wp_nav_menu() in one location.
     */
    register_nav_menus( array(
        'primary' => __( 'Primary Menu', 'shape' ),
    ) );
}
endif; // shape_setup
add_action( 'after_setup_theme', 'shape_setup' );

Este código está bien comentado, de manera que puede darse una buena idea de qué es lo que hace. ¿Se dio cuenta que en su mayoría se trata de llamados a funciones? ¿Puede reconocer las funciones a las que se le pasan parámetros?
Hagamos un recorrido por este código, función por función.
Estamos llamado a dos archivos que estarán alojados en el directorio inc/, template-tags.php y tweaks.php. Vamos a crear esos dos archivos un poquito más adelante en esta lección.
Después, llamamos a la función load_theme_textdomain(). Esto le dice a WordPress que queremos que nuestro Tema esté disponible para traducción y que los archivos de traducción se pueden encontrar en el directorio de nuestro Tema, dentro de un directorio llamado “languages”. Si va a crear un Tema para WordPress, debería siempre intentar su mejor esfuerzo para asegurarse que todo sea traducible. Nunca se sabe cuando usted, u otra persona, vaya a necesitar contenido codificado disponible en otro lenguaje. Hay varias maneras de hacer que un texto sea traducible, y trataremos el tema cuando lleguemos a ese punto. Pero, si no puede esperar, I18n for WordPress Developers es una gran introducción.

Muy bien, sigamos adelante. Las dos funciones siguientes agregan soporte, respectivamente, para los vínculos a sus RSS feeds en la cabecera y para el Formato de Entrada "Aside" (Minientrada). La última función registra una ubicación de menú de navegación, que utilizaremos para nuestro menú principal.
Luego, cerramos la función con una llave derecha “}”, y la llamamos a nuestro Tema "enganchándola" dentro de otra función de WordPress:
add_action( 'after_setup_theme', 'shape_setup' );
En pocas palabras, le estamos diciendo a WordPress que ejecute shape_setup() cuando ejecute la función after_setup_theme(). ¿Notó que add_action() es, en sí misma, una función, y que le estamos pasando dos parámetros?
En próximas lecciones le vamos a hacer agregados a functions.php, pero, por ahora, hemos terminado con él.
Puede haber notado que functions.php no tiene la etiqueta de cierre de PHP (“?>”). Cuando un archivo contiene PHP puro, es más seguro omitir la etiqueta de cierre. ¿Por qué? Porque nos ayuda a evitar los errores causados por dejar espacios en blanco después de la etiqueta de cierre de PHP.

template-tags.php y tweaks.php

¿Recuerda estas líneas del archivo functions.php ya vistas previamente en esta lección?:

/**
     * Custom template tags for this theme.
     */
    require( get_template_directory() . '/inc/template-tags.php' );
 
    /**
     * Custom functions that act independently of the theme templates
     */
    require( get_template_directory() . '/inc/tweaks.php' );

Siga adelante y cree los archivos template-tags.php y tweaks.php en su directorio inc. ¿Por qué estamos colocando estas funciones personalizadas en archivos separados? Mayormente, para mantener limpio a nuestro archivo functions.php, y para mantener modular al Tema. Si no necesita estas funciones, simplemente borre estas líneas.

template-tags.php

Primero lo primero. ¿Qué es, exactamente, una etiqueta de plantilla ("template tag")? Una función, ¡por supuesto! (“Función” parece ser una palabra mágica en esta lección). Específicamente, son funciones de WordPress que se insertan en su Tema para mostrar información dinámica. Puede aprender todo lo que quiera saber sobre template tags en el Codex de WordPress.
La mayoría de las veces, agregaremos a nuestro Tema etiquetas de plantilla en cualquier lugar que las querramos. Sin embargo, habrá veces en las que pondremos múltiples etiquetas de plantilla para producir una sinfonía de datos. Y, ya que, en nuestro Tema, a algunas de esas "sinfonías" las "ejecutamos" más de una vez, es una buena idea juntar todas esas etiquetas de plantilla en una función que podemos llamar cuando sea que querramos utilizarlas. Entonces, piense en todas las funciones que vamos a agregar a este archivo como "mini-sinfonías" de etiquetas de plantilla que trabajan juntas para producir un bloque de información; por ejemplo: una oración que dice cuándo fue publicada una entrada y por quién; o una serie de vínculos "entrada anterior" y "entrada siguiente"; o una lista de comentarios. Esa es la idea. "Escribimos" la sinfonía una vez y la "ejecutamos" muchas veces. O, en términos más técnicos: definimos la función una vez y la llamamos muchas veces.
Para evitar que esta entrada quede demasiado larga, en próximas lecciones volveremos a template-tags.php para agregarle funciones a medida que las necesitemos. Por ahora, simplemente agreguemos, al principio del archivo, la documentación básica.

<?php
/**
 * Custom template tags for this theme.
 *
 * Eventually, some of the functionality here could be replaced by core features
 *
 * @package Shape
 * @since Shape 1.0
 */

Una última cosa: “Eventually, some of the functionality here could be replaced by core features” (Con el tiempo, algunas de las funciones de aquí podrían ser sustituidas con características básicas). Las funciones que agregamos aquí representan unas funcionalidades que sería genial que formaran parte de las características de fábrica de WordPress. Todo esto tendrá más sentido después que hayamos agregado las funciones, lo prometo.
Ahora, con seguridad, también podemos omitir la etiqueta PHP de cierre de este archivo.

tweaks.php

Las funciones que colocaremos en este archivo no involucran etiquetas de plantilla. En su lugar, mejorarán nuestro Tema mediante la modificación de algunas características de fábrica de WordPress. Estas funciones realizan tareas detrás de bambalinas para agregarle "sorpresas" a nuestro Tema.
En la parte superior del archivo pegue la habitual información de documentación.

<?php
/**
 * Custom functions that act independently of the theme templates
 *
 * Eventually, some of the functionality here could be replaced by core features
 *
 * @package Shape
 * @since Shape 1.0
 */

Luego, pegue las siguientes funciones.

/**
 * Get our wp_nav_menu() fallback, wp_page_menu(), to show a home link.
 *
 * @since Shape 1.0
 */
function shape_page_menu_args( $args ) {
    $args['show_home'] = true;
    return $args;
}
add_filter( 'wp_page_menu_args', 'shape_page_menu_args' );
 
/**
 * Adds custom classes to the array of body classes.
 *
 * @since Shape 1.0
 */
function shape_body_classes( $classes ) {
    // Adds a class of group-blog to blogs with more than 1 published author
    if ( is_multi_author() ) {
        $classes[] = 'group-blog';
    }
 
    return $classes;
}
add_filter( 'body_class', 'shape_body_classes' );
 
/**
 * Filter in a link to a content ID attribute for the next/previous image links on image attachment pages
 *
 * @since Shape 1.0
 */
function shape_enhanced_image_navigation( $url, $id ) {
    if ( ! is_attachment() && ! wp_attachment_is_image( $id ) )
        return $url;
 
    $image = get_post( $id );
    if ( ! empty( $image->post_parent ) && $image->post_parent != $id )
        $url .= '#main';
 
    return $url;
}
add_filter( 'attachment_link', 'shape_enhanced_image_navigation', 10, 2 );

La primera función, shape_page_menu_args, está relacionada con nuestro menú de navegación principal. Previamente, en shape_setup(), registramos soporte para menúes de navegación. Si no se han configurado menúes de navegación, en su lugar, WordPress mostrará una lista de Páginas (controladas por wp_page_menu()). Esta función agrega a esta lista de páginas un vínculo a la página inicio.

Con la segunda función, shape_body_classes(), estamos agregando a la etiqueta <body> de nuestro Tema una nueva clase CSS: ‘group-blog’. Hablaremos sobre clases en el body en la lección sobre la plantilla Header de WordPress, pero, por ahora, simplemente entienda que las clases en el body nos dan la posibilidad de estilizar partes de nuestro Tema dependiendo de varias condiciones (como, por ejemplo, el tipo de página que estamos viendo, o el número de autores que tengamos publicados).
Finalmente, la tercera función, shape_enhanced_image_navigation(), agrega, en las páginas de adjuntos, un “#main” al final de los vínculos de imagen anterior/siguiente (que los construiremos en una futura lección). Recordemos que “#main” es el nombre de ID del div que envuelve nuestros contenido y áreas de widgets. Los IDs son, también, anclas dentro de la página. Cuando la gente pincha en sus vínculos de imagen anterior/siguiente, no quieren tener que desplazarse hacia abajo para poder ver cada imagen.
Y eso es todo con respecto a tweaks.php. Recuerde, no se necesita etiqueta de cierre PHP al final del archivo.

¡Fiuuu! Esto sí que es un montón de funciones. Hemos establecido una gran cantidad de trabajo de base en esta lección. Aún queda mucho más por venir, así que manténganse sintonizados.

Sumario de entradas

No hay comentarios:

Publicar un comentario

Lo que escriba a continuación será revisado antes de publicarse.
Gracias por tus comentarios.