WordPress: Shortcodes API

Los shortcodes son códigos que se utilizan en las entradas/páginas para realizar tareas que sólo se podrían hacer mediante programación y dárselas al usuario como herramienta para construir las entradas/páginas. Para crear nuevos shortcodes se puede hacer desde functions.php o desde un plugin , ya sea mediante código o incluyendo algún archivo. Existen 2 tipos los que no encierran contenido y los que si. Para ambos tipo es común la forma de crearlos:

add_shortcode( $tag , $func )

 

• tag, el nombre del shortcode [tag saludo = “hola”]
• func, función que llama para realizar el tratamiento. Ésta función recibe 3 parámetros:
  • atts, los parámetros del propio shortcode (saludo) en forma de array asociativo:
  • array (‘saludo’ => ‘hola’)
  • las claves del array serán convertidas siempre a lower
  • content, el contenido del shortcode si éste encierra contenido.(ver cerrar shortcodes más adelante)
  • tag, el nombre del shortcode

Dentro de func se usará la función shortcode_atts,

shortcode_atts( $pairs , $atts )

 

• pairs, array con los valores por defecto de los parámetros que va a recibir
• atts, array parámetros enviados por el shortcode

Esta función combina ambos arrays para obtener uno solo con todos los parámetros y llenos de datos. Se combina con la función php extract:

extract( $array_asociativo )

Esta función extrae las claves del array asociativo y las convierte en variables con sus correspondientes valores.

Unos ejemplos de shortcodes:

// [bartag foo=”foo-value”] function bartag_func( $atts ) { extract( shortcode_atts( array( ‘foo’ => ‘something’, ‘bar’ => ‘something else’, ), $atts ) ); return “foo = “.$foo; } add_shortcode( ‘bartag’, ‘bartag_func’ ); //El resultado será foo = foo-value

Para hacer shortcodes que encierran contenido se deberá definir la función con el parámetro content = ‘’

//[callout align=”center” width=”400″] Texto dentro de la caja [/callout] function st_callout( $atts, $content = null ) { extract(shortcode_atts(array( ‘width’ => ”, ‘align’ => ” ), $atts)); $style; if ($width || $align) { $style .= ‘style=”‘; if ($width) $style .= ‘width:’.$width.’px;’; if ($align == ‘left’ || ‘right’) $style .= ‘float:’.$align.’;’; if ($align == ‘center’) $style .= ‘margin:0px auto;’; $style .= ‘”‘; } return ‘<div ‘.$style.’>’ . do_shortcode($content) . ‘</div><div></div>’; } add_shortcode(‘callout’, ‘st_callout’);

do_shortcode ($string) acepta cualquier tipo de texto. Si la cadena contiene un shortcode procesará ese código.

Anuncios

WordPress: Admin API

Para insertar un nuevo item en el menú de administrador se utiliza la función, unida al hook admin_menu:

hookname <= add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, [$icon_url], [$position] )

 

• page_title, es el título que tendrá la página a la que se accede con este menu
• menu_title, será el título que tenga el menu en sí
• capability, es el permiso necesario para que se vea el menu , normalmente ‘manage_options’. (http://codex.wordpress.org/Roles_and_Capabilities)
• menu_slug, nombre único por el cual es referenciado este item.
• function, es el nombre de la  función que renderiza la página de opciones. (Si la función está dentro de un objeto se llamara mediante: array ($obj, $function_name) que represetnará  a $obj::function_name)
• icon_url, url donde está el icono para el item.
• position, entero que define la posición dentro del menú
  • 2 Dashboard
  • 4 Separator
  • 5 Posts
  • 10 Media
  • 15 Links
  • 20 Pages
  • 25 Comments
  • 59 Separator
  • 60 Appearance
  • 65 Plugins
  • 70 Users
  • 75 Tools
  • 80 Settings
  • 99 Separator

La función devuelve un hookname usado internamente para seguir las llamadas a la página a la que apunta el menú, por ejemplo para asignarle un css particular.

Para añadir un submenú a éste menu item,  unido al mismo hook que la anterior, se utilizará la función:

1	hook_sufix <= add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function );

 

• parent_slug, es una cadena que debe de coincidir con el menu_slug definido en la función anterior. Hay que tener en cuenta que con esta función se pueden crear submenús a menús ya existentes conociendo su parent_slug, aunque también con una función propia de cada menú:

 

Para Dashboard (una de las dos):

add_submenu_page( ‘index.php’, … );

add_dashboard_page();

 

Para Posts (una de las dos):

add_submenu_page( ‘edit.php’, … );

add_posts_page()

 

Para Media (una de las dos):

add_submenu_page( ‘upload.php’, … );

add_media_page()

Para Links (una de las dos):

add_submenu_page( ‘link-manager.php’, … );

add_links_page()

 

Para Pages (una de las dos):

add_submenu_page( ‘edit.php?post_type=page’, … );

add_pages_page()

 

Para Comments (una de las dos):

add_submenu_page( ‘edit-comments.php’, … );

add_comments_page()

 

Para Custom Post Types:

add_submenu_page( ‘edit.php?post_type=your_post_type’, … );

 

Para Appearance (una de las dos):

