Cgi(3)

Материал из wiki.lissyara.su
Перейти к: навигация, поиск

CGI(3) Справочное руководство Perl программистов CGI(3)


ИМЯ

CGI - Класс Интерфейса Простого Общего Шлюза

СИНТАКСИС

# CGI сценарий, создающий заполняемые формы
# и возвращающий эхом их значения.
use CGI qw/:standard/;
print header,
      start_html('A Simple Example'),
      h1('A Simple Example'),
      start_form,
      "What's your name? ",textfield('name'),p,
      "What's the combination?", p,
      checkbox_group(-name=>'words',
                     -values=>['eenie','meenie','minie','moe'],
                     -defaults=>['eenie','minie']), p,
      "What's your favorite color? ",
      popup_menu(-name=>'color',
                     -values=>['red','green','blue','chartreuse']),p,
      submit,
      end_form,
      hr;
 if (param()) {
     my $name	    = param('name');
     my $keywords  = join ', ',param('words');
     my $color     = param('color');
     print "Your name is",em(escapeHTML($name)),p,
           "The keywords are: ",em(escapeHTML($keywords)),p,
           "Your favorite color is ",em(escapeHTML($color)),
           hr;
 }
 print end_html;

АННОТАЦИЯ

Эта perl библиотека использует объекты perl5 для простого создания заполняемых форм и разбора их содержимого. Этот пакет описывает CGI объекты, содержащие значения текущих строк запроса и других значений состояния. Используя методы CGI объектов, Вы можете изучать ключевые слова и параметры передаваемые Вашим сценариям, и создавать формы инициализационные значения которых передаются с текущего запроса (сохраняя, таким образом, информацию о состоянии). Модуль обеспечивает сокращённые функции производящие шаблонный HTML, и тем самым, сокращая время разработки и ошибки в коде. Также обеспечивает функциональность для некоторых расширенных особенностей CGI сценариев, включая поддержку для закачки файлов, куки, каскадных таблиц стилей, server push (способ передачи данных с сервера на клиент) и фреймов.
CGI.pm также обеспечивает простой функционально-ориентированный стиль программирования для программистов не использующих объектно-ориентированные особенности.
Текущая версия CGI.pm доступна по ссылкам:
http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
ftp://ftp-genome.wi.mit.edu/pub/software/WWW/

ОПИСАНИЕ

СТИЛЬ ПРОГРАММИРОВАНИЯ
Есть два стиля программирования с использованием CGI.pm: объектно-ориентированный стиль и функционально-ориентированный стиль. В объектно-ориентированном стиле Вы создаёте один или более CGI объектов и затем используете методы объекта для создания различных элементов страницы. Каждый CGI объект начинается со списка именованных параметров, передаваемых Вашему CGI сценарию от сервера. Вы можете модифицировать объекты, сохранить их в файл или базу данных и пересоздать их. Поскольку каждый объект соответствует "состоянию" CGI сценария, и поскольку каждый параметр объекта перечислен независимо от остальных объектов, становится возможным сохранить состояние сценария и затем восстановить его.
На пример, используя объектно-ориентированный стиль, ниже показан способ создания простой "Hello World" HTML страницы:
#!/usr/local/bin/perl -w
use CGI;			       # загрузить CGI процедуры
$q = new CGI; 		       # создать новый CGI объект
print $q->header,		       # создать HTTP заголовок
      $q->start_html('hello world'), # начать HTTML
      $q->h1('hello world'),	       # заголовок 1-го уровня
      $q->end_html;		       # конец HTML
В функционально-ориентированном стиле, по умолчанию, есть один CGI объект, с которым Вы редко будете работать напрямую. Взамен Вы только вызываете функции для извлечения CGI параметров, создаёте HTML теги, управляете кукисами, и т.д. Так обеспечивается аккуратный программный интерфейс, но ограниченный использованием одного CGI объекта одновременно. Следующий пример выводит некоторую страницу, с использованием функционально-ориентированного интерфейса. Главное различие в том, что мы должны импортировать набор функций в наше пространство имён (обычно "стандартные" ("standard") функции) и нет надобности в создании CGI объекта.
#!/usr/local/bin/perl
use CGI qw/:standard/;	   # загрузить стандартые CGI процедуры
print header, 		   # создать HTTP заголовок
      start_html('hello world'), # начать HTML
      h1('hello world'),	   # заголовок 1-го уровня
      end_html;		   # конец HTML
Примеры приведённые в этом документе в основном используются в объектно-ориентированном стиле. Смотрите КАК ИМПОРТИРОВАТЬ ФУНКЦИИ для важной информации в функционально-ориентированном программировании в CGI.pm
ВЫЗОВ CGI.PM ПРОЦЕДУР
Многие CGI.pm процедуры принимают несколько аргументов, иногда более чем 20-ти! Для упрощения этого интерфейса, все процедуры используют именованные аргументы вызываемые стилем похожим на следующий:
print $q->header(-type=>'image/gif',-expires=>'+3d');
Каждому аргументу предшествует тире. Регистр букв не играет роли в списке аргументов. Можно использовать -type, -Type и -TYPE. По сути, только первый аргумент должен начинаться с тире. Если тире присутствует в первом аргументе, CGI.pm предполагает тире для следующих аргументах.
Некоторые процедуры обычно вызываются с единственным аргументом. В случае этих процедур Вы можете использовать единственный аргумент не используя имени аргумента. header() является одним из этих процедур. В этом случае, единственный аргумент в типе документа.
print $q->header('text/html');
Другие подобные процедуры задокументированы ниже.
Иногда именованные аргументы ожидают скаляр, иногда ссылка на массив и иногда ссылка на хеш. Часто, Вы можете передать другой тип аргумента и процедура сама преобразует его. На пример, процедура param() используется для установки CGI параметра в единственное или многозначное значение. Два этих случая показаны ниже:
$q->param(-name=>'veggie',-value=>'tomato');
$q->param(-name=>'veggie',-value=>['tomato','tomahto','potato','potahto']);
Большое число процедур в CGI.pm не объявлено, но автоматически генерируются при надобности. Есть "HTML сокращения", процедуры генерирующие HTML теги для использования динамически-генерируемых страниц. HTML теги имеют два атрибута (пара атрибут="значение" внутри тега) и содержимое (часть между открытием и закрытием пар.) Для различия между атрибутами и содержимым, CGI.pm использует соглашения передающие HTML атрибуты как хеш ссылку в качестве первого атрибута и содержимое, в качестве следующего аргумента. Работает так:
Код Генерируемый HTML
h1() <h1>
h1('некоторые','данные'); <h1>некоторые данные</h1>
h1({-align=>left}); <h1 align="LEFT">
h1({-align=>left},'содержимое'); <h1 align="LEFT">содержимое</h1>
Описание HTML тегов в деталях смотрите ниже.
Много новичков, использующие CGI.pm, непонимают различий между вызовом HTML сокращений, которые требуют фигурных скобок вокруг атрибутов HTML тегов и вызов других процедур, управляющих генерацией атрибутов без фигурных скобок. Не смущайтесь. Фигурные скобки удобно использовать во всём, кроме HTML сокращений. Если Вам нравится, Вы можете использовать фигурные скобки при вызове процедур, принимающих именованные аргументы. Например:
print $q->header( {-type=>'image/gif',-expires=>'+3d'} );
Если Вы используете переключатель -w, Вы получите предупреждение, что некоторое CGI.pm имя атрибута конфликтует со встроенным в Perl функциями. Наиболее часто такое поведение проявляется в аргументе -values, используемом для создания много-значных меню, блоков радио-кнопок и т.д. Есть несколько путей обхода этого предупреждения:
1. Использовать другое имя для аргумента, если это имя доступно. Например, -value является алиасом для -values.
2. Изменить регистр, т.е. -Values
3. Окружить имя аргумента кавычками, т.е. '-values'
Есть много процедур, которые могут быть полезными при работе с не опознаваемым именованным аргументом. Например, Вы можете создать нестандартные поля HTTP заголовока с помощью именованных аргументов:
print $q->header(-type  =>  'text/html',
                 -cost  =>  'Three smackers',
                 -annoyance_level => 'high',
                 -complaints_to   => 'bit bucket');
Получится следующий нестандартный HTTP заголовок:
HTTP/1.0 200 OK
Cost: Three smackers
Annoyance-level: high
Complaints-to: bit bucket
Content-type: text/html
Помните, что метод помеченный подчёркиванием автоматически транслируется в дефисы. HTML-сгенерированные процедуры выполняются с помощью различных типов трансляций.
Эта свойство позволяет Вам поддерживать часто сменяющиеся HTTP и HTML "стандарты".
СОЗДАНИЕ НОВОГО ОБЪЕКТА ЗАПРОСА (ОБЪЕКТНО-ОРИЕНТИРОВАННЫЙ СТИЛЬ):
$query = new CGI;
Будет проанализирован ввод (поддерживает GET и POST методы) и держит его внутри объекта perl5 под названием $query.
Все дескрипторы файлов с закачек файлов будут сброшены с текущих позиций на начало файла.
СОЗДАНИЕ НОВОГО ОБЪЕКТА ЗАПРОСА С ВВОДА ФАЙЛА
$query = new CGI(ВВОДНЫЙ_ФАЙЛ);
Если Вы обеспечите дескриптор файла для метода new(), будут прочтены параметры с файла (или STDIN, или любого другого). Файл может быть в любых формах описанных после отладки (то есть серии новых строк разделённых парами ТЕГ=ЗНАЧЕНИЕ будут работать). Удобно, этот тип файла создан с помощью метода save() (смотрите ниже). Можно восстанавливать и сохранять сразу несколько записей.
Сторонники чистоты языка Perl будут рады узнать о том, что этот синтаксис применим к дескрипторам файлов и даже к спискам glob дескрипторов, имеющих "официальный" способ передачи дескриптора:
$query = new CGI(\*STDIN);
Также можно инициализировать CGI объект с помощью объектов FileHandle или IO::File.
Если Вы используете функционально-ориентированный интерфейс и хотите инициализировать состояние CGI с дескриптора файла, используйте restore_parameters(). Произойдёт (пере)инициализация CGI объекта по умолчанию с помощью указанного дескриптора файла.
open (IN,"test.in") || die;
restore_parameters(IN);
close IN;
Также можно инициализировать объект запроса со списка ассоциативного массива:
$query = new CGI( {'dinosaur'=>'barney',
                   'song'=>'I love you',
                   'friends'=>[qw/Jessica George Nancy/]}
                );
