Curso de desarrollo de módulos para Drupal 7(III): hook_schema explicado con el módulo User

25 abril 2012
Categories: base de datos, campos, desarrollo de módulos, drupal, drupal7, hook_install, hook_schema, instalación, modelo, tablas

Para entender bien esta entrega será necesario tener conocimientos avanzados de uso de arrays en PHP.
Como explicar el hook_schema requiere de un modelo de datos en concreto vamos a apoyarnos sobre el módulo User, que forma parte del nucleo de Drupal.
Abrimos el fichero “modules/user/user.install” desde Aptana para ver su contenido, pulsando doble clic sobre él. Y nos encontramos con el siguiente código en la función user_schema():
/**
 * Implements hook_schema().
 */
function user_schema() {
  $schema[‘authmap’] = array(
    ‘description’ => ‘Stores distributed authentication mapping.’,
    ‘fields’ => array(
      ‘aid’ => array(
        ‘description’ => ‘Primary Key: Unique authmap ID.’,
        ‘type’ => ‘serial’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
      ),
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => “User’s {users}.uid.”,
      ),
      ‘authname’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 128,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => ‘Unique authentication name.’,
      ),
      ‘module’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 128,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => ‘Module which is controlling the authentication.’,
      ),
    ),
    ‘unique keys’ => array(
      ‘authname’ => array(‘authname’),
    ),
    ‘primary key’ => array(‘aid’),
    ‘foreign keys’ => array(
      ‘user’ => array(
        ‘table’ => ‘users’,
        ‘columns’ => array(‘uid’ => ‘uid’),
      ),
    ),
  );

  $schema[‘role_permission’] = array(
    ‘description’ => ‘Stores the permissions assigned to user roles.’,
    ‘fields’ => array(
      ‘rid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Foreign Key: {role}.rid.’,
      ),
      ‘permission’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 128,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => ‘A single permission granted to the role identified by rid.’,
      ),
      ‘module’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 255,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => “The module declaring the permission.”,
      ),
    ),
    ‘primary key’ => array(‘rid’, ‘permission’),
    ‘indexes’ => array(
      ‘permission’ => array(‘permission’),
    ),
    ‘foreign keys’ => array(
      ‘role’ => array(
        ‘table’ => ‘roles’,
        ‘columns’ => array(‘rid’ => ‘rid’),
      ),
    ),
  );

  $schema[‘role’] = array(
    ‘description’ => ‘Stores user roles.’,
    ‘fields’ => array(
      ‘rid’ => array(
        ‘type’ => ‘serial’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Primary Key: Unique role ID.’,
      ),
      ‘name’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 64,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => ‘Unique role name.’,
        ‘translatable’ => TRUE,
      ),
      ‘weight’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => ‘The weight of this role in listings and the user interface.’,
      ),
    ),
    ‘unique keys’ => array(
      ‘name’ => array(‘name’),
    ),
    ‘primary key’ => array(‘rid’),
    ‘indexes’ => array(
      ‘name_weight’ => array(‘name’, ‘weight’),
    ),
  );

  $schema[‘users’] = array(
    ‘description’ => ‘Stores user data.’,
    ‘fields’ => array(
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Primary Key: Unique user ID.’,
        ‘default’ => 0,
      ),
      ‘name’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 60,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => ‘Unique user name.’,
      ),
      ‘pass’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 128,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => “User’s password (hashed).”,
      ),
      ‘mail’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 254,
        ‘not null’ => FALSE,
        ‘default’ => ”,
        ‘description’ => “User’s e-mail address.”,
      ),
      ‘theme’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 255,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => “User’s default theme.”,
      ),
      ‘signature’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 255,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => “User’s signature.”,
      ),
      ‘signature_format’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 255,
        ‘not null’ => FALSE,
        ‘description’ => ‘The {filter_format}.format of the signature.’,
      ),
      ‘created’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => ‘Timestamp for when user was created.’,
      ),
      ‘access’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => ‘Timestamp for previous time user accessed the site.’,
      ),
      ‘login’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => “Timestamp for user’s last login.”,
      ),
      ‘status’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘size’ => ‘tiny’,
        ‘description’ => ‘Whether the user is active(1) or blocked(0).’,
      ),
      ‘timezone’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 32,
        ‘not null’ => FALSE,
        ‘description’ => “User’s time zone.”,
      ),
      ‘language’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 12,
        ‘not null’ => TRUE,
        ‘default’ => ”,
        ‘description’ => “User’s default language.”,
      ),
      ‘picture’ => array(
        ‘type’ => ‘int’,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => “Foreign key: {file_managed}.fid of user’s picture.”,
      ),
      ‘init’ => array(
        ‘type’ => ‘varchar’,
        ‘length’ => 254,
        ‘not null’ => FALSE,
        ‘default’ => ”,
        ‘description’ => ‘E-mail address used for initial account creation.’,
      ),
      ‘data’ => array(
        ‘type’ => ‘blob’,
        ‘not null’ => FALSE,
        ‘size’ => ‘big’,
        ‘serialize’ => TRUE,
        ‘description’ => ‘A serialized array of name value pairs that are related to the user. Any form values posted during user edit are stored and are loaded into the $user object during user_load(). Use of this field is discouraged and it will likely disappear in a future version of Drupal.’,
      ),
    ),
    ‘indexes’ => array(
      ‘access’ => array(‘access’),
      ‘created’ => array(‘created’),
      ‘mail’ => array(‘mail’),
    ),
    ‘unique keys’ => array(
      ‘name’ => array(‘name’),
    ),
    ‘primary key’ => array(‘uid’),
    ‘foreign keys’ => array(
      ‘signature_format’ => array(
        ‘table’ => ‘filter_format’,
        ‘columns’ => array(‘signature_format’ => ‘format’),
      ),
    ),
  );

  $schema[‘users_roles’] = array(
    ‘description’ => ‘Maps users to roles.’,
    ‘fields’ => array(
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => ‘Primary Key: {users}.uid for user.’,
      ),
      ‘rid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘default’ => 0,
        ‘description’ => ‘Primary Key: {role}.rid for role.’,
      ),
    ),
    ‘primary key’ => array(‘uid’, ‘rid’),
    ‘indexes’ => array(
      ‘rid’ => array(‘rid’),
    ),
    ‘foreign keys’ => array(
      ‘user’ => array(
        ‘table’ => ‘users’,
        ‘columns’ => array(‘uid’ => ‘uid’),
      ),
      ‘role’ => array(
        ‘table’ => ‘roles’,
        ‘columns’ => array(‘rid’ => ‘rid’),
      ),
    ),
  );

  return $schema;
}

