🛠 Añadir un campo personalizado a los ajustes de WordPress: add_settings_field

Los ajustes estándar de WordPress cubren la mayoría de las tareas cotidianas. Pero tarde o temprano necesitará un campo que no existe en el administrador: un número de teléfono de la empresa en la sección General, una clave API de servicio, un campo de número de licencia o un texto de pie de página.

Los desarrolladores de temas y plugins manejan esto a través de la API de Ajustes, un conjunto de funciones de WordPress para registrar sus propias secciones y campos en las páginas de ajustes estándar. La función clave es add_settings_field(): añade un campo personalizado a una sección y página especificadas.

Al final de este tutorial tendrá un código funcional que muestra un campo de texto en el administrador, guarda el valor en la base de datos y lo muestra en el sitio. Sin plugins de terceros, solo la API integrada.

💡 Resumen rápido:

• Prepare su entorno: cree un tema hijo o instale el plugin Code Snippets para que su código no se borre cuando el tema padre se actualice.
• Registre el ajuste: llame a register_setting() en el hook admin_init, de lo contrario WordPress no guardará los datos del campo.
• Añada una sección y un campo: use add_settings_section() para un nuevo bloque y add_settings_field() para el campo de entrada dentro de él.
• Muestre el valor: use get_option() en cualquier parte de una plantilla para mostrar los datos guardados en el sitio.

Qué es add_settings_field y dónde se usa

La función add_settings_field() apareció en WordPress 2.7.0 y ha seguido siendo la herramienta principal para ampliar las páginas de ajustes desde entonces. Según la documentación de WordPress, añade un nuevo campo a una sección existente en una de las páginas de administración.

Lo que esto significa en la práctica. Puede mostrar un campo adicional en cualquier página estándar: General (general), Escritura (writing), Lectura (reading), Comentarios (discussion) o Medios (media). Y si creó su propia página de ajustes mediante add_options_page(), el campo también irá allí.

Escenarios típicos:

• Un campo «Teléfono de contacto» en la sección de ajustes generales, para que el gestor no necesite tocar código para actualizar el número.
• Un campo de clave API para su plugin, donde el usuario introduce la clave en el administrador en lugar de editar wp-config.php.
• Un grupo de campos para una sección personalizada (teléfono, correo electrónico, dirección), usando add_settings_section() más múltiples llamadas a add_settings_field().

Nota: add_settings_field() solo muestra el HTML del campo. El guardado real lo maneja register_setting(); sin ella, WordPress ignorará los datos introducidos.

Sintaxis y parámetros de add_settings_field

La firma de la función, cuatro parámetros obligatorios y dos opcionales:

1
add_settings_field(
2
    string $id,
3
    string $title,
4
    callable $callback,
5
    string $page,
6
    string $section = 'default',
7
    array $args = array()
8
);

Repasemos cada parámetro.

$id, el identificador único del campo. Este valor se convierte en el atributo HTML id de la etiqueta <input> que muestre en la función callback. Use un prefijo para evitar conflictos, por ejemplo myplugin_phone_number.

$title, la etiqueta del campo que se muestra en el administrador a la izquierda de la entrada. Escríbala con claridad: «Teléfono de contacto», «Clave API del servicio».

$callback, el nombre de su función que muestra el HTML del campo (input, textarea, select). Aquí es donde escribe echo. La función debe declararse previamente; pásela como una cadena: 'my_field_callback'.

$page, el slug de la página de ajustes. Valores estándar: general, reading, writing, discussion y media. Si creó una página personalizada, use su slug. Determina dónde aparece el campo.

$section (opcional), el slug de la sección a la que pertenece el campo. Por defecto es 'default', que es la sección superior de la página. Si creó su propia sección mediante add_settings_section(), especifique su ID aquí.

$args (opcional), un array de ajustes adicionales. Las claves admitidas son label_for (el valor del atributo HTML for en la <label>) y class (una clase CSS para el contenedor del campo).

