Drupal → Создание простейшего модуля управления данными

Временами возникает необходимость хранить данные в собственной таблице. Например модуль BUEditor хранит список кнопок в таблице bueditor_buttons, а модуль Contact список категорий в таблице contact. Понятно, что ноды для этого не подходят и встаёт вопрос о создании функционала по управлению этими данными.

Для примера создадим модуль, который будет управлять набором неких альбомов. Минимум функций, который требуется от него это — форма добавления альбома, возможность отредактировать или удалить созданный альбом, и страница со списком всех альбомов.

Первым делом создаём файл album.install, в котором описываем схему таблицы и реализуем хуки для ёё создания/удаления:

/**
 * Реализация hook_schema()
 * Описание таблицы `albums` с тремя полями - идентификатор альбома, название, год выхода
 */
function album_schema()
{
    $schema['albums'] = array(
        'fields' => array(
            'aid' => array(
                'description' => 'Album ID',
                'type' => 'serial',
                'unsigned' => true,
                'not null' => true,
            ),
            'title' => array(
                'description' => 'Album title',
                'type' => 'varchar',
                'length' => 100,
                'not null' => true,
            ),
            'year' => array(
                'description' => 'Album year',
                'type' => 'int',
                'unsigned' => true,
                'not null' => true,
            ),
        ),
        'primary key' => array('aid'),
    );
    
    return $schema;
}

/**
 * Реализация hook_install()
 * Создание таблицы `albums` при первом включении модуля
 */
function album_install()
{
    drupal_install_schema('album');
}
 
/**
 * Реализация hook_uninstall()
 * Удаление таблицы `albums` при деинсталяции модуля
 */
function album_uninstall()
{
    drupal_uninstall_schema('album');
}

В файле album.module регистрируем адреса, по которым будет осуществляться управление данными:

/**
 * Реализация hook_menu()
 */
function album_menu()
{
    // список альбомов
    $items['album'] = array(
        'title' => 'Albums',
        'page callback' => 'album_list',
        'access arguments' => array('administer site configuration'),
    );
 
    $items['album/list'] = array(
        'title' => 'Albums list',
        'type' => MENU_DEFAULT_LOCAL_TASK,
        'weight' => 1,
    );
 
    // форма добавления альбома
    $items['album/add'] = array(
        'title' => 'Add album',
        'page callback' => 'drupal_get_form',
        'page arguments' => array('album_form'),
        'access arguments' => array('administer site configuration'),
        'type' => MENU_LOCAL_TASK,
        'weight' => 2,
    );
    
    // редактирование альбома
    $items['album/%album/edit'] = array(
        'title' => 'Edit album',
        'page callback' => 'drupal_get_form',
        'page arguments' => array('album_form', 1),
        'access arguments' => array('administer site configuration'),
        'type' => MENU_CALLBACK,
    );
    
    // удаление альбома
    $items['album/%album/delete'] = array(
        'title' => 'Delete album',
        'page callback' => 'album_delete',
        'page arguments' => array(1),
        'access arguments' => array('administer site configuration'),
        'type' => MENU_CALLBACK,
    );
    
    return $items;
}

Список альбомов и форма добавления альбома будут доступны в виде вкладок, о чём говорит тип MENU_DEFAULT_LOCAL_TASK и MENU_LOCAL_TASK.

Создаём форму добавления/редактирования альбома и функцию, которая будет обрабатывать форму и записывать результат в базу:

/**
 * Форма добавления/редактирования альбома
 */
function album_form(&$form_state, $album = null)
{
    $form['title'] = array(
        '#title' => 'Название',
        '#description' => 'Название альбома',
        '#type' => 'textfield',
        '#default_value' => $album ? $album->title : '',
        '#required' => true,
    );
    
    $form['year'] = array(
        '#title' => 'Год',
        '#description' => 'Год выхода альбома',
        '#type' => 'textfield',
        '#default_value' => $album ? $album->year : '',
        '#required' => true,
        '#size' => 5,
    );
    
    $form['submit'] = array(
        '#type' => 'submit',
        '#value' => $album ? 'Сохранить' : 'Добавить',
    );
    
    if ($album)
    {
        $form['aid'] = array(
            '#type' => 'value',
            '#value' => $album->aid,
        );
    }
    
    return $form;
}

/**
 * Добавление/сохранение альбома
 */
function album_form_submit($form, &$form_state)
{
    $album = array(
        'title' => $form_state['values']['title'],
        'year'  => $form_state['values']['year'],
    );
    
    // сохранение
    if (isset($form_state['values']['aid']))
    {
        $album['aid'] = $form_state['values']['aid'];
        drupal_write_record('albums', $album, 'aid');
        drupal_set_message('Альбом сохранён');
    }
    // добавление
    else
    {
        drupal_write_record('albums', $album);
        drupal_set_message('Альбом добавлен');
    }
    
    drupal_goto('album');
}

Добавляем page callback для просмотра списка альбомов в виде таблицы:

/**
 * Список альбомов
 */
function album_list()
{
    $tableHeader = array('Название', 'Год', 'Действия');
    $tableData = array();
    $albums = db_query("SELECT * FROM {albums}");
    
    while ($album = db_fetch_object($albums))
    {
        $actions = array(
            l('редактировать', 'album/' . $album->aid . '/edit'),
            l('удалить',       'album/' . $album->aid . '/delete', array('query' => 'token=' . drupal_get_token('album-' . $album->aid))),
        );
        
        $tableData[] = array($album->title, $album->year, implode(' | ', $actions));
    }
    
    return theme('table', $tableHeader, $tableData);
}

Добавляем функцию удаления альбома, не забывая про защиту от CSRF:

/**
 * Удаление альбома
 */
function album_delete($album)
{
    if (!drupal_valid_token($_GET['token'], 'album-' . $album->aid))
    {
        return drupal_access_denied();
    }
    
    db_query("DELETE FROM {albums} WHERE aid = %d", $album->aid);
    drupal_set_message('Альбом удалён');
    drupal_goto('album');
}

И последним штрихом добавляем функцию, которая будет возвращать информацию об альбоме по его id:

/**
 * Возвращает информацию о альбоме
 */
function album_load($aid)
{
    return db_fetch_object(db_query("SELECT * FROM {albums} WHERE aid = %d", $aid));
}

Благодаря ей, в hook_menu() можно использовать wildcard loader %album, который передаст в page callback не id альбома, а объект с заполненными свойствами.

Исходники модуля.

После написания статьи понял, что в друпале не хватает какого-нибудь кодо-генератора/круд-генератора или скафолдинга. Например описываешь модель по подобию Schema DB, а друпал сам генерит формы, таблицы, функции, на основе этой модели. Жизнь была бы немного проще.

Создание простейшего модуля управления данными в Drupal 7.