Como puede verse en el ejemplo, básicamente está utilizando una variable llamada “$schema” que al final de la función devuelve. Dicha variable es un array que contiene un índice por cada tabla que necesita generar.
Por ejemplo si queremos generar la tabla ‘users’, indicamos que sobre el array $schema metemos un nuevo elemento con el índice ‘users’ y como valor metemos otro array.
El primer elemento del array valor de la tabla ‘users’ será la descripción de la tabla, cuyo índice será ‘description’ y cuyo valor será una cadena de caracteres con la descripción de la tabla.
El segundo elemento tendrá como índice el nombre de ‘fields’ y contiene un array con las defniciones de los campos de la tabla.
Así tendremos un array $schema definido de esta manera:
$schema[‘users’] = array(
    ‘description’ => ‘Stores user data.’,
    ‘fields’ => array()
);
En dicho array de campos (‘fields’), vamos introducciendo cada campo como un elemento cuyo índice es el nombre del campo y su valor es otro array con los metadatos del campo que queremos meter en la tabla, como el caso del campo ‘uid’…
$schema[‘users’] = array(
    ‘description’ => ‘Stores user data.’,
    ‘fields’ => array(
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Primary Key: Unique user ID.’,
        ‘default’ => 0,
      )
     )
);
En este caso, el campo uid, tiene los siguientes elementos definidos:

  • type: tipo de campo definido por drupal
  • unasigned: valor booleano que permite definir si el campo es con o sin signo. Sólo disponible para campos numéricos.
  • not_null: valor booleano que nos indica si es campo puede ser null o no
  • description: descripción del campo
  • default: valor por defecto del campo

Como puede verse dicha definición de campo es una estructuración en forma de array de las típias configuraciones que solemos hacer en la propia base de datos cuando creamos un campo nuevo.
De esta manera ñadiríamos todos los campos que queremos que tenga la tabla, como distintos elementos del valor del array ‘fields’.
A continuación seguramente será necesario indicar de todos los campos cual (o cuales) es la clave primaria, en el caso de la tabla de users el campo ‘uid’ es el campo de clave primaria de la tabla, por lo que tenemos que insertar un nuevo elemento en el array principal $schema[‘users’] llamado ‘primary_key’ cuyo valor es un array con el nombre de los campos que son clave primaria. Por lo que el código quedaría así:
$schema[‘users’] = array(
    ‘description’ => ‘Stores user data.’,
    ‘fields’ => array(
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Primary Key: Unique user ID.’,
        ‘default’ => 0,
      )
     ),
    ‘primary key’ => array(‘uid’)
);
 En el caso de la tabla users, tambiñen necesita hacer uso de índices sobre campos, para ello introduce también dentro del array $schema[‘users’] un elemento cuyo índice es ‘indexes’ cuyo valor debería ser un array con el nombre del índice y su valor un array con los nombres de los campos que queremos introducir en el índice. Así quedaría el array de la siguiente manera…
