Conocimientos previos para entender este

tutorial:
PHP, Desarrollo en drupal, POO, Base de datos relacionales.

Nota: Este tutorial enfocará solo los aspectos dirigidos a entity api, no se explicará nada relacionado al
desarrollo común de módulos de drupal, se toma como consenso que ya es un conocimiento previamente
tomado.

Objetivo del curso

Aprender mediante un ejemplo práctico como desarrollar entidades en drupal7.

Subjetivos:

 Como crear entidades en drupal 7.

 Gestión entre entidades.

Introducción:
El curso estará estructurado por un conjunto de artículos que abarcarán los aspectos básicos a conocer para
desarrollar entidades en drupal 7. Este desarrollo estará basado en un ejemplo práctico que ayudará a salir
de un ambiente conceptual y adentrarnos en un caso particular.

Caso práctico:
Se pretende desarrollar un módulo para drupal 7 que permita llevar las estadísticas de campeonatos de fútbol,
donde se gestionen los torneos, jornadas y partidos por jornadas, así como toda la gestión de equipos que
participen en cada uno de los torneo.
Diagrama de gestión :

Un torneo se conforma por varias jornadas y varios equipos, una jornada por muchos partidos y estos a su
vez por 2 equipos.
Se debe llevar una tabla de resultados donde se reporten la cantidad de juegos jugados, juegos perdidos,
juegos empatados y ganados, así como la cantidad de goles a favor y en contra y el total de puntos acumulados
por cada equipo participante en el torneo.
Desarrollo Tema 1:
Nota: Se tomará la entidad torne como base para explicar todo el contenido del código mostrado.

Puntos a tratar:

 Extraer las entidades del caso práctico.

 Implementación del hook_schema.
 Implementación del hook_entity_info.
 Implementación de nuestros EntityController.

Desarrollo:
Extraer las entidades del caso práctico.
Diagrama de entiddes:
Como se muestra en el diagrama trabajaremos solo con 4 entidades (torneo, jornada, equipo, juego).

/* Implements hook_schema().
*
*/
function module_name_schema() {
$schema = array();

//--------------------MODULE_NAME_TORNEO----------------------
$schema ['module_name_torneo'] = array(
'fields' => array(
'torneo_id' => array( //nombre de la propiedad o columna de la entidad
'unsigned' => TRUE, //auto incrementado el campo
'type' => 'serial', // se define el tipo de dato
'not null' => TRUE, //Si puede o no ser nudo este valor
),
'categoria_id' => array(
'type' => 'int', // se define el tipo de dato
'default' => 0, //se define valor por defecto
),
'estado' => array(
'type' => 'int',
'default' => 0,
),
'nombre' => array(
'type' => 'varchar',
'length' => '100', //se asigna un tamaño del campo
'default' => '',
),
),
'primary key' => array(//se declara la llave primaria de la entidad
'torneo_id'
),
);
//Continuamos con las otras entidades de la misma forma que //anteriormente se explicó...
return $schema;
}

Implementación del hook_entity_info:

function module_name_entity_info() {

//------------------------------module_name_torneo-------------------------------------------
$info['module_name_torneo'] = array(
//Etiqueta para identificar la entidad.
'label' => t('module_name_torneo'),

//Controlador que maneja los métodos de la entidad, por defecto es

// EntityAPIController.
'controller class' => 'Entitymodule_name_torneoController',

//Definimos la tabla relacionada en el hook_schema() que manejará esta //entidad.

'base table' => 'module_name_torneo',

//Define la función que retornara la entidad en cuestión

'uri callback' => 'module_name_torneo_uri',

//Se le da la posibilidad a la entidad de agregar nuevos campos, como hace las //entity node,user...

'fieldable' => TRUE,

//Identificador de la entidad, llave que se definió en el hook_schema() para esta entidad.

'entity keys' => array(

 'id' => 'torneo_id' ,//llave de la tabla
),

//Así definimos un bundle para agrupar entidades de un mismo

//tipo o que represente herencias, y quede de una forma organizada.
//ejemplo es Content Type que agrupa a artículos, paginas básicas...
'bundles' => array(
'module_name_torneo_bundle' => array(
//Etiqueta del bundle
'label' => 'module_name_torneo bundle',
//Datos administrativos de la entidad
'admin' => array(
//Definimos la dirección desde donde se administrara la entidad.
'path' => 'admin/structure/module_name_torneo/manage',

//Permiso que se debe tener para poder gestionar esta entidad,

//este permiso debe de ser declarado previamente en el hook__permission() del módulo en cuestión.
'access arguments' => array('administer module_name_torneo entities'),
),
),
),
//Se definen los modos de vistas para distintos contexto donde participe esta entidad, se puede relacionar con el
modulo view.
'view modes' => array(
'tweaky' => array(
'label' => t('Tweaky'),
'custom settings' => FALSE,
),
)
);
//Se debe continuar con la implementación de las 3 entidades restantes de la misma manera que implementada esta.

return $info;
}

Implementación de nuestros EntityController:

El EntityController conforma la capa de negocio de la entidad, es donde se definen nuevos métodos o