add_submenu_page( ‘themes.php’, … );

add_theme_page()

 

Para Plugins (una de las dos):

add_submenu_page( ‘plugins.php’, … );

add_plugins_page()

 

Para Users (una de las dos):

add_submenu_page( ‘users.php’, … );

add_users_page()

 

Para Tools (una de las dos):

add_submenu_page( ‘tools.php’, … );

add_management_page()

 

Para Settings (una de las dos):

add_submenu_page( ‘options-general.php’, … );

add_options_page()

Éstas funciones tienen los mismos parámetros que add_submenu_page, salvo el  parent_slug:

hook_suffix <= add_XX_page( $page_title, $menu_title, $capability, $menu_slug, $function )

Devuelven un hook_suffix usado internamente para seguir las llamadas a la página a la que apunta el menú, por ejemplo para asignarle un css particular, la ayuda contextual, que se unen a los hook:
admin_head-hook_suffix ó load-hook_suffix, repectivamente.

Otra opción interesante es añadir la ayuda contextual del menú mediante:

add_contextual_help (hook_sufix, $texto)

WordPress: Settings API

Para entender los plugins se debe estudiar antes la settings API, ésta hace que no tengamos que preocuparnos del tratamiento del formularios enviados e incluso de la renderización de los mismos.

Para que un formulario se actualice automáticamente, sin necesidad de estarnos preocupando por el control de las variables del formulario deberemos registrar el conjunto de variables que representa el formulario para ello usaremos la función:

register_setting( $option_group, $option_name, [$sanitize_callback] )

• option_group, es el nombre virtual de una variable o conjunto de variables option_name, es el nombre de la variable en la tabla wp_options (tipo diccionario)
• sanitize_callback, es una función que recibe como argumento el valor de la opción para validarla o tratarla

Esta función relaciona el nombre virtual con la/s variable/s de wp_options. Para no llenar de variables independientes las filas de la tabla wp_options se intenta agrupar las variables en arrays asociativos para guardar los datos. Dicho esto, para una sola variable se podrá guardar como tal o en un array con una sola variable previendo futuras modificaciones.

Con la función anterior le decimos a WordPress que existen las variables, pero ¿cómo hacemos para usarlas?. Simplemente cuando se defina el formulario de configuración del plugin (ver más adelante), justo después de la etiqueta form usaremos la función:

settings_fields( $option_group )

• option_group, es el mismo que el definido en la función anterior register_settings.

Esta función hace que las actualizaciones de los datos del formulario se hagan sin preparar el fichero de tratamiento de las variables $_POST. Pero aún existe un problema, y es que cuando el plugin se acaba de instalar,  y no está activo aún, no existe ese par en la tabla wp_options. Esto se resuelve con hook especial que ejecuta una función cuando se activa el plugin, que además inicializa los valores por defecto en la base de datos:

register_activation_hook($fichero , $funcion)

• fichero, es el fichero donde se encuentra $funcion