$schema[‘users’] = array(
    ‘description’ => ‘Stores user data.’,
    ‘fields’ => array(
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Primary Key: Unique user ID.’,
        ‘default’ => 0,
      )//aquí introduciríamos el resto de elementos para definir el resto de campos de la tabla
     ),
    ‘primary key’ => array(‘uid’) ,
    ‘indexes’ => array(
      ‘access’ => array(‘access’),
      ‘created’ => array(‘created’),
      ‘mail’ => array(‘mail’),
    )
);
En este ejemplo, define 3 índices, sobre los campos access, created y mail. Por otra parte podemos definir índices únicos sobre campos, para ello debemos introducir un elemento más con índice ‘unique keys’ cuyo valor es un array con los nombres del índice y el valor de ese elemento es otro array con los campos que pertenecen a dicho array, en el ejemplo…
$schema[‘users’] = array(
    ‘description’ => ‘Stores user data.’,
    ‘fields’ => array(
      ‘uid’ => array(
        ‘type’ => ‘int’,
        ‘unsigned’ => TRUE,
        ‘not null’ => TRUE,
        ‘description’ => ‘Primary Key: Unique user ID.’,
        ‘default’ => 0,
      )//aquí introduciríamos el resto de elementos para definir el resto de campos de la tabla

     ),
    ‘primary key’ => array(‘uid’) ,
    ‘indexes’ => array(
      ‘access’ => array(‘access’),
      ‘created’ => array(‘created’),
      ‘mail’ => array(‘mail’),
    ),
    ‘unique keys’ => array(
      ‘name’ => array(‘name’),
    )
);
En el ejemplo crea un índice único llamado ‘name’  sobre el campo ‘name’. Dejamos para otro momento el índice ‘foreing keys’ por que tendríamos que explicar el modelo entero de users.

Debemos pensar que Drupal utilizará este hook para crear las tablas necesarias en la base de datos para el módulo, pero seguiríamos necesitando modificar el hook_install para introducir los datos iniciales en las tablas definidas en el hook_schema, como en el ejemplo…
// Insert a row for the anonymous user.
  db_insert(‘users’)
    ->fields(array(
      ‘uid’ => 0,
      ‘name’ => ”,
      ‘mail’ => ”,
    ))
    ->execute();
  Debido que al realizar la desinstalación del módulo user no hay que realizar más acciones que el borrado de las tablas generadas con la definición del hook_schema, el módulo user no necesita un hook_uninstall().

Práctica

  1. Genera un nuevo módulo en base a unos requisitos de base de datos dados.
  2. Define el hook_schema definiendo el modelo de base de datos
  3. Define el hook_install para introducir los datos iniciales en las tablas
  4. Prueba a realizar la instalación e activación del módulo, comprueba si las tablas se han generado correctamente.
  5. prueba a desactivar y desinstalar el módulo y mira a ver si ha borrado correctamente las tablas en la BBDD.

Referencias

Licencia Creative Commons

Curso de desarrollo de módulos con Drupal 7 (II): Instalación y Desinstalación

25 abril 2012
Categories: desarrollo, desarrollo de módulos, devel, development, drupal, drupal7, field api, hook_install, hook_schema, hook_uninstall

En esta entrega generaremos el fichero module.install en el que colocaremos los hooks de instalación y desinstalación. Para ello crearemos un nuevo fichero en el módulo, en nuestro caso el ejemplo.install y lo colocaremos en la carpeta principal del módulo. Como todo fichero de php del módulo deberemos colocar la cabecera apropiada e incluirlo en el fichero .info. Dentro del fichero ejemplo.info incluiremos una línea con el siguiente código:
files[] = ejemplo.install
De esta manera el módulo configura la inclusión del fichero ejemplo.install para que Drupal sepa que dispone de él.
Por otra parte, dentro del fichero ejemplo.install incluiremos el siguiente código:
<?php
/**
* @file
* Fichero del módulo de ejemplo para drupal
*
* Descripción larga del fichero que netra dentro del módulo de ejemplo de Drupal
*/
/**
 * implements hook_install
 */

function ejemplo_install() {
}

/**
 * implements hook_uninstall
 */
function ejemplo_uninstall() { 
}
Como puede verse incluimos dos funciones nuevas en el fichero: ejemplo_install() y ejemplo_uninstall(). En este caso están vacías, pero dichas funciones va a ejecutarse cuando se realice la instalación y desinstalación del módulo respectivamente.
La instalación del módulo, cuando se está haciendo el desarrollo, se realiza la primera vez que entramos en Drupal  y existe la carpeta del módulo.
Por lo que puede llegar a ser necesario realizar manualmente la desinstalación del módulo para que aplique los cambios de la instalación al volver a entrar. Para realizar la desinstalación deberemos acceder al listado de módulos, y desactivar el módulo.
Después en el listado de módulos deberemos pulsar en la pestaña “Desinstalar”…

Como puede verse esa pestaña aparece en la parte superior derecha de la página. Pulsamos en ella y nos aparecerá un formulario de desinstalación de módulos similar al siguiente…

com puede verse aparecerá todos aquellos módulos desactivados, en los cuales esté permitida su desinstalación. Pulsaremos la checkbox la lado del módulo que queremos desinstalar y pulsaremos en el botón “Desinstalar”. Nos aparecerá una confirmación de la desinstalación del módulo, similar a la siguiente…