или с помощью правильно форматированной URL строки запроса:
$query = new CGI('dinosaur=barney&color=purple');
или с предварительно созданного CGI объекта (в данном случае: клон списка параметров, но не включающих других объектно-специфических полей, таких как авто выход):
$old_query = new CGI;
$new_query = new CGI($old_query);
Для создания пустого запроса, инициализируйте его с помощью пустой строки или хеша:
$empty_query = new CGI("");
-или-
$empty_query = new CGI({});
ПОЛУЧЕНИЕ СПИСКА КЛЮЧЕВЫХ СЛОВ С ЗАПРОСА:
@keywords = $query->keywords
Если сценарий ссылается как результат <ISINDEX> поиска, то проанализированные ключевые слова могут быть получены в виде массива через использование метода keywords().
ПОЛУЧЕНИЕ ИМЁН ВСЕХ ПАРАМЕТРОВ ПЕРЕДАННЫХ ВАШЕМУ СЦЕНАРИЮ:
@names = $query->param
Если сценарий был вызван со списком параметров (т.е. "name1=value1&name2=value2&name3=value3"), метод param() вернёт имена параметров в виде списка. Если сценарий вызван как <ISINDEX> сценарий и содержит строку без амперсандов (т.е. "value1+value2+value3"), то в этом случае будет единственный параметр под названием "keywords" содержащий ключевые слова разделённые "+".
ПОМНИТЕ: Как в версии 1.5, массив параметра имён будет возвращён в том же порядке, в котором он был отправлен браузером. Обычно этот порядок следует тому же порядку что и объявленный в форме (однако это не часть спецификации, и, соответственно, не гарантируется).
ПОЛУЧЕНИЕ ЗНАЧЕНИЯ ИЛИ ЗНАЧЕНИЙ ЕДИНСТВЕННОГО ИМЕНОВАННОГО ПАРАМЕТРА:
@values = $query->param('foo');
-или-
$value = $query->param('foo');
Передаёт методу param() единственный аргумент для получения значения именованного параметра. Если параметр является многозначным (т.е. от многозначного выбора в прокручивающемся списке), Вы можете запросить получение массива. В противном случае метод вернёт единственное значение.
Если значение не получено в строке запроса, как в запросе "name1=&name2=", будет возвращена пустая строка.
Если параметр вообще не создан, param() вернёт undef в скалярном контексте, и пустой список в контексте списка.
УСТАНОВКА ЗНАЧЕНИЯ(ИЙ) ИМЕНОВАННОГО ПАРАМЕТРА:
$query->param('foo','an','array','of','values');
Устанавливаются значение для именованного параметра 'foo' в массив значений. Это один из путей изменения значения поля ПОСЛЕ вызова сценария. (Другой путь использование параметра -override применённого всеми методами генерирующими элементы формы.)
param() также определяет стиль именованных параметров вызванных следующим образом:
$query->param(-name=>'foo',-values=>['an','array','of','values']);
-или-
$query->param(-name=>'foo',-value=>'the value');
ДОБАВЛЕНИЕ ДОПОЛНИТЕЛЬНЫХ ЗНАЧЕНИЙ К ИМЕНОВАННЫМ ПАРАМЕТРАМ:
$query->append(-name=>'foo',-values=>['yet','more','values']);
Этот способ добавляет значение или список значений именованному параметру. Значения добавляются в конец параметра, при условии что он уже создан. В противном случае этот параметр создаётся. Помните что этот метод может определять только синтаксис вызываемых именованных аргументов.
ИМПОРТИРОВАНИЕ ВСЕХ ПАРАМЕТРОВ В ПРОСТРАНСТВО ИМЁН:
$query->import_names('R');
Создаются серии переменных в пространстве имён 'R'. Например, $R::foo, @R:foo. Для списков ключевых списков, применяется ключевое слово @R:: (@R::keywords). Если пространство имён не дано, будет применён метод 'Q'. ПРЕДУПРЕЖДЕНИЕ: не импортируйте в 'main'; это большая брешь в безопасности!!!!
ПРИМЕЧАНИЕ №1: Имена переменных трансформируются при необходимости в допустимые имена переменных языка Perl. Все не-допустимые символы трансформируются в подчёркивания. Если Вам надо сохранить оригинальные имена, используйте метод param() взамен доступа к CGI переменным по именам.
ПРИМЕЧАНИЕ №2: В ранних версиях, этот метод вызывается с помощью import(). Как и в версии 2.20, это имя окончательно удалено с целью избежания конфликтов со встроенным в модуль Perl оператора импортирования.
ПОЛНОЕ УДАЛЕНИЕ ПАРАМЕТРА:
$query->delete('foo','bar','baz');
Полная очистка списка параметров. Временами полезно для сброса параметров, которые не должны передаваться между вызовами сценариев.
Если Вы используете функцию вызова интерфейса, используйте "Delete()" взамен обхода конфликтов с помощью встроенного оператора delete языка Perl.
УДАЛЕНИЕ ВСЕХ ПАРАМЕТРОВ:
$query->delete_all();
Производится полная очистка CGI объектов. Может оказаться полезным для установки параметров по умолчанию заполняемых форм.
Используйте Delete_all() взамен интерфейса вызова функции.
ОБРАБОТКА НЕ-URLКОДИРОВАННЫХ АРГУМЕНТОВ
Если данные передаваемые с помощью POST не являются application/x-www-form-urlencoded или multipart/form-data, то в этом случае данные не будут передаваться, но будут возвращены как-есть в параметре под названием POSTDATA. Для получения его, используйте следующий код:
my $data = $query->param('POSTDATA');
Также данные переданные через PUT можно получить с помощью следующего кода:
my $data = $query->param('PUTDATA');
(Не переживайте, если Вы не знаете каким методом были переданы данные. Эти проблемы должны волновать людей использующих XML в связке с CGI для специализированных задач.)
ПРЯМОЙ ДОСТУП К СПИСКУ ПАРАМЕТРОВ:
$q->param_fetch('address')->[1] = '1313 Mockingbird Lane';
unshift @{$q->param_fetch(-name=>'address')},'George Munster';
Если Вы хотите получить доступ к списку параметров с помощью метода не соответствующего вышеприведённому, то можно использовать прямую ссылку плюс вызов метода param_fetch() с именем . Будет возвращён массив с ссылками к именованным параметрам, которыми Вы можете манипулировать любым способом.
Также возможно использование стиля именованных аргументов с использованием аргумента -name.
ПОЛУЧЕНИЕ СПИСКА ПАРАМЕТРОВ КАК ХЕША:
$params = $q->Vars;
print $params->{'address'};
@foo = split("\0",$params->{'foo'});
%params = $q->Vars;
use CGI ':cgi-lib';
$params = Vars;
Многим людям бывает нужно получить список параметров в виде хеша в котором ключами являются имена CGI параметров, а значениями - значения параметров. Метод Vars() выполняет это. Вызываемый в скалярном контексте, он возвращает список параметра в виде связанной ссылки хеша. Изменение ключа изменяет значение параметра в основном списке CGI параметра. Вызываемый в контексте списка, он возвращает список параметра в виде обычного хеша. Позволяет Вам читать содержимое списка параметра, но не изменять его.
При использовании этого метода, следует остерегаться многозначных CGI параметров. Поскольку хеш не может различать скалярный и списочный контексты, многозначные параметры возвращаются в виде упакованной строки, разделённой символом "\0" (null). Вам нужно разделять эту упакованную строку в порядке получения отдельных значений. Это соглашение введено Стивом Бреннером (Steve Brenner) в его cgi-lib.pl модуле для Perl 4-ой версии.
Если Вам понадобиться использовать Vars() как функцию, импортируйте :cgi-lib для вызовов функции (также читайте секцию о совместимости CGI-LIB).
СОХРАНЕНИЕ СОСТОЯНИЯ СЦЕНАРИЯ В ФАЙЛ:
$query->save(\*FILEHANDLE)
Сохранение текущего состояния формы в указанный дескриптор файла. Вы можете прочесть его для восстановления с дескриптора файла с помощью метода new(). Помните что дескриптор файла может быть в файле, в трубе (pipe) или в любом другом месте!
Формат сохранённого файла следующий:
NAME1=VALUE1
NAME1=VALUE1'
NAME2=VALUE2
NAME3=VALUE3
=
Пара имя и значение URL независимы. Многозначные CGI параметры представлены в виде повторяющихся имён. Запись сессии разделяется одним символом =. Вы можете писать на вывод множественные записи и читать их с помощью нескольких вызовов. Вы можете выполнять эту операцию с помощью нескольких сессий и открытием файла в режиме добавления, помогает создать простейшую гостевую книгу, или хранить историю запросов пользователей. Вот простой пример создания множественных записей сессии:
use CGI;
open (OUT,">>test.out") || die;
$records = 5;
foreach (0..$records) {
    my $q = new CGI;
    $q->param(-name=>'counter',-value=>$_);
    $q->save(\*OUT);
}
close OUT;
# переоткрытие для чтения
open (IN,"test.out") || die;
while (!eof(IN)) {
    my $q = new CGI(\*IN);
    print $q->param('counter'),"\n";
}
Формат файла используемый для сохранения/восстановления идентичен формату "Boulderio" используемому для обмена данными в Whitehead Genome Center и позволяет манипуляции над собой с помощью утилит Boulderio. Смотрите
http://stein.cshl.org/boulder/
для подробных характеристик.
Если Вы хотите использовать этот метод для функционально-ориентированных (не ОО) интерфейса, экспортированное имя для этого метода: save_parameters().
ИЗВЛЕЧЕНИЕ CGI ОШИБОК
Ошибки могут происходить при осуществлении пользовательского ввода, особенно при загрузке файлов на сервер. При возникновении ошибки, CGI остановит работу и возвратит пустой список параметров. Вы можете проверять наличие и природу возникновения ошибок используя функцию cgi_error(). Сообщение об ошибке форматируется как код статуса HTTP. Вы можете либо включать текст ошибки в HTML страницу, или использовать его как значение HTTP статуса:
my $error = $q->cgi_error;
if ($error) {
    print $q->header(-status=>$error),
          $q->start_html('Problems'),
          $q->h2('Request not processed'),
          $q->strong($error);
    exit 0;
}
При использовании функционально-ориентированного интерфейса (смотрите следующую секцию), ошибки могут появиться только при первом вызове param(). Будьте готовы к этому!
ИСПОЛЬЗОВАНИЕ ФУНКЦИОНАЛЬНО-ОРИЕНТИРОВАННОГО ИНТЕРФЕЙСА
Для использования функционально-ориентированного интерфейса, Вы должны объявить какие-либо CGI.pm процедуры или установить процедуры для импортирования в Вашы имена сценариев. Есть некоторые издержки связанные с этим импортированием, но их немного.
use CGI <list of methods>;
Перечисленные методы импортируются в текущий пакет; Вы можете вызывать их прямо без предварительного создания CGI объекта. Этот пример покзывает как импортировать методы param() и header() и затем непосредственно использовать их:
use CGI 'param','header';
print header('text/plain');
$zipcode = param('zipcode');
Чаще Вам придёться импортировать общие установки функций, ссылаясь на группы по имени. Всем настройкам функции предшествует символ ":", например ":html3" (для тегов в стандарте HTML 3).
Вот список настроек функции, которые Вы можете импортировать:
:cgi
Импорт всех методов CGI-дескрипторов, таких как param(), path_info() и тому подобное.
:form
Импорт всех методов, заполняющих формы, таких как textfield().
:html2
Импорт всех методов, генерирующих стандартные элементы HTML 2.0.
:html3
Импорт всех методов, генерирующих элементы HTML 3.0 (таких как <table>, <super> и <sub>).
:html4
Импорт всех методов, генерирующих элементы HTML 4 (таких как <abbrev>, <acronym> и <thead>).
:netscape
Импорт всех методов, генерирующих Netscape-специфичные HTML расширения.
:html
Импорт всех HTML-генерированных ярлыков (т.е. 'html2' + 'html3' + 'netscape')...
:standard
Импорт "standard" особенностей, 'html2', 'html3', 'html4', 'form' и 'cgi'.
:all
Импорт всех доступных методов. Полный список, смотрите в коде CGI.pm, где объявлена переменная %EXPORT_TAGS.
Если Вы импортируете функцию, имя которой не является частью CGI.pm, модуль будет обращаться с ним, как с новым HTML тегом и генерировать соответствующую подпрограмму. Вы можете использовать её как и остальные HTML теги. Эти образом обеспечивается быстро развивающийся "стандарт" HTML. Например, Microsoft выпустит новый тег названный как <gradient> (которая заливает монитор пользователя переливающимся градиентом, отмена градиента происходит после перезагрузки машины). Вам не нужно ожидать выхода новой версии CGI.pm, можете пользоваться этим тегом незамедлительно:
use CGI qw/:standard :html3 gradient/;
print gradient({-start=>'red',-end=>'blue'});
Помните, что в целях увеличения производительности CGI.pm не надо использовать стандартный Экспортер синтаксис для загрузки указанных символов. В будущем это положение может измениться.
Если Вы импортируете какой-нибудь разрабатываемый CGI или методы генерации форм, тогда, по умолчанию, CGI объект будет создан и инициализирован автоматически, для этого достаточно один раз использовать любой существующий метод. В эти методы входят param(), textfield(), submit() и им подобные. (Если Вам нужен прямой доступ к CGI объекту, Вы можете его в глобальной переменной $CGI::Q). Импортируя CGI.pm методы, Вы можете создавать визуально элегантные сценарии:
use CGI qw/:standard/;
print
    header,
    start_html('Simple Script'),
    h1('Simple Script'),
    start_form,
    "What's your name? ",textfield('name'),p,
    "What's the combination?",
    checkbox_group(-name=>'words',
                   -values=>['eenie','meenie','minie','moe'],
                   -defaults=>['eenie','moe']),p,
    "What's your favorite color?",
    popup_menu(-name=>'color',
               -values=>['red','green','blue','chartreuse']),p,
    submit,
    end_form,
    hr,"\n";
 if (param) {
    print
        "Your name is ",em(param('name')),p,
        "The keywords are: ",em(join(", ",param('words'))),p,
        "Your favorite color is ",em(param('color')),".\n";
    }
    print end_html;
