Template Toolkit

(русская редакция)

 [ Пособия ] [ Руководство ] [ Модули ] [ Библиотеки ] [ Утилиты ] [ Вопросы ] [ Релиз ] [ Perl-ресурсы ]
 
Поиск
Template Toolkit | Модули | Template::Plugin::DBI

Template::Plugin::DBI

 [ ◄ Template::Plugin::CGI ] [ Template::Plugin::Datafile ► ]
Интерфейс к модулю DBI.

Оглавление

ОБЗОР

 [ Индекс ] [ Модули ] [ Наверх ]

Неявное создание соединения с базой данных: 

    # ...использование списка аргументов
    [% USE DBI('dbi:driver:dbname', 'user', 'pass') %]
    # ...использование именованных параметров
    [% USE DBI( database = 'dbi:driver:dbname',
                username = 'user',
                password = 'pass' )
    %]
    # ...использование коротких именованных параметров (для ленивых людей и плохих машинисток)
    [% USE DBI( db   = 'driver:dbname',
                user = 'user',
                pass = 'pass' )
    %]
    # ...или существующий дескриптор DBI
    [% USE DBI( dbh = my_dbh_ref ) %]

Явное создание соединения с базой данных: 

    [% USE DBI %]
    [% DBI.connect(db, user, pass) %]
       ...
    [% DBI.connect(new_db, new_user, new_pass) %]
       ...
    [% DBI.disconnect %]      # final disconnect is optional

Автомагическое создание соединения с базой данных с использованием переменной окружения DBI_DSN: 

    [% USE DBI %]

Запросы к базе данных: 

    # одношаговый запрос
    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% user.uid %] blah blah [% user.name %] etc. etc.
    [% END %]
    # в два шага prepare/execute
    [% query = DBI.prepare('SELECT * FROM users WHERE uid = ?') %]
    [% FOREACH user = query.execute('sam') %]
       ...
    [% END %]
    [% FOREACH user = query.execute('abw') %]
       ...
    [% END %]

Выполнение не-SELECT команд: 

    [% IF DBI.do("DELETE FROM users WHERE uid = '$uid'") %]
       The user '[% uid %]' was successfully deleted.
    [% END %]

Использование именованных DBI соединений: 

    [% USE one = DBI(...) %]
    [% USE two = DBI(...) %]
    [% FOREACH item = one.query("SELECT ...etc...") %]
       ...
    [% END %]
    [% FOREACH item = two.query("SELECT ...etc...") %]
       ...
    [% END %]

Связывание с таблицой базы данных (через Tie::DBI): 

    [% people = DBI.tie('users', 'uid') %]
    [% me = people.abw %]   # => SELECT * FROM users WHERE uid='abw'
    I am [% me.name %]
    # clobber option allows table updates (see Tie::DBI)
    [% people = DBI.tie('users', 'uid', clobber=1) %]
    [% people.abw.name = 'not a number' %]
    I am [% people.abw.name %]   # I am a free man!

ОПИСАНИЕ

 [ Индекс ] [ Модули ] [ Наверх ]

Этот плагин Template Toolkit предоставляет интерфейс к perl-модулям DBI/DBD, позволяя интегрировать SQL запросы в шаблоны. Он также предоставляет интерфейс через модуль Tie::DBI (если он установлен в системе), так что вы можете обращаться к записям базы данных без использования SQL в шаблонах.

Объект плагина DBI можно создать следующим образом: 

    [% USE DBI %]

Это создаст неинициализированный объект DBI. Затем можно открыть соединение с базой данных с помощью метода connect(). 

    [% DBI.connect('dbi:driver:dbname', 'user', 'pass') %]

Соединение DBI может быть открыто при создании плагина, если передать аргументы конструктору, вызываевому в директиве USE. 

    [% USE DBI('dbi:driver:dbname', 'user', 'pass') %]

Вы можете использовать именованные параметры для передачи источника данных соединения, имени пользователя и пароля. 

    [% USE DBI(database => 'dbi:driver:dbname',
               username => 'user',
               password => 'pass')  %]

Для обратной совместимости с предыдущими версиями этого плагина, наряду с 'database' допускается использование 'data_source'. 

    [% USE DBI(data_source => 'dbi:driver:dbname',
               username    => 'user',
               password    => 'pass')  %]

Ленивые хакеры Template могут предпочесть использовать 'db', 'dsn' или 'connect' в качестве сокращенной формы параметра 'database', а 'user' и 'pass' как сокращение 'username' и 'password' соответственно. В строке источника данных можно опустить префикс 'dbi:', так как плагин дописывает его автомагически. 

    [% USE DBI(db   => 'driver:dbname',
               user => 'user',
               pass => 'pass')  %]

