Agrega una página de ajustes a tu plugin con la Settings API

En la primera parte de esta serie creamos Caja Foro, un plugin que agrega una invitación al foro al final de cada entrada. Funciona, pero tiene un problema: para cambiar el texto hay que editar el código. Hoy le damos una página de ajustes en el panel, como cualquier plugin profesional.

Antes de empezar

• Necesitas el plugin de la primera parte, «Tu primer plugin de WordPress en 15 minutos». Si no lo tienes, créalo primero: esta entrada parte desde ahí.
• Trabaja en un sitio de pruebas y guarda una copia de caja-foro.php antes de editarlo.

Cómo guarda WordPress los ajustes

WordPress tiene una tabla llamada wp_options donde cada plugin puede guardar sus datos con un nombre. Y tiene una herramienta, la Settings API, que se encarga de lo tedioso: dibujar el formulario, verificar que quien guarda tenga permiso, protegerlo contra ataques y mostrar el mensaje «Ajustes guardados».

Nosotros guardaremos todo en una sola opción, caja_foro_opciones, que contendrá un pequeño arreglo con el título, el texto y el texto del botón.

Paso 1. Valores por defecto

Agrega esta función en caja-foro.php, debajo de la cabecera. Devuelve los ajustes guardados, completando con valores por defecto lo que falte:

function caja_foro_opciones() {
	$por_defecto = array(
		'titulo' => '¿Te quedó alguna duda?',
		'texto'  => 'Sigue la conversación en el foro.',
		'boton'  => 'Ir al foro',
	);
	$guardadas = get_option( 'caja_foro_opciones', array() );
	return wp_parse_args( $guardadas, $por_defecto );
}

wp_parse_args() mezcla los dos arreglos: lo guardado gana, y lo que no se ha guardado toma el valor por defecto. Así el plugin funciona desde el primer momento, aunque nadie haya entrado a los ajustes.

Paso 2. Agrega la página al menú Ajustes

add_action( 'admin_menu', 'caja_foro_menu' );

function caja_foro_menu() {
	add_options_page(
		'Caja Foro',               // título de la pestaña del navegador
		'Caja Foro',               // texto en el menú
		'manage_options',          // permiso necesario (administradores)
		'caja-foro',               // identificador de la página
		'caja_foro_pagina'         // función que dibuja la página
	);
}

function caja_foro_pagina() {
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}
	?>
	<div class="wrap">
		<h1>Caja Foro</h1>
		<form action="options.php" method="post">
			<?php
			settings_fields( 'caja_foro' );
			do_settings_sections( 'caja-foro' );
			submit_button();
			?>
		</form>
	</div>
	<?php
}

Guarda y mira el panel: en Ajustes aparece Caja Foro. La página todavía está vacía porque falta registrar los campos.

• settings_fields() agrega campos ocultos de seguridad (un nonce) que demuestran que el formulario salió de tu panel.
• do_settings_sections() dibuja las secciones y campos que registraremos ahora.
• El formulario envía a options.php, el archivo de WordPress que guarda las opciones.

Paso 3. Registra la opción y los campos

add_action( 'admin_init', 'caja_foro_registrar_ajustes' );

function caja_foro_registrar_ajustes() {
	register_setting(
		'caja_foro',
		'caja_foro_opciones',
		array( 'sanitize_callback' => 'caja_foro_limpiar' )
	);

	add_settings_section(
		'caja_foro_principal',
		'Texto de la caja',
		'__return_false',
		'caja-foro'
	);

	$campos = array(
		'titulo' => 'Título',
		'texto'  => 'Texto',
		'boton'  => 'Texto del botón',
	);

	foreach ( $campos as $clave => $etiqueta ) {
		add_settings_field(
			'caja_foro_' . $clave,
			$etiqueta,
			'caja_foro_campo',
			'caja-foro',
			'caja_foro_principal',
			array(
				'clave'     => $clave,
				'label_for' => 'caja_foro_' . $clave,
			)
		);
	}
}

function caja_foro_campo( $args ) {
	$opciones = caja_foro_opciones();
	$clave    = $args['clave'];
	printf(
		'<input type="text" class="regular-text" id="caja_foro_%1$s" name="caja_foro_opciones[%1$s]" value="%2$s">',
		esc_attr( $clave ),
		esc_attr( $opciones[ $clave ] )
	);
}

Recarga Ajustes → Caja Foro: ahora verás los tres campos con sus valores por defecto.

Paso 4. Limpia lo que se guarda

Nunca guardes lo que llega de un formulario sin revisarlo. Esta función, que indicamos en sanitize_callback, se ejecuta antes de guardar:

function caja_foro_limpiar( $entrada ) {
	$limpio = array();
	foreach ( array( 'titulo', 'texto', 'boton' ) as $clave ) {
		$limpio[ $clave ] = isset( $entrada[ $clave ] )
			? sanitize_text_field( $entrada[ $clave ] )
			: '';
	}
	return $limpio;
}

sanitize_text_field() quita etiquetas HTML, saltos de línea y caracteres raros. Además, solo guardamos las tres claves que esperamos: si alguien intenta colar otra, se descarta.

Paso 5. Usa los ajustes en la caja

Reemplaza la función caja_foro_agregar() de la primera parte por esta versión:

function caja_foro_agregar( $contenido ) {
	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		return $contenido;
	}
	return $contenido . caja_foro_html();
}

function caja_foro_html() {
	$o   = caja_foro_opciones();
	$url = function_exists( 'bbp_get_forums_url' ) ? bbp_get_forums_url() : home_url( '/' );

	return sprintf(
		'<div class="caja-foro"><p><strong>%s</strong> %s</p><a class="caja-foro-boton" href="%s">%s</a></div>',
		esc_html( $o['titulo'] ),
		esc_html( $o['texto'] ),
		esc_url( $url ),
		esc_html( $o['boton'] )
	);
}

Separamos el HTML en su propia función, caja_foro_html(), porque en la próxima parte la reutilizaremos para el shortcode.

Fíjate en la regla de seguridad: limpiar al guardar (sanitize_text_field) y escapar al mostrar (esc_html, esc_url, esc_attr). Siempre las dos.

Paso 6. Prueba

1. Ve a Ajustes → Caja Foro, cambia el título y guarda. Debe aparecer «Ajustes guardados».
2. Abre una entrada: la caja muestra el texto nuevo.
3. Prueba escribir <b>hola</b> en un campo y guardar: las etiquetas desaparecen. La limpieza funciona.

Un detalle profesional: el enlace «Ajustes» en la lista de plugins

add_filter( 'plugin_action_links_' . plugin_basename( __FILE__ ), 'caja_foro_enlace_ajustes' );

function caja_foro_enlace_ajustes( $enlaces ) {
	$url = admin_url( 'options-general.php?page=caja-foro' );
	array_unshift( $enlaces, '<a href="' . esc_url( $url ) . '">Ajustes</a>' );
	return $enlaces;
}

Ahora, en Plugins, bajo «Caja Foro» aparece un enlace directo a sus ajustes.

¿Te funcionó? Muéstranos en el foro tu página de ajustes. Y si quieres un reto: agrega una casilla para activar o desactivar la caja sin desactivar el plugin.