ПРАГМЫ
В дополнение к настройкам функции, существует число прагм, которые Вы можете импортировать. Прагмы, всегда предшествующие дефисом, изменяют путь функций CGI.pm различными способами. Прагмы, установки функции, и индивидуальные функции могут импортироваться той же use() строкой. Например, следующий код использует оператор импортирующий стандартную настройку функций и включает режим отладки (pragma -debug):
use CGI qw/:standard -debug/;
Текущий список прагм следующий:
-any
Когда Вы используете CGI -any, затем метод, не распознающий объект запроса, будет интерпретирован как новый HTML тег. Таким образом осуществляется поддержка следующего специального Netscape или Microsoft HTML расширения. Позволит работать с новыми и не поддерживаемыми тегами:
use CGI qw(-any);
$q=new CGI;
print $q->gradient({speed=>'fast',start=>'red',end=>'blue'});
Затем использование <cite>any</cite> может быть причиной опечатки имени метода интерпретируемого как HTML тег, используйте с осторожностью и не всегда.
-compile
Предварительная компиляция обнаруженных автоматически загруженных методов, взамен поздней компиляции. Полезно для сценариев запускаемых в продолжительный период времени под FastCGI или mod_perl, и предназначено для Perl компилятора за авторством Малкольма Битти (Malcolm Beattie). Используйте совместно с методами или с семейством метода.
use CGI qw(-compile :standard :html3);
или взамен
use CGI qw(-compile :all);
Помните, что использование прагмы -compile в этом пути всегда имеет эффект импортирования скомпилированных функций в текущее пространство имён. Если Вы хотите произвести компиляцию без импортирования, используйте метод compile():
use CGI();
CGI->compile();
Особенно полезно в окружении mod_perl, в котором Вам, возможно, понадобится прекомпилировать все CGI процедуры в сценарий запуска, и затем импортировать функции отдельно в каждом сценарии mod_perl.
-nosticky
По умолчанию модуль CGI выполняет функцию сохранения состояния вызываемую "липкими" ("sticky") полями. Принцип работы следующий: если Вы пересоздали форму, методы, генерирующие значения полей формы, будут вызывать param() для проверки существования аналогично названных параметров, присутствующих в строке запроса. Если они найдут параметр с подобным именем, они используют его для установки значений по умолчанию.
Временами это не то что Вам надо. Прагма -nosticky запрещает такое поведение. Вы также можете избирательно изменять липкое (sticky) поведение для каждого генерируемого элемента.
-tabindex
Автоматически добавлять аттрибуты tab индекса для каждого поля формы. С отключенной опцией, Вы можете вручную добавлять индексы tab'ам с помощью передачи опции -tabindex каждому методу генерирующему поля.
-no_undef_params
Указывает CGI.pm не включать параметр undef в список параметра.
-no_xhtml
По умолчанию, CGI.pm версии 2.69 и выше создаёт XHTML (http://www.w3.org/TR/xhtml1/). Прагма -no_xhtml отключает эту особенность. Спасибо за эту особенность Михалису Карбианису (Michalis Kabrianis) <kabrianis@hellug.gr>.
Если параметр -dtd функции start_html() указан в HTML 2.0 или 3.2 DTD, XHTML будет автоматически отключать эту прагму в случае её не нужности.
-utf8
Указывает CGI.pm создавать все параметры в виде UTF-8 строк. Используйте эту прагму с осторожностью, так как она может воспрепятствовать процессу бинарной загрузки файлов на сервер. Лучше вручную выбрать поля ожидающие возврата utf-8 строк и конвертирующих их с помощью строк подобной этой:
use Encode;
my $arg = decode utf8=>param('foo');
-nph
Указывает CGI.pm создавать заголовки соответствующие сценарию NPH (no parsed header - не разбираемые заголовки). Вам может понадобится выполнять другие вещи для указания серверу что этот сценарий является NPH. Смотрите обсуждение NPH сценариев ниже.
-newstyle_urls
Разделять пары имя=значение в строке запроса CGI параметра точкой с запятой, а не амперсандами. Например:
?name=fred;age=24;favorite_color=3
Строка запроса разделённая точкой с запятой всегда принимается, но не создаётся функциями self_url() и query_string() если не указать прагму -new- style_urls.
Применяется по умолчанию в версии 2.64.
-oldstyle_urls
Разделять пары имя=значение в строках запроса CGI параметра амперсандами а не точками с запятой. По умолчанию не применяется.
-autoload
Принудительно включает автозагрузку, таким образом, все функции в Вашей программе не распознаются при отсылке к CGI.pm для возможной оценки. Позволяет Вам использовать все CGI.pm функции без добавления их в Вашу символьную таблицу, относящуюся к пользователям mod_perl озабоченным проблемой потребленя памяти. Предупреждение: при активированном -autoload, Вы не сможете использовать "режим поэзии" (функции без круглых скобок). Используйте hr() взамен hr, или добавьте что-нибудь похожее на использование qw/hr p header/ в начале Вашего сценария.
-no_debug
Отключает свойство обработки командной-строки. Если Вы хотите запустить сценарий CGI.pm с командной строки для создания HTML, и не хотите читать CGI параметры с командной строки или с STDIN, используйте эту прагму:
use CGI qw(-no_debug :standard);
-debug
Включение полной отладки. В дополнение к чтению CGI аргументов с командной строки, CGI.pm сделает паузу и попытается прочитать аргументы с STDIN, выведя сообщение "(offline mode: enter name=value pairs on standard input)".
Смотрите раздел отладки для подробной информации.
-private_tempfiles
CGI.pm имеет процесс загрузки файла на сервер. Обычно загруженные на сервер файлы помещаются во временную директорию, затем удаляются по завершению работы. Однако, появляется риск перехвата описанный в секции загрузки файлов на сервер. Автор другого CGI сценария может заглянуть в эти данные во время загрузки, возможен случай когда этими данными может быть конфиденциальная информация. На Unix системах, прагма -private_tempfiles заставляет разъединять временные файлы во время загрузки на сервер, а затем восстанавливает их, но этот способ не может полностью исключить перехват данных (всё же остаётся состояние потенциальной гонки). Для усложнения жизни атакующим личностяи, программа выбирает имена временных файлов путём высчитывания 32 битовой контрольной суммы входящего HTTP заголовка.
Для гарантиии невозможности прочтения временного файла другими CGI сценариями, используйте suEXEC или программу-обёртку CGI для запуска Вашего сценария. Временный файл создаётся в режиме 0600 (другая группа не сможет прочесть).
Временная директория выбирается с использованием следующего алгоритма:
1. если текущий пользователь (т.е. "nobody") имеет директорию названную как "tmp" в его домашней директории, то именно эта директория и будет использоваться (только для Unix систем).
2. если в переменных окружения существует TMPDIR, используется указанная директория.
3. В другом случае производится попытка доступа к директориям /usr/tmp, /var/tmp, C:\temp, /tmp, /temp, ::Temporary Items и \WWW_ROOT.
Каждая из этих путей проверяется на наличие директории и на доступ к записи. При отрицательном результате алгоритм переходит на следующий пункт.
СПЕЦИАЛЬНЫЕ ФОРМЫ ДЛЯ ИМПОРТА ФУНКЦИЙ HTML-ТЕГОВ
Много методов генерируют HTML теги. Как описано ниже, функции тегов автоматически генерируют оба тега закрытия и открытия. На пример:
print h1('Level 1 Header');
на выходе получается
<h1>Level 1 Header</h1>
Иногда Вам захочется самим создавать открывающие и закрывающие теги. В этом случае, Вы можете использовать форму start_tag_name и end_tag_name, как в этом примере:
print start_h1,'Level 1 Header',end_h1;
С несколькими исключениями (описанными ниже), функции start_tag_name и end_tag_name не генерируются автоматически при использовании CGI. Однако, Вы можете определить нужные Вам теги для генерации начала/конца функций вставкой звёздочки в начало его имени, или, альтернативный способ, запрашивая "start_tag_name" или "end_tag_name" в списке импорта.
Пример:
use CGI qw/:standard *table start_ul/;
В этом примере, следующие функции генерируются в дополнение к стандартным:
1. start_table() (генерирует тег <table>)
2. end_table() (генерирует тег </table>)
3. start_ul() (генерирует тег <ul>)
4. end_ul() (генерирует тег </ul>)

ГЕНЕРАЦИЯ ДИНАМИЧЕСКИХ ДОКУМЕНТОВ

Большинство функций CGI.pm применяются для создания документов на лету. В основном Вы будете вначале создавать HTTP заголовок, а затем сам документ. CGI.pm предоставляет функции для генерации HTTP заголовков различных типов HTML. Для создания GIF изображений смотрите модуль GD.pm.
Каждая из этих функций создаёт фрагмент HTML или HTTP который Вы можете в свою очередь выдавать прямо на печать, отображаемую в окне браузера, добавить к строке или сохранить в файл для последующего использования.
СОЗДАНИЕ СТАНДАРТНЫХ HTTP ЗАГОЛОВКОВ:
Обычно первая вещь которую Вы будете делать в любом CGI сценарии - это вывод на печать HTTP заголовка. Он говорит браузеру о типе ожидаемого документа и опционально выдаёт информацию, такую как язык, дата окончания и где кэшировать документ. Заголовок может также управлять специальными настройками, такими как вставка сервера и оплата за просмотр страниц.
print header;
-или-
print header('image/gif');
-или-
print header('text/html','204 No response');
-или-
print header(-type=>'image/gif',
             -nph=>1,
             -status=>'402 Payment required',
             -expires=>'+3d',
             -cookie=>$cookie,
             -charset=>'utf-7',
             -attachment=>'foo.gif',
             -Cost=>'$2.00');
header() возвращает Content-type: header. Вы можете предоставить Ваш собственный MIME тип по Вашему выбору, в другом случае, по умолчанию, будет предоставляться text/html. Опционально второй параметр определяет код статуса и сообщение для прочтения человеком. На пример, Вы можете определить 204, "No response" для создания сценария говорящему браузеру не производить никаких действий.
Последний пример показывает именованный стиль аргумента для передачи аргументов CGI методу используя именованные параметры. Распознаваемые параметры: -type, -status, -expires и -cookie. Все другие именованные параметры будут отделены от их инициализирующих дефисов и включатся в поле заголовка, позволяющих Вам определить HTTP заголовок по Вашему желанию. Внутренние нижние подчёркивания должны включаться в дефисы:
print header(-Content_length=>3002);
Большинство браузеров не кэшируют вывод с CGI сценариев. Каждый раз браузер перезагружает страницу, и сценарий вызывается заново. Вы можете изменить это поведение используя параметр -expires. Когда Вы определите абсолютный или относительный срок истечения с помощью этого параметра, некоторые браузеры и прокси сервера будут кэшировать вывод сценария пока не наступила дата истечения. Следующие формы соответствуют полю -expires:
+30s срок истечения - 30 секунд
+10m срок истечения - десять минут
+1h срок истечения - один час
-1d вчера (т.е. "ASAP!")
now незамедлительно
+3M в три месяца
+10y в течении 10 лет
Thursday, 25-Apr-1999 00:40:33 GMT в указанные время и дату
Параметр -cookie генерирует заголовок, указывающий браузеру предоставлять "магические cookie" в течении всех последующих транзакций для Вашего сценария. Куки Netscape имеют специальный формат включающий интересующие атрибуты, такие как срок годности. Используйте метод cookie() для создания и получения кукисов данной сессии.
Параметр -nph, при установке его в true, будет корректировать заголовки для работы с NPH (no-parse-header - не-разбираемый-заголовок) сценариями. Важно для использования с некоторыми серверами, работающими только с NPH.
Параметр -charset может использоваться для контроля символов отправляемых браузеру. При отключённом параметре, по умолчанию, выдаётся ISO-8859-1. В результате, затрагивается метод charset().
Параметр -attachment используется для добавления страницы во вложение. Взамен отображения страницы, некоторые браузеры предлагают пользователю сохранить её на диск. Значение аргумента является предлагаемым именем сохраняемого файла. Для работы с этим параметром, Вы можете установить -type в "application/octet-stream".
Параметр -p3p добавляет P3P тег в исходящий заголовок. Параметр может быть в виде массива или разделённой пробелом строки содержащей P3P теги.
Например:
print header(-p3p=>[qw(CAO DSP LAW CURa)]);
print header(-p3p=>'CAO DSP LAW CURa');
В другом случае, исходящий заголовок может формироваться как:
P3P: policyref="/w3c/p3p.xml" cp="CAO DSP LAW CURa"
ГЕНЕРАЦИЯ ЗАГОЛОВКА ПЕРЕНАПРАВЛЕНИЯ
print redirect('http://somewhere.else/in/movie/land');
Иногда Вам не нужно создавать документ самому, но нужно простое перенаправление браузера куда-либо, возможно выбор URL основан на времени дня или идентификации пользователя.
Функция redirect() перенаправляет браузер на различные URL. Если Вы используете перенаправление подобное этому, Вы не должны выдавать на печать заголовок.
Необходимо всегда использовать полные URL'ы (включая http: или ftp:) в запросе перенаправления. Относительные URL'ы не всегда корректно работают.
Вы можете также использовать именованные аргументы:
print redirect(-uri=>'http://somewhere.else/in/movie/land',
                       -nph=>1,
                       -status=>301);
Параметр -nph, при установке в true, будет корректировать заголовки для работы с NPH (no-parse-header - не-разбираемый-заголовок) сценарием. Важно для работы с не которыми серверами, такими как Microsoft IIS, ожидающими, что все сценарии будут относится к NPH.
Параметр -status устанавливает статус перенаправления. HTTP определяется тремя различными возможными статусами кода перенаправления:
301 Moved Permanently
302 Found
303 See Other
По умолчанию, при явно не определённом коде, установлен в 302, который означает "moved temporarily" ("временно перемещён").Вы можете изменить код статуса на другой код, по Вашему желанию. Предварительно обдумайте, стоит ли менять статус на что-либо отличное от 301, 302, или 303, так как, не обдуманное изменение кода статуса может прервать перенаправление.
СОЗДАНИЕ ЗАГОЛОВКА HTML ДОКУМЕНТА
print start_html(-title=>'Secrets of the Pyramids',
                 -author=>'fred@capricorn.org',
                 -base=>'true',
                 -target=>'_blank',
                 -meta=>{'keywords'=>'pharaoh secret mummy',
                                     'copyright'=>'copyright 1996 King Tut'},
                 -style=>{'src'=>'/styles/style1.css'},
                 -BGCOLOR=>'blue');
После создания HTTP заголовка, большинство CGI сценариев начинают вывод HTML документа. Процедура start_html() создаёт верх страницы, некоторую опциональную информацию, которая осуществляет контроль внешнего вида страницы.
Этот метод возвращает законсервированный HTML заголовок и открывает тег <body>. Все параметры опциональны. В именованном параметре формы, распознаваемые параметры следующие: -title, -author, -base, -xbase, -dtd, -lang и -target (подробности ниже). Все дополнительные параметры, которые Вы можете обеспечить, такие как, неофициальный Netscape атрибут BGCOLOR, добавляется в тег <body>. Дополнительные параметры должны быть представлены дефисом.
Аргумент -xbase предоставляет HREF для тега <base> отличающегося от текущего расположения, что-то вроде
-xbase=>"http://home.mcom.com/"
Все относительные ссылки будут интерпретироваться относительно этого тега.
Аргумент -target позволяет Вам использовать по умолчанию целевой фрейм для всех ссылок и заполняемых форм на странице. Это не стандартная особенность HTTP работает только с браузерами Netscape! Смотрите документацию Netscape о фреймах для детальных сведений о манипулировании ими.
-target=>"answer_window"
Все относительные ссылки будут интерпретироваться относительно этого тега. Вы добавляете произвольную мета информацию заголовку с помощью аргумента -meta. Этот аргумент ожидает ссылку на ассоциативный массив содержащий пары имя/значение мета информации. Передаётся в серии заголовков <meta> тегов, которые выглядят примерно так:
<meta name="keywords" content="pharaoh secret mummy">
<meta name="description" content="copyright 1996 King Tut">
Для создания HTTP-EQUIV типов тега <meta> используйте -head, описанный ниже.
Аргумент -style используется для встроенных каскадных таблиц стилей в Вашем коде.Смотрите секцию КАСКАДНЫХ ТАБЛИЦ СТИЛЕЙ для подробной информации.
Аргумент -lang используется для встроенного языка атрибутов в теге <html>. Например:
print $q->start_html(-lang=>'fr-CA');
По умолчанию, при не указанном теге принимается "en-US" для Английского языка Соединённых Штатов, до тех пор пока параметр -dtd существует в HTML 2.0 или 3.2 DTD, в другом случае атрибут отбрасывается. Вы можете указать принудительный отброс языка передачей пустой строки (-lang=>).
Аргумент -encoding может быть использован для определения установок символов для XHTML. По умолчанию установлено в iso-8859-1.
Аргумент -declare_xml, при использовании с XHTML, вставляет <?xml> описание в начало HTML заголовка. Основное назначение этого описания - описать кодировку набора символов. При отсутствии -declare_xml, вывод HTML содержит тег <meta> описывающий кодировку, позволяющую HTML проходить через множество валидаторов. По умолчанию, -declare_xml установлен в false.
Вы можете расположить другие случайные HTML элементы в секцию <head> с помощью тега -head. Например, для расположения редко используемого элемента <link> в заголовочной секции, используйте следующее:
print start_html(-head=>Link({-rel=>'next',
                              -href=>'http://www.capricorn.com/s2.html'}));
Для встравивания множественных HTML элементов в секцию <head>, достаточно передать ссылку массива:
print start_html(-head=>[
                         Link({-rel=>'next',
                               -href=>'http://www.capricorn.com/s2.html'}),
                         Link({-rel=>'previous',
                               -href=>'http://www.capricorn.com/s1.html'})
                         ]
                );
А теперь, о том, как создать HTTP-EQUIV <meta> тег:
print start_html(-head=>meta({-http_equiv => 'Content-Type',
                              -content    => 'text/html'}))
JAVASCRIPT'ОВАНИЕ: Параметры -script, -noScript, -onLoad, -onMouseOver, -onMouseOut и -onUnload используются для добавления вызовов JavaScript в Ваши страницы. -script выражает точку блока текста содержащего описание функции JavaScript. Этот блок должен располагаться внутри блока <script> и внутри заголовка HTML (не HTTP). Блок расположен в заголовке для передачи Вашей странице возможности запуска функций JavaScript до того, как пользователь нажмёт кнопку СТОП, прерывающую загрузку страницы. CGI.pm пытается форматировать сценарий таким образом, чтобы браузеры не пропускающие JavaScript не могли запретить его (JavaScript): к несчастью есть некоторые браузеры, такие как Chimera для Unix, в любом случае не ставящие в замешательство.
Параметры -onLoad и -onUnload точки в фрагментах JavaScript кода исполняющиеся в случае открытия и закрытия страницы браузером. Обычно эти параметры вызываются функциями объявленными в поле -script:
$query = new CGI;
print header;
$JSCRIPT=<<END;
// Задать глупый вопрос
function riddle_me_this() {
   var r = prompt("Кто ходит на четырёх ногах утром, " +
                  "на двух ногах в полдень, " +
                  "и на трёх ногах вечером?");
   response(r);
}
// Получить глупый ответ
function response(answer) {
   if (answer == "человек")
      alert("Вы угадали!");
   else
      alert("Ошибка! Попробуйте ещё.");
}
END
print start_html(-title=>'Загадка Сфинкса',
                         -script=>$JSCRIPT);
Используйте параметр -noScript для передачи некоторого HTML текста отображаемого на браузере не имеющего поддержку JavaScript (или браузеров где JavaScript отключён).
Тег <script>, имеет несколько атрибутов включая "type" и src. Последнее очень интересно, так как позволяет хранить JavaScript код в файле или CGI сценарии,что позволяет не загромождать каждую страницу кучей кода. Для использования этих атрибутов передайте ссылку на HASH в параметре -script содержащему один или более -type, -src или -code:
print $q->start_html(-title=>'Загадка Сфинкса',
                     -script=>{-type=>'JAVASCRIPT',
                               -src=>'/javascript/sphinx.js'}
                    );
print $q->(-title=>'Загадка Сфинкса',
           -script=>{-type=>'PERLSCRIPT',
                     -code=>'print "Привет, мир!\n;"'}
           );
Последняя особенность позволит Вам вставить множественные <script> секции в заголовок. Достаточно передать список секций сценария как ссылку на массив. Таким образом, можно объявить различные источники файлов для различных диалектов JavaScript. Пример:
print $q->start_html(-title=>'Загадка Сфинкса',
                     -script=>[
                               { -type => 'text/javascript',
                                 -src      => '/javascript/utilities10.js'
                               },
                               { -type => 'text/javascript',
                                 -src      => '/javascript/utilities11.js'
                               },
                               { -type => 'text/jscript',
                                 -src      => '/javascript/utilities12.js'
                               },
                               { -type => 'text/ecmascript',
                                 -src      => '/javascript/utilities219.js'
                               }
                             ]
                         );
Опция "-language" синоним для -type и поддерживается для обратной совместимости.
Старый стиль позиционирования параметров следующий:
Параметры:
1. Заглавие
2. Адрес электронной почты автора (будет создан тег <link rev="MADE"> если он присутствует)
3. Флаг 'true' если Вы хотите включить тег <base> в заголовок. Помогает резолвить относительные адреса к абсолютным в случае перемещённого документа, но делает иерархию документа не-портативной. Пользуйтесь аккуратно!
4, 5, 6...
Остальные параметры Вы можете включить в тег <body>. Это хорошее место для вставки Netscape расширений, таких как цвета и образцы обоев.
КОНЕЦ HTML ДОКУМЕНТА:
print end_html
Завершает конец HTML документа с помощью печати тегов </body></html>.
СОЗДАНИЕ URL ПРИВЯЗАННОГО-К-САМОМУ-СЕБЕ И ПРЕДОСТАВЛЯЮЩЕМУ ИНФОРМАЦИЮ О СОСТОЯНИИ:
$myself = self_url;
print q(<a href="$myself">Я обращаюсь к себе.</a>);
self_url() возвращает URL, который, при выборе, вызовет сценарий с информацией о состоянии. Очень полезно в случае, когда Вы хотите перемещаться внутри документа использующего внутренние связи, но не хотите изменить текущее содержимое форм(ы). Что-то вроде этого позволит провести этот трюк.
$myself = self_url;
print "<a href=\"$myself#table1\">Смотрите таблицу 1</a>";
print "<a href=\"$myself#table2\">Смотрите таблицу 2</a>";
print "<a href=\"$myself#yourself\">Посмотрите на себя</a>";
Если Вы хотите больше контролировать, то, что будет возвращаться, используйте взамен метод url().
Также Вы можете получить необработанную строку запроса с query_string():
$the_string = query_string;
ПОЛУЧЕНИЕ URL СЦЕНАРИЕВ
$full_url	  = url();
$full_url	  = url(-full=>1);  #альтернативный синтаксис
$relative_url  = url(-relative=>1);
$absolute_url  = url(-absolute=>1);
$url_with_path = url(-path_info=>1);
$url_with_path_and_query = url(-path_info=>1,-query=>1);
$netloc	  = url(-base => 1);
url() возвращает URL сценариев в разнообразных форматах. Вызывается без аргументов, возвращает полную форму URL, включая имя хоста и номер порта
http://your.host.com/path/to/script.cgi
Вы можете модифицировать этот формат с помощью следующих именованных аргументов:
-absolute
Если установлен в true, использует абсолютный URL, т.е.
/path/to/script.cgi
-relative
Использует относительный URL. Полезно при надобности повторного вызова Вашего сценария с различными параметрами. На пример:
script.cgi
-full
Использовать полный URL, как если бы он был вызван без каких-либо аргументов. Отменяет использование аргументов -relative и -absolute.
-path (-path_info)
Добавляет дополнительную информацию о пути к URL. Можно комбинировать с -full, -absolute или -relative. -path_info выступает в роли синонима.
-query (-query_string)
Добавление строки запроса к URL. Можно комбинировать с -full, -absolute или -relative. -query_string выступает в роли синонима.
-base
Генерация только протокола и сетевого расположения, как в http://www.foo.com:8000
-rewrite
Если включён mod_rewrite Apache'а, то имя сценария и информация о пути возможно не будет соответствовать запросу посланному пользователем. Установите -rewrite=>1 (по умолчанию) для возвращения URL'ов соответствующих посланному от пользователя (оригинальный запрос URI). Установите -rewrite=>0 для возвращения URL'ов соответствующих URL после запущенных правил mod_rewrite'а. Причина: дополнительная информация о пути делает чувствительной в контексте перезаписанных URL, -rewrite установлен в false когда Ваша информация о пути запроса находится в URL.
СМЕШИВАНИЕ ПАРАМЕТРОВ POST И URL
$color = url_param('color');
Для сценариев возможно получение CGI параметров в URL как в заполняемых формах с помощью создания форм, в которых, POST'ы к URL содержат строку запроса ("?" следует за аргументами). Метод param() всегда возвращает содержимое заPOST'енной заполняемой формы, игнорируя строку запроса URL'ов. Полученные URL параметры, вызывают метод url_param(). Используйте его так же, как и param(). Главное различие в том, что он позволяет Вам читать параметры, но не устанавливать их.
Под действием обстоятельств содержимое URL запроса может воспрепятствовать CGI параметрам названным аналогичным образом в POST формах. Если Вы попробуете смешать строку URL запроса с формой, полученной методом GET, результат может оказаться совсем не таким, каким Вы ожидали его увидеть.

СОЗДАНИЕ ПРОСТЫХ HTML ЭЛЕМЕНТОВ:

CGI.pm содержит описания многих HTML методов, но не всех HTML 3 и HTML 4 тегов. HTML ярлыки именованы после одиночных HTML элементов и возвращают фрагмент HTML текста, который затем Вы можете напечатать или манипулировать им так, как Вам заблагорассудится. Каждый ярлык возвращает фрагмент HTML кода, который Вы можете добавить к строке, сохранить в файл или, чаще всего, выводить на печать таким, каким он отображается в окне браузера.
Этот пример показывает как использовать HTML методы:
print $q->blockquote(
                  "Много лет назад на острове ",
                  $q->a({href=>"http://crete.org/"},"Крит "),
                  "жил Минотавр с именем ",
                  $q->strong("Фред."),
                 ),
    $q->hr;
Результатом будет следующий HTML код (лишние новые строки добавлены для увеличения читабельности):
<blockquote>
Много лет назад на острове 
<a href="http://crete.org/">Крит </a> жил 
Минотавр с именем <strong>Фред.</strong>
</blockquote>
<hr>
Если Вы находите синтаксис вызова HTML ярлыков awk-образным, Вы можете импортировать их в Ваше пространство имён и распределять с завершённым объектным синтаксисом (смотрите следующий раздел для дополнительных деталей):
use CGI ':standard';
print blockquote(
   "Много лет назад на острове ",
   a({href=>"http://crete.org/"},"Крит "),
   "жил Минотавр с именем ",
   strong("Фред."),
   ),
   hr;
ПРЕДОСТАВЛЕНИЕ АРГУМЕНТОВ К HTML ЯРЛЫКАМ
Методы HTML принимают нулевой, ординарный или множественный аргументы. Если Вы не предоставляете аргументы, используйте единственный тег:
print hr;    #  <hr>
Если Вы предоставляете один или больше строковых аргументов, они должны быть связаны между собой пробелами и расположены между тегами открытия и закрытия:
print h1("Глава","1"); # <h1>Глава 1</h1>"
Если первый аргумент является ссылкой на ассоциативный массив, то ключи и значения ассоциативного массива становятся атрибутами HTML тегов:
print a({-href=>'fred.html',-target=>'_new'},
   "Открыть в новом фрейме");
            <a href="fred.html",target="_new">Открыть в новом фрейме</a>
Вы можете обойтись без тире в начале имени атрибута:
print img {src=>'fred.gif',align=>'LEFT'};
        <img align="LEFT" src="fred.gif">
Иногда атрибут HTML тега не имеет аргумента. Например, упорядоченный список может быть маркирован как COMPACT. Синтаксис для этого аргумента точка строки вида undef:
print ol({compact=>undef},li('один'),li('два'),li('три'));
Ранее в CGI.pm версии 2.41, использовалась пустая ('') строка в качестве атрибута аргумента теперешнего undef. Однако, это трансформировалось, в следующий вид: <img alt="">. Разница показана в двух кусках кода:
КОД РЕЗУЛЬТАТ
img({alt=>undef}) <img alt>
img({alt=>''}) <img alt="">
РАЗДЕЛИТЕЛЬНОЕ СВОЙСТВО HTML ЯРЛЫКА
Одно из сильных особенностей HTML ярлыков - это разделительность. Если Вы получите их как аргумент состоящий из ссылки на список, тег будет разделён между каждым элементом списка. Например, вот один из способов создания упорядоченного списка:
print ul(
          li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy'])
        );
Этот пример создаст HTML вывод подобный этому:
<ul>
  <li type="disc">Sneezy</li>
  <li type="disc">Doc</li>
  <li type="disc">Sleepy</li>
  <li type="disc">Happy</li>
</ul>
Очень удобно для создания таблиц. На пример:
print table({-border=>undef},
        caption('When Should You Eat Your Vegetables?'),
        Tr({-align=>CENTER,-valign=>TOP},
        [
           th(['Vegetable', 'Breakfast','Lunch','Dinner']),
           td(['Tomatoes' , 'no', 'yes', 'yes']),
           td(['Broccoli' , 'no', 'no',  'yes']),
           td(['Onions'   , 'yes','yes', 'yes'])
        ]
        )
     );
HTML ЯРЛЫКИ И ВСТАВКА СПИСКОВ
Рассмотрим часть кода:
print blockquote(em('Привет'),'мам!'));
Он просто возвращает строку, которую Вы, возможно, ожидали:
<blockquote><em>Привет</em> мам!</blockquote>
Помните, что есть пробел между элементами "Привет" и элементом "мам!". CGI.pm вставляет дополнительные пробелы, используемые вставкой массива, контролирующие магическую переменную $". Иногда этот дополнительный пробел будет не тем, что Вы ожидали, например, когда Вы захотите расположить в одну линию рисунки. В этом случае, Вы можете просто изменить значение переменной $" на пустую строку.
{
   local($") = '';
   print blockquote(em('Привет'),'мам!'));
}
Я предлагаю Вам вставлять код в блок, как показано здесь. Иначе изменения в $" подействует на весь остальной код, до тех пор, пока Вы явно не сбросите его.
НЕ-СТАНДАРТНЫЕ HTML ЯРЛЫКИ
Несколько HTML тегов не следуют стандартному образцу, по некоторым причинам.
comment() генерирует HTML комментарий (<!-- comment -->). Вызывайте его так
print comment('это мой комментарий');
Поскольку есть конфликт со встроенными Perl функциями, следующие функции начинаются с большой буквы:
Select
Tr
Link
Delete
Accept
Sub
В дополнение, start_html(), end_html(), start_form(), end_form(), start_multipart_form() и все теги заполняющие форму являются специальными. Читайте соответствующие разделы.
АВТОВЫСВОБОЖДЕНИЕ HTML
По умолчанию, весь HTML созданный формо-генерирующими функциями проходит через функцию названную escapeHTML():
$escaped_string = escapeHTML("не освобождённая строка");
    Освобождение HTML форматирует символы в строку.