pulsaremos en el botón “Desinstalar”. Y nos aparecerá el resultado de la desinstalación, si todo ha ido correctamente, veremos una pantalla indicando que el módulo se ha desinstalado correctamente, similar a la siguiente…

De esta manera se ejecutará el hook_uninstall, en nuestro caso la función ejemplo_uninstall() del ejemplo.module.
Después podemos volver al listado de módulos y volver a activar el módulo, por lo que se ejecutará el hook_install, en nuestro caso la función ejemplo_uninstall().
La idea fundamental de estas dos funciones es que deberían ser totalmente atómicas en su concepto. Es decir, todo aquello que haga el hook_install, debería ser deshecho por el hook_uninstall.

Planificando el módulo

Es hora de decidir qué es lo que queremos que haga el nuevo módulo. En nuesto ejemplo, intentaremos añadir un campo nuevo a Drupal para luego poder usarlo desde los contenidos. Por lo que necesitaremos usar ese campo dentro del módulo.

Desde la instalación deberemos decirle a Drupal que queremos usar un nuevo campo.
Desde la administración del módulo podremos elegir que tipos de contenido tendrán disponible este nuevo campo.
Desde la desinstalación, deberemos mirar todos los tipos de contenido para ver cuales de ellos disponen de ese campo, después borrar el campo de aquellos tipos de contenido que lo tengan y luego borrar el campo para que drupal no lo use.

hook_install()

Desde el hook_install() deberemos decir que debe ejecutar drupal cuando el módulo se instala.
En nuestro caso, debemos usar el propio API de Drupal para retocar los campos disponible para los tipos de datos, por lo que no es necesario cambiar el modelo de la base de datos, y no tenemos que hacer uso del hook_schema(). En el caso de que tuviesemos que generar nuevas tablas y campos de tabla en el modelo de la base de datos, sí tendríamos quehacer uso de hook_schema().
Para incluir el campo deberemos incluir el códufo en el hook_install(), en nuestro caso, en la función ejemplo_install(), con el siguiente código:
function ejemplo_install() {

  // comprueba si existe el código
  $field = field_info_field(‘annotation’);

  // if the annotation field does not exist then create it
  if (empty($field)) {
    $field = array(
      ‘field_name’ => ‘annotation’,
      ‘type’ => ‘text_with_summary’,
      ‘entity_types’ => array(‘node’),
      ‘translatable’ => TRUE,
    );
    $field = field_create_field($field);
  }

}
Com puede verse en este código fundamentalmente estamos usando las funciones del API de Field, cuyos nombres siempre empiezan por “field_”.
Las dos primeras líneas intenta averiguar mediante la función “field_info_field()” si el campo para las anotaciones ‘annotation’ existe ya en el Drupal donde queremos instalar el módulo.
Si es así no hace nada, si no es así, intenta crear el campo mediante la llamada a la función “field_create_field()” donde le pasa como parámetro un array con los metadatos principales del campo que quiere crear, en nuestro caso:

  • field_name: nombre del campo que queremos crear.
  • type: tipo de campo, responde a los distintos tipos redefinidos dentro de drupal
  • entity_types: tipo de entidad sobre el cual queremos hacer uso del campo
  • translatable: boolean que representa si el campo es traducible o no.

hook_uninstall()

Como se ha explicado anteriormente será necesario deshacer las acciones realizadas desde la administración y desde la instalación del módulo, por lo que el código de nuestro ejemplo_uninstall() será el siguiente…
/**
 * implements hook_uninstall
 */
function ejemplo_uninstall() {

   watchdog(“Annotate Module”, “Uninstalling module and deleting fields”);
  
   $types = node_type_get_types();  
  
   foreach($types as $type) {
      delete_annotation($type);  
   }
  
   $field = field_info_field(‘annotation’);

   if ($field) {
      field_delete_field(‘annotation’);
   }
  
}
 Como podemos observar lo primero que hacemos es sacar un mensaje a través de la función watchdog, donde pasamos dos parámetros, el nombre del módulo que genera el mensaje y el mensaje en sí mismo. Para informar de lo que estamos haciendo.
Posteriormente cogemos el listado de tipos de contenidos como un array mediante la función node_type_get_types().
Después recorremos el array de tipos para ir borrando uno a uno el campo ‘annotation’ en todos y cada uno de ellos, a través de una función creada por nosotros que incluiremos más adelante.
Finalmente, miramos a ver si existe el campo ‘annotation’ en el Drupal y si es así lo eliminamos mediante la función field_delete_field(), donde le pasamos como parámetro el nombre del campo ‘annotation’.
De esta manera toda la información que gestiona el módulo será borrada, tanto los campos que hayamos utilizado en los distintos tipos de datos, como el campo en sí mismo.
Por lo que podemos decir que hemos conseguido mantener esa atomicidad en el comportamiento entre install, admin y uninstall, como explicamos anteriormente.

Para que funcione correctamente el hook_uninstall(), agregamos también la función delete_annotation() al fichero ejemplo.install..
/**
 * Function:  delete_annotation($type)
 * Purpose :  deletes instances of the annotation field from content types
 */