1. función, es la función que se ejecutará y que probablemente contenga la función que cree el registro en la tabla wp_options de la base de datos:

   add_option ($nombre, $valor, $no_se_usa, [$autoload])

   • nombre, es el nombre del registro de la base de datos al cual se asociarán los datos
   • valor, son los datos a guardar, normalmente arrays para no llenar la tabla de variables independientes
   • no se usa, es un parámetro que se usa para mantener la compatibilidad y es un espacio en blanco (‘ ‘).
   • autoload, indica si se cargará automáticamente cuando se ejecute la función wp_load_alloptions(). Su valor será true o false.

   Existe además un hook que se ejecuta cuando se desactiva el plugin, para deshacer los cambios:

   register_deactivation_hook($fichero, $funcion) delete_option( $option ) update_option( $option, $newvalue )

   
   (delete_option y update_options realizan operaciones sobre la tabla wp_options)

   Hasta aquí la actualización automática de los formularios. Ahora se verá cómo construir los formularios.

   Construcción de los formularios
   La función que construye la página de las opciones de un plugin ha de mantener esta estructura:

   <div> <h2>Your Plugin Name</h2> <form method=”post” action=”options.php”> <?php settings_fields( ‘option-group’ ); ?> <input type=”text” name=”nombre_wp_options” value=”<?php echo get_option(‘nombre_wp_options’); ?>” /> <?php do_settings_sections(__FILE__) ?> <p><input type=”submit” value=”<?php _e(‘Draft’) ?>” />   </p> <p><input type=”submit” value=”<?php _e(‘Save Changes’) ?>” /></p> </form> </div>

   Los elementos obligatorios son:
   

   • div.wrap
   • form method post, action options.php
   • p.submit
   • input type submit.button-primary

   
   El formulario se ha construido a mano mediante el input y la función get_option. Observar que el parámetro name del input es el mismo que el de get_option, NO ES CASUALIDAD. Hay que tener en cuenta que si la variable de get_option es un array se deberá obtener primero el valor:

   <?php $options = get_option(‘array’); $option = $options[‘key’]; ?> <div> <h2>Your Plugin Name</h2> <form method=”post” action=”options.php”> <?php settings_fields( ‘option-group’ ); ?> <input type=”text” name=”array[key]” value=”<?php echo $option ?>” /> . .

   Una vez más el parámetro name tiene un nombre singular que coincide con el dato que solicitamos a get_option. Para la construcción automática de los formularios, se usarán las funciones:

   add_settings_section( $id, $title, $callback, $page ); add_settings_field( $id, $title, $callback, $page,$section,[$args] );

   • id, es un identificador único.
   • title, el título de la sección/campo.
   • callback, es la función que renderizará  la sección/el campo y relacionará los datos con los del register settings
   • page, puede ser cualquier texto pero ha de coincidir en ambas funciones y en do_settings_section (ver más adelante). También puede usarse __FILE__ si es el mismo archivo el que contiene las opciones. Si se va a insertar campos en páginas de ajustes se usará: general, reading, writing, discussion, media, privacy o permalink.
   • section, en la función add_settings_field debe de coincidir con el id de add_settings_sections.
   • args, en la función add_settings_field son para pasarle parámetros a la función $callback para renderizar el campo.

   
   Estas funciones construyen las secciones en las que se dividen las páginas de opciones de los plugins:

   do_settings_sections( $page ) do_settings_fields( $page, $section )

   • page, deben de coincidir con las definidas en las funciones add_settings_field y add_settings_sections.
   • section, en la función do_settings_fields debe de coincidir con el id de add_settings_sections.

   
   Estas funciones se deberán usar dentro de la etiqueta HTML <form> y renderizan el formulario asociado a la sección o una parte de una sección particular, respectivamente.

   Un ejemplo de todo junto, en la función del hook admin_init:

   <div> <h2>Your Plugin Name</h2> <form method=”post” action=”options.php”> <?php settings_fields( ‘plugins_options’ ); ?> <?php do_settings_sections(__FILE__) ?> <p><input type=”submit” value=”<?php _e(‘Draft’) ?>” /></p> <p> <input type=”submit” value=”<?php _e(‘Save Changes’) ?>”/> </p> </form> </div> add_action(‘admin_init’, ‘register_personalizar_texto_opciones’ ); function plugin_init() { register_setting( ‘plugin_options’, ‘plugin_options’ ); add_settings_section(‘formulario’, ‘Formulario’, ‘form_section_fn’, __FILE__); add_settings_field(‘campo_1’, ‘Campo 1’, ‘campo_1_fn’, __FILE__, ‘formulario’); } function form_section_fn(){ echo ‘<h2>Formulario</h2>’; } function campo_1_fn(){ $options = get_option(‘plugin_options’); echo “<input id=’plugin_text_string’ name=’plugin_options[text_string]’ type=’text’ value='{$options[‘text_string’]}’ />”; }

   Se observa en la última línea una serie de curiosidades como el uso de comillas dobles para interpretar el php dentro de ellas y otras como el empleo de {} para imprimir el valor del array[‘key’]

WordPress: Storage API

Cuando empezamos a desarrollar un proyecto necesitamos guardar ciertos datos, ya sean parte de las entradas u opciones de configuración. WordPress tiene una forma para cada cosa:

POSTMETAS, son datos que forman parte de las entradas y podemos crearlos y administrarlos desde el administrador (si no puedes cambiar las opciones de visualización) y se almacenan en la tabla wp_postmeta en forma de clave-valor, sólo que una clave puede tener más de un valor, en cuyo caso devolvería un array numérico (unique=false).

Para añadir datos al postmeta usaremos:

add_post_meta($post_id, $meta_key, $meta_value, [$unique])

• post_id, es el id del post donde queremos meter los metadatos
• meta_key, es la clave de del valor que queremos insertar
• meta_value, es el valor que asociamos a meta_key
• unique, (false) puede ser true o false e indica si la clave tendrá más de un valor o no. Si el valor es true y se intenta insertar una clave que ya existe devuelve false y no hace nada, si no existe la crea como única.

Para actualizar los metadatos:

update_post_meta($post_id, $meta_key, $meta_value, [$prev_value])

• prev_value, el valor anterior de la clave que quieres cambiar. Se usa para diferenciar los valores cuando la clave es la misma.

Para eliminar los metadatos:

delete_post_meta($post_id, $meta_key, [$meta_value])

Para rescatar los metadatos, existen varios métodos:

$meta_values = get_post_meta($post_id, $meta_key, [$single])

• single, (false) establece si recuperará un valor como string o un array numérico.

  $meta_values = get_post_custom_values($key, $post_id)

  
  (Cuando $key contiene más de un valor, devuelve array)

  OPTIONS, son datos independientes no están ligados a nada. Se almacenan en la tabla wp_options en forma de clave-valor, y una clave puede contener más de un valor, pero esta vez puede ser en forma de array asociativo.

  Para añadir datos se usará la función:

  add_option ($option_name, $valor, $no_se_usa, [$autoload])

  • option_name, es el nombre del registro de la base de datos al cual se asociarán los datos
  • valor, son los datos a guardar, normalmente arrays para no llenar la tabla de variables independientes
  • no se usa, es un parámetro que se usa para mantener la compatibilidad y es un espacio en blanco (‘ ‘).
  • autoload, indica si se cargará automáticamente cuando se ejecute la funciónwp_load_alloptions(). Su valor será true o false.

  
  Para actualizar los datos:

  update_option( $option_name, $nuevovalor )

  Para eliminar los datos:

  delete_option( $option_name )

  Para obtener los datos:

  string <= get_option( $option, [$default_value] )

  TABLAS. Por supuesto se puede crear una tabla para uso personal, mediante el uso de $wpdb

  global $wpdb; $sql = “CREATE TABLE $table_name ( id mediumint(9) NOT NULL AUTO_INCREMENT, time datetime DEFAULT ‘0000-00-00 00:00:00’ NOT NULL, name tinytext NOT NULL, text text NOT NULL, url VARCHAR(55) DEFAULT ” NOT NULL, UNIQUE KEY id (id) );”; require_once(ABSPATH . ‘wp-admin/includes/upgrade.php’); dbDelta($sql);

WordPress: Plugins y Widgets

Escribiendo Plugins/Widgets  (Ver primero settings API) (ver Plugin API y  Escribiendo un plugin)
Para crear un plugin/widget lo recomendable es crear una carpeta dentro de la carpeta plugins y dentro de ésta poner nuestros archivos, aunque si se trata de un solo archivo se puede colocar dentro de la carpeta plugins directamente. Lo importante es que el archivo principal del plugin tenga esta cabecera:

/* Plugin Name: Name Of The Plugin Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates Description: A brief description of the Plugin. Version: The Plugin’s Version Number, e.g.: 1.0 Author: Name Of The Plugin Author Author URI: http://URI_Of_The_Plugin_Author License: A “Slug” license name e.g. GPL2 */

 

Otro detalle importante es el nombre de las funciones dentro del plugin lo recomendable para que no se pisen con otras funciones de otros plugins es utilizar un sufijo como las iniciales de tu nombre o algo así.
También se puede incluir las funciones dentro de clases como métodos estáticos:
Versión normal

function email_friends($post_ID)  { $friends = ‘bob@example.org,susie@example.org’; mail($friends, “sally’s blog updated”, ‘I just put something on my blog: http://blog.example.com’); return $post_ID; }

 

Versión usando clases

class emailer { function send($post_ID)  { $friends = ‘bob@example.org,susie@example.org’; mail($friends,”sally’s blog updated”,’I just put something on my blog: http://blog.example.com’); return $post_ID; } } $myEmailClass = new emailer(); add_action(‘publish_post’, array($myEmailClass, ‘send’));

 

Para hacer que las funciones que se crean en los plugins se “enganchen” al wordpress se usan los hooks que ya se han comentado. Éstos son una API que permite extender la funcionalidad de wordpress, se dividen en 2 partes: las acciones y los filtros.

-Acciones, son como eventos que se disparan en distintos momentos de la ejecución como cuando publicamos un post. Aquí hay una lista de acciones que wordpress ejecuta en su core. También se pueden crear eventos personalizados para un determinado momento.

Para añadir nuestra función a un evento

add_action( $hook_name, $function_to_add, [$priority], [$accepted_args] )

 

• hook_name, el nombre del “evento” al que será vinculada la function_to_add
• function_to_add, nombre de la función,si se usa un array se entiende que es un método estático de una clase, donde array (‘clase’, ‘metodo’).
• priority (10), prioridad dentro de la pila de ejecución
• accepted_args (1), número de argumentos que acepta el “evento”.

Para ejecutar las funciones vinculadas a un evento propio (tener en cuenta que wordpress ejecuta los suyos, los de la lista) :

do_action( $hook_name, [$arg], [$argN] );

 

• args, argumentos que serán pasados a function_to_add, dependen de accepted_args de add_action

-Filtros, son funciones que se interponen entre la base de datos y el navegador y por donde se hacen pasar los datos para su tratamiento. La mayor parte de las entradas y salidas de wordpress se pasa a través de al menos un filtro. Esta es una lista de filtrosque wordpress ejecuta en algún momento, pero podemos crear nuestros propios filtros.  Entonces lo primero es crear la función que hará de filtro y luego vincularla a algún filtro:

add_filter( $hook_name, $function_to_add, $priority, $accepted_args )

 

Para aplicar el filtro definido (tener en cuenta que wordpress ya aplica los de la lista):

valor_filtrado <= apply_filters( $hook_name, $value, $argN … )

 

• value, es el valor que pasa por el filtro para ser tratado

Los Widgets, son mini programas que se ejecutan dentro de una zona de widget y pueden tener prácticamente cualquier funcionalidad. Para crear widgets, primero se necesita una zona para ello, registrarla en el administrador para poder ponerle contenido y renderizarla en la parte del usuario.

Las zonas de widgets se registran  en el fichero functions.php mediante el siguiente fragmento, por ejemplo:

function inicializar_widgets(){ register_sidebar( array( ‘name’ => __( ‘Nombre del área’, ‘nombre_tema’ ), ‘id’ => ‘identificador_unico_area_widget’, ‘description’ => __( ‘descripción’, ‘nombre_tema’ ), //etiqueta html que delimita los widgets. %1$s indica que use name… ‘before_widget’ => ‘<li id=”%1$s”  class=”widget-container %2$s”>’, ‘after_widget’ => ‘</li>’, //etiqueta html que delimita el titulo del widget ‘before_title’ => ‘<h3>’, ‘after_title’ => ‘</h3>’, ) ); } add_action( ‘widgets_init’, ‘inicializar_widgets’ );

 

Renderizando la zona de widget. Las zonas de widget se pueden colocar en cualquier parte del código para (header, footer….) para establecer la estructura como se quiera. Es interesante, antes de renderizar, comprobar si la zona contiene algún widget:

//comprueba que la zona de widget contenga algún widget if (is_active_sidebar(‘identificador_unico_area_widget’)) { echo ‘<div id=”before_header_area_content”>’; //muestra la zona de widget dynamic_sidebar(‘identificador_unico_area_widget’); echo ‘</div>’; }

 

Escribiendo el plugin. Ahora se puede comenzar con el escritura de un plugin, este es un ejemplo muy básico al cual se le implementará poco a poco más cositas (settings API o la llamada al mismo mediante un enlace del menú de administración). Recordar que la cabecera mostrada anteriormente es necesaria:

add_action (“wp_footer”, “holaMundo”); function holaMundo(){ echo ‘Hola Mundo’; }

 

Este plugin añade al footer la frase “Hola Mundo”, así de simple.

Complicando el plugin. Se va a crear una opción en el administrador para gestionar la frase que ponga en el footer. Para entenderlo mejor se describen los pasos a seguir:

1.- Modificar la función holamundo para que se pueda cambiar la frase:

function holaMundo(){ $texto = get_option(‘personalizar_texto’); echo $texto[‘texto’]; }

 

2.- Crear un item en el menú de administrador como una opción de Ajustes:

add_action(‘admin_menu’, ‘personalizar_texto_menu’); function personalizar_texto_menu(){ add_options_page(‘Personaliza el texto’, ‘Texto’, ‘manage_options’, ‘personaliza-texto-menu’, ‘personalizar_texto_opciones’); }

 

3.- Crear una página a la cual apunte el item anterior

function personalizar_texto_opciones(){ ?> <div> <form method=”post” id=”personalizar_texto_form” action=”options.php”> <?php settings_fields(‘personalizar_texto_section’); $options = get_option(‘personalizar_texto’); ?> <h2>Personaliza el Texto</h2> <p> <label>Texto: </label> <input type=”text” name=”personalizar_texto[texto]” id=”custom_text” value=”<?php echo $options[‘texto’]?>”/> </p> <p> <input type=”submit” name=”submit” value=”Update Options” /> </p> </form> </div> <?php } ?>

 

4.- Gestionar el formulario

add_action(‘admin_init’, ‘register_personalizar_texto_opciones’ ); function register_personalizar_texto_opciones() { register_setting( ‘personalizar_texto_section’, ‘personalizar_texto’ ); }

 

5.- Gestionar la activación del plugin

register_activation_hook(__FILE__, ‘personalizar_texto_activation’); function personalizar_texto_activation() { $options = array(); $options[‘texto’] = ‘Hola Mundo’; add_option(‘personalizar_texto’, $options, ”, ‘yes’); }

 

Escribiendo un widget. Un widget es un plugin que se engancha a wordpress en otro punto de ejecución usando un hook particular (plugins_loaded). Se empezará por un widget muy sencillo y complicarlo poco a poco:

function widget_miwidget($args) { extract($args); echo $before_widget; echo $before_title. “Hola Mundo”, “Mi Widget”). $after_title; echo “Hola Mundo”; echo $after_widget; } function miwidget_init() { wp_register_sidebar_widget(1, __(“Mi Widget”), “widget_miwidget”); } add_action(“plugins_loaded”, “miwidget_init”);

 

Las variables before_widget, before_title, after_title y after_widget fueron definidas cuando se registró la zona de widget. La función que registra el widget en la parte de administrador es:

wp_register_sidebar_widget ( $widget_id, $name, $cb_function, [$options], [$params]… )

 

• widget_id, el identificador único del widget
• name, nombre con el que se mostrará en el administrador
• cb_function, ($args_arr, [$params]) la función que llamará cuando se ejecute el widget.
• options, opciones del widget
• params, parámetros para cb_function

Complicando el widget, ahora el widget tendrá una interfaz de administración para cambiar la frase “Hola Mundo”. Los pasos serán

1.- Registrar la función que creará la interfaz, para ello hay que modificar la función miwidget_init:

function miwidget_init() { wp_register_sidebar_widget(1, __(“Mi Widget”), “widget_miwidget”); wp_register_widget_control(1, __(“Mi Widget”), “miwidget_customize”); }

 

La función wp_register_widget_control registra la función para configurar las opciones del widget:

wp_register_widget_control ( $widget_id, $name, $cb_function, [$options])

 

• widget_id, el identificador del widget que se quiere personalizar
• name, nombre con el que se mostrará en el administrador
• cb_function, la función que creará el formulario de administración del widget.
• options, opciones del widget

2.- La interfaz y la gestión de los datos

function miwidget_customize() { echo “<label>T&iacute;tulo</label><br/>”; echo ‘<input name=”miwidget_title” type=”text” value=”‘.get_option(‘miwidget_title_opt’).'”/>’; if (isset($_POST[“miwidget_title”])) update_option(“miwidget_title_opt”, attribute_escape($_POST[“miwidget_title”])); } register_activation_hook(__FILE__, ‘miwidget_activation); function miwidget_activation(){ add_option(“miwidget_title_opt”); }

Con respecto a la interfaz se observa:

• Que el formulario se crea a mano
• La inexistencia de las etiquetas <form> para el formulario
• La actualización de las variables se efectúa mediante el control de $_POST [ ]
• Se crea la opción cuando se activa el plugin

WordPress: El Loop

El loop es es componente activo básico de wordpress, el que muestra los post o páginas que se solicitan. Funciona mediante un bucle sobre una consulta predefinida que muestra los post o las páginas. El Loop usa el objeto WP_Query para cumplir su objetivo:
WP_Query ($args), devuelve los posts según la consulta generada mediante $args. (ver en Codex). Los componentes básicos del loop son:

• have_post(), comprueba si hay post que mostrar
• the_post(), actualiza el objeto $post con los valores del post actual y pasa al siguiente registro.
• propiedades $post   ( $post->propiedad)
  • ID,
  • post_author,
  • post_date,
  • post_date_gmt,
  • post_content,
  • post_title,
  • post_excerpt,
  • post_status,
  • post_comment_status,
  • post_ping_status,
  • post_password,
  • post_name,
  • post_to_ping,
  • post_pinged,
  • post_modified,
  • post_modified_gmt,
  • post_content_filtered,
  • post_parent,
  • post_guid,
  • post_menu_order,
  • post_type,
  • post_mime_type,
  • post_comment_count,
  • post_filter

Estos son los parámetros que acepta WP_Query para modificar la consulta, organizados por su cometido. Están expuestos como tienen que escribirse p.e:

$query = new WP_Query ($args)

NOTA: * puede usarse el signo – para excluir las IDs

• AUTOR*
  • ‘author = 25[,N1,N2,Nn…]’ {ID}
  • ‘author_name = slug_name’

• CATEGORIA*
  • ‘cat = 25[,N1,N2,Nn…]’ {ID}
  • ‘category_name = cat_slug1[,cat_slugN…]‘

• TAG
  • ‘tag_id = tagid1[,tag_idN…]‘
  • ‘tag = tag_slug1[,tag_slugN…]’ ó tag_slug1[+tag_slugN…]’
  • (+ significa AND)

• TAX
  • array (‘taxonomy_name’ => ’taxonomy_value’)
  • array (tax_query’ => array (
    • array (
      • ‘taxonomy’ = > ‘gente’,
      • ‘campos’ = > ‘slug’,
      • ‘terms’ => ‘bob’
      • )
    • )
  • );

• POST & PAGE
  • ‘p = 25′ {ID}
  • ‘name = post_slug’
  • ‘page_id = 25′ {ID}
  • ‘pagename = page_slug’ ó ‘pagename = parent_slug/page_slug’
  • ‘post_parent = page_id’   {ID, Devuelve las páginas hijas}
  • ‘post__in => array(id).     {Devuelve los post del array}
  • ‘post__not => array(id)’   {Excluye los post del array}

• TIPO & STATUS
  • ‘post_type=(string / array varios strings)’
    • ‘post’
    • ‘page’
    • ‘revision’
    • ‘attachment’  (post_status=inherit)
    • ‘any’ (salvo revisions y ‘exclude_from_search’=true)
    • Custom Post Types (p.e. ‘movies’)

• ‘post_status (string / array)’
  •  ’publish’
  •  ’pending’
  •  ’draft’
  •  ’auto-draft’
  •  ’future’ –  se publicará en el futuro
  •  ’private’
  •  ’inherit’
  •  ’trash’
  •  ’any’ – salvo exclude_from_search= true.

• PAGINATION
  • ‘posts_per_page=nº post por pag’ (-1= todos)
  • ‘posts_per_archive_page=nº post en archive’
  • ‘nopaging=(bool)’ – no paginacion?false
  • ‘paged=pag’ – ir a la pag pag
  • (get_query_var(‘page’))

• ORDER
  • ‘order=(string)’
    •  ’ASC’
    •  ’DESC’

• ‘orderby=(string)’ valores separados space
  •  ’none’ – No order .
  •  ’ID’ – Order by post id.
  •  ’author’ – Order by author.
  •  ’title’ – Order by title.
  •  ’date’ – Order by date.
  •  ’modified’ – Order by last modified date.
  •  ’parent’ – Order by post/page parent id.
  •  ’rand’ – Random order.
  •  ’comment_count’ – nº de comentarios
  •  ’menu_order’ – Order by Page Order.
  •  ’meta_value’
  •  ’meta_value_num’

Un ejemplo de utilización:

$query = new WP_Query( array( ‘post_type’ => ‘page’, ‘post__in’ => array( 2, 20 )));

Ejemplo básico de loop:

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?> //Código para el loop <?php endwhile; else _e(‘Sorry, no posts matched your criteria.’); endif; ?>

Modificando la consulta:

$myquery = new WP_Query(‘category_name=cat_1’); while ( $myquery->have_posts() ) : $myquery->the_post();?> <?php echo the_content(); // Los campos personalizados de una entrada, no se muestran en the_content() echo ‘Habitaciones:’.get_post_meta($post->ID, ‘habitaciones’, true). ‘<br/>’; echo ‘Superficie:’.get_post_meta($post->ID, ‘superficie’, true). ‘<br/>’; echo $post->post_author; endwhile; ?>

Una vez WP_Query hace la consulta y the_post() actualiza el objeto $post se puede extraer los datos del post solicitado fácilmente con las siguientes templates tags:

• the_title(), muestra el título del post actual
• the_content(), muestra el contenido del post actual
• the_author(), muestra el autor del post actual
• the_category(), muestra la categoría del post actual
• the_permalink(), muestra el enlace permanente del post actual
• the_time( l, j de F de Y ver)  {Viernes, 27 de Abril de 1978 para mes en número (m)}
• the_tags(), muestra los tags del post actual
• the_meta(), muestra los campos personalizados del post actual
• the excerpt(), muestra el resumen del post actual

Lo mismo pero sin echo:

• get_title(), idem a the_title() pero no escribe el valor, solo devuelve.
• get_content(), idem a the_content() pero no escribe el valor, solo devuelve.
• get_author(), idem a the_author() pero no escribe el valor, solo devuelve.
• get_category(), idem a the_category() pero no escribe el valor, solo devuelve.
• get_permalink(), idem a the_permalink() pero no escribe el valor, solo devuelve.
• get_time(ver), idem a the_time() pero no escribe el valor, solo devuelve.
• get_tags(),  idem a get_tags() pero no escribe el valor, solo devuelve.
• get_meta(), idem a get_meta() pero no escribe el valor, solo devuelve.
• get excerpt(), idem a get_excerpt() pero no escribe el valor, solo devuelve.

Además existen otras template tags útiles que nos ayudarán a construir contenido:

• wp_get_attachment_image, devuleve una <img>
• wp_get_attachment_image_src, devuelve array (url, ancho y alto de la imagen)

Existe otra manera de hacer una consulta más libre de lo que permite WP_Query, se trata del objeto global $wpdb

• $wpdb->prefix – Devuelve el prefijo de las tablas de la BBDD
• $wpdb->prepare (‘query’) – Asegura la query | como sprintf (%d=int; %s=string)
• $wpdb->escape(‘string’) – Escapa string
• $wpdb->query(‘query’) – Ejecuta query y devuleve nº filas afectadas. (para comandos como INSERT,UPDATE,DELETE)
• $wpdb->get_results(‘query’,tipo_salida) -Devuelve el resultado de query como tipo_salida
  • tipo_salida: ej: $prueba=$wpdb->get_result(‘SELECT * from <tabla> WHERE …’);
  • OBJECT: array de objetos de fila
  • *OBJECT_K: foreach ($prueba as $p) $p->post_title
  • ARRAY_A: array de arrays asociativos (nombre columnas=keys)
  • ARRAY_N: array de arrays numérico
• $wpdb->insert($tabla, $data[], $format[] )
• $wpdb->insert_id – Accede al valor del auto incremento.
• $wpdb->update($tabla, $data[], $where, $format[], $where_format[] )

Ejemplo para $wpdb->insert o update:

$wpdb->insert( ‘tabla’, array(‘column1’=>’value1,’column2’=>123), array(‘%s’,’%d’) );

Ejemplo de consulta con $wpdb

<?php global $wpdb; $tabla = $wpdb->prefix.’posts’; echo “SELECT guid FROM “.$tabla.” WHERE post_name LIKE ‘%slider%'”; $sliders = $wpdb->get_results(“SELECT guid FROM “.$tabla.” WHERE post_name LIKE ‘%slider%'”); foreach ($sliders as $slide) echo ‘<img src=”‘.$slide->guid.'” />’; ?>

WordPress: Principios básicos

Funcionamiento básico

Una vez que el usuario hace una petición, wordpress carga su core, desgrana la petición y recaba el contenido deseado mediante una petición a la base de datos para luego renderizar los datos mediante un tema elegido por nosotros.

Permisos

Los permisos que funcionan bien para actualizar y funcionar son propietario www-data y grupo ftpgroup. Todos los permisos han de ser 755 salvo .htaccess y /admin/index.php que serán 644, de todas formas con el plugin WSD security detectará rápidamente los permisos necesarios

Estructura básica

Los temas están basados en un style.css, como mínimo, que es donde se definen todos los datos del tema en forma de comentario; y compuestos de plantillas que a su vez se componen de template tags y bloques de éstas. Lo primero que hace wordpress es cargar el fichero functions.php que contiene todas las funciones que necesita el tema y no se encuentran en el core, luego llamará a una de las plantillas básicas que existen en todos los temas, configuradas en ajustes-lectura:

• index.php, para iniciar con los posts del blog
• page.php, para iniciar con una página

Luego cuando se solicite una página puede renderizarse con una plantilla personalizada. Para hacer una plantilla personalizada crearemos un fichero nuevo dentro del tema por ejemplo miplantilla.php y se pondrá esto al inicio:

/**
 * Template Name: Nombre de la plantilla
*/

Los template tags que forman las plantillas provienen de funciones del core o de functions.php, lógicamente sólo se tratarán los del core puesto que los otros son independientes de cada tema. Las partes de las templates básicas son header, sidebar, y footer, además del loop (del que se hablará más adelante).

Header, muestra la cabecera html (<head>), y la cabecera del blog/página
Sidebar, muestra la barra lateral, normalmente compuesta de widgets (ver más adelante), aunque los widgets también pueden existir en otros bloques.
Footer, muestra el footer del blog/página

get_XXX($slug);

Donde XXX pueder ser:

• header, esta función se utiliza para llamar a header.php
• sidebar, esta función se utiliza para llamar a sidebar.php
• footer esta función se utiliza para llamar a footer.php

Si se usa el parámetro slug llamará al fichero XXX-slug.php
Si se necesita incluir en la plantilla algún otro bloque que no sea alguno de los anteriores, como el loop por ejemplo, se usará:

get_template_part($nombre,[$slug])

• nombre, es el nombre del fichero.php que se quiere cargar
• slug, es el modificador del fichero.php (fichero-slug.php) si se deja en blanco wordpress buscará nombre.php, nombre-index.php

El formulario de búsqueda se podrá llamar desde la función:

get_search_form($echo)

• echo, permite mostrar el formulario o sólo devolverlo como cadena

Otras funciones interesantes son:

__($string,$contexto) //Devuelve la traducción _e($string,$contexto) //Escribe la traduccion (echo)

Se utilizan para traducir los textos del contexto donde se encuentren (tema, plugin,etc) mediante archivos .po, o .mo que funcionan como un diccionario.
Dentro de los bloques, existen necesidades que surgen como por ejemplo la ubicación de nuevos archivos css, javascript o imágenes estáticas, etc para esto está la función:

bloginfo($show)

$show, puede ser:

• name = nombre del blog
• description = descripción del blog
• admin_email = admin@example
• url = url raiz del sitio http://example/home [usar home_url(‘/’) ]
• wpurl                = url donde se encuentra el wp instalado [usar site_url(‘/’) ]
• stylesheet_directory  = http://example/home/wp/wp-content/themes/child-theme
• stylesheet_url  = http://example/home/wp/wp-content/themes/child-theme/style.css
• template_directory = http://example/home/wp/wp-content/themes/parent-theme
• template_url    = http://example/home/wp/wp-content/themes/parent-theme
• atom_url           = http://example/home/feed/atom
• rss2_url             = http://example/home/feed
• rss_url               = http://example/home/feed/rss
• pingback_url     = http://example/home/wp/xmlrpc.php
• rdf_url               = http://example/home/feed/rdf
• comments_atom_url    = http://example/home/comments/feed/atom
• comments_rss2_url    = http://example/home/comments/feed
• charset              = UTF-8
• html_type         = text/html
• language            = en-US
• text_direction   = ltr
• version               = 3.1

Aunque existen una serie de funciones que nos ayudan mejor a obtener las URLs:

home_url()	raiz del sitio	http://www.example.com
site_url()	Sitio donde está WP	http://www.example.com/wordpress
admin_url()	Directorio Admin	http://www.example.com/wp-admin
includes_url()	Directorio Includes	http://www.example.com/wp-includes
content_url()	Directorio Content	http://www.example.com/wp-content
plugins_url()	Directorio Plugins	http://www.example.com/wp-content/plugins
wp_upload_dir()	Upload directory URL	http://www.example.com/wp-content/uploads

En el caso de wp_upload_dir() devuelve un array que contiene:

[path] – ruta de fisica del archivo

[url] – url del archivo

[subdir] – subdirectorios desde /uploads

[basedir] – ruta la carpeta uploads

[baseurl] – url de la carpeta uploads

[error] – establecido en false.

Para cargar nuevos ficheros javascript o css se emplearán las siguientes funciones. Es importante llamar estas funciones antes de wp_head():

Para javascript
En la parte del usuario

wp_enqueue_script ( $handle, [$src], [$deps], [$ver], [$in_footer] );

En la parte del Administrador

admin_enqueue_script( $handle,[$src],[$deps], [$ver], [$in_footer] );

Para CSS:
Si se quiere usar sólo el handle, se deberá de registrar, auqnue no es obligatorio:

wp_register_style( $handle, [$src], [$deps], [$ver], [$media] )

Luego para llamar las hojas de estilo, se usará la siguiente función con el handle. Atención que se puede usar esta función para cargar el estilo, pero no se registrará, debiendo escribir siempre el src del fichero en cuestión:

wp_enqueue_style ( $handle, [$src], [$deps], [$ver], [$media] );

• handle, identificador del fichero  para ser utilizado por otras funciones. Lista de handles definidos por wordpress
• src, ubicación del fichero físico. Se puede concatenar los strings devueltos por las funciones anteriores para conocer dicha ubicación.
• deps, dependencia de otros ficheros utilizando handles de ficheros ya registrados
• ver, versión del fichero
• in_footer (false), Indica si el script se cargará en la cabecera o en el footer. Para que se ejecute en footer (true) la plantilla ha de ejecutar wp_footer()
• media, especifica el tipo para el que se dirige la hoja de estilo (all, screen, handhelld, print)