Предусмотренный, для Вашего использования, набор символов установлен в ISO-8859-1 (по умолчанию), используются стандартные правила освобождения HTML. Символ "<" аналогичен "<", ">" аналогичен ">", "&" аналогичен "&", и символ кавычки аналогичен """. В дополнение, шестнадцатеричные символы 0x8b и 0x9b не корректно интерпретируются некоторыми браузерами как угловые левый и правый символы, и замещаются их цифровым содержимым ("&#8249" and "›"). Если Вы вручную измените кодировку символов, либо явно с помощью метода charset() или передачей аргумента -charset header()'у, то все символы будут замещены их цифровым содержимым, так-как CGI.pm не имеет таблицы соответствия для всех возможных кодировок.
Автоматическое освобождение не применяется к остальным ярлыкам, таким как h1(). Вы можете вызвать сами escapeHTML() для недоверенных данных для защиты Ваших страниц от попыток взлома, которые люди могут ввести в гостевую книгу и т.д. Для изменения набора символов, используйте charset(). Для полного отключения автовысвобождения, используйте autoEscape(0):
$charset = charset([$charset]);
   Получить или установить текущую установку символа.
$flag = autoEscape([$flag]);
   Получить или установить значение флага автовысвобождения.
ЧИТАБЕЛЬНЫЙ HTML
По умолчанию, весь HTML производится с помощью этих функций, и представляет собой одну длинную строку без возврата каретки и выделения отступами. Это отвратительно, но позволяет уменьшить размер документа на 10-20%. Для получения читабельного вывода, пожалуйста используйте CGI::Pretty, подкласс курируемый Брайаном Полсеном (Brian Paulsen).

СОЗДАНИЕ ЗАПОЛНЯЕМЫХ ФОРМ:

Главное примечание: Всё множество методов создания форм возвращают строки вызвавшему элементу и содержат тег или теги создающие запрошенный элемент формы. Вы ответственны за правильную печать этих строк. Поэтому Вы можете разместить теги форматирования между элементами формы.
Другое примечание: Значения по умолчанию, которые Вы определили для форм, используются только один раз при ссылке на сценарий (когда нет строки запроса). Последующие ссылки сценария (когда есть строка запроса), прошлые значения используются даже если они были пустыми.
Если Вы хотите изменить значение поля, то у Вас есть две пути:
(1) вызвать метод param() для установки этих значений.
(2) использоваеть параметр -override (алиас -force) (новое свойство в версии 2.15). В результате происходит принудительное использование значения по умолчанию, независимо от предыдущего значения:
print textfield(-name=>'имя_поля',
                        -default=>'начальное значение',
                        -override=>1,
                        -size=>50,
                        -maxlength=>80);
Ещё одно примечание: По умолчанию, текст и метки элементов форм освобождаются в соответствии с HTML правилами. Эти средства позволяют Вам безопасно использовать "<CLICK ME>" в качестве метки для кнопки. Однако, это также мешает встраиванию в Ваши поля последовательностей специальных HTML символов, таких как Á. Если Вы хотите отключить автоматический выход, вызовите метод autoEscape() с ложным значением сразу после создания CGI объекта:
$query = new CGI;
autoEscape(undef);
Подводный камень! Некоторые методы генерации элементов-форм возвращают множественные теги. В скалярном контексте, теги объединяются пробелами, или любое текущее значение глобальной переменной $". В контексте списка, методы возвращающие список элементов, позволяют Вам модифицировать их по Вашему желанию. Обычно Вы не знаете об этом поведении, но берегитесь этого:
printf("%s\n",end_form())
end_form() создаёт несколько тегов и только первый из них будет выдан на печать, поскольку согласно формату ожидается только одно значение.
СОЗДАНИЕ ТЕГА ISINDEX
print isindex(-action=>$action);
-или-
print isindex($action);
Выводит на печать тег <isindex>. Не очень интересно. Параметр -action определяет URL сценария для обработки запроса. По умолчанию, процесс запроса происходит с текущим сценарием.
НАЧАЛО И КОНЕЦ ФОРМЫ
print start_form(-method=>$method,
                 -action=>$action,
                 -enctype=>$encoding);
  <... различное содержимое формы ...>
print endform;
-или-
print start_form($method,$action,$encoding);
  <... различное содержимое формы ...>
print endform;
start_form() возвращает тег <form> с помощью опционального метода, действие и кодировка формы будет той, которую Вы укажете. Умолчания следующие:
method: POST
action: this script
enctype: application/x-www-form-urlencoded
endform() возвращает тег закрытия </form>.
Аргумент типа кодировки Start_form() говорит браузеру как паковать различные поля форм перед отправкой формы серверу. Возможны два значения:
Примечание: Этот метод был поначалу назван как startform() и startform(). Эти имена определяются как алиас.
application/x-www-form-urlencoded
Это старый тип кодировки используемый всеми браузерами до Netscape 2.0. Он совместим с многими CGI сценариями и годен для коротких полей содержащих текстовые данные. Для Вашего удобства, CGI.pm сохраняет имена этих типов кодировки в &CGI::URL_ENCODED.
multipart/form-data
Это новый тип кодировки введённый Netscape 2.0. Применим для форм содержащих очень большие поля или предназначенных для передачи бинарных данных. Самое важное, он включает особенность "file upload" Netscape 2.0 форм. Для Вашего удобства, CGI.pm хранит имя этого типа кодировки в &CGI::MULTIPART.
Формы использующие этот тип кодировки не так просто интерпретируются с помощью CGI сценариев, кроме случая когда они используют CGI.pm или другую библиотеку, созданную для управления ими.
Если активирован XHTML (по умолчанию), затем формы будут автоматически созданы используя этот тип кодировки.
Для совместимости, метод start_form(), по умолчанию, использует старую форму кодировки. Если Вы хотите использовать более новые формы, кодируемые по умолчанию, Вы можете вызвать start_multipart_form() взамен start_form().
JAVASCRIPT'ОВАНИЕ: Параметры -name и -onSubmit предоставлены для использования с JavaScript. Параметр -name даёт форме имя, таким образом, она может идентифицироваться и управляться функциями JavaScript. -onSubmit - точка для функции JavaScript, которая должна исполняться только перед формой подтверждённой для Вашего сервера. Вы можете использовать эту возможность для проверки содержимого формы на согласованность и полноту. Если Вы найдёте что-то не правильное, Вы можете выдать окошко с предупреждением или, возможно, исправить эти вещи своими силами. Вы можете прервать передачу, вернув false от этой функции.
Обычно объём JavaScript функций определён в блоке <script>, заголовке HTML и -onSubmit точке для одного из этих вызовов функции. Дополнительную информацию смотрите в start_html().
ЭЛЕМЕНТЫ ФОРМ
После запуска формы, Вы обычно создаёте одну или более текстовых полей, всплывающие меню, радио группы и другие элементы формы. Каждый из этих элементов принимает стандартную установку именованных аргументов. Некоторые элементы также имеют опциональные аргументы. Стандартные аргументы следующие:
-name
Имя поля. После представления, это имя можно использовать для получения значения полей с помощью метода param().
-value, -values
Инициализационное значение поля, которое возвращается сценарию после представления формы. Некоторые элементы формы, такие как текстовые поля, принимают единственный скалярный аргумент -value. Остальные, такие как всплывающие меню, принимают ссылку на массив значений. Два аргумента являются синонимами.
-tabindex
Числовое значение, которое устанавливает порядок, в котором элементы формы принимают фокус при нажатии пользователем клавиши tab. Элементы с меньшими значениями получают фокус первыми.
-id
Идентификатор строки используемый для идентификации этого элемента в JavaScript и DHTML.
-override
Булева, которое при истинном значении, принудительно присваивает элементу значение указанное в -value, включает липкое поведение описанное ранее для прагмы -no_sticky.
-onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut, -onSelect
Всё это используется для назначения дескрипторов события JavaScript. Для дополнительной информации, смотрите секцию JavaScript'ование.
Другие общие аргументы описаны в следующей секции. В дополнение к этому, также поддерживаются все атрибуты описанные в HTML спецификации.
СОЗДАНИЕ ТЕКСТОВОГО ПОЛЯ
print textfield(-name=>'название_поля',
                -value=>'начальное значение',
                -size=>50,
                -maxlength=>80);
-или-
print textfield('название_поля','начальное значение',50,80);
textfield() возвращает поле ввода текста.
Параметры
1. Первый параметр требует имя для поля (-name).
2. Опциональный второй параметр, по умолчанию, начальное значение для содержимого поля (-value, раньше известное как -default).
3. Опциональный третий параметр - размер поля в символах (-size).
4. Опциональный четвёртый параметр - принимаемое максимальное число символов в поле (-maxlength).
Как и со всеми этими методами, поле будет инициализироваться предыдущим содержимым более ранних обращений сценария. Когда форма уже создана, значение текстового поля может быть получено с помощью:
$value = param('foo');
Если Вы хотите сбросить его с инициализационного значения после вызова сценария, Вы можете сделать нечто подобное этому:
param('foo',"Я буду поверх этого значения!");
СОЗДАНИЕ БОЛЬШОГО ТЕКСТОВОГО ПОЛЯ
print textarea(-name=>'foo',
                       -default=>'стартовое значение',
                       -rows=>10,
                       -columns=>50);
-или
print textarea('foo','стартовое значение',10,50);
textarea() подобен текстововму полю, но позволяет определить строки и столбцы для многострочного текстового ввода. Вы можете указать стартовое значение для поля, оно может быть длинным и содержать много строк.
СОЗДАНИЕ ПОЛЯ ВВОДА ПАРОЛЯ
print password_field(-name=>'секрет',
                             -value=>'стартовое значение',
                             -size=>50,
                             -maxlength=>80);
-или-
print password_field('секрет','стартовое значение',50,80);
password_field() идентичен textfield(), за исколючением того, что его содержимое будет закрыто звёздочками на веб странице.
СОЗДАНИЕ ПОЛЯ ЗАГРУЗКИ ФАЙЛА НА СЕРВЕР
print filefield(-name=>'загружаемый_файл',
                        -default=>'начальное значение',
                        -size=>50,
                        -maxlength=>80);
-или-
print filefield('загружаемый_файл','начальное значение',50,80);
filefield() вернёт поле для загрузки файла на сервер для браузеров Netscape 2.0. Для того, чтобы получить весь функционал, Вы должны использовать новую многосоставную схему кодировки для формы. Вы можете делать это либо вызовом start_form() с типом кодировки &CGI::MULTIPART или вызовом нового метода start_multipart_form() взамен избитого start_form().
Параметры
1. Первый параметр - требуемое имя для поля (-name).
2. Опциональный второй параметр - начальное значение для содержимого поля, используемого по умолчанию имени файла (-default).
По соображениям безопасности, браузеры не выдают ни какого предупреждения для этого поля, и поэтому начальное значение будет всегда пустой строкой. Худшее, поле теряет его "клейкое" поведение и забывает его предыдущее содержимое. Начальное значение поля вызывается в HTML спецификацию, однако, возможно некоторые браузеры в конечном итоге будут поддерживать его.
3. Опциональный третий параметр - размер поля в символах (-size).
4. Опциональный четвёртый параметр - максимальное число принимаемых символов в поле (-maxlength).
Когда форма уже создана, Вы можете получить введённое имя файла с помощью вызова param():
$filename = param('загруженный_на_сервер_файл');
Различные браузеры будут возвращать имена, немного различающиеся друг от друга. Некоторые браузеры возвращают только имя файла. Другие возвращают полный путь к файлу, используя пути в формате пользовательской машины. Независимо от обстоятельств, возвращаемое имя - имя файла на машине пользователя, и не связаны с именем временного файла, который создаёт CGI.pm во время спулинга загрузки (смотрите ниже).
Имя файла возвращается также файловым дескриптором. Вы можете читать содержимое файла используя стандартный вызов Perl для чтения файла:
# Прочесть текстовый файл и напечатать его
while (<$filename>) {
   print;
}
# Копировать бинарный файл куда-либо
open (OUTFILE,">>/usr/local/web/users/feedback");
while ($bytesread=read($filename,$buffer,1024)) {
   print OUTFILE $buffer;
}
Однако, есть проблемы с двойной природой загрузкой полей. Если Вы применили "use strict", то Perl будет выдавать предупреждения при попытке использовать строку как дескриптор файла. Вы можете обойти эту проблему разместив участок кода, отвечающий за чтение файла в блоке содержащем прагму "no strict". Кроме шуток, удалённый пользователь может ввести в поле загрузки какой-либо символьный мусор, в этом случае Вы получите от param() не дескриптор файла, а строку.
Для безопасности, используйте функцию upload() (новое в версии 2.47). При вызове с именем загруженного поля, upload() вернёт объект подобный дескриптору файла или undef если параметр не правильный дескриптор файла.
$fh = upload('загруженный_файл');
while (<$fh>) {
      print;
}
В контексте списка, upload() вернёт массив дескрипторов файлов. Это делает возможным создавать формы, которые используют имена для полей многократных загрузок.
Это рекомендованная идиома.
Легковесный дескриптор файла возвращаемый с помощью CGI.pm, не совместим с IO::Handle; например, не может иметь функции read() или getline(), но взамен должен манипулировать используя read($fh) или <$fh>. Для получения совместимого IO::Handle объекта, вызывая метод дескрипторов handle().
my $real_io_handle = upload('загруженный_файл')->handle;
Когда файл загружен, браузер обычно отправляет информацию в формате заголовков. Информация обычно включает содержимое типа MIME. В будущем браузеры смогут отправлять и другую информацию (такую как дата модификации и размер). Для получения этой информации, применяйте uploadInfo(). Он возвращает ссылку на асоциативный массив содержащий все заголовки документов.
$filename = param('загруженный_файл');
$type = uploadInfo($filename)->{'Content-Type'};
unless ($type eq 'text/html') {
   die "ТОЛЬКО HTML ФАЙЛЫ!";
}
Если Вы используете машину, распознающую режимы данных "text" и "binary", убедитесь что Вы точно знаете когда и как использовать их (смотрите Книгу Верблюда (Camel book)). В противном случае Вы можете обнаружить что бинарные файлы были повреждены в процессе загрузки на сервер.
Порою случаются проблемы с разбором загруженного файла. Такое обычно случается, когда пользователь нажимает "Stop" в процессе загрузки файла на сервер. В этом случае, CGI.pm возвращает undef для имени загруженных файлов и устанавливает cgi_error() в строку "400 Bad request (malformed multipart POST)". Это сообщение об ошибке создано для того, чтобы Вы могли включить его в код статуса отправляемого браузеру. Пример:
$file = upload('загруженный_файл');
if (!$file && cgi_error) {
   print header(-status=>cgi_error);
   exit 0;
}
Вы вольны создавать пользовательские HTML страницы для сообщения об ошибках, по своему желанию.
Вы можете установить обратную связь, которая может быть вызвана всякий раз, когда производится попытка читать при загрузке файла на сервер и пока обрабатывается форма. Аналогично объекту UPLOAD_HOOK доступному в Apache::Request, за исключением того, что первый аргумент для обратной связи - объект Apache::Upload, это его удалённое имя файла.
$q = CGI->new(\&hook [,$data [,$use_tempfile]]);
sub hook
{
       my ($filename, $buffer, $bytes_read, $data) = @_;
       print  "Прочитано $bytes_read байтов из $filename\n";
}
Поле $data опционально; оно позволяет Вам передать информацию о конфигурации (т.е. дескриптор базы данных) для Вашего обработчика обратной связи.
Поле $use_tempfile - флаг, который позволяет Вам включить и выключить использование CGI.pm, как временного дискообразного файла в процессе загрузки файла на сервер. Если Вы установите его в значение FALSE (по умолчанию true), то param('загруженный_файл') не будет работать, и единственный путь получить загруженные на сервер данные через ловушку, управляемую Вами.
Если использование функционально-ориентированного интерфейса, вызывайте метод CGI::upload_hook() до вызова param() или других CGI функций:
CGI::upload_hook(\&hook [,$data [,$use_tempfile]]);
Этот метод не экспортируется по умолчанию. Вы можете явно импортировать его, если хотите использовать его без префикса CGI::.
Если Вы используете CGI.pm на Windows платформе и найти, что бинарные файлы немного больше во время загрузки, а текстовые файлы остаются такими же, какими и были, это значит что Вы забыли активировать бинарный режим на выводе файлового дескриптора. Убедитесь что вызов binmode() на других дескрипторах, создаваемых Вами, записывает файл на диск.
JAVASCRIPT'ОВАНИЕ: Определяются параметры -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut и -onSelect. За подробными деталями смотрите textfield().
СОЗДАНИЕ ВСПЛЫВАЮЩЕГО МЕНЮ
print popup_menu('название_меню',
                             ['eenie','meenie','minie'],
                             'meenie');
-или-
%labels = ('eenie'=>'Ваш первый выбор',
           'meenie'=>'Ваш второй выбор',
           'minie'=>'Ваш третий выбор');
%attributes = ('eenie'=>{'class'=>'класс первого выбора'});
print popup_menu('название_меню',
                             ['eenie','meenie','minie'],
       'meenie',\%labels,\%attributes);
-или (стиль именованных параметров)-
print popup_menu(-name=>'название_меню',
                 -values=>['eenie','meenie','minie'],
                 -default=>['meenie','minie'],
       -labels=>\%labels,
       -attributes=>\%attributes);
popup_menu() создаёт меню.
1. Требуемый первый аргумент - название меню (-name).
2. Требуемый второй аргумент (-values) - массив ссылок содержащих список пунктов меню в меню. Вы можете передавать метод в анонимный массив, как показано в примере, или ссылаться на именованный массив, такой как "\@foo".
3. Опциональный третий параметр (-default) - имя выбора меню по умолчанию. Если не определено, первый пункт будет установлен по умолчанию. Значения предыдущего выбора будут поддержаны с помощью запросов. Передача ссылки на массив для выбора множества по умолчанию.
4. Опциональный четвёртый параметр (-labels) предназначен для людей, которые хотят использовать различные значения для видимых пользователю меток внутри всплывающего меню и значения возвращаемого Вашему сценарию. Это указатель на асоциативный массив касающийся значений меню для видимых пользователю меток. Если Вы оставите пустым этот параметр, значения меню будут установлены по умолчанию. (При желании, Вы также можете оставить метку не определённой).
5. Опциональный пятый параметр (-attributes) позволяет назначить любой из HTML атрибутов в пункт индивидуального меню. Это указатель на асоциативный массив, касающийся значений меню другого ассоциативного массива с именами атрибутов в качестве ключа и значениями атрибутов в качестве значения.
Когда форма уже создана, выбранное значение всплывающего меню может быть получено так:
$popup_menu_value = param('название_меню');
СОЗДАНИЕ ГРУППЫ ОПЦИИ
Именованный стиль параметра
print popup_menu(-name=>'menu_name',
                -values=>[qw/eenie meenie minie/,
                          optgroup(-name=>'optgroup_name',
                                           -values => ['moe','catch'],
                                           -attributes=>{'catch'=>{'class'=>'red'}})],
                -labels=>{'eenie'=>'one',
                          'meenie'=>'two',
                          'minie'=>'three'},
                -default=>'meenie');
Старый стиль
print popup_menu('menu_name',
                 ['eenie','meenie','minie',
                  optgroup('optgroup_name', ['moe', 'catch'],
                                  {'catch'=>{'class'=>'red'}})],'meenie',
                 {'eenie'=>'one','meenie'=>'two','minie'=>'three'});
optgroup() создаёт группу опций в всплывающем меню.
1. Требуемый первый аргумент (-name) - атрибут метки опциональной группы и не вставляемый в список параметров запроса.
2. Требуемый второй аргумент (-values) - ссылка на массив содержащий список пунктов меню в меню. Вы можете передать метод в анонимный массив, как показано в примере, или ссылку на именованный массив, такой как \@foo. Если Вы передадите HASH ссылку, ключи будут использоваться для значений меню и значения будут использоваться для меток меню (смотрите -labels ниже).
3. Опциональный третий параметр (-labels) позволяет Вам передавать ссылку на асоциативный массив содержащий метки видимые пользователю для одного или более пунктов меню. Вы можете использовать его когда хотите чтобы пользователь видел строку меню, но браузер возвращал Вашей программе только одно значение. Если Вы не определили его, то взамен будет использована строка значения ("eenie", "meenie" и "minie" в этом примере). Это эквивалентно использованию ссылки на хэш для параметра -values.
4. Опциональный четвёртый параметр (-labeled) может быть установлен в значение true и отображать использование значений в качестве атрибутов меток для каждого элемента опции в опциональной группе.
5. Опциональный пятый параметр (-novals) может быть установлен в значение true и отображать подавление значения атрибута в каждом элементе опции в опциональной группе.
За дополнительными сведениями обращайтес в дискуссию о опциональной группе в W3C (http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP).
6. Опциональный шестой параметр (-attributes) предназначен для назначения любых HTML атрибутов пункту индивидуального меню. Это указатель на асоциативный массив касающийся значений меню другого асоциативного массива с именем атрибутов в качестве ключа и значений атрибутов в качестве значения.
СОЗДАНИЕ ПРОКРУЧИВАЮЩЕГОСЯ СПИСКА
print scrolling_list('list_name',
                             ['eenie','meenie','minie','moe'],
     ['eenie','moe'],5,'true',{'moe'=>{'class'=>'red'}});
-или-
print scrolling_list('list_name',
                             ['eenie','meenie','minie','moe'],
                             ['eenie','moe'],5,'true',
    \%labels,%attributes);
-или-
print scrolling_list(-name=>'list_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -default=>['eenie','moe'],
                             -size=>5,
                             -multiple=>'true',
     -labels=>\%labels,
     -attributes=>\%attributes);
scrolling_list() создаёт прокручивающийся список.
Параметры:
1. Первый и второй аргументы являются списком имени (-name) и значений (-values). Как и в всплывающем меню, второй аргумент должен быть в ссылке на массив.
2. Опциональный третий аргумент (-default) должен быть либо ссылкой на список содержащий значения выбранные по умолчанию или единственным значением для выбора. Если этот аргумент отсутствует или не определён, то в этом случае ничего не выбирается при первом появлении списка. В версии именованного параметра, Вы можете использовать синоним "-defaults" для этого параметра.
3. Опциональный четвёртый аргумент - размер списка (-size).
4. Опциональный пятый аргумент может быть установлен в true для возможности одновременного множественного выбора (-multiple). В другом случае доступен выбор одного значения.
5. Опциональный шестой аргумент - указатель на асоциативный массив, содержащий длинные, видимые пользователю метки для пунктов списка (-labels). Если этот аргумент не определён, будут отображены значения.
6. Опциональный шестой параметр (-attributes) обеспечивает доступ к любым доступным HTML атрибутам в пункте индивидуального меню. Это указатель на асоциативный массив указывающий значения меню другому асоциативному массиву с атрибутами имени в качестве ключа и атрибутами значения в качестве значения.
Когда эта форма создана, все выбранные пункты списка будут возвращаться в виде списка под именем параметра 'list_name'. Значения выбранных пунктов можно получить так:
@selected = param('list_name');
СОЗДАНИЕ ГРУППЫ СВЯЗАННЫХ ЧЕКБОКСОВ
print checkbox_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -default=>['eenie','moe'],
                             -linebreak=>'true',
                             -disabled => ['moe'],
     -labels=>\%labels,
     -attributes=>\%attributes);
print checkbox_group('group_name',
                             ['eenie','meenie','minie','moe'],
     ['eenie','moe'],'true',\%labels,
     {'moe'=>{'class'=>'red'}});
ТОЛЬКО ДЛЯ HTML3-СОВМЕСТИМЫХ БРАУЗЕРОВ:
print checkbox_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -rows=2,-columns=>2);
checkbox_group() создайт список чекбоксов, которые связаны между собой каким-либо именем.
Параметры:
1. Первый и второй аргументы - соответственно имя чекбокса и значения (-name и -values). Как и в всплывающем меню, второй аргумент должен быть ссылкой на массив. Эти значения используются для меток видимых пользователю и выводимых на печать после чекбоксов, также как и для значений передаваемых Вашему сценарию в строке запроса.
2. Опциональный третий аргумент (-default) может быть либо ссылкой на список содержащий значения устанавливаемые по умолчанию или может быть единственным установленным значением. Если этот аргумент отсутствует или не определён, то в этом случае ничего не выбирается при первом появлении списка.
3. Опциональный четвёртый аргумент (-linebreak) может быть установлен в true для размещения прерывания строк между чекбоксами, так что они появляются в виде вертикального списка. В другом случае, они будут растянуты в горизонтальную строку.
Опциональный b<-labels> аргумент - указатель на асоциативный массив указывающий на значения чекбокса и меток читаемых пользователем и выводимых после чекбокса. Если ничего не указано, будут использоваться значения по умолчанию.
Опциональные параметры -rows и -columns указывают checkbox_group() возвращать HTML3 совместимое таблицу содержащую группу чекбоксов форматированных со специальными номерами строк и столбцов. При желании Вы можете использовать только параметр -columns; checkbox_group сам будет вычислять правильное число строк для Вас.
Опция b<-disabled> получает в массив значения чекбоксов и дективизирует их, при этом чекбоксы становятся серыми (поддерживается не всеми браузерами).
Опциональный аргумент -attributes позволяет назначить любым общим HTML атрибутам пункт индивидуального меню. Это указатель на асоциативный массив позволяющий перевести значения меню к другому ассоциативному массиву с именем атрибутов в качестве ключа и значением атрибутов в качестве значения.
Опциональный аргумент -tabindex может быть использован для контроля порядка, в котором радио кнопки получают фокус при нажатии пользователем клавиши tab. Если передано скалярное цифровое значение, первый элемент в группе будет получать индекс tab'а и последующие элементы будут инкрементированы по одному. Если дана ссылка на массив значений радио кнопок, то в этом случае индексы будут игнорированы и порядок будет такой-же как и порядок tab'а. Вы можете также передать ссылку на хэш в котором хэш ключи будут обозначать значения радио кнопок и значения - tab индексы каждой кнопки. Примеры:
-tabindex => 100    # эта группа начинается с индекса 100 и далее
-tabindex => ['moe','minie','eenie','meenie']	# tab в этом порядке
-tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab в этом порядке
Опциональный аргумент -labelattributes содержит атрибуты присоединённые к элементу <label> обрамляющему каждую клавишу.
Когда форма уже создана, все нажатые чекбоксы будут возвращены в виде списка под именем параметра 'group_name'. Значения "отмеченных" чекбоксов можно получить так:
@turned_on = param('group_name');
Значение возвращённое с помощью checkbox_group() похоже на массив элементов клавиш. Вы можете захватить их и использовать их в таблицах, списках или по своему усмотрению:
@h = checkbox_group(-name=>'group_name',-values=>\@values);
&use_in_creative_way(@h);
СОЗДАНИЕ ОТДЕЛЬНО СТОЯЩЕГО ЧЕКБОКСА
print checkbox(-name=>'checkbox_name',
                       -checked=>1,
                       -value=>'ON',
                       -label=>'CLICK ME');
-или-
print checkbox('checkbox_name','checked','ON','CLICK ME');
checkbox() используется для создания изолированного чекбокса, логически не связанного с остальными.
Параметры:
1. Первый параметр - требуемое имя для чекбокса (-name). Также может использоваться для читаемых пользователем меток, напечатанных после чекбокса.
2. Опциональный второй параметр (-checked) определяет включён ли чекбокс по умолчанию. Синонимы: -selected и -on.
3. Опциональный третий параметр (-value) определяет чекбокса при его включении. Если не определено, используется слово "on".
4. Опциональный четвёртый параметр (-label) - видимая пользователю метка, присоединённая к чекбоксу. Если не определена, используется имя чекбокса.
Значение чекбокса можно получить так:
$turned_on = param('checkbox_name');
СОЗДАНИЕ ГРУППЫ РАДИО КНОПОК
print radio_group(-name=>'group_name',
                          -values=>['eenie','meenie','minie'],
                          -default=>'meenie',
                          -linebreak=>'true',
       -labels=>\%labels,
       -attributes=>\%attributes);
-или-
print radio_group('group_name',['eenie','meenie','minie'],
         'meenie','true',\%labels,\%attributes);
ТОЛЬКО ДЛЯ HTML3-СОВМЕСТИМЫХ БРАУЗЕРОВ:
print radio_group(-name=>'group_name',
                          -values=>['eenie','meenie','minie','moe'],
                          -rows=2,-columns=>2);
radio_group() создаёт набор логически связанных радио кнопок (включение одной кнопки отключает другие кнопки)
Параметры:
1. Первый аргумент - обязательное имя группы (-name).
2. Второй аргумент (-values) - список значений для радио кнопок. Значения и метки отображаемые на странице являются идентичными. Передавайте ссылки на массив во втором аргументе, либо используйте анонимный массив, как показано или ссылаясь на именованный массив, например "\@foo".
3. Опциональный третий параметр (-default) - имя кнопки включённой по умолчанию. Если не определена, первый пункт будет установлен по умолчанию. Вы можете указать не существующее имя кнопки, такое как "-" для запуска без выбранных кнопок.
4. Опциональный четвёртый параметр (-linebreak) может быть установлен в 'true' для вставки разрыва строки между клавишами, созданием вертикального списка.
5. Опциональный пятый параметр (-labels) - указатель на ассоциативный массив передающий значения радио кнопок на видимые пользователю метки, которые отображаются на дисплее. Если ничего не указано, на вывод будут выводиться сами значения.
Все современные браузеры могут обрабатывать опциональные параметры -rows и -columns. Эти параметры указывают radio_group() возвращать HTML3 совместимую таблицу содержащую радио группы форматированные со специальными номерами строк и столбцов. При желании, Вы можете указывать всего лишь параметр -columns; радио группа сама подсчитает правильное количество строк для Вас.
Для включения строк и столбцов, находящихся в начале возвращаемой таблицы, Вы можете использовать параметры -rowheaders и -colheaders. Эти оба параметра принимают указатель на массив заголовков. Заголовки всего лишь декорация. Они не реорганизуют интерпретацию радио кнопок - они всего лишь именованная единица.
Опциональный аргумент -tabindex может быть использован для контроля очереди, в которой радио кнопки принимают фокус, при нажатии пользователем клавиши tab. Если переданное скалярное числовое значение, первый элемент в группе будет принимать этот табуляционный индекс и следующие элементы будут инкрементированы по одному. Если получена ссылка на массив значений радио кнопок, то индексы будут игнорированы, таким образом порядок определяется в массиве соответствующему порядку табуляции. Также Вы можете передать хэш, в котором хэш ключи соответствуют значениям радио кнопок и значения соответствуют индексам табуляции каждой клавиши. Примеры:
-tabindex => 100    #	эта группа начинается с индекса 100 и идёт выше
-tabindex => ['moe','minie','eenie','meenie']	# табуляция в этом порядке
-tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # табуляция в этом порядке
Опциональный аргумент -attributes осуществляет передачу любого общего HTML атрибута к индивидуальному пункту меню. Это указатель на ассоциативный массив передающий значения меню к другому ассоциативному массиву с именем атрибутов в качестве ключа и значением атрибутов в качестве значения.
Опциональный аргумент -labelattributes будет содержать атрибуты присоединённые к элементу <label> окружающему каждую кнопку.
Когда форма создана, выбранная радио кнопка может быть получена следующим образом:
$which_radio_button = param('group_name');
Значение возвращаемое radio_group() относится к массиву элементов кнопки. Вы можете захватить их и использовать в таблицах, списках или так, как Вам заблогарассудится:
@h = radio_group(-name=>'group_name',-values=>\@values);
&use_in_creative_way(@h);
СОЗДАНИЕ КНОПКИ ПОДТВЕРЖДЕНИЯ
print submit(-name=>'button_name',
                     -value=>'value');
-или-
print submit('button_name','value');
submit() создаёт кнопку отправки запроса. Каждая форма должна иметь одну из них.
Параметры:
1. Первый аргумент (-name) опционален. Вы можете дать кнопке имя в случае наличия нескольких кнопок в Вашей форме и Вы хотите, чтобы они отличались между собой.
2. Второй аргумент (-value) также опционален. Он устанавливает значение кнопки, передаваемое Вашему сценарию в строке запроса. Имя должно также использоваться в виде видимой пользователю метки.
3. Вы можете использовать -label в качестве алиаса для -value. Я всегда путаю какой из параметров -name и -value изменяет видимую пользователю метку на кнопке.
С помощью различных значений Вы можете вычислять какая кнопка была нажата:
$which_one = param('button_name');
СОЗДАНИЕ КНОПКИ СБРОСА
print reset
reset() создаёт кнопку "reset". Помните, что она восстанавливает форму к её значениям с момента вызова прошлого сценария, НЕ обязательно к значениям по умолчанию.
Помните, что возникает конфликт со встроенной функцией reset(). Используйте CORE::reset() для получения настоящей функции сброса.
СОЗДАНИЕ КНОПКИ ПО УМОЛЧАНИЮ
print defaults('button_label')
defaults() создаёт кнопку, которая будучи нажата, сбросит все произведённые пользователем настройки. И вернёт все настройки по умолчанию.
СОЗДАНИЕ СКРЫТОГО ПОЛЯ
print hidden(-name=>'hidden_name',
                     -default=>['value1','value2'...]);
-или-
print hidden('hidden_name','value1','value2'...);
hidden() создаёт текстовое поле, невидимое пользователю. Удобно для передачи информации о состоянии от одного вызова сценария к следующему.
Параметры:
1. Первый аргумент обязателен и определяет имя этого поля (-name).
2. Второй аргумент также обязателен и определяет его значение (-default). При вызове в стиле именованного параметра, Вы можете передать единственное значение или ссылку на целый список.
Получить значение скрытого поля можно таким образом:
$hidden_value = param('hidden_name');
Помните, что подобно остальным элементам формы, значение скрытого поля является "липким". Если Вы хотите заменить скрытое поле некоторыми другими значениями после вызова сценария, то придёться делать это вручную:
param('hidden_name','new','values','here');
СОЗДАНИЕ НАЖИМАЕМОЙ КНОПКИ С РИСУНКОМ
print image_button(-name=>'button_name',
                           -src=>'/source/URL',
                           -align=>'MIDDLE');
-или-
print image_button('button_name','/source/URL','MIDDLE');
image_button() создаёт нажимаемый рисунок. При нажатии по позиции нажимания Вашему сценарию будут возвращены значения "button_name.x" и "button_name.y", где "button_name" имя присвоенное в функции.
Параметры:
1. Первый аргумент (-name) - обязателен и объявляет имя поля.
2. Второй аргумент (-src) также обязателен и объявляет URL
3. Третья опция (-align, optional) тип выравнивания и может быть TOP, BOTTOM или MIDDLE
Получение значения кнопки производится так:
$x = param('button_name.x');
$y = param('button_name.y');
СОЗДАНИЕ JAVASCRIPT ДЕЙСТВИЙ НА КНОПКУ
print button(-name=>'button_name',
                     -value=>'user visible label',
                     -onClick=>"do_something()");
-или-
print button('button_name',"do_something()");
button() создаёт кнопку совместимую с JavaScript в Netscape 2.0. При нажатии фрагмент JavaScript кода указывает на исполняемый параметр -onClick. На не-Netscape браузерах эта форма элемента, скорее всего, отображаться не будет.

HTTP КУКИСЫ

Netscape браузеры версий 1.1 и выше и все версии Internet Explorer'а поддерживают так называемые "куки" созданные с целью помочь управлению состоянием без сессии браузера. CGI.pm имеет несколько методов поддержки кукисов.
Куки - это пары имя=значение, похожие на именованные параметры в строке запроса CGI. CGI сценарии создают один или более кукисов и отправляют их к браузеру в заголовке HTTP. Браузер управляет списком кукисов принадлежащих Web серверу и возвращают их CGI сценарию в процессе следующих взаимодействий.
В дополнение к требуемой паре имя=значение, каждое куки имеет несколько опциональных атрибутов:
1. срок годности
Это строка время/дата (в специальном GMT формате), которая определяет когда закончится срок действия куки. Куки может быть сохранена и возвращена Вашему сценарию до истечения срока годности, если пользователь закрыл браузер или перезагрузил его. Если срок годности не истёк, куки будет оставаться активной, пока пользователь не выйдет из браузера.
2. домен
Это часть или полное доменное имя для активного куки. Браузер вернёт куки любому хосту, который соответствует части доменного имени. Например, если Вы определили доменное имя ".capricorn.com", то браузер будет возвращать куки Web серверам, запущенных на машинах "www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com" и т.д. Доменное имя должно состоять, как минимум из двух частей для предотвращения соответствия доменам первого уровня вроде ".edu". Если домен не определён, то браузер будет возвращать куки серверу породившему его.
3. путь
Если Вы указали атрибут пути куки, браузер будет проверять его снова перед запуском URL сценария, создающего куки. Для примера, если Вы определили путь "/cgi-bin", то куки будет возвращать каждому сценарию "/cgi-bin/tally.pl", "/cgi-bin/order.pl" и "/cgi-bin/customer_service/complain.pl", но не сценарию "/cgi-private/site_admin.pl". По умолчанию, путь установлен в "/", в результате каждая куки будет посылаться к любому CGI сценарию на Вашем сайте.
4. флаг "secure"
Если установлен атрибут "secure", куки будут посылаться только Вашему сценарию если CGI запрос производится по защищённому каналу типа SSL.
Интерфейс для HTTP кукисов, метод cookie():
$cookie = cookie(-name=>'sessionID',
                         -value=>'xyzzy',
                         -expires=>'+1h',
                         -path=>'/cgi-bin/database',
                         -domain=>'.capricorn.org',
                         -secure=>1);
print header(-cookie=>$cookie);
cookie() создаёт новое куки. Его параметры включают в себя:
-name
Имя куки (обязательно). Любая строка. Браузеры допускают к использованию в качестве имён куки не пробельные, числовые и буквенные символы, CGI.pm обходит это ограничение свободными и несвободными кукисами за кулисами.
-value
Значение куки. Это может быть скалярное значение, ссылка на массив или ссылка на ассоциативный массив. Например, Вы можете сохранить вход ассоциативного массива в куки таким образом:
$cookie=cookie(-name=>'family information',
                       -value=>\%childrens_ages);
-path
Опциональная часть пути для каждого куки применяется так, как было сказано выше.
-domain
Опциональная часть домена для которого соответствует эта куки, как было сказано выше.
-expires
Опциональный срок годности для этого куки. Формат описан в секции метода header():
"+1h"  one hour from now
-secure
Если установлено в true, эта куки будет использоваться только внутри безопасной SSL сессии.
Куки созданые с помощью cookie() должны входить в HTTP заголовок в строке возвращаемой методом header():
use CGI ':standard';
print header(-cookie=>$my_cookie);
Для создания множественных кукисов, передайте методу header() ссылку на массив:
$cookie1 = cookie(-name=>'riddle_name',
                          -value=>"The Sphynx's Question");
$cookie2 = cookie(-name=>'answers',
                          -value=>\%answers);
print header(-cookie=>[$cookie1,$cookie2]);
Для получения куки, запросите его по имени с помощью метода cookie() без параметра -value. Для примера использующего объектно-ориентированную форму:
use CGI;
$query = new CGI;
$riddle = $query->cookie('riddle_name');
%answers = $query->cookie('answers');
Кукисы созданные с помощью единственного скалярного значения, подобно куки "riddle_name", будут возвращены в форму. Кукисы с массивами и хэш значениями также могут быть получены.
Куки и пространство имён CGI являются разделёнными. Если Вы имеете параметр названный как 'answers' и куки названный 'answers', значения полученные с помощью param() и cookie() будут независимы друг от друга. Однако, можно легко вставить CGI параметр в куки и наоборот:
# вставка CGI параметра в куки
$c=cookie(-name=>'answers',-value=>[param('answers')]);
# и наоборот
param(-name=>'answers',-value=>[cookie('answers')]);
Если Вы вызвали cookie() без каких-либо параметров, то в этом случае будет возвращён список имён всех кукисов переданных Вашему сценарию:
@cookies = cookie();
Смотрите примерный сценарий cookie.cgi для некоторых эффективных приёмов работы с кукисами.

РАБОТА С ФРЕЙМАМИ

Для некоторых браузеров CGI.pm может может писать панели и окна используя механизм фреймов HTML4. Есть три технологии программного объявления новых фреймов:
1. Создание документа <Frameset>
После вывода записи в HTTP заголовок, взамен созданию стандартного HTML документа использующего вызов start_html() можно создать документ <frameset>, определяющий фреймы на странице. Объявите Ваш сценрий(и) (с соответствующими параметрами) как SRC для каждого из фреймов.
Не существует специальной поддержки для создания секции <frameset> в CGI.pm, но HTML очень прост для записи. За дополнительной информацией, обращайтесь к документации фреймов в домашней странице Netscape.
http://wp.netscape.com/assist/net_sites/frames.html
2. Определить пункт назначения для документа в HTTP заголовке
Вы можете определить параметр -target в методе header():
print header(-target=>'ResultsWindow');
Эта инструкция скажет браузеру загрузить вывод Вашего сценария в фрейм под именем "ResultsWindow". Если фрейм с этим именем не существует, браузер создаст новое окно и загрузит Ваш документ сценария в него. Существует число магических имён, которые Вы можете использовать в качестве целей. За деталями обращайтесь к документации фреймов на домашней странице Netscape.
3. Определить назначение для документа в теге <form>
Вы можете определить фрейм к загрузке внутри тега FORM. В случае с CGI.pm это выглядит так:
print start_form(-target=>'ResultsWindow');
Когда Ваш сценарий перезагружается формой, его вывод будет загружен в фрейм под названием "ResultsWindow". Если он не создан, то будет создано новое окно.
Сценарий "frameset.cgi" в директориях с примерами показывает один из пути создания страниц, где заполняемая форма и ответ от формы живут в соседних фреймах.

ПОДДЕРЖКА JAVASCRIPT

Netscape версии 2.0 и выше содержат интерпретируемый язык под названием JavaScript. Internet Explorer 3.0 и выше поддерживает близкий диалект названный как JScript. JavaScript не означает Java, и к сожалению он не похож на Perl. JavaScript позволяет Вам программно менять содержимое заполняемых форм, создавать новые окна и всплывающие диалоги внутри Netscape. С точки зрения CGI сценариев, JavaScript вполне пригоден для работы с заполняемыми формами до их отправки на сервер.
Вам может понадобиться знание JavaScript в процессе работы. В интернете есть очень много источников сведений о JavaScript.
Обычный путь использования JavaScript - определить функции внутри <SCRIPT> блока HTML заголовка и затем, регистрировать событие дескрипторов в различных элементах страницы. События включающие таки вещи как переход мышки через элемент формы, нажатие кнопки, изменение содержимого текстового поля или подтверждения формы. В случае, когда происходит событие элемент регистрирует дескриптор события и происходит вызов соответствующего JavaScript кода.
Элемент, могущий регистрировать дескрипторы событий, включается в <BODY> HTML документа, гипертекстовые ссылки, все предыдущие элементы заполняемой формы и сама форма внутри секции <BODY>. Есть большое количество событий и каждая относится к определённому элементу. Вот частичный список:
onLoad
Браузер загрузит текущий документ. Приемлемо в:
+ Только для секции <BODY> HTML.
onUnload
Браузер закрывает текущую страницу или фрейм. Приемлемо для:
+ Только для секции <BODY> HTML.
onSubmit
Пользователь нажал кнопку подтверждения на форме. Это событие возникнет только перед подтверждением формы и Ваша функция может вернуть значение false при отмене подтверждения. Приемлемо для:
+ Только для форм.
onClick
Мышка кликнула по пункту в заполнямой форме. Приемлемо для:
+ Кнопок (включая подтверждение, сброс и кнопки-рисунки)
+ Чекбоксы
+ Радио кнопки
onChange
Пользователь изменил содержимое поля. Приемлемо для:
+ Текстовых полей
+ Текстовых областей
+ Полей ввода пароля
+ Полей файла
+ Всплывающих Меню
+ Прокручиваемых списков
onFocus
Пользователь выбрал поле для последующей работы. Приемлемо для:
+ Текстовые поля
+ Текстовые области
+ Поля для ввода пароля
+ Поля файлов
+ Всплывающие меню
+ Прокручиваемые списки
onBlur
Пользователь снял выделение с поля (начал работу с чем-то другим). Приемлемо для:
+ Текстовых полей
+ Текстовых областей
+ Полей ввода пароля
+ Файловых полей
+ Всплывающих меню
+ Прокручиваемые списки
onSelect
Пользователь изменил часть выбранного текстового поля. Приемлемо для:
+ Текстовые поля
+ Текстовые области
+ Поля ввода пароля
+ Файловые поля
onMouseOver
Мышка переместилась над элементом.
+ Текстовые поля
+ Текстовые области
+ Поля ввода пароля
+ Файловые поля
+ Всплывающие меню
+ Прокручиваемые списки
onMouseOut
Мышка ушла за пределы элемента.
+ Текстовые поля
+ Текстовые области
+ Поля ввода пароля
+ Файловые поля
+ Всплывающие Меню
+ Прокручиваемые списки
При регистрации JavaScript события дескриптор с HTML элементом всего лишь использует имя события в качестве параметра при вызове соответствующего CGI метода. Например, для исполнения Вашего validateAge() JavaScript кода, исполняемого каждый раз при изменении текстового поля под названием "age", сгенерируйте поле подобное этому:
print textfield(-name=>'age',-onChange=>"validateAge(this)");
Этот пример получает уже объявленную функцию validateAge() путём вставки её в блок <SCRIPT>. Метод start_html() относящийся к CGI.pm обеспечивает удобный способ для создания этой секции.
Так же Вы можете создать форму, проверяющую себя на правильность и предупреждающую пользователя если некоторые значения отсутствуют:
print startform(-onSubmit=>"validateMe(this)");
Смотрире сценарий javascript.cgi для демонстрации принципа работы.

ОГРАНИЧЕННАЯ ПОДДЕРЖКА КАСКАДНЫХ ТАБЛИЦ СТИЛЕЙ

CGI.pm имеет ограниченную поддержку каскадных таблиц стилей HTML3 (css). Для вставки таблиц стилей в Ваш документ, передайте методу start_html() параметр -style. Значение этого параметра может быть скалярным, в этом случае будет произведена интерпретация в виде источника URL для таблиц стилей или значение может быть ссылкой на хэш. В последнем случае Вы должны предоставить хэш с одним или более параметрами -src или -code. -src указывает URL'у где находится внешне объявленная таблица стилей. -code указывает на то, что скалярное значение должно входить в секцию <style>. Объявление стиля в -code перекрывает аналогично-именованные объявления в -src, отсюда и название "каскадное".
Также Вы можете определить тип таблиц стилей добавлением опционального параметра -type, указанного в хэше с помощью -style. Если не определено, то устанавливаются значения по умолчанию 'text/css'.
Для ссылки на стиль в теле Вашего документа, добавьте параметр -class в любой HTML элемент:
print h1({-class=>'Fancy'},'Welcome to the Party');
Или объявите стили на лету с помощью параметра -style:
print h1({-style=>'Color: red;'},'Welcome to Hell');
Вы можете также использовать новый элемент span() для применения стилей в секции текста:
print span({-style=>'Color: red;'},
           h1('Welcome to Hell'),
           "Where did that handbasket get to?"
           );
Помните что Вы должны импортировать объявление ":html3" для получения доступа к методу span(). Это быстрый и не красивый пример использования CSS. Смотрите спецификацию CSS по адресу http://www.w3.org/pub/WWW/TR/Wd-css-1.html.
use CGI qw/:standard :html3/;
#это таблица стилей вставленная прямо в страницу
$newStyle=<<END;
END
print header();
print start_html( -title=>'CGI with Style',
                  -style=>{-src=>'http://www.capricorn.com/style/st1.css',
                           -code=>$newStyle}
                );
print h1('CGI with Style'),
      p({-class=>'Tip'},
        "Better read the cascading style sheet spec before playing with this!"),
      span({-style=>'color: magenta'},
           "Look Mom, no hands!",
           p(),
           "Whooo wee!"
           );
print end_html;
Передайте ссылку на массив в -code или -src для вставки множественных таблиц стилей в Ваш документ.
Вы можете вставить дословную таблицу стилей, включающую произвольное форматирование в заголовке, Вы можете передать тег -verbatim для хэша -style, как указано в прмере:
print start_html (-style  =>  {-verbatim => '@import url("/server-com-
mon/css/'.$cssFile.'");',
                  -src	 =>  '/server-common/css/core.css'});
Сгенерирует HTML заголовок содержащий следующее:
<link rel="stylesheet" type="text/css"	href="/server-common/css/core.css">
  <style type="text/css">
  @import url("/server-common/css/main.css");
  </style>
Другие дополнительные аргументы передаются в переменной -style внутри тега <link>. На пример:
start_html(-style=>{-src=>['/styles/print.css','/styles/layout.css'],
                         -media => 'all'});
Получится следующее:
<link rel="stylesheet" type="text/css" href="/styles/print.css" media="all"/>
<link rel="stylesheet" type="text/css" href="/styles/layout.css" media="all"/>
Для создание более сложных <link> тегов, используйте функцию Link() и передайте её функции start_html() в аргументе -head:
@h = (Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/ss.css',-media=>'all'}),
      Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/fred.css',-media=>'paper'}));
print start_html({-head=>\@h})
Для создания главной и "альтернативной" таблицы стилей, используйте опцию -alternate:
start_html(-style=>{-src=>[
                          {-src=>'/styles/print.css'},
                          {-src=>'/styles/alt.css',-alternate=>1}
                          ]
                   });

ОТЛАДКА

Если Вы запустили сценарий для командной строки или в perl отладчике, Вы можете передать сценарию список ключевых слов или пару параметр=значение в командной строке или со стандартного ввода (Вам не надо беспокоиться о каких-нибудь методах получения переменных среды). Вы можете передать ключевые слова подобные следующим:
your_script.pl keyword1 keyword2 keyword3
или так:
your_script.pl keyword1+keyword2+keyword3
или так:
your_script.pl name1=value1 name2=value2
или так:
your_script.pl name1=value1&name2=value2
Для отключения этой особенности, используйте прагму -no_debug.
Для теста метода POST, Вы можете включить полную отладку с помощью прагмы -debug. Эта прагма позволит Вам передавать разграниченные новыми строками пары имя=значение для сценария на стандартном вводе.
При отладке, Вы можете использовать кавычки и обратные слэши для экранирования символов в стиле простой оболочки, что в свою очередь, даёт Вам возможность использовать пробелы и другие забавные символы в парах параметр=значение:
your_script.pl "name1='I am a long value'" "name2=two\ words"
И под конец, Вы можете установить информацию о пути для сценария, для этого путь должен предшествовать параметрам имя/значение со знаком вопроса между путём и значениями (?):
your_script.pl /your/path/here?name1=value1&name2=value2
ВЫВОД ВСЕХ ПАР ИМЯ/ЗНАЧЕНИЕ
Метод Dump() выдаёт строку состоящую из всех пар имя/значение, относящихся к запросу, в виде вложенного списка. Удобно в целях отладки:
print Dump
Создаст что-то похожее на это:
<ul>
<li>name1
    <ul>
    <li>value1
    <li>value2
    </ul>
<li>name2
    <ul>
    <li>value1
    </ul>
</ul>
Как и сокращение, Вы можете вставить внутрь CGI строку и заменить её красивым HTML дампом, как показано ниже:
$query=new CGI;
print "<h2>Current Values</h2> $query\n";

ПОЛУЧЕНИЕ ПЕРЕМЕННЫХ ОКРУЖЕНИЯ

Некоторые из большинства полезных переменных окружения могут быть получены через этот интерфейс. Методы могут быть следующими:
Accept()
Возвращает список MIME типов, принимаемых удалёнными браузерами. Если Вы применяете этот метод на единственный аргумент, соответствующий MIME типу, как в Accept('text/html'), то будет возвращено значение с плавающей точкой, соответствующей предпочтениям браузеров начинаются с 0.0 (не нужно) до 1.0. Glob типы (т.е. text/*) в принимаемом списке браузеров управляются корректно.
Помните, что функция начинается с большой буквы с версий 2.43 и 2.44 для обхода конфликта с функцией Perl accept().
raw_cookie()
Возвращает переменную HTTP_COOKIE, HTTP расширение включено в браузеры Netscape версии 1.1 и выше, и все версии Internet Explorer. Кукисы имеют специальный формат и этот метод вызова только возвращает сырую форму (?cookie dough). Смотрите cookie() для изучения путей настройки и приёма готовых кукисов.
Вызванные без параметров, raw_cookie() возвращает структуру упакованных куки. Вы можете разделить их между индивидуальными кукисами с помощью символьной последовательности "; ". Вызванная с именем куки, принимается неэкранированная форма этих куки. Вы можете использовать метод регулярных cookie() для получения их имён или использовать метод raw_fetch() для модуля CGI::Cookie.
user_agent()
Возвращает переменную HTTP_USER_AGENT. Если Вы применяете этот метод с единственным аргументом, то метод будет использовать образец для поиска, позволяющего Вам использовать что-либо вроде user_agent(netscape);
path_info()
Возвращает дополнительную информацию о пути с URL сценария. Т.е. получение /cgi-bin/your_script/additional/stuff будет результатом в path_info() возвращающим "/additional/stuff".
ПОМНИТЕ: Microsoft Internet Information Server не корректно работает с информацией о дополнительных путях. Если Вы используете DLL библиотеку Perl'а, IIS сервер будет пытаться исполнить дополнительную информацию о пути как Perl сценарий. Если Вы используете отображение простых файлов, информация пути будет присутствовать в окружении, но некорректно. Лучшая вещь для исполнения этого - использовать информацию дополнительного пути в CGI сценарии предназначенных для использования с IIS.
path_translated()
Также как и path_info() но возвращает дополнительную информацию о пути, переведённую в физический путь, т.е. "/usr/local/etc/httpd/htdocs/additional/stuff".
Microsoft IIS не корректно работает с транслированными путями.
remote_host()
Возвращает либо имя хоста, либо IP адрес. в случае недоступного имени хоста.
script_name()
Возвращает имя сценария как частичное URL, для ссылающихся на себя сценариев.
referer()
Возвращает URL страницы, видимой до полученного сценария, браузеру. Не доступно для всех браузеров.
auth_type ()
Возвращает метод авторизации/верификации для использования этого сценария.
server_name ()
Возвращает имя сервера, обычно имя хоста машины.
virtual_host ()
Когда используются виртуальные хосты, возвращают имя хоста, используемый браузером для контакта.
server_port ()
Возвращает порт, прослушиваемый сервером.
virtual_port ()
Подобно server_port(), за исключением того, что виртуальные хосты принимаются в хост. Используйте это при работе с виртуальными хостами.
server_software ()
Возвращает программное обеспечение сервера и номер версии.
remote_user ()
Возвращает имя авторизации/верификации используемое для проверки пользователей, если сценарий защищён.
user_name ()
Пытается получить имя удалённого пользователя, используя разнообразную технологию. Работает только со старыми браузерами, такими как Mosaic. Новые браузеры не отчитываются о именах пользователя по причинам безопасности!
request_method()
Возвращает метод используемый для доступа к Вашему сценарию, обычно 'POST', 'GET' или 'HEAD'.
content_type()
Возвращает данные о типе_содержимого полученном через POST, главным образом multipart/form-data или application/x-www-form-urlencoded
http()
Вызывается без аргументов, возвращает список переменных HTTP окружения, включая такие вещи как HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE и HTTP_ACCEPT_CHARSET соответствующие также-названными полями HTTP заголовка в запросе. Вызывается с именем поля HTTP запроса, возвращает его значение. Использование верхнего регистра и использование дефисов взамен нижнего подчёркивания не существенно.
Например, все три этих примера эквивалентны:
$requested_language = http('Accept-language');
$requested_language = http('Accept_language');
$requested_language = http('HTTP_ACCEPT_LANGUAGE');
https()
Также как и http(), но работает с переменными HTTPS окружения, при включённом SSL протоколе. Можно использовать с целью определения включённого SSL.

ИСПОЛЬЗОВАНИЕ NPH СЦЕНАРИЕВ

NPH, или "no-parsed-header" ("не-разбираемый-заголовок") сценарии полностью обходят сервер с помощью отправки завершённых HTTP заголовок прямо браузеру. Это незначительный плюс в плане производительности, но это больше всего используется для получения преимущества над HTTP расширений, прямо не поддерживаемых Вашим сервером, таких как вставка сервера и PICS заголовков.
Серверы используют различные допущения для назначений CGI сценариев в качестве NPH. Многие Unix серверы смотрят на начало имени сценариев на наличие префикса "nph-". Сервер WebSTAR Macintosh и Microsoft Internet Information Server, в противоположность, пытаются решить является ли программа NPH сценарием по первой строке вывода сценария.
CGI.pm поддерживает NPH сценарии со специальным NPH режимом. Когда в этом режиме, CGI.pm будет выдавать необходимую дополнительную информацию о заголовке, при вызове методов header() и redirect().
Microsoft Internet Information Server требует NPH режима. Как в версии 2.30, CGI.pm будет автоматически определять когда сценарий запущен под IIS и работает под этим режимом. Вам не нужно делать это вручную, хотя ничто Вам не мешает работать вручную. Однако, запомните, что если Вы установили Service Pack 6, большая часть функциональности NPH сценариев, включая свойство перенаправления при установке куки, b<работает не везде> на IIS без специальных патчей от Microsoft. Смотрите http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP: Не Работающие Не-Разбираемые Заголовки От CGI Приложений Имеющих Префикс nph- в Имени.
В случае метода use
Простое добавление прагмы "-nph" к списку символов импортируемых в Ваш сценарий:
use CGI qw(:standard -nph)
Вызовом метода nph():
Вызов nph() с не-нулевым параметром в любой точке после использования CGI.pm в Вашу программу.
CGI->nph(1)
С помощью использования параметра -nph в функциях header() и redirect():
print header(-nph=>1);

Вставка Сервера

CGI.pm обеспечивает четыре простых функций для создания многосоставных документов со вставкой сервера. Эти функции любезно предоставлены Эдом Джорданом <ed@fidalgo.net> (Ed Jordan). Для импортирования их в Ваше пространство имён, Вы должны импортировать установку ":push". Также рекомендуется установить сценарий в режим NPH и установить $| в 1 для обхода проблем буферизации.
Это простой сценарий, демонстрирующий вставку сервера:
#!/usr/local/bin/perl
use CGI qw/:push -nph/;
$| = 1;
print multipart_init(-boundary=>'----here we go!');
foreach (0 .. 4) {
    print multipart_start(-type=>'text/plain'),
          "The current time is ",scalar(localtime),"\n";
    if ($_ < 4) {
            print multipart_end;
    } else {
            print multipart_final;
    }
    sleep 1;
}
Этот сценарий инициализирует вставку сервера путём вызова multipart_init(). Затем вводит цикл, в котором начинается новая многосоставная секция вызывающая multipart_start(), выводящая текущее время и конец многосоставной секции с multipart_end(). Далее следует задержка на секунду и начинается следующий цикл. В финальной итерации, концы многосоставной секции с multipart_final() идёт раньше multipart_end().
multipart_init()
multipart_init(-boundary=>$boundary);
Инициализация многосоставной системы. Аргумент -boundary определяет границы MIME строки для разделения частей документа. Если не определено, CGI.pm сам выберет подходящие границу для Вас.
multipart_start()
multipart_start(-type=>$type)
Запускает новую часть многосоставного документа использующего определённый MIME тип. Если не определено, применяется text/html.
multipart_end()
multipart_end()
Конец части. Вы должны помнить что вызов multipart_end() производится один раз для каждого multipart_start(), за исключением конца последней части многосоставного документа при вызове multipart_final() взамен multipart_end().
multipart_final()
multipart_final()
Конец всех частей. Вы должны вызывать multipart_final() раньше чем multipart_end() в конце прошлой части многосоставного документа.
Пользователи интересующиеся вставкой приложений сервера, должны обратиться к модулю CGI::Push.
Вставку сервера поддерживает только Netscape Navigator. Internet Explorer не поддерживает вставку сервера.

Обход Атак Отказа в Обслуживании

Потенциальная проблема с CGI.pm - то, что по умолчанию, он пытается запуститься с POST'а вне зависимости насколько он большой. Хитрый хакер может атаковать Ваш сайт путём отправки через POST CGI сценарий с огромным количеством мегабайтов. CGI.pm будет считывать входящее с POST'а в переменные, которые в свою очередь разрастаются в размере так, что занимают всё место в памяти. Пока сценарий будет высвобождать память, система будет тормозить катастрофически. Это - вид атаки в обслуживании.
Другая возможная атака - для удалённых пользователей заставить CGI.pm принять на загрузку на сервер большой файл. CGI.pm будет пытаться загрузить и сохранить его во временную директорию, даже если Ваш сценарий не ожидает приёма загруженного файла. CGI.pm будет удалять файл автоматически по завершению работы, но, тем временем удалённый пользователь может заполнить всё пространство жёсткого диска сервера, создавая проблемы для других программ.
Лучший путь обойти атаки отказа в обслуживании - ограничить количество памяти, времени CPU и дискового пространства для CGI сценариев. Некоторые Web сервера предоставляют встроенные функции для подобных операций. В других случаях, Вы можете использовать команду limit оболочки или ulimit для установки ограничения на использование CGI ресурсов.
CGI.pm также имеет некоторую простую встроенную защиту от атаки отказа в обслуживании, но Вы должны активировать их перед использованием. Есть форма из двух глобальных переменных в пространстве имён CGI:
$CGI::POST_MAX
Если установлено в не-отрицательное целое число, это значение установит ограничение на размер данных, передаваемых через POST в байтах. Если CGI.pm определит что POST больше ограничения, то произойдёт выход с сообщением об ошибке. Это значение действует и на ординарный POST и на многосоставные POST'ы, ограничивая максимальный размер загружаемых файлов. Вы должны установить его в допустимо большое значение, такое как 1 мегабайт.
$CGI::DISABLE_UPLOADS
Если установлено не-нулевое значение, загрузка файлов на сервер будет полностью отключена. Другие значения заполняемой формы будут работать как обычно.
Вы можете использовать эти значения двумя способами.
1. Отдельно для каждого сценария
Установить значение в начале сценария, сразу после оператора "use":
use CGI qw/:standard/;
use CGI::Carp 'fatalsToBrowser';
$CGI::POST_MAX=1024 * 100;  # максимум 100K для post'ов
$CGI::DISABLE_UPLOADS = 1;  # без загрузок на сервер
2. Глобально для всех сценариев
Откройте CGI.pm, найдите определения для $POST_MAX и $DISABLE_UPLOADS, и установите их в желаемые значения. Вы можете найти их в верху файла в процедуре под названием initialize_globals().
На попытку отправки POST больше чем $POST_MAX байт param() вернёт пустой список CGI параметров. Вы можете испытать это событие с помощью проверки cgi_error(), либо после создания CGI объекта или, если Вы используете функционально-ориентированный интерфейс, вызовите в начале <param()>. Если POST был перехвачен, то cgi_error() вернёт сообщение "413 POST too large".
Это сообщение об ошибке предусмотрено для HTTP протокола, и предназначено для возвращения браузеру в виде кода статуса ошибки CGI сценариев. Например:
$uploaded_file = param('upload');
if (!$uploaded_file && cgi_error()) {
    print header(-status=>cgi_error());
    exit 0;
}
Однако, это не всегда срабатывает, так как не все браузеры знают что делать с этим кодом статуса. Так что будет лучше если Вы сами создадите HTML страницу с предупреждением пользователя о проблеме.

СОВМЕСТИМОСТЬ С CGI-LIB.PL

Для облегчения портирования программ использующих cgi-lib.pl создана процедура совместимости "ReadParse". Портирование происходит легко:
СТАРАЯ ВЕРСИЯ
require "cgi-lib.pl";
&ReadParse;
print "The value of the antique is $in{antique}.\n";
НОВАЯ ВЕРСИЯ
use CGI;
CGI::ReadParse();
print "The value of the antique is $in{antique}.\n";
Процедура ReadParse() из CGI.pm создаёт связанную переменную под именем в %in, которая может быть использована для получения переменных запросов. Подобно ReadParse, Вы также можете использовать свою собственную переменную. Редко используемые особенности ReadParse, такие как создание переменных @in и $in, не поддерживается.
Однажды использовав ReadParse, Вы можете получить объект запроса таким образом:
$q = $in{CGI};
print textfield(-name=>'wow',
                    -value=>'does this really work?');
С помощью этого метода Вы можете использовать более интересные особенности CGI.pm без переписывания Ваших старых сценариев с нуля.

ИНФОРМАЦИЯ ОБ АВТОРАХ

Правообладание интерфейсом GD.pm принадлежит Линкольну Д. Штайну (Lincoln D. Stein), 1995-2007. Распространяется под лицензией GPL и Artistic License 2.0.
Об исправлениях ошибок и комментарии пишите сюда: lstein@cshl.org. При отсылке отчёта об ошибке, пожалуйста, укажите версию CGI.pm, версию Perl, имя и версию Вашего Web сервера, имя и версию используемой операционной системы. Если проблема связана с конкретным браузером, пожалуйста, предоставьте информацию о браузере.

ВКЛАД

Большое спасибо следующим людям:
Мэтт Хефрон (Matt Heffron) (heffron@falstaff.css.beckman.com)
Джеймс Тейлор (James Taylor) (james.taylor@srs.gov)
Скотт Энгуиш (Scott Anguish) <sanguish@digifix.com>
Майк Джуелл (Mike Jewell) (mlj3u@virginia.edu)
Тимоти Шиммин (Timothy Shimmin) (tes@kbs.citri.edu.au)
Джорджен Хэгг (Joergen Haegg) (jh@axis.se)
Лорент Дельфосс (Laurent Delfosse) (delfosse@delfosse.com)
Ричард Ресник (Richard Resnick) (applepi1@aol.com)
Крейг Бишоп (Craig Bishop) (csb@barwonwater.vic.gov.au)
Тони Куртис (Tony Curtis) (tc@vcpc.univie.ac.at)
Тим Банс (Tim Bunce) (Tim.Bunce@ig.co.uk)
Том Христиансен (Tom Christiansen) (tchrist@convex.com)
Андреас Коениг (Andreas Koenig) (k@franz.ww.TU-Berlin.DE)
Тим МакКензи (Tim MacKenzie) (Tim.MacKenzie@fulcrum.com.au)
Кевин Б. Хендрикс (Kevin B. Hendricks) (kbhend@dogwood.tyler.wm.edu)
Стефен Дамен (Stephen Dahmen) (joyfire@inxpress.net)
Эд Джордан (Ed Jordan) (ed@fidalgo.net)
Дэвид Алан Писони (David Alan Pisoni) (david@cnation.com)
Дуг МакЭшерн (Doug MacEachern) (dougm@opengroup.org)
Робин Хьюстон (Robin Houston) (robin@oneworld.org)
...и много много других...
за предложения и исправление ошибок.

ЗАВЕРШЁННЫЙ ПРИМЕР ПРОСТОГО ФОРМО-ОРИЕНТИРОВАННОГО СЦЕНАРИЯ

#!/usr/local/bin/perl
use CGI ':standard';
print header;
print start_html("Example CGI.pm Form");
print "<h1> Example CGI.pm Form</h1>\n";
print_prompt();
do_work();
print_tail();
print end_html;
sub print_prompt {
   print start_form;
   print "<em>What's your name?</em><br>";
   print textfield('name');
   print checkbox('Not my real name');
   print "<p><em>Where can you find English Sparrows?</em><br>";
   print checkbox_group(
                        -name=>'Sparrow locations',
                        -values=>[England,France,Spain,Asia,Hoboken],
                        -linebreak=>'yes',
                        -defaults=>[England,Asia]);
   print "<p><em>How far can they fly?</em><br>",
        radio_group(
                -name=>'how far',
                -values=>['10 ft','1 mile','10 miles','real far'],
                -default=>'1 mile');
   print "<p><em>What's your favorite color?</em>  ";
   print popup_menu(-name=>'Color',
                            -values=>['black','brown','red','yellow'],
                            -default=>'red');
   print hidden('Reference','Monty Python and the Holy Grail');
   print "<p><em>What have you got there?</em><br>";
   print scrolling_list(
                 -name=>'possessions',
                 -values=>['A Coconut','A Grail','An Icon',
                           'A Sword','A Ticket'],
                 -size=>5,
                 -multiple=>'true');
   print "<p><em>Any parting comments?</em><br>";
   print textarea(-name=>'Comments',
                          -rows=>10,
                          -columns=>50);
   print "<p>",reset;
   print submit('Action','Shout');
   print submit('Action','Scream');
   print endform;
   print "<hr>\n";
}
sub do_work {
   my(@values,$key);
   print "<h2>Here are the current settings in this form</h2>";
   foreach $key (param) {
      print "<strong>$key</strong> -> ";
      @values = param($key);
      print join(", ",@values),"<br>\n";
     }
    }
sub print_tail {
   print <<END;
<hr>
<address>Lincoln D. Stein</address><br>
<a href="/">Home Page</a>
END
}

ОШИБКИ

Пожалуйста, отправляйте отчёт о них.

СМОТРИТЕ ТАКЖЕ

CGI::Carp, CGI::Fast, CGI::Pretty


perl v5.8.9 2001-09-21 CGI(3)