redefinen otros a nuestra conveniencia, esta clase es a la que hace referencia el hook_entity_info
anteriormente explicado 'controller class' => 'Entitymodule_name_torneoController', cuando se solicite un
método de una de las entidades serán buscados en este controlador y luego ejecutado. EntityAPIController
ya implementa por defecto los métodos principales save,delete,update,load. Si se utiliza EntityAPIController
en el en el hook_entity_info ('controller class' => EntityAPIController) no será necesario implementar un
nuevo controlador, solo si necesitamos realizar operaciones especifica en nuestra entidad.
//Se crea esta interfaz porque cualquiera puede alterar la entidad con el hook ¬¬//hook_entity_info_alter(). Aquí se da a saber
que métodos necesita la clase //para que interactúe con el resto del módulo.
interface Entitymodule_name_torneoControllerInterface
extends DrupalEntityControllerInterface {
public function create();
public function save($entity);
public function delete($entity);
}

//Esta clase permite implementar los nuevos métodos no heredados de ¬¬//DrupalDefaultEntityController y re implementar
los de la interface //anteriormente explicada a su conveniencia.
class Entitymodule_name_torneoController
extends DrupalDefaultEntityController
implements Entitymodule_name_torneoControllerInterface {

//Se crea una nueva entidad y se definen los vlores por defecto de la misma.
public function create() {
 $entity = new stdClass();
$entity->type = 'module_name_torneo';
$entity->bundle_type = 'module_name_torneo';
$entity->torneo_id=0;
$entity->categoria_id=0;
$entity->estado=0;
$entity->nombre='';

return $entity;
}

// Este método es el encargado de guardar o actualizar la entidad en caso que ya exista.

public function save($entity) {

//Se invoca el hook_entity_presave() de entity api.

module_invoke_all('entity_presave', $entity, 'module_name_torneo');
//Se toman las llaves de la entidad, en caso de que ya exista la entidad y se //quiera actualizar en caso de ser una nueva entidad
se retorna un array vacío.
$primary_keys = $entity->torneo_id ? 'torneo_id' : array();
//Se escribe el registro de la entidad.
drupal_write_record('module_name_torneo', $entity, $primary_keys);

//se define la variable invocation con valor de inserción por defecto.

$invocation = 'entity_insert';
//verificando si la entidad existe o es nueva, si es nueva existira al ¬¬menos una //llave en el array $primary_keys (llave
primaria definida en el //hook_entity_info()) .
if (empty($primary_keys)) {
//insertando los nuevos campos adicionados a la entidad (como la entidad no contien llaves, se inserta como nueva)
field_attach_insert('module_name_torneo', $entity);
}
else {
//Si contiene alguna llave es que ya la entidad existe y lo que debe hacer es actualizarse los nuevos campos.
field_attach_update('module_name_torneo', $entity);
//Se cambia el valor de la variable del insert anteriormente asignado a update.
$invocation = 'entity_update';
}
//Se invoca el hook 'entity_update o 'entity_insert' en dependencia del valor //que traiga en el campo llave de la entidad.
module_invoke_all($invocation, $entity, 'module_name_torneo');
return $entity;
}

//Metodo eliminar de la entidad

public function delete($entity) {
//Se invoca el metodo delete_multiple posteriormente explicado.
$this->delete_multiple(array($entity));
}

//Este método elimina 1 o varias entidades en dependencia de lo que se envié //en el array $entities pasado como parámetro.
public function delete_multiple($entities) {
$torneo_ids = array();
if (!empty($entities)) {
//Se crea una transaction
$transaction = db_transaction();
try {
//Se recorre el array de entidades y se invoca el hook 'entity_delete' de la //entity API y se eliminan los campos añadidos a la
entidad.
foreach ($entities as $entity) {

module_invoke_all('entity_delete', $entity, 'module_name_torneo');

field_attach_delete('module_name_torneo', $entity);
//Se guarda cada uno de los ids o llaves de la entidad que se eliminará.
$torneo_ids[] = $entity->torneo_id;
}
 //Se eliminan los registros de la tabla module_name_torneo que tengan en su campo de llave primaria alguno de los ids del
array , $torneo_ids.
db_delete('module_name_torneo')
->condition('torneo_id', $torneo_ids, 'IN')
->execute();
}
catch (Exception $e) {
//Se reinvierte el proseso si ocurrio un problema en la ejecución.
$transaction->rollback();
watchdog_exception('torneo_id', $e);
throw $e;
}
}
}
// Aquí podemos definir tantos métodos como necesitemos en nuestra entidad
}

Conclución:
Hasta aquí la primera parte de este curso, entre los aspectos tratados en esta primera parte, se destaca
la creación de entidades,implementación de EntityController e integración con el hook_schema() y
hook_entity_info, en próximos capítulos veremos la integración con los módulos y la gestión de los field, las
vistas y el manejo entre entidades a través del EntityContoller implementado en esta primera parte.

Anexo:
Si no quedo muy claro la explicación de la integración entre hook_schema, hook_entity_info y
EntityController, se le muestra una imagen donde se refleja la integración entre los mismo.

Se refleja la relación entre Schema,entity_info y contoladores, el hoock_entity_info integra todo ,¨base table¨
integra el schema con la entidad,y ¨controller class¨ integra los controladores que la gestionarán, y estos a
su vez implementan todos los metodos de la misma.