Todos los parámetros y su comportamiento se describen en la guía oficial de la API de Ajustes en WordPress.org.

Ejemplo práctico: añadir un campo de texto a Ajustes generales

Vamos a unirlo todo. El objetivo: mostrar un campo de texto «Teléfono de contacto» en la página Ajustes → Generales, guardar el valor introducido y recuperarlo con get_option().

El código va en el archivo functions.php del tema hijo o mediante el plugin Code Snippets. La segunda opción es más segura: el fragmento no se borrará con una actualización del tema.

1
// Callback to output the section description
2
function my_custom_section_callback() {
3
    echo 'Contact information for the organization. Phone number is displayed in the site footer.';
4
}
5
 
6
// Callback to output the input field
7
function my_phone_field_callback() {
8
    $value = get_option( 'my_contact_phone', '' );
9
    echo '<input 
10
        name="my_contact_phone" 
11
        type="text" 
12
        id="my_contact_phone" 
13
        value="' . esc_attr( $value ) . '" 
14
        class="regular-text" 
15
        placeholder="+1 (555) 123-4567" 
16
    />';
17
}
18
 
19
// Register the section and field
20
function my_register_settings() {
21
    // Register the setting — without this, data will not be saved
22
    register_setting( 'general', 'my_contact_phone' );
23
 
24
    // Add a section to the General settings page
25
    add_settings_section(
26
        'my_contact_section',            // Section ID
27
        'Contact Information',            // Section title
28
        'my_custom_section_callback',    // Callback for description
29
        'general'                         // Page slug
30
    );
31
 
32
    // Add a field to the section
33
    add_settings_field(
34
        'my_contact_phone',              // Field ID
35
        'Contact Phone',                  // Field label
36
        'my_phone_field_callback',       // Callback to render the field
37
        'general',                        // Page slug
38
        'my_contact_section'             // Section ID
39
    );
40
}
41
add_action( 'admin_init', 'my_register_settings' );

Qué sucede aquí línea por línea. register_setting() le dice a WordPress: guarda el valor del campo my_contact_phone como una opción en la tabla wp_options cuando se haga clic en «Guardar cambios» en la página general.

add_settings_section() crea un nuevo bloque con el encabezado «Contactos de la organización» en la página de ajustes generales. La función callback my_custom_section_callback() muestra el texto de descripción encima de los campos de la sección.

add_settings_field() coloca nuestro campo dentro de esa sección y lo vincula a la función callback my_phone_field_callback(), que renderiza <input type="text">. La función get_option() inserta el valor guardado en el atributo value, y esc_attr() escapa la salida.

Todo el código está enganchado a admin_init, que se dispara cuando se carga el administrador y garantiza que la sección y el campo ya estén registrados para cuando se renderice la página de ajustes.

Después de añadir el código, abra wp-admin/options-general.php y verá el resultado:

Introduzca un número, haga clic en Guardar cambios y el valor se escribirá en la base de datos. Para mostrar el número de teléfono en el sitio, use get_option() en cualquier parte de una plantilla:

1
$phone = get_option( 'my_contact_phone', '' );
2
if ( $phone ) {
3
    echo '<a href="tel:' . esc_attr( $phone ) . '">' . esc_html( $phone ) . '</a>';
4
}

Dónde colocar el código y cómo probar

Tres opciones de colocación, de peor a mejor.

Tema padre (functions.php). No haga esto. Cuando el tema se actualiza, el archivo se sobrescribe y su personalización desaparece.

Tema hijo (****functions.php** del tema hijo).** Una opción viable para ediciones vinculadas a un sitio específico. El código sobrevive a las actualizaciones del tema padre.

Plugin Code Snippets. La mejor opción para pruebas y mantenimiento a largo plazo. Puede activar/desactivar el fragmento con un clic, sin tocar el sistema de archivos. Además obtiene aislamiento: si el fragmento causa un error fatal, WordPress lo desactiva automáticamente y el sitio no se caerá.

