Vamos a continuar viendo como se pueden preparar los ajustes desde una página ya existente, ya vimos en la entrada anterior como se puede hacer desde una página independiente y ahora utilizaremos las funciones del API para conectar estas páginas y añadir los ajustes del plugin.

Vamos a ver un código diseccionado trozo a trozo y luego lo mostraremos completo para que se pueda modificar a nuestras necesidades. Comenzaremos creando la acción y creando la función de configuración.

//ejecutar la función de la sección de ajustes
add_action( 'admin_init', 'prowp_settings_init' );

function prowp_settings_init() {
	
    //crea la nueva sección de ajustes en la página Ajustes>lectura
    add_settings_section( 'prowp_setting_section', 'Configuración del plugin', 'prowp_setting_section', 'reading' );

    // registra las opciones de cada ajuste
    add_settings_field( 'prowp_setting_enable_id', '¿Habilitar el plugin?',	'prowp_setting_enabled', 'reading', 'prowp_setting_section' );
	
    add_settings_field( 'prowp_saved_setting_name_id', 'Su nombre',	'prowp_setting_name', 'reading', 'prowp_setting_section' );

    // registra el ajuste para almacenar la matriz de valores
    register_setting( 'reading', 'prowp_setting_values', 'prowp_sanitize_settings' );
	
}

En primer lugar utilizamos el conector de acción admin_init con el fin de cargar la funcion personalizada prowp_setting_init() antes de representar cualquier página de administración. Tras ello podemos invocar la función add_setting_section() con el fin de crear la nueva sección en la línea 7.

• El primer parámetro que se le pasa es la ID exclusiva de la sección (recordemos que el espacio de nombres es muy importante en WordPress)
• El segundo es el nombre que se mostrará en nuestra página
• El tercero es la nombre de la función de retrollamada para mostrar la sección
• El cuarto indica a que página de ajustes añadir la sección, siendo los valores predeterminados (general, writing, reading, media, privacy, permalink)

Una vez que hemos registrado la sección de ajustes debemos de registrar las opciones de cada uno de los ajustes. Para ello utilizamos la función add_setting_field() en cada campo que queremos crear y cuyos parámetros son:

• El primero es la ID exclusiva del campo
• El segundo es el título del campo que se muestra a la izquierda del input
• El tercero es el nombre de la función de retrollamada utilizada para mostrar el campo.
• El cuarto es la página de ajustes en la que mostrar el campo
• El quinto es el nombre de la sección a la que se le añade el campo, en nuestro caso, prowp-setting_section que se creó al invocar la función add_setting_section() en la línea 7

Continuamos registrando el campo del ajuste, por medio de register_setting(), donde deberemos utilizar una matriz para guardarlos en una única tupla de la BBDD, registrando de este modo únicamente prowp_setting_values y que mantiene tres argumentos.

• Primero: el grupo de opciones
• Segundo: el nombre de la opción que debe de ser exclusivo y empleado para recuperar el valor de la opción
• Tercero (opcional): Función personalizada para sanear los valores de las opciones (pese a ser opcional es muy recomendable)

Siguiendo con nuestro ejemplo vamos a sanear los valores con la siguiente función:

function prowp_sanitize_settings( $input ) {
	
	$input['enabled'] = ( $input['enabled'] == 'on' ) ? 'on' : '';
	$input['name'] = sanitize_text_field( $input['name'] );
	
	return $input;
	
}

Al sanear nuestras opciones vemos que el primero llamado enabled, se trata de una casilla de verificación y que solo puede tener dos valores (seleccionado o no), y aquí usamos un operador ternario de PHP para determinar el valor de enabled; si esta activa se considera «on» en caso contrario está desactivada y se considera of. Saneamos tambien el nombre como un campo de texto impidiendo etiquetas PHP, HTML y XML.

Una vez que ya tenemos que tenemos todos los registros y saneamientos listos, es momento de pasar a crear las funciones personalizadas que hemos creado para mostrarlas.

Comenzaremos con prowp_setting_section()