Любые дополнительные атрибуты DBI можно указать как именованные параметры. Атрибут 'PrintError' по умолчанию установлен в 0, если явно не установить его в истинное занчение. 

    [% USE DBI(db, user, pass, ChopBlanks=1) %]

Плагину можно присвоить альтернативное имя переменной в рамках обычного синтаксиса Template Toolkit: 

    [% USE mydb = DBI('dbi:driver:dbname', 'user', 'pass') %]
    [% FOREACH item = mydb.query('SELECT * FROM users') %]
       ...
    [% END %]

Имя плагина DBI можно указать в нижнем регистре, если вам так удобнее: 

    [% USE dbi(dsn, user, pass) %]
    [% FOREACH item = dbi.query('SELECT * FROM users') %]
       ...
    [% END %]

Для явного закрытия соединения с текущей базой данных можно вызвать метод disconnect(), но в общем случае в этом нет необходимости, поскольку он автоматически вызвается, когда плагин выходит из области видимости. В любое время вы можете вызвать connect(), чтобы открыть соединение с другой базой данных. Предыдущее соединение будет закрыто автоматически.

Внутри, вместо метода connect() используется метод DBI connect_cached(). Это позволяет кешировать соединение в окружении сервера, например когда Template Toolkit используется из обработчика Apache mod_perl. В этом случае просто включите модуль mod_env и используйте следующую директиву конфигурации сервера: 

    SetEnv DBI_DSN "dbi:mysql:dbname;host=dbhost;user=uname;password=pword"

Далее можно использовать плагин DBI без параметров или необходимости явно вызывать connect().

Загрузив плагин DBI и открыв соединение с базой данных одним из приведенных выше способов, вы можете далее делать запросы к базе данных, используя знакомую точечную нотацию: 

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% user.uid %] blah blah [% user.name %] etc. etc.
    [% END %]

Метод query() одновременно готовит запрос и исполняет его. Если вы хотите повторять запрос с различными параметрами, вы можете использовать отдельно prepare() и execute(). 

    [% query = DBI.prepare('SELECT * FROM users WHERE uid = ?') %]
    [% FOREACH user = query.execute('sam') %]
       ...
    [% END %]
    [% FOREACH user = query.execute('abw') %]
       ...
    [% END %]

Методы query() и execute() возвращают объект-итератор, который управляет результирующим набором. Можно сохранить ссылку на итератор и использовать метод size(), чтобы определить количество строк, возвращенных запросу. 

    [% users = DBI.query('SELECT * FROM users') %]
    [% users.size %] records returned

или даже 

    [% DBI.query('SELECT * FROM users').size %]

При использовании внутри цикла FOREACH итератор всегда связывается со специальной переменной 'loop'. Это дает возможность выполнять подобные вещи: 

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% loop.count %]/[% loop.size %]: [% user.name %]
    [% END %]

чтобы вывести результирующий набор в виде: 

    1/3: Jerry Garcia
    2/3: Kurt Cobain
    3/3: Freddie Mercury

Более подробную информацию об итераторах и реализуемых ими методах смотрите в Template::Iterator.

Плагин DBI также предоставляет метод do() для выполнение не-SELECT команд, подобных следующей: 

    [% IF DBI.do("DELETE FROM users WHERE uid = '$uid'") %]
       The user '[% uid %]' was successfully deleted.
    [% END %]

Плагин также позволяет создавать связь с таблицой в базе данных черз модуль Tie::DBI. Просто вызовите метод tie(), передав в качестве параметров имя таблицы и название поля первичного ключа. 

    [% people = DBI.tie('person', 'uid') %]

Полсе этого можно обращаться к записям таблицы базы данных как если бы они были элементами хеша 'people'. 

    My name is [% people.abw.name %]

ВАЖНОЕ ЗАМЕЧАНИЕ: XS Stash (Template::Stash::XS) в настоящий момент не поддерживает доступ к связанным хешам. Если у вас есть проблемы при использовании XS Stash, можно попробовать разрешить использование обычного модуля вместо XS. Это можно сделать установкой $Template::Config::STASH в 'Template::Stash' до создания объекта Template.

МЕТОДЫ ОБЪЕКТА

 [ Индекс ] [ Модули ] [ Наверх ]

connect($database, $username, $password)

Устанавливает соединение с базой данных. Этот метод принимает как список аргументов, так и именованные параметры, например: 

    [% DBI.connect( 'dbi:driver:dbname', 'timmy', 'sk8D00Dz' ) %]
    [% DBI.connect( database = 'dbi:driver:dbname'
                    username = 'timmy'
                    password = 'sk8D00Dz' ) %]

Метод connect() позволяет явно соединиться с источником данных. Он также может использоваться пересоединения существующего объекта к другому источнику данных.

Если дескриптор базы данных уже существует, можно передать его плагину для повторного использования через параметр 'dbh'. 

    [% DBI.connect( dbh = my_dbh_ref ) %]