function delete_annotation($type) {

  $instance = field_info_instance(‘node’, ‘annotation’, $type->type);

  if ($instance) {
     field_delete_instance($instance);
  }

}
Como puede verse, según el tipo de contenido que pasamos, intentamos saber si dicho tipo tiene asociado el campo ‘annotation’, mediante la llamada a la función field_info_instance. Como primer parámetro pasamos el tipo de contenido que queremos comprobar ‘node’, los contenidos. Como segundo parámetro pasamos el nombre del campo ‘annotation’ y como tercer parámetro pasamos el nombre del tipo de contenido que estamos comprobando.
Si dicho campo está relacionado con el tipo de contenido la variable $instance tendrá un valor distinto a false, por lo que ejecutaremos el método field_delete_instance(), pasándole como parámetro la variable $instance, que eliminará dicha relación con el tipo de contenido.

Referencias: 

Licencia Creative Commons

Curso de Desarrollo de módulos con Drupal 7 (I): Introducción

25 abril 2012
Categories: desarrollo, desarrollo de módulos, devel, development, drupal7, introducción, modules, modulos

En las siguientes entregar veremos cómo crear nuevos módulos de Drupal 7. Para realizar la programación utilizaremos Aptana Studio 3 , una distribución basada en Eclipse, como editor de código y gestor de proyectos PHP.
Para comenzar la programación necesitamos disponer de una instalación limpia de Drupal 7 que poder utilizar. Digamos que la hemos instalado en el directorio “c:xampphtdocsdrupaldev”.
Para los desarrollos con Drupal, es altamente recomendable la instalación de los módulos deve, tal como indica la XI entrega del curso de Drupal 7.
Arrancamos Aptana y vamos a realizar la importación del directorio de drupaldev como proyecto de Aptana.

Importación del proyecto en Aptana

Para ello en el “Project Exlorer” pulsamos el botón derecho del ratón y seleccionamos la opción “Import”…

Nos aparecerá una pantalla de selección  de tipo de importación similar a la siguiente…

Nos saldrán distintas opciones, expandimos la opción “General” y seleccionamos la opción “Existing Folder as New Project” y pulsamos en “Next>”, nos aparecerá una pantalla donde deberemos decir qué directorio debemos importar…

A través del botón “Browse…” seleccionamos el directorio de instalación de drupal que queremos importar, seleccionamos el tipo de proyecto “PHP”, ponemos el nombre de proyecto, por ejemplo “drupaldev” y pulsamos en el botón “Finish”. Veremos en el “Project Explorer” cómo ha aparecido una nueva carpeta llamada “drupaldev” que corresponde al proyecto que acabamos de importar…

Si expandimos la carpeta del proyecto podremos ver las carpetas y ficheros que se incluyen en el mismo, cualquier cambio que hagamos desde Aptana se reflejará en el directorio de Drupal y viceversa…

Creando el Módulo: Primeros pasos

 Una vez configurado el proyecto en Aptana, deberemos dar los primeros pasos en la generación del proyecto.
Todas las rutas de carpetas y ficheros serán relativas al proyecto de drupal en aptana. 
Crearemos una carpeta llamada “custom” en el directorio “sites/all/modules” del proyecto, para ello navegaremos por los directorio del proyecto hasta encontrar la carpeta “sites/all/modules” y pulsamos botón derecho encima de la carpeta “modules”, navegamos al menú “New” y pulsamos en la opción “Folder”…

a continuación nos saldrá una ventana en la que podremos selccionar la localización y el nomrbe de la carpeta…

y pulsamos en el botón “Finish”. Veremos que nos aparecerá en el Project Explorer dicha carpeta custom dentro de modules.

Carpeta de módulo y ficheros iniciales

Ahora es cuando debemos decidir el nombre del módulo ya que debemos crear una carpeta con el nombre para almacenar los ficheros del mismo. Pongamos por ejemplo que el el módulo se va a llamar “ejemplo”, por lo tanto deberemos crear una carpeta llamada “ejemplo” dentro de la carpeta custom, tal como describimos anterioremente.
 En el directorio del módulo debemos crear un fichero “info” con la información del módulo, el fichero debe llamarse “[nombredemodulo].info”, en nuestro caso deberá llamarse “ejemplo.info”.
Para ello pulsamos el botón derecho del ratón sobre la carpeta “ejemplo”, navegamos al menú “New” y seleccionamos la opción “File”…

a continuación, nos saldrá la pantalla de localización del fichero…

pondremos el nombre al fichero, en nuestro caso, “ejemplo.info” y pulsamos en “Finish”. Veremos que nos abrirá la edición del fichero recien creado en la parte derecha de la pantalla, el fichero estará vacío…

como puede verse en la captura, existen pestañas en la parte de edición de código, una por fichero abierto para edición.

Notas sobre las vistas de Eclipse(Aptana)