// seccion de ajustes
function prowp_setting_section() {
    echo 'Configure las caracteristicas del plugin';
}

En esta función se puede introducir el texto que queramos, como explicación, subtitulo…

Y finalmente creamos las funciones para nuestros campos, empezando por el campo enabled:

// crea la seccion del chackbox
function prowp_setting_enabled() {
	
    //carga las opciones del plugin
    $prowp_options = get_option( 'prowp_setting_values' );

    //muestra la casilla de verificación
    echo '<input '.checked( $prowp_options['enabled'], 'on', false ).' name="prowp_setting_values[enabled]" type="checkbox" /> Enabled';

}

En esta función, lo primero que realizamos es la carga de la matriz (si existe) que guarda los datos de las opciones y al crear el input se utiliza la función checked() de wordpress que tiene tres parámetros.

• Los dos primeros son valores para comparar y si son ciertos mostrara checked=»checked»
• El tercero determina si queremos reproducir el valor o devolverlo, al estar en false significa que queremos devolverlo.

Tras ello, mostramos el nombre del campo de entrada, que debe de ser el mismo que se haya registrado antes. Al guardar los datos en una matriz es necesario definir el nombre de la misma, indicándole al API de ajustes donde y que tiene que guardar, en nuestro caso es:  prowp_deting_values[enabled]

Finalmente solo nos queda crear la función del segundo campo de ajustes, el nombre:

// crea el ajuste del campo de texto para guardar el nombre
function prowp_setting_name() {

	//carga el valor de la opcion
    $prowp_options = get_option( 'prowp_setting_values' );

    //muestra el campo de texto del formulario
    echo '<input type="text" name="prowp_setting_values[name]" value="'.esc_attr( $prowp_options['name'] ).'" />';
	
}

Al igual que antes lo primero que hacemos es cargar la matriz de opciones mostrando el campo de entrada con el mismo nombre definido en la función register_setting() y se le da la salida.

De esta forma debemos de tener un resultado similar al siguiente:

Y cuyo código total sería:

//ejecutar la función de la sección de ajustes
add_action( 'admin_init', 'prowp_settings_init' );

function prowp_settings_init() {
	
    //crea la nueva sección de ajustes en la página Ajustes>lectura
    add_settings_section( 'prowp_setting_section', 'Configuración del plugin', 'prowp_setting_section', 'reading' );

    // registra las opciones de cada ajuste
    add_settings_field( 'prowp_setting_enable_id', '¿Habilitar el plugin?',	'prowp_setting_enabled', 'reading', 'prowp_setting_section' );
	
    add_settings_field( 'prowp_saved_setting_name_id', 'Su nombre',	'prowp_setting_name', 'reading', 'prowp_setting_section' );

    // registra el ajuste para almacenar la matriz de valores
    register_setting( 'reading', 'prowp_setting_values', 'prowp_sanitize_settings' );
	
}

function prowp_sanitize_settings( $input ) {
	
	$input['enabled'] = ( $input['enabled'] == 'on' ) ? 'on' : '';
	$input['name'] = sanitize_text_field( $input['name'] );
	
	return $input;
	
}

// seccion de ajustes
function prowp_setting_section() {
    echo '

Configure las caracteristicas del plugin

';
}

// crea la seccion del chackbox
function prowp_setting_enabled() {
	
    //carga las opciones del plugin
    $prowp_options = get_option( 'prowp_setting_values' );

    //muestra la casilla de verificación
    echo '<input '.checked( $prowp_options['enabled'], 'on', false ).' name="prowp_setting_values[enabled]" type="checkbox" /> Enabled';

}

// crea el ajuste del campo de texto para guardar el nombre
function prowp_setting_name() {

	//carga el valor de la opcion
    $prowp_options = get_option( 'prowp_setting_values' );

    //muestra el campo de texto del formulario
    echo '<input type="text" name="prowp_setting_values[name]" value="'.esc_attr( $prowp_options['name'] ).'" />';
	
}

Espero que os haya servido de ayuda, y en las siguientes entradas comenzaremos con la integración de los plugins en wordpress…