Procedimiento de prueba. Cree una copia de seguridad completa del sitio (base de datos + archivos), esta es una precaución estándar para cualquier edición del administrador. Añada el código usando el método elegido. Abra la página de ajustes y verifique que el campo se muestra. Introduzca un valor y guárdelo. Compruebe la persistencia: actualice la página, el campo debería aparecer relleno con lo que introdujo.

Si el campo no aparece, compruebe que no confundió el ID de la sección en el parámetro $section de add_settings_field(). Un error común: la sección se crea con un ID, pero se pasa uno diferente al campo.

Videotutorial sobre el tema

Para reforzar el material, vea un recorrido en vídeo de la API de Ajustes por un desarrollador de WordPress. Muestra el ciclo completo: registrar una sección, añadir un campo, guardar y mostrar en el sitio.

⁉️🤔 Preguntas frecuentes

¿Puedo añadir múltiples campos a una sección?

Sí. Llame a add_settings_field() tantas veces como campos necesite. Pase el mismo ID de sección en el parámetro $section. Cada campo recibe un $id único y su propio callback. El orden de las llamadas a add_settings_field() determina el orden de los campos en la página.

¿Cómo añado un select, textarea o checkbox en lugar de un campo de texto?

El tipo de campo se establece dentro de la función callback mediante HTML. Para un select, construya un <select> con etiquetas <option>; para un textarea, una etiqueta <textarea>; para un checkbox, <input type="checkbox">. El valor se guarda de la misma manera mediante register_setting() y se recupera mediante get_option(). Los detalles están solo en el HTML.

¿Necesito escapar la salida en el callback?

Sí, absolutamente. Use esc_attr() para valores de atributos (value, name, id) y esc_html() para texto entre etiquetas. Esto protege contra XSS y asegura que los caracteres especiales en el valor guardado no rompan el diseño.

¿Puedo añadir un campo a la página de mi propio plugin?

Sí. Cree una página mediante add_options_page() o add_menu_page(), luego registre secciones y campos de la misma manera. Use el slug de su página en el parámetro $page de add_settings_field(). La mecánica no es diferente de las páginas estándar.

¿Qué pasa si el valor no se guarda después de hacer clic en «Guardar cambios»?

Es casi seguro que omitió register_setting(). Sin esta función, WordPress no sabe que el campo necesita ser guardado y lo ignora al enviar. Compruebe: el primer parámetro de register_setting() debe coincidir con el nombre de la página (por ejemplo, 'general'), y el segundo debe coincidir con el atributo name de su campo.

Conclusión: cuándo tiene sentido ampliar los ajustes del administrador

La API de Ajustes de WordPress es un mecanismo maduro y estable: add_settings_field() no ha cambiado desde la versión 2.7 y sigue siendo relevante en 2026. Añadir sus propios campos al administrador se justifica en tres casos:

• Está desarrollando un tema o plugin y quiere dar al usuario una interfaz para introducir datos, sin editar código.
• Necesita un campo de ajuste a nivel de sitio (número de teléfono, clave API, ID de catálogo) y debe ser accesible a través del administrador, no mediante wp-config.php.
• Está personalizando el sitio de un cliente y quiere que el gestor pueda cambiar los datos por sí mismo sin contactar al desarrollador.

Si el campo es solo para usted y cambia una vez al año, es más sencillo codificar el valor de forma fija. La API de Ajustes brilla cuando los ajustes los usa alguien que no es el desarrollador.

Empiece de forma sencilla: añada un campo de texto siguiendo el ejemplo anterior. Una vez que domine el flujo básico, registro, callback, guardado, salida, pase a selects, grupos de campos y páginas de ajustes personalizadas. ¿Y con qué tipo de campo trabaja más a menudo? Háganoslo saber en los comentarios.