Dichas pestañas pueden cerrarse pulsando en la “X” que aprece al lado del nombre del fichero. Para volver a abrir el fichero para edición, basta con hacer doble clic en el nombre del fichero y veremos que aparecerá de nuevo en la parte de edición.
Si pulsamos doble clic sobre el nombre de la pestaña del fichero se colocará esta “vista” (como se llaman los componentes visuales de Eclipse y Aptana) a modo “pantalla completa”. Si queremos volver al modo de pantalla normal y así poder ver el resto de “vistas” volveremos a pulsar doble clic en el nombre de la pestaña.
Si aparece un * la lado del nombre del fichero es porque el fichero se ha modificado pero no se ha guardado todavía.
Para guardar el fichero bastará con pulsar “Control+S”.

Contenido del fichero .info

El fichero [nombredemodulo].info corresponde a la definición o información del módulo. Indica entre otras informaciones:

  • name: el nombre del módulo
  • description: descripción de las funcionalidades del módulo
  • core: versión de drupal para la que está desarrollado
  • package: nombre del paquete donde irá colocado el módulo
  • stylesheets[]:  ficheros CSS relacionados
  • scripts[]: ficheros JS relacionados
  • dependencies[]: módulos de los que depende el módulo
  • php: versión mínima de PHP para que funcione el módulo
  • files[]: ficheros que están disponibles en el módulo
  • configure: ruta de configuración del módulo

Para nuestro caso rellenaremos el fichero con el siguiente contenido:
name = ejemplo
description = modulo de ejemplo para drupal 7
core = 7.x
package = Plexxoo
php = 5.3
configure = admin/config/ejemplo/settings

Una vez copiado el contenido al fichero, lo salvamos, pulsando “Control+S”o pulsando en el icono del disquete.

Creación de ficheros Suplementarios del módulo

De esta manera el fichero info está configurado, pero tenemos un módulo que no hace nada, para ello deberemos añadir funcionalidades y otros ficheros al módulo y reflejar estos ficheros en el fichero info.
Crearemos 3 ficheros:

  • ejemplo.module
  • ejemplo.install
  • ejemplo.admin.inc

Estos tres ficheros nos servirán de base para el desarrollo del módulo. Ahora los incluiremos en el fichero ejemplo.info añadiendo las siguientes líneas:
files[] = ejemplo.module
files[] = ejemplo.install
files[] = ejemplo.admin.inc

De esta manera Drupal sabrá que tiene esos ficheros suplementarios relacionados con el módulo.
En el fichero ejemplo.module introducimos el siguiente contenido base:

<?php 
/** 
* @file 
* Fichero del módulo de ejemplo para drupal 
* 
* Descripción larga del fichero que entra dentro del módulo de ejemplo de Drupal
*/
?>

El @file indica la descripción de uso del fichero, de cara a la documentación de Drupal.

Los hooks

Drupal se basa en un sistema de conectores para enganchar contra las funcionalidades de los módulos, tales como añadir un menú. Dichos conectores son principalmente funciones consultadas desde Drupal a los distintos módulos activados.
En este ejemplo utilizaremos un hook muy sencillo el “hook_help()”. cuando se habla de la palabra “hook”, en el módulo debe substiruirse con el nombre del módulo. De esta manera será necesario nombrarlo como “ejemplo_help()”.
 El siguiente código deberemos incluirlo en el fichero ejemplo.module dentro del bloque php…
 /**
* Implements hook_help.
*
* Displays help and module information.
*
* @param path
*   Which path of the site we’re using to display help
* @param arg
*   Array that holds the current path as returned from arg() function
*/
function ejemplo_help($path, $arg) {
  switch ($path) {
    case “admin/help#ejemplo”:
      return ‘<p>’.  t(“texto de ayuda del módulo”) .'</p>’;
      break;
  }
}
como pude verse tenemos una función nueva en el fichero que define lo que drupal debe hacer para atender la petición de ayuda sobre el módulo ejemplo.
Todas las funciones hook, pueden tener parámetros de entrada, para poder pasar el contexto en el cual se mueve el módulo y poder interactuar con los parámetros.
En este caso el parámetro principal de $path, que es que determina la ruta a través de la cual se desea acceder al contenido.
Así dependiendo de dicho path tenemos un switch que nos permite ofrecer salidas distintas. En este caso sólo hay un caso, que es que nos ofrece un código HTML de vuelta con el texto de la ayuda.
Dicho texto debería ser traducible ya que se utiliza la función t que permite la traducción de literales por parte de Drupal. Si existe esa traducción para el idioma seleccionado la presenta, sino deja el texto del literal.

Activando el módulo

Una vez realizados todos estos pasos deberemos activar el módulo que hemos creado. Como el módulo ya está instalado, debido a que está ya colocado en el directorio “sites/all/custom/ejemplo” no es necesario realizar la instalación. Para activarlo seguiremos los mismos pasos de activación de un módulo que describimos en la entrega de módulos.
Si accedemos a la Configuración->Módulos veremos nuestro módulo dentro de la categoría “Plexxoo”…