query($sql)

Этот метод отправляет SQL-запрос к базе данных и создает объект-итератор для возвращения результатов. Это можно использовать непосредственно в директиве FOREACH, как показано ниже. Данные из результирующего набора запроса автоматически выбираются по строке за цикл, как требуется для эффективного расхода памяти. 

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       Each [% user.field %] can be printed here
    [% END %]

prepare($sql)

Готовит запрос для последующего использования. Метод возвращает скомпилированный объект запроса (класса Template::Plugin::DBI::Query), у которого можно последовательно вызывать метод execute(). 

    [% query = DBI.prepare('SELECT * FROM users WHERE id = ?') %]

execute(@args)

Исполняет предварительно подготовленный запрос. Этот метод нужно вызывать у объекта запроса, возвращаемого методом prepare(). Возвращает объект-итератор, который можно использовать непосредственно в директиве FOREACH. 

    [% query = DBI.prepare('SELECT * FROM users WHERE manager = ?') %]
    [% FOREACH minion = query.execute('abw') %]
       [% minion.name %]
    [% END %]
    [% FOREACH minion = query.execute('sam') %]
       [% minion.name %]
    [% END %]

do($sql)

Метод do() выполняет SQL-выражения, не возвращающие записи. Возвращает истинное значение в случае успешного выполнения выражения. 

    [% IF DBI.do("DELETE FROM users WHERE uid = 'sam'") %]
       The user was successfully deleted.
    [% END %]

tie($table, $key, \%args)

Возвращает ссылку на хеш, связанный с таблицей в базе данных, реализован через модуль Tie::DBI. Методу нужно передать в качестве аргументов имена таблицы и ключевого поля. 

    [% people = DBI.tie('users', 'uid') %]

Или, если вам так больше нравится, можно использовать именованные параметры 'table' и 'key'. 

    [% people = DBI.tie(table='users', key='uid') %]

В этом примере, модуль Tie::DBI будет преобразовывать запросы к хешу 'people' в SQL-запросы вида: 

    SELECT * FROM users WHERE uid=?

Например: 

    [% me = people.abw %]

Возвращаемая запись затем может быть использована как обычный хеш. 

    I am [% me.name %]

Пройти по всем записям таблицы можно следующим образом: 

    [% FOREACH uid = people.keys.sort;
            person = people.$uid
    %]
        * [% person.id %] : [% person.name %]
    [% END %]

С установленной опцией 'clobber' (или 'CLOBBER'), вы можете обновить запись, и эти изменения будут автоматически отражены в базе данных. 

    [% people = DBI.tie('users', 'uid', clobber=1) %]
    [% people.abw.name = 'not a number' %]
    I am [% people.abw.name %]  # I am a free man!

Также вы можете добавлять новые записи. 

    [% people.newguy = {
           name = 'Nobby Newguy'
	   ...other fields...
       }
    %]

Более подробно об опции 'CLOBBER' смотрите в Tie::DBI.

quote($value, $type)

Вызывает метод quote() лежащего в основе дескриптора DBI для квотирования значения, указанного в соответсвующем ее типу виде.

dbh()

Возвращает дескриптор базы данных, используемый в текущий момент плагином.

disconnect()

Закрывает соединение с текущей базой данных.

АВТОРЫ

 [ Индекс ] [ Модули ] [ Наверх ]

Плагин DBI был написан Симоном Мэттьюсом (Simon A Matthews), и поставлялся как отдельный модуль. Он был интегрирован в состав Template Toolkit версии 2.00 и содержит доработки Энди Уардли (Andy Wardley), Крейга Барретта (Craig Barratt), Дейва Ходжкинсона (Dave Hodgkinson) и Рафаэла Китовера (Rafael Kitover).

ВЕРСИЯ

 [ Индекс ] [ Модули ] [ Наверх ]

2.63, поставляется в составе Template Toolkit версии 2.14, дата релиза - 4 октября 2004.

АВТОРСКИЕ ПРАВА

 [ Индекс ] [ Модули ] [ Наверх ] 

  Copyright (C) 1999-2001 Simon Matthews.  All Rights Reserved

Этот модуль является свободно-распространяемым программным обеспечением; вы можете распространять и/или модифицировать его на тех же условиях, что и Perl.

СМОТРИ ТАКЖЕ

 [ Индекс ] [ Модули ] [ Наверх ]

Template::Plugin, DBI, Tie::DBI
[ ◄ Template::Plugin::CGI ] [ Template::Plugin::Datafile ► ]

[ Пособия ] [ Руководство ] [ Модули ] [ Библиотеки ] [ Утилиты ] [ Вопросы ] [ Релиз ] [ Perl-ресурсы ]

http://www.template-toolkit.ru/