Lo único que tendremos que hacer es activar el módulo y volver a entrar al listado de módulos de la administración, veremos que el módulo está activado y nos aparecerán dos enlaces en la parte derecha del módulo: Ayuda y Configuración.
De momento el único enlace funcional es el de Ayuda, que el único hook que hemos escrito para ese módulo. Si pulsamos sobre él, veremos la siguiente pantalla…

 Como puede observarse desde la captura aparece el texto generado desde la función, así como un enlace a la configuración del módulo. Pero la gestión de la configuración lo veremos en la siguiente entrega.

Referencias:

Licencia Creative Commons

Curso de Drupal 7 (XI): Vistas, Vistas y más Vistas

24 abril 2012
Categories: blocks, bloques, drupal, drupal7, nodes, nodos, paneles, panels, views, vista

Módulos de generación automática de contenidos

 Una de las tareas básicas en el diseño de sitios web es la generación de contenidos que nos permitan visualizar cómo podría quedar el sitio web una vez se hayan introducido los contenidos.
Para ello será necesario la instalación de un conjunto de módulos:

  • Devel: módulo base de generación
  • Devel image provider: módulo que permite la introducción de fotografías en los contenidos generados
  • Drupal Ipsum: módulo de generación de lorem ipsum para los textos de los contenidos
  • Variable: módulo de pedendencia del módulo Lorem Ipsum

Una vez instalados y activados los módulos dispondremos de un nuevo apartado en la Configuración, llamado “Desarrollo”…

como puede verse en la captura disponemos de una serie de enlaces que nos vana permitir la generación de contenidos, menús, taxonomías, términos, usuarios, etc…
La parte más interesante es la generación de contenidos, si pulsamos en el enlace veremos lo siguiente…



como puede observarse, nos salen disponibles todos los tipos de contenido que disponemos, apra poder selccionar los que queremos generar y las siguientes ocpiones:

  • Drupal Ipsum Settings: donde podemos configurar si deseamos usar el drupal ipsum para generar los textos y los comentarios.
  • Delete all content: si queremos borrar todo el contenido disponible en el sitio. Esta opción es sólo recomendable si estamos maquetando Views o si el sitio realmente está vacío de contenido.
  • How many nodes would you like to generate? indicamos en número de nodos (contenido) que queremos generar.
  • How far back in time should the nodes be dated? indicamos la fecha en la que los nodos deberían ser generados.
  • Maximun number of coments por node. Número de comentarios maximos de comenarios por nodo.
  • Max word length of titles. Número máximo de palabras para el título.
  • Add url alias  for each node. Añadir una alias de URL para cada nodo.
  • Set Language on nodes. Seleccionar el idioma o idiomas del contenido generado.

Una vez configurado el formulario pulsamos en el botón “Generate”.Nos indicará los nodos que haya añadido y eliminado. Si vamos al listado de contenidos nos aparecerán los nuevos contenidos…

Y ya podremos usarlos como ejemplos en a configuración de las Views.

Integración Panels con Views

una de las cuestiones principales en la generación de los paneles es la posibilidad de integrar Views (en adelante Vistas) con los paneles.
Para ello deberemos realizar la activación de módulos de integración: page manager, views content panes
A continuación, veremos un ejemplo de inetgración de una vista en un panel y la asignación de nodos a paneles. Como vimos en la anterior entrega tendremos que generar una vista y un nuevo panel.
Con los módulos activamos deberíamos poder integrar ambos contenidos en una misma página.
Desde el menú de administración->Estructura->Paneles llegaremos al menú principal de gestión de paneles…

como puede observarse disponemos de los siguientes elementos en pantalla:

  • En la parte de la superior izquierda está un listado de acciones principales:
    • Añadir una nueva página de panel.
    • Añadir un mini panel: un bloque con contenidos
    • Añadir un panel con contenido (nodo)
    • Construir un nuevo Layout: una nueva manera de estructurar los contenidos en paneles
    • Construir un estilo nuevo para paneles.
  • En la parte inferior izquierda aparecen los listados de minipaneles y estilos
  • En la parte superior derecha aparece el asistente de creación de “Landing page” páginas con url , entradas a menú, etc…
  • En la parte inferior derecha aparece el listado de páginas con paneles.

 Para la práctica utilizaremos el panel que hemos contruido en la anterior entrega y que deberíamos ver en listado de páginas de panel de la derecha. Como puede verse podemos elegir un conjunto de acciones la lado de cada página. Aquellas páginas que hemos generado nosotros, la operación por defecto es la edición, pero si pulsamos sobre el triángulo que tiene la lado al botón nos aparecerán las otras opciones disponibles para ese elemento. De esta manera podremos cambiar la selección y luego pulsar sobre el botón una vez cambiado.
En este caso pulsamos sobre el botón “edición” del panel y llegaremos a la configuración del panel…

Como puede observarse en un formulario bastante complejo y está organizado en pestañas que facilitan su configuración:

  • Opciones:
    • Resumen de los datos de la página generada con el panel
    • Básico: donde podemos configurar su nombre, su URL de acceso, hacerla página principal, etc..
    • Access: nos permite cambiar varios criterios dependiendo del contexto en el que nos movamos, tales como el tema presente en ese momento, si estamos en la página principal, etc…
    • Menú: nos permite configurar la entra al panel desde los menús.
  • Panel:
    • Resumen
    • General: donde podemos configurar los ID’s y estilos visuales asignados al panel.
    • Selection Rules: configuración similar a la de access de las opciones, pero esta vez específicas del panel que estamos editando.
    • Contexts: contexto en el que nos encontramos, tales como si estamos presentado un determinado nodo, o si estamos en un determiando término de una taxonomía.
    • Layout: configuración de la forma del panel, con sus elementos, nos ofrecen plantillas de paneles a elegir.
    • Content: elección del contenido a integrar en los paneles.
    • Vista previa: previsualización del panel.

Cuando termiamos de configurar el panel pulsamos en el botón “Guardar”.
En este caso nos centraremos en la introducción de contenido en los paneles, para ello pulsaremos en la opción Contenido del Panel…

como puede observarse, podemos gestionar las distintas zonas visuales que tenemos en el panel, en este caso sólo hay dos zonas, la izquierda y la derecha. Para agregar un contenido a una de estas zonas existen en cada zona menús contextuales con el icono de una rueda dentada, si los pulsamos se nos despliega el menú y nos aparece la opción de agregar contenido…

si pulsamos sobre el enlace de “Agregar contenido” nos aparecerá una nueva ventana sobre la que podremos selccionar el contenido que queremos agregar…

En nuestro caso seleccionaremos primero la opción existing node y nos aparecerá la pantalla de búsqueda de nodo…

En ella buscaremos en la caja principal de texto por título o número de nodo la página que buscamos, al ser un autocompletado nos irá mostrando las distintas páginas que cumplen con la búsqueda, selccionaremos una, configuramos el resto de campos a nuestro gusto y pulsamos en “Finish”. Y volveremos a la configuración de zonas visuales donde nos aparecerá el contenido que hemos seleccionado en la zona en la que lo agregamos.
De la misma manera que intentamos agregar un nodo, intentaremos agregar una vista. Salvo que después de “agregar contenido” seleccionaremos “Views” y debería aparecer un listado similar al siguiente…

seleccionamos la Vista pulsando en ella y pulsamos en continuar. Nos aparecerá la pantalla de configuración de la vista en el panel…

configuramos los parámetros y pulsamos en “Finish” y veremos la vista en la zona definida.

Como puede verse tanto el módulos Views com Panels son muy complejos, pero con estos pequeños consejos podemos hacer un uso sencillo y práctico de ellos para construir vistas complejas y listados de tipos de contenidos, incluso mini paneles para usar como bloques en los temas visuales.

Gestión de Eventos y Calendarios 

Módulo: Calendar
Dependencias: Date
Una vez instalador y activados los módulos, incluido el Date Views, para su integración con Views. podemos añadir un nuevos nuevos tipos de campos a los tipos de contenido de Drupal 7.
A modo de ejemplo crearemos un nuevo tipo de contenido denominado Eventos al que agregaremos un campo de tipo “Date(Iso Format)” al tipo de contenido tal como vimos en anteriores entregas…

Después de añadir el campo y seleccionar el control como campo de texto, pulsaremos en “Guardar”.
De esta manera ya dispondremos de un tipo de contenido con un campo por el que podremos filtar por fecha.
Desde el módulo Views podremos gestionar una vista de calendario, así desde el listado de Vistas…

pulsamos sobre el enlace “Add view from template” y llegaremos a la selcción de plantilla…

de esta manera podremos selccionar una plantilla de View conforme al tipo del contenido y el campo por el que queremos filtrar, en este caso por la plantilla de “A calendar view of the ‘field_nombredelcampoquehayamospuestoenloseventos’ in the node base table” y pulsamos en el enlace “add” que hay al lado derecho de dicha pantilla de vista.
Rellenamos el nombre de la vista, por ejemplo con “Calendario de Eventos” y pulsamos en “Continuar”. Y nos lleva a la pantalla de configuración de la vista del Calendario…

donde podemos gestionar el resto de campos de friltrado que consideremos necesarios y después pulsaremos en “Guardar”.
De esta manera dispondremos de una vista con el calendario configurado que podremos usar como página, bloque o parte de un panel.

Mejoras de Views 

Los módulos que podeís echarle un vistacillo, son aquellos que complementan las Vistas:

  • Views slideshow (para hacer sliders y similares), Libraries (dependencia de views slideshow) 
  • Advanced help (ayuda para views y panels)
Licencia Creative Commons

Suscríbete al Boletín

Si quieres estar al tanto de las novedades del blog, ya sabes :)
* = campo obligatorio

powered by MailChimp!

Uso de cookies

Este sitio web utiliza cookies para que usted tenga la mejor experiencia de usuario. Si continúa navegando está dando su consentimiento para la aceptación de las mencionadas cookies y la aceptación de nuestra política de cookies, pinche el enlace para mayor información. ACEPTAR

Aviso de cookies