CGI.pm - библиотека CGI для Perl 5
Версия 2.56, 13.09.1999, Л. Штейн. Перевод 13.02.2000, П. Шмидт.
Содержание
Загрузка и установка
- Загрузка архива gzip tar (для Unix)
- Загрузка архива pkzip (для Windows)
- Загрузка архива sit (для Macintosh)
- Загрузка только модуля CGI (несжатого)
Текущая версия программного обеспечения может быть всегда загружена с копии владельца этого документа, поддерживаемой на http://stein.cshl.org/WWW/software/CGI/.
Этот пакет требует Perl 5.004 или выше. Ранние версии Perl могут работать, но CGI.pm не тестировался с ними. Если вам действительно невтерпеж, отредактируйте исходный код, чтобы удалить строку, которая говорит "требуется 5.004" ("require 5.004"), но не удивляйтесь, если вы натолкнетесь на проблемы.
Если вы используете систему Unix, вам следует сделать установку Perl для себя. Направляйтесь в каталог, содержащий CGI.pm, и наберите следующие команды:
% perl Makefile.PL % make % make install
Возможно, вам придется быть администратором (root), чтобы сделать следующий шаг.
Это создаст два новых файла в вашей библиотеке Perl. CGI.pm - главный файл библиотеки. Carp.pm (в подкаталоге "CGI") содержит некоторые необязательные полезные подпрограммы для написания хорошо форматированных сообщений об ошибках в журналах (log) вашего сервера. Смотрите man-страницу Carp.pm более детально.
Если вы получаете сообщения об ошибках, когда вы пытаетесь устанавливать, тогда вы:
- либо запускаете версию Perl для Windows NT или Macintosh, которая не имеет встроенной в него программы make или MakeMaker.
- либо имеете старую версию Perl. Обновите до 5.004 или выше.
В первом случае не паникуйте. Вот рецепт, который работает (команды даны в форме MS-DOS/Windows):
> cd CGI.pm-2.46 > copy CGI.pm C:\Perl\lib > mkdir C:\Perl\lib\CGI > copy CGI\*.pm C:\Perl\lib\CGI
Измените этот рецепт, если ваша библиотека Perl имеет другое местонахождение.
Для пользователей Macintosh просто перетащите файл, называющийся CGI.pm, в папку, где хранятся ваши другие файлы .pm для Perl. Также перетащите папку, называющуюся "CGI".
Если вы не имеете достаточных привилегий для установки в /usr/local/lib/perl5, вы все же можете использовать CGI.pm. Измените рецепт установки следующим образом:
% perl Makefile.PL INSTALLDIRS=site INSTALLSITELIB=/home/your/private/dir % make % make install
Замените /home/your/private/dir полным путем в каталог, в который вы хотите, чтобы библиотека была помещена. Теперь начинайте ваши скрипты CGI с преамбулы вроде следующей:
use lib '/home/your/private/dir'; use CGI;
Не забудьте заменить /home/your/private/dir подлинным местонахождением CGI.pm.
Замечания об использовании CGI.pm на NT и других платформах не-Unix
Функционально-ориентированное использование в сравнении с объектно-ориентированным
CGI.pm может использоваться в двух различных режимах, называемых функционально-ориентированным и объектно-ориентированным. В функционально-ориентированном режиме, вы сначала импортируете функции CGI в пространство имен вашего скрипта, затем непосредственно вызываете эти функции. Простенький функционально-ориентированный скрипт выглядит следующим образом:
#!/usr/local/bin/perl
use CGI qw/:standard/;
print header(),
start_html(-title=>'Здорово!'),
h1('Здорово!'),
'Смотри, мам, нету рук!',
end_html();
Оператор use загружает определения CGI.pm и импортирует набор ":standard" определений функций. Потом мы делаем вызовы различных функций, таких как header(), чтобы сгенерировать заголовок HTTP, start_html(), чтобы воспроизвести верхнюю часть документа HTML, h1(), чтобы воспроизвести заголовок первого уровня и так далее.
В дополнение к стандартному набору, существует много необязательных наборов менее часто использующихся функций CGI. Смотрите импортирование методов CGI за всеми подробностями.
В объектно-ориентированном режиме, вы пишите use CGI; без указания каких-либо функций или наборов функций для импорта. В этом случае, вы связываетесь с CGI.pm через объект CGI. Этот объект создается вызовом CGI::new() и инкапсулирует (заключает в себе) всю информацию о состоянии текущей транзакции CGI, такую как значения параметров CGI, переданные вашему скрипту. Хотя и более многословен, этот стиль кодирования имеет преимущество, позволяющее вам создавать множество объектов CGI, сохранять их состояние на диск или в базу данных, а также манипулировать ими, чтобы достичь ловких эффектов.
Тот же скрипт, написанный, используя объектно-ориентированный стиль, выглядит следующим образом:
#!/usr/local/bin/perl
use CGI;
$q = new CGI;
print $q->header(),
$q->start_html(-title=>'Здорово!'),
$q->h1('Здорово!'),
'Смотри, мам, нету рук!',
$q->end_html();
Объектно-ориентированный режим имеет также преимущество потребления несколько меньшего количества памяти, чем функционально-ориентированный стиль кодирования. Это может иметь значение для пользователей постоянных интерпретаторов Perl, таких как mod_perl.
Большинство примеров кода показаны ниже в объектно-ориентированном стиле кодирования. Мысленно переводите их функционально-ориентированный стиль, если вы предпочитаете его.
Создание нового объекта CGI
Самое основное использование CGI.pm - добраться до параметров запроса, представленного вашему скрипту. Чтобы создать новый объект CGI, который содержит параметры переданные вашему скрипту, помещайте следующее наверху ваших программ CGI на Perl:
use CGI; $query = new CGI;
В объектно-ориентированном мире Perl 5, этот код вызывает метод new() класса CGI и сохраняет новый объект CGI в переменной, названной $query. Метод new() делает всю грязную работу по грамматическому разбору параметров скрипта скрипта и переменных окружения и сохраняет свои результаты в новом объекте. Теперь вы будете делать вызовы методов, используя этот объект, чтобы добираться до параметров, генерировать элементы формы и делать другие полезные вещи.
Альтернативная форма метода new() позволяет вам читать параметры скрипта из ранее открытого указателя файла:
$query = new CGI(FILEHANDLE)
Указатель файла может содержать URL-закодированную строку запроса или может быть рядом разделенных символами новой строки пар ЯРЛЫК=ЗНАЧЕНИЕ. Это совместимо с методом save(). Это позволяет вам сохранить состояние скрипта CGI в файл и перезагрузить его позднее. Также возможно сохранять содержимое нескольких объектов запросов в один и тот же файл, как внутри одиночного скрипта так и на период времени. Вы можете затем перезагрузить множество записей в массив объектов запросов чем-то вроде следующего:
open (IN,"test.in") || die;
while (!eof(IN)) {
my $q = new CGI(IN);
push(@queries,$q);
}
Вы можете делать простые базы данных таким образом или создать гостевую книгу. Если вы - пурист Perl, вы можете передавать ссылку на glob указателя файла вместо имени указателя файла. Это "официальный" способ передавать указатели файлов в Perl 5:
my $q = new CGI(\*IN);
(Если вы не знаете, о чем я говорю, тогда вы - не пурист Perl, и вам не нужно беспокоиться об этом.)
Если вы используете функционально-ориентированный интерфейс и вы хотите инициировать состояние CGI из указателя файла, способ сделать это - использование restore_parameters(). Он будет (пере)инициировать объект CGI по умолчанию из обозначенного указателя файла.
open (IN,"test.in") || die; restore_parameters(IN); close IN;
Вы можете инициировать объект CGI из ссылки на ассоциативный массив. Значения могут быть как одно- так и многозначными:
$query = new CGI({'динозавр'=>'барни','песня'=>'Я люблю тебя',
'друзья'=>[qw/Джессика Джордж Нэнси/]});
Вы можете инициировать объект CGI, передавая строку запроса в стиле URL в метод new(), как здесь:
$query = new CGI('динозавр=барни&цвет=фиолетовый');
Или вы можете клонировать объект CGI из существующего. Список параметров клона будет идентичным, но другие поля, такие как autoescaping - нет:
$old_query = new CGI; $new_query = new CGI($old_query);
Эта форма также позволяет вам создавать объект CGI, который изначально пуст:
$empty_query = new CGI('');
Смотрите продвинутые приемы за большей информацией.
Вызов списка ключевых слов из запроса
@keywords = $query->keywords
Если скрипт был вызван, как результат поиска <ISINDEX>, синтаксически разобранные ключевые слова могут быть получены методом keywords(). Этот метод вернет ключевые слова, как массив Perl.
Вызов имен всех параметров, переданных в ваш скрипт
@names = $query->param
Если скрипт был вызван со списком параметров (например, "имя1=значение1&имя2=значение2&имя3=значение3"), метод param() вернет имена параметров, как список. Для обратной совместимости этот метод будет работать, даже если скрипт был вызван, как скрипт <ISINDEX>: в этом случае будет возвращен одиночный параметр, названный 'keywords'.
Вызов значения(ий) именованного параметра
@values = $query->param('фу');
-или-
$value = $query->param('фу');
Передайте методу param() один аргумент, чтобы вызвать значение именованного параметра. Если параметр многозначен (например, из множества выбора в списке с возможностью прокрутки), вы можете запросить на получение массива. Иначе метод вернет одно значение.
Как и для версии 1.50 этой библиотеки, возвращаемый массив имен параметров будет в том же порядке, в котором браузер послал их. Хотя это и не гарантирует идентичность порядку, в котором параметры были определены в заполняемой форме, обычно это так.
Установка значения(ий) именованного параметра
$query->param('фу','один','массив','значений');
-или-
$query->param(-name=>'фу',-values=>['один','массив','значений']);
Это устанавливает значение для именованного параметра 'фу' в одно или более значений. Эти значения будут использоваться для инициации элементов формы, если вы так пожелаете. Заметьте, что это единственный способ насильственно изменить значение поля формы после его предыдущей установки.
Второй пример показывает альтернативный стиль вызова функции "с именованными параметрами", который принят многими методами CGI. Смотрите вызов функций CGI, которые принимают множество аргументов для объяснения этого стиля.
Присоединение параметра
$query->append(-name=>'фу',-values=>['еще','больше','значений']);
Это добавляет значение или список значений к именованному параметру. Значения присоединяются к концу параметра, если он уже существует. Иначе параметр создается.
Удаление именованного параметра совсем
$query->delete('фу');
Это удаляет именованный параметр совсем. Это полезно, когда вы хотите переустановить значение параметра, так чтобы он не передавался дальше между вызовами скрипта.
Удаление всех параметров
$query->delete_all();
Это удаляет все параметры и оставляет вас с пустым объектом CGI. Это может быть полезно, чтобы восстановить все установки по умолчанию, произведенные методами, генерирующими элементы формы.
Импортирование параметров в пространство имен
$query->import_names('R');
print "Ваше имя - $R::name\n"
print "Ваши любимые цвета: @R::colors\n";
Это импортирует все параметры в заданное пространство имен. Например, если были параметры, названные 'foo1', 'foo2' и 'foo3', после исполнения $query->import_names('R'), переменные @R::foo1, $R::foo1, @R::foo2, $R::foo2, и тому подобные удобно появятся среди существующих. Так как CGI не имеет пути узнать, ожидаете ли вы много- или однозначный параметр, он создает две переменных для каждого параметра. Одна, массив, содержит все значения, а другая - скаляр, содержащий первый член массива. Используйте ту, которая уместна. Для списков ключевых слов (a+b+c+d), будет создана переменная @R::keywords.
Если вы не указываете пространство имен, этот метод предполагает пространство имен "Q".
Необязательный второй аргумент import_names, если он присутствует и ненулевой, удалит содержимое пространства имен перед загрузкой в него. Это может быть полезно для окружений, таких как mod_perl, из которых скрипт не выходит после обработки запроса.
Предупреждение: не импортируйте в пространство имен 'main'. Это представляет крупный риск безопасности, так как злые люди могут тогда использовать эту особенность для переопределения центральных переменных, таких как @INC. CGI.pm выйдет с ошибкой, если вы попытаетесь сделать это.
Прямой доступ к списку параметров
$q->param_fetch('адрес')->[1] = 'переулок Пересмешника, 1313';
unshift @{$q->param_fetch(-name=>'адрес')},'Джордж Манстер';
Если you need access to the parameter list in a way that isn't covered by the methods above, вы можете obtain a direct reference to it by calling the param_fetch() method with the name of the parameter you want. This will return an array reference to the named parameters, which you then can manipulate in any way you like.
Вы можете call param_fetch() with the name of the CGI parameter, or with the -name argument, which has the same meaning as elsewhere.
Fetching the Parameter List as a Hash
$params = $q->Vars;
print $params->{'адрес'};
@foo = split("\0",$params->{'фу'});
%params = $q->Vars;
use CGI ':cgi-lib';
$params = Vars;
Many people want to fetch the entire parameter list as a hash in which the keys are the names of the CGI parameters, and the values are the parameters' values. The Vars() method does this. Called in a scalar context, it возвращает the parameter list as a tied hash reference. Changing a key changes the value of the parameter in the underlying CGI parameter list. Called in an array context, it возвращает the parameter list as an ordinary hash. This allows you to read the contents of the parameter list, but not to change it.
When using this, the thing you must watch out for are multivalued CGI parameters. Because a hash cannot distinguish between scalar and array context, multivalued parameters will be returned as a packed string, separated by the "\0" (null) character. You must split this packed string чтобы get at the individual values. This is the convention introduced long ago by Steve Brenner in his cgi-lib.pl module for Perl version 4.
Если вы желаете использовать Vars(), как функцию, импортируйте набор вызовов функций :cgi-lib (смотрите также раздел про совместимость с CGI-LIB).
Возвращение ошибок CGI
Ошибки can occur while processing user input, particularly when processing uploaded files. When these errors occur, CGI will stop processing and return an empty parameter list. Вы можете test for the existence and nature of errors using the cgi_error() function. The error messages are formatted as HTTP status codes. Вы можете either incorporate the error text into an HTML page, or use it as the value of the HTTP status:
my $error = $q->cgi_error;
if ($error) {
print $q->header(-status=>$error),
$q->start_html('Проблемы'),
$q->h2('Запрос не обработан'),
$q->strong($error);
exit 0;
}
Когда вы используете функционально-ориентированный интерфейс (смотрите следующий раздел), ошибки могут встречаться только, когда вы в первый раз вызываете param(). Будьте готовы к этому!
Сохранение текущего состояния формы
Сохранение состояния в файл
$query->save(FILEHANDLE)
This writes the current query out to the file handle of your choice. The file handle must already be open and be writable, but other than that it can point to a file, a socket, a pipe, or whatever. The contents of the form are written out as TAG=VALUE pairs, which can be reloaded with the new() method at some later time. Вы можете write out multiple queries to the same file and later read them into query objects one by one.
Если вы желаете использовать этот метод method from the function-oriented (non-OO) interface, the exported name for this method is save_parameters(). Смотрите продвинутые приемы за большей информацией.
Сохранение состояния in a Self-Referencing URL
$my_url=$query->self_url
Этот вызов возвращает a URL that, when selected, reinvokes this script with all its state information intact. Это может быть полезно, когда вы хотите to jump around within a script-generated document using internal anchors, but don't want to disrupt the current contents of the form(s). Смотрите продвинутые приемы для примера.
If you'd like to get the URL without the entire query string appended to it, use the url() method:
$my_self=$query->url
Получение URL скрипта
$full_url = $query->url(); $full_url = $query->url(-full=>1); #альтернативный синтаксис $relative_url = $query->url(-relative=>1); $absolute_url = $query->url(-absolute=>1); $url_with_path = $query->url(-path_info=>1); $url_with_path_and_query = $query->url(-path_info=>1,-query=>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 предусмотрен как синоним.
Смешивание параметров POST и URL
$color = $query->url_param('цвет');
It is possible for a script to receive CGI parameters in the URL as well as in the fill-out form by creating a form that POSTs to a URL containing a query string (a "?" mark followed by arguments). Метод param() всегда будет будет возвращать содержимое POST заполняемой формы, игнорируя строку запроса URL. Чтобы вернуть параметры URL, вызывайте метод url_param(). Используйте его тем же способом, что и param(). Главное отличие в том, что он позволяет вам читать параметры, но не установливать их.
Under no circumstances will the contents of the URL query string interfere with similarly-named CGI parameters in POSTed forms. Если вы попытаетесь смешать строку запроса URL с a form submitted методом GET, результаты не будут теми, которые вы ожидаете.
Вызов функций CGI, которые принимают множество аргументов
In versions of CGI.pm prior to 2.0, it could get difficult to remember the proper order of arguments in CGI function calls that accepted five or six different arguments. As of 2.0, there's a better way to pass arguments to the various CGI functions. In this style, you pass a series of name=>argument pairs, like this:
$field = $query->radio_group(-name=>'OS',
-values=>[Unix,Windows,Macintosh],
-default=>'Unix');
The advantages of this style are that you don't have to remember the exact order of the arguments, and if you leave out a parameter, it will usually default to some reasonable value. If you provide a parameter that the method doesn't recognize, it will usually do something useful with it, such as incorporating it into the HTML tag as an attribute. Например if Netscape decides next week to add a new JUSTIFICATION parameter to the text field tags, вы можете start using the feature without waiting for a new version of CGI.pm:
$field = $query->textfield(-name=>'State',
-default=>'gaseous',
-justification=>'RIGHT');
This will result in an HTML tag that looks like this:
<INPUT type="text" name="State" value="gaseous" justification="RIGHT">
Parameter names are case insensitive: вы можете использовать -name, or -Name or -NAME. You don't have to use the hyphen if you don't want to. After creating a CGI object, call the use_named_parameters() method with a nonzero value. This will tell CGI.pm that you intend to use named parameters exclusively:
$query = new CGI;
$query->use_named_parameters(1);
$field = $query->radio_group('name'=>'OS',
'values'=>['Unix','Windows','Macintosh'],
'default'=>'Unix');
Actually, CGI.pm only looks for a hyphen in the first parameter. So вы можете leave it off subsequent parameters if you like. Something to be wary of is the potential that a string constant like "values" will collide with a keyword (and in fact it does!) While Perl usually figures out when you're referring to a function and when you're referring to a string, you probably should put quotation marks around all string constants just to play it safe.
Параметры HTML/HTTP, которые содержат внутренние дефисы, такие как -Content-language могут быть passed by putting quotes around them, or by using an underscore for the second hyphen, например -Content_language.
The fact that you must use curly {} braces around the attributes passed to functions that create simple HTML tags but don't use them around the arguments passed to all other functions has many people, including myself, confused. As of 2.37b7, the syntax is extended to allow you to use curly braces for all function calls:
$field = $query->radio_group({-name=>'OS',
-values=>[Unix,Windows,Macintosh],
-default=>'Unix'});
Создание заголовка HTTP
Создание стандартного заголовка для виртуального документа
print $query->header('image/gif');
Это распечатывает необходимый HTTP Content-type: заголовок и строку бланка реквизита под ним. Если не определен параметр, он по умолчанию 'text/html'.
Расширенная форма этого метода позволяет вам определять код состояния и сообщение, передаваемые назад в браузер:
print $query->header(-type=>'image/gif',
-status=>'204 No Response');
Это предоставляет браузеру код состояния 204 (Нет ответа). Подобающе ведущие себя браузеры не предпринимают никаких действий, просто остаются на текущей странице. (Это предназначено для скрипта, который делает некоторую обработку, но не нуждается в представлении каких-либо результатов, или для скрипта, вызванного, когда пользователь щелкнул на пустой части активной карты изображения (clickable image map).)
Распознаются несколько других именованных параметров. Здесь искусственный пример, который использует их все:
print $query->header(-type=>'image/gif',
-status=>'402 Payment Required',
-expires=>'+3d',
-cookie=>$my_cookie,
-Cost=>'$0.02');
-expires
Некоторые браузеры, такие как Internet Explorer, кэшируют выходную информацию скриптов CGI. Другие, такие как Netscape Navigator, - нет. Это ведет к раздражению и несовместимому поведению, когда переходишь от одного браузера к другому. Вы можете заставить поведение быть совместимым, используя параметр -expires. Когда вы определяете абсолютный или относительный интервал истечения этим параметром, браузеры и прокси-серверы будут кэшировать выходную информацию скрипта до указанного срока истечения. Все следующие формы действительны для поля -expires:
+30s 30 секунд с настоящего момента +10m десять минут с настоящего момента +1h один час с настоящего момента -1d вчера (т.е. "ASAP!") now немедленно +3M через три месяца +10y через срок в десять лет Thu, 25-Apr-1999 00:40:33 GMT в указанное время и дату
Когда вы используете -expires, скрипт также генерирует корректный штамп времени для сгенерированного документа, чтобы убедиться в том, что ваши часы и часы браузера согласованы. Это позволяет вам создавать документы, которые надежно кэшируются на короткие периоды времени.
CGI::expires() - статический вызов функции, используемой для внутренних нужд, которая обращает относительные временные интервалы в даты HTTP. Вы можете вызывать ее непосредственно, если желаете.
-cookie
Параметр -cookie генерирует заголовок, который говорит браузерам Netscape возвращать "magic cookie" в течение всех последующих транзакций с вашим скриптом. HTTP cookies имеют специальный формат, который включает интересные атрибуты, такие как срок истечения. Используйте метод cookie(), чтобы создавать и возвращать cookies сессии. Значение этого параметра может быть или скалярным значением или ссылкой на массив. Вы можете использовать последний, чтобы генерировать множество cookies. (Вы можете использовать псевдоним -cookies для читабельности.)
-nph
Параметр -nph, если он установлен в ненулевое значение, будет генерировать заголовок действительный заголовок для использования в скриптах с заголовками, не подлежащими грамматическому разбору. Например:
print $query->header(-nph=>1,
-status=>'200 OK',
-type=>'text/html');
Вам понадобится использовать это, если:
- Вы используете Microsoft Internet Information Server.
- Вам нужно создать небуферизированный вывод, например, для использования в скрипте "server push".
- Вам нужно воспользоваться расширениями HTTP, не поддерживаемыми вашим сервером.
Смотрите использование скриптов NPH за большей информацией.
Другие поля заголовка
Некоторые другие параметры, которые вы передаете в header(), обращаются в корректно отформатированные поля заголовка HTTP, даже если они не вызываются для текущей спецификации HTTP. Например, образец, который появился несколькими абзацами выше, создает поле, которое похоже на следующее:
Cost: $0.02
Вы можете использовать его, чтобы воспользоваться новыми полями заголовка HTTP, не дожидаясь следующего выпуска CGI.pm.
Создание заголовка для запроса переадресации
print $query->redirect('http://somewhere.else/in/the/world');
Это генерирует запрос переадресации для удаленного браузера. Он немедленно перейдет на указанный URL. Вам следует выйти вскоре после этого. Больше ничего не будет демонстрироваться.
Вы можете добавить ваши собственные заголовки к этому, как и в методе header().
Вам следует всегда использовать абсолютные или полные URL в запросах переадресации. Относительные URL не будут работать корректно.
Альтернативный синтаксис для redirect() таков:
print $query->redirect(-location=>'http://somewhere.else/',
-nph=>1);
Параметр -location дает URL места назначения. Вы можете также использовать -uri или -url, если предпочитаете.
Параметр -nph, если он ненулевой, говорит CGI.pm, что этот скрипт запущен, как скрипт с заголовком, не подлежащим грамматическому разбору. Смотрите использование скриптов NPH за большей информацией.
Параметр -method говорит браузеру, какой метод использовать для переадресации. Это удобно, если, например, ваш скрипт был вызван из операции POST заполняемой формы, а вы хотите переадресовать браузер на статическую страницу, которая требует GET.
Все другие параметры, распознаваемые методом header(), также справедливы в redirect.
Ярлыки HTML
Создание заголовка HTML
Стиль с именованными параметрами
print $query->start_html(-title=>'Секреты пирамид',
-author=>'fred@capricorn.org',
-base=>'true',
-meta=>{'keywords'=>'фараон секрет мумия',
'copyright'=>'авторские права 1996 King Tut'},
-style=>{'src'=>'/styles/style1.css'},
-dtd=>1,
-BGCOLOR=>'blue');
print $query->start_html('Секреты пирамид','fred@capricorn.org','true');
Это вернет закрытый заголовок HTML и открывающий тег <BODY>. Все параметры необязательные:
- Название документа (-title)
- Адрес электронной почты автора создаст тег <LINK REV="MADE">, если присутствует (-author)
- Флаг истинности, если вы хотите включить тег <BASE> в заголовок (-base). Он поможет разрешить относительные адреса с абсолютными, когда документ перемещен, но сделает иерархию документов непортативной. Используйте с осторожностью!
- Параметр -xbase, если вы хотите включить тег <BASE>, который указывает некоторое внешнее расположение. Пример:
print $query->start_html(-title=>'Секреты пирамид', -xbase=>'http://www.nile.eg/pyramid.html'); - Параметр -target, если вы хотите иметь все ссылки и заполняемые формы на странице при переходе к другому кадру (frame). Пример:
print $query->start_html(-title=>'Секреты пирамид', -target=>'answer_frame');-target может быть использован или с -xbase или с -base.
- Параметр -meta используется, чтобы определить один или более тегов <META>. Передавайте этому параметру ссылку на ассоциативный массив, содержащий пары ключ/значение. Каждая пара становится тегом <META> в формате похожем на этот.
<META name="keywords" content="фараон секрет мумия"> <META name="description" content="авторские права 1996 King Tut">
Поддержки типа HTTP-EQUIV для тега <META> нет. Это потому что вы можете изменять заголовок HTTP непосредственно методом header. Пример:
print $q->header(-Refresh=>'10; URL=http://www.capricorn.com');
- Параметр -dtd используется, чтобы заставить start_html() генерировать для данного документа определение типа документа SGML. Оно используется редакторами SGML и издательскими системами Web класса high-end, чтобы определить тип документа. Однако, оно нарушает работу некоторых браузеров, в частности AOL. Значение этого параметра может быть одним из следующих:
- действительный DTD (смотрите http://ugweb.cs.ualberta.ca/~gerald/validate/lib/catalog для списка). Пример:
-dtd=>'-//W3C//DTD HTML 3.2//EN'
- значение истинности, которое не начинается с "-//", в этом случае вы получите стандартный DTD по умолчанию (справедливо для HTML 2.0).
Вы можете изменить DTD по умолчанию, вызвав default_dtd() с предпочитаемым значением.
- действительный DTD (смотрите http://ugweb.cs.ualberta.ca/~gerald/validate/lib/catalog для списка). Пример:
- Параметр -style используется, чтобы определить каскадную таблицу стилей. Больше информации по этому вопросу может быть найдено в ограниченной поддержке каскадных таблиц стилей
- Параметр -head используется, чтобы определить произвольные элементы радела <HEAD>. Например:
print header(-head=>Link({-rel=>'next', -href=>'http://www.capricorn.com/s2.html'}));или даже
print header(-head=>[Link({-rel=>'next', -href=>'http://www.capricorn.com/s2.html'}), Link({-rel=>'previous', -href=>'http://www.capricorn.com/s1.html'})]); - Параметр -script используется, чтобы определить функции Netscape JavaScript, чтобы включить их в страницу HTML. Это предпочтительный способ, чтобы библиотеку функций JavaScript, которые будут вызываться откуда-нибудь изнутри страницы. CGI.pm будет пытаться форматировать код JavaScript тем же способом, каким браузеры не-Netscape не хотят пытаться демонстрировать код JavaScript. К сожалению некоторые браузеры тем не менее путаются. Вот пример того, как создать библиотеку JavaScript и включить ее внутрь кода заголовка HTML:
$query = new CGI; print $query->header; $JSCRIPT=<<END; // Задать глупый вопрос function riddle_me_this() { var r = prompt("Кто ходит на четырех ногах утром, " + "на двух ногах днем, и на трех ногах вечером?"); response(r); } // Получить глупый ответ function response(answer) { if(answer == "человек") alert("Вы правы!"); else alert("Неверно! Угадывайте заново."); } END print $query->start_html(-title=>'Загадка Сфинкса', -script=>$JSCRIPT);Netscape 3.0 и выше позволяет вам помещать код JavaScript во внешний документ и ссылаться на него по URL. Это позволяет вам хранить код JavaScript в файле или скрипте CGI , чтобы не загромождать каждую страницу исходным кодом. Netscape 3.X-4.X и Internet Explorer 3.X-4.X также распознают параметр "language", который позволяет вам использовать другие языки, такие как VBScript и PerlScript (ну да!) Чтобы использовать эти атрибуты передайте в параметр -script ссылку на хеш, содержащий один или более ключей language, src или code. Вот, как сослаться на URL внешнего скрипта:
print $q->start_html(-title=>'Загадка Сфинкса', -script=>{-language=>'JavaScript', -src=>'/javascript/sphinx.js'});Вот как сослаться на код скрипта, включенного непосредственно в страницу:
print $q->start_html(-title=>'Загадка Сфинкса', -script=>{-language=>'PerlScript', -code->'print "Привет, мир!\n;"');Последняя особенность позволяет вам включать множество разделов <SCRIPT> в заголовок. Просто передайте список разделов скриптов, как ссылку на массив. Это позволяет вам определять различные исходные файлы для разных диалектов JavaScript. Пример:
print $q->start_html(-title=>'Загадка Сфинкса', -script=>[{-language=>'JavaScript1.0', -src=>/javascript/utilities10.js'}, {-language=>'JavaScript1.1', -src=>'/javascript/utilities11.js'}, {-language=>'JavaScript1.2', -src=>'/javascript/utilities12.js'}, {-language =>'JavaScript28.2', -src=>'/javascript/utilities219.js'}]);(Если это выглядит чуть-чуть экстравагантно, воспользуйтесь моим советом и не отделывайтесь от чистого написания скриптов CGI.)
- Параметр -noScript используется, чтобы передавать некоторый HTML, который будет демонстрироваться в браузерах, которые не имеют JavaScript (или имеют отключенный JavaScript).
- Параметры -onLoad и -onUnload используются, чтобы зарегистрировать обработчики событий JavaScript, которые нужно исполнить, когда страница, сгенерированная скриптом, открыта и закрыта соответственно. Пример:
print $query->start_html(-title=>'Загадка Сфинкса', -script=>$JSCRIPT, -onLoad=>'riddle_me_this()');Смотрите JavaScripting за большими подробностями.
- Любые дополнительные атрибуты, которые вы хотите включить в тег <BODY> (сколько вам нравится). Это хороший способ включать другие расширения Netscape, такие как цвет фона и образец обоев. (Пример выше устанавливает фон страницы в трепетно синий.) Вы можете использовать эту особенность, чтобы воспользоваться новыми особенностями HTML, не дожидаясь выпуска CGI.pm.
Окончание документа HTML
print $query->end_html
Это оканчивает документ HTML печатью тегов </BODY> </HTML>.
Другие теги HTML
CGI.pm provides shortcut methods for many other HTML tags. All HTML 2 tags and the Netscape extensions are supported, as well as the HTML 3 tags that are in common usage (including tables). Unpaired tags, paired tags, and tags that contain attributes are all supported using a simple syntax.
To see the list of HTML tags that are supported, open up the CGI.pm file and look at the functions defined in the %EXPORT_TAGS array.
Непарные теги
Unpaired tags include <P>, <HR> and <BR>. The syntax for creating them is:
print $query->hr;
This prints out the text "<hr>".
Парные теги
Paired tags include <EM>, <I> and the like. The syntax for creating them is:
print $query->em("What a silly art exhibit!");
This prints out the text "<em>What a silly art exhibit!</em>".
Вы можете pass as many text arguments as you like: they'll be concatenated together with spaces. This allows you to create nested tags easily:
print $query->h3("The",$query->em("silly"),"art exhibit");
This создает the text:
<h3>The <em>silly</em> art exhibit</h3>
When used in conjunction with the import facility, the HTML shortcuts can make CGI scripts easier to read. Например:
use CGI qw/:standard/;
print h1("Road Guide"),
ol(
li(a({href=>"start.html"},"The beginning")),
li(a({href=>"middle.html"},"The middle")),
li(a({href=>"end.html"},"The end"))
);
Most HTML tags are represented as lowercase function calls. There are a few exceptions:
- The <tr> tag used to start a new table row conflicts with the Perl translate function
tr(). Use TR() or Tr() instead. - The <param> tag used to pass parameters to an applet conflicts with CGI's own
param()method. Use PARAM() instead. - The <select> tag used to create selection lists conflicts with Perl's select() function. Use
Select()instead. - The <sub> tag used to create subscripts conflicts wit Perl's operator for creating subroutines. Use
Sub()instead.
Теги с атрибутами
To add attributes to an HTML tag, simply pass a reference to an associative array as the first argument. The keys and values of the associative array become the names and values of the attributes. Например, here's how to generate an <A> anchor link:
use CGI qw/:standard/;
print a({-href=>"bad_art.html"},"Jump to the silly exhibit");
<A HREF="bad_art.html">Jump to the silly exhibit</A>
You may dispense with the dashes in front of the attribute names if you prefer:
print img {src=>'fred.gif',align=>'LEFT'};
<IMG ALIGN="LEFT" SRC="fred.gif">
Sometimes an HTML tag attribute has no argument. Например, ordered lists can be marked as COMPACT, or you желаете to specify that a table has a border with <TABLE BORDER>. The syntax for this is an argument that that points to an undef string:
print ol({compact=>undef},li('one'),li('two'),li('three'));
Prior to CGI.pm version 2.41, providing an empty ('') string as an attribute argument was the same as providing undef. Однако, this has changed чтобы accomodate those who want to create tags of the form <IMG ALT="">. The difference is shown in this table:
| CODE | RESULT |
|---|---|
| img({alt=>undef}) | <IMG ALT> |
| img({alt=>''}) | <IMT ALT=""> |
Distributive HTML Tags and Tables
All HTML tags are distributive. If you give them an argument consisting of a reference to a list, the tag will be distributed across each element of the list. Например, here's one way to make an ordered list:
print ul(li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy']););
This example will result in HTML output that looks like this:
<UL>
<LI TYPE="disc">Sneezy</LI>
<LI TYPE="disc">Doc</LI>
<LI TYPE="disc">Sleepy</LI>
<LI TYPE="disc">Happy</LI>
</UL>
Вы можете take advantage of this to create HTML tables easily and naturally. Here is some code and the HTML it outputs:
use CGI qw/:standard :html3 -no_debug/;
print table({-border=>undef},
caption(strong('When Should You Eat Your Vegetables?')),
Tr({-align=>CENTER,-valign=>TOP},
[
th(['','Breakfast','Lunch','Dinner']),
th('Tomatoes').td(['no','yes','yes']),
th('Broccoli').td(['no','no','yes']),
th('Onions').td(['yes','yes','yes'])
]
)
);
| Breakfast | Lunch | Dinner | |
|---|---|---|---|
| Tomatoes | no | yes | yes |
| Broccoli | no | no | yes |
| Onions | yes | yes | yes |
Notice the use of -no_debug in a program that we intend to call from the command line.
If you want to produce tables programatically, вы можете do it this way:
use CGI qw/:standard :html3 -no_debug/;
@values = (1..5);
@headings = ('N','N'.sup('2'),'N'.sup('3'));
@rows = th(\@headings);
foreach $n (@values) { push(@rows,td([$n,$n**2,$n**3])) }
print table({-border=>undef,-width=>'25%'},
caption(b('Wow. I can multiply!')),
Tr(\@rows)
);
| N | N2 | N3 |
|---|---|---|
| 1 | 1 | 1 |
| 2 | 4 | 8 |
| 3 | 9 | 27 |
| 4 | 16 | 64 |
| 5 | 25 | 125 |
Создание форм
Общее замечание 1. Все различные методы создания форм возвращают строки вызывающему. Эти строки будут содержать код HTML, который создаст запрашиваемый элемент формы. Вы несете ответственность собственно за распечатку этих строк. Она осуществляется таким образом, что вы можете помещать форматирующие теги вокруг элементов формы.
Общее замечание 2. Значения по умолчанию, которые вы определяете для форм используются только при первом вызове скрипта. Если значения уже присутствуют в строке запроса, то используются они, даже если они пусты.
Если вы хотите изменить значение поля из его предыдущего значения, вы имеете два выбора:
- вызвать метод param(), чтобы установить его.
- использовать параметр -override (псевдоним -force). (Это новая особенность в 2.15) Это заставит использовать значение по умолчанию, не считаясь с предыдущим значением поля:
print $query->textfield(-name=>'любимый_цвет', -default=>'красный',-override=>1);
Если вы хотите переустановить все поля в их значения по умолчанию, вы можете:
- Создать специальную кнопку defaults, используя метод defaults().
- Создать гипертекстовую ссылку, которая вызывает ваш скрипт без каких-либо параметров.
Общее замечание 3. Вы можете помещать множество форм на одну и ту же страницу, если желаете. Однако, учтите, что не всегда просто сохранять инфомацию о состоянии для более чем одной формы за раз. Смотрите продвинутые приемы за некоторыми советами.
Общее замечание 4. По популярному требованию, текст и метки, которые вы предусматриваете для элементов форм are escaped согласно правилам HTML. Это означает, что вы можете безопасно использовать "<НАЖМИ МЕНЯ>" как метку для кнопки. Однако, это поведение может вмешаться в вашу способность включать специальные последовательности символов HTML, такие как Á (Á), в ваши поля. Если вы желаете выключить автоматический escaping, вызывайте метод autoEscape() со значением false непосредственно после создания объекта CGI:
$query = new CGI; $query->autoEscape(undef);
Вы можете обратно включить autoescaping в любое время вызовом $query->autoEscape('да')
Элементы формы
Создание тега ISINDEX
print $query->isindex($action);
isindex() без каких-либо аргументов возвращает тег <ISINDEX>, который обозначает ваш скрипт, как URL для вызова. Если вы хотите, чтобы браузер вызвал другой URL для управления поиском, передайте isindex() URL, который вы хотите чтоб был вызван.
Starting And Ending A Form
print $query->startform($method,$action,$encoding); ...различный материал формы... print $query->endform;
startform() вернет тег <FORM> с необязательными методом, действием и form encoding, которые вы определяете. endform() возвращает тег </FORM>.
The form encoding supports the "file upload" feature of Netscape 2.0 (и выше) и Internet Explorer 4.0 (и выше). The form encoding tells the browser, как to package up the contents of the form чтобы transmit it across the Internet. Существует два типа of encoding, that вы можете определить:
application/x-www-form-urlencoded
This is the type of encoding used by all browsers prior to Netscape 2.0. It is compatible with many CGI scripts and is suitable for short fields containing text data. For your convenience, CGI.pm stores the name of this encoding type in
$CGI::URL_ENCODED.multipart/form-data
This is the newer type of encoding introduced by Netscape 2.0. It is suitable for forms that contain very large fields or that are intended for transferring binary data. Most importantly, it enables the "file upload" feature of Netscape 2.0 forms. For your convenience, CGI.pm stores the name of this encoding type in
CGI::MULTIPART()Формы, которые используют этот тип of encoding, are not easily interpreted by CGI scripts unless they use CGI.pm or another library that knows how to handle them. Unless you are using the file upload feature, there's no particular reason to use this type of encoding.
For compatability, the startform() method uses the older form of encoding by default. If you want to use the newer form of encoding By default, вы можете call start_multipart_form() instead of startform().
Если вы планируете использовать особенности JavaScript, вы можете обеспечить startform() необязательными параметрами -name и/или -onSubmit. -name has no effect on the display of the form, but can be used to give the form an identifier so that it can be manipulated by JavaScript functions. Provide the -onSubmit parameter in order, чтобы зарегистрировать некоторый код JavaScript code to be performed just before the form is submitted. This is useful for checking the validity of a form before submitting it. Your JavaScript code should return a value of "true" to let Netscape know that it can go ahead and submit the form, and "false" to abort the submission.
Starting a Form, которая использует особенность "выгрузки файла"
print $query->start_multipart_form($method,$action,$encoding); ...различный материал формы... print $query->endform;
This has exactly the same usage as startform(), but it specifies form encoding type multipart/form-data as the default.
Создание текстового поля
Стиль с именованными параметрами
print $query->textfield(-name=>'имя_поля',
-default=>'начальное значение',
-size=>50,-maxlength=>80);
Старый стиль
print $query->textfield('фу','начальное значение',50,80);
textfield() вернет поле ввода текста.
- Первый параметр (-name) - необходимое имя для поля.
- Необязательный второй параметр (-default) - начальное значение для содержимого поля.
- Необязательный третий параметр (-size) - размер поля в символах.
- Необязательный четвертый параметр (-maxlength) - максимальное число символов, которое поле вместит.
As with all these methods, the field will be initialized with its previous contents from earlier invocations of the script. Если вы хотите to force in the new value, overriding the existing one, смотрите Общее замечание 2.
Когда форма обработана, значение текстового поля может быть возвращено вызовом:
$value = $query->param('фу');
JavaScripting: Вы можете also provide -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut and -onSelect parameters to register JavaScript event handlers.
Создание большого текстового поля
Стиль с именованными параметрами
print $query->textarea(-name=>'фу',-default=>'начальное значение',
-rows=>10,-columns=>50);
Старый стиль
print $query->textarea('фу','начальное значение',10,50);
textarea() is just like textfield(), but it allows you to specify rows and columns for a multiline text entry box. Вы можете provide a начальное значение for the field, which can be long and contain multiple lines.
JavaScripting: Like textfield(), вы можете provide -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut and -onSelect parameters to register JavaScript event handlers.
Создание поля пароля
Стиль с именованными параметрами
print $query->password_field(-name=>'секрет',-value=>'начальное значение',
-size=>50,-maxlength=>80);
Старый стиль
print $query->password_field('секрет','начальное значение',50,80);
password_field() идентично textfield(), за исключением того, что его содержимое будет представляться звездочками на странице Web.
Создание поля выгрузки файла
Стиль с именованными параметрами
print $query->filefield(-name=>'выгруженный_файл',-default=>'начальное значение',
-size=>50,-maxlength=>80);
Старый стиль
print $query->filefield('выгруженный_файл','начальное значение',50,80);
filefield() вернет поле формы, которое побудит пользователя выгрузить файл.
- Первый параметр (-name) - обязательное имя для поля.
- Необязательный второй параметр (-default) - начальное значение для имени файла. Это поле в настоящее время игнорируется всеми браузерами, но всегда есть надежда!
- Необязательный третий параметр (-size) - размер поля в символах.
- Необязательный четвертый параметр (-maxlength) - максимальное число символов, которое поле вместит.
filefield() вернет поле выгрузки файла для использования в современных браузерах. Браузер побудит удаленного пользователя выбрать файл для передачи через Интернет на сервер. Другие браузеры в настоящее время игнорируют это поле.
Чтобы полностью воспользоваться легкостью выгрузки файла, вы должны использовать новую многодольную схему кодирования формы. Вы можете сделать это или вызовом startform() и определением типа кодирования $CGI::MULTIPART, или использованием нового метода start_multipart_form(). Если вы не используете многодольное кодирование, тогда вы сможете вернуть имя файла, выбранного пользователем, но вы не сможете получить доступ к его содержимому.
Когда форма обработана, вы можете вернуть введенное имя файла, вызвав param().
$filename = $query->param('выгруженный_файл');
где "выгруженный_файл" - то, как вы назвали поле выгрузки файла. В зависимости от версии браузера имя файла, которое возвращено может быть полным локальным путем файла на машине удаленного пользователя, или только голым именем файла. Если путь предусмотрен, он следует обычаям путей локальной машины.
Возвращенное имя файла - также указатель файла. Вы можете читать содержимое файла, используя стандартные для Perl вызовы чтения файла:
# Прочитать текстовый файл и распечатать его
while (<$filename>) { print }
# Скопировать двоичный файл куда-нибудь в безопасное место
open (OUTFILE,">>/usr/local/web/users/feedback");
while ($bytesread=read($filename,$buffer,1024)) { print OUTFILE $buffer }
close $filename;
There are problems with the dual nature of the upload fields. If you use strict, then Perl will complain when you try to use a string as a filehandle. Вы можете get around this by placing the file reading code in a block containing the no strict pragma. More seriously, it is possible for the remote user to type garbage into the upload field, in which case what you get from param() is not a filehandle at all, but a string.
To be safe, use the upload() function (new in version 2.47). When called with the name of an upload field, upload() возвращает a filehandle, or undef if the parameter is not a valid filehandle.
$fh = $query->upload('выгруженный_файл');
while (<$fh>) { print; }
This is the recommended idiom.
Вы можете have several file upload fields in the same form, and even give them the same name if you like (in the latter case param() will return a list of file names). Однако, if the user attempts to upload several files with exactly the same name, CGI.pm will only return the last of them. This is a known bug.
When processing an uploaded file, CGI.pm создает a temporary file on your hard disk and passes you a file handle to that file. After you are finished with the file handle, CGI.pm unlinks (deletes) the temporary file. If you need to вы можете access the temporary file directly. Its name is stored inside the CGI object's "private" data, and вы можете access it by passing the file name to the tmpFileName() method:
$filename = $query->param('выгруженный_файл');
$tmpfilename = $query->tmpFileName($filename);
The temporary file will be deleted automatically when your program exits unless you manually rename it. On some operating systems (such as Windows NT), you will need to close the temporary file's filehandle before your program exits. Otherwise the attempt to delete the temporary file will fail.
A potential problem with the temporary file upload feature is that the temporary file is accessible to any local user on the system. In previous versions of this module, the temporary file was world readable, meaning that anyone could peak at what was being uploaded. As of version 2.36, the modes on the temp file have been changed to read/write by owner only. Only the Web server and its CGI scripts can access the temp file. Unfortunately this means that one CGI script can spy on another! To make the temporary files really private, set the CGI global variable $CGI::PRIVATE_TEMPFILES to 1. Alternatively, call the built-in function CGI::private_tempfiles(1), or just use CGI qw/-private_tempfiles. The temp file will now be unlinked as soon as it is created, making it inaccessible to other users. The downside of this is that you will be unable to access this temporary file directly (tmpFileName() will continue to return a string, but you will find no file at that location.) Further, since PRIVATE_TEMPFILES is a global variable, its setting will affect all instances of CGI.pm if you are running mod_perl. Вы можете work around this limitation by declaring $CGI::PRIVATE_TEMPFILES as a local at the top of your script.
On Windows NT, it is impossible to make a temporary file private. This is because Windows doesn't allow you to delete a file before closing it.
Usually the browser sends along some header information along with the text of the file itself. Currently the headers contain only the original file name and the MIME content type (if known). Future browsers might send other information as well (such as modification date and size). Чтобы вернуть эту информацию, вызовите uploadInfo(). Он возвращает ссылку на ассоциативный массив, содержащий все заголовки документов. Например, этот фрагмент кода возвращает тип MIME выгруженного файла (be careful to use the proper capitalization for "Content-Type"!):
$filename = $query->param('выгруженный_файл');
$type = $query->uploadInfo($filename)->{'Content-Type'};
unless ($type eq 'text/html') { die "ТОЛЬКО ФАЙЛЫ HTML!" }
JavaScripting: Like textfield(), filefield() accepts -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut and -onSelect parameters to register JavaScript event handlers. Предостережения и потенциальные проблемы в особенности для выгрузки файлов.
Создание A Popup Menu
Стиль с именованными параметрами
print $query->popup_menu(-name=>'имя_меню',-values=>[qw/eenie meenie minie/],
-labels=>{'eenie'=>'один','meenie'=>'два','minie'=>'три'},
-default=>'meenie');
print $query->popup_menu(-name=>'имя_меню',
-values=>['eenie','meenie','minie'],
-default=>'meenie');
Старый стиль
print $query->popup_menu('имя_меню',['eenie','meenie','minie'],'meenie',
{'eenie'=>'один','meenie'=>'два','minie'=>'три'});
popup_menu() создает меню.
- Обязательный первый аргумент (-name) - это имя меню.
- Обязательный второй аргумент (-values) is an array reference containing the list of menu items in the menu. Вы можете pass the method an anonymous array, as shown in the example, or a reference to a named array, such as \@foo. If you pass a HASH reference, the keys will be used for the menu values, and the values will be used for the menu labels (смотрите -labels below).
- Необязательный третий параметр (-default) is the name of the default menu choice. If not specified, the first item will be the default. The value of the previous choice will be maintained across queries.
- Необязательный четвертый параметр (-labels) allows you to pass a reference to an associative array containing user-visible labels for one or more of the menu items. Вы можете использовать this when you want the user to see one menu string, but have the browser return your program a different one. If you don't specify this, the value string will be used instead ("eenie","meenie" and "minie" in this example). This is equivalent to using a hash reference for the -values parameter.
Когда форма обработана, выбранное значение of the popup menu может быть возвращено, используя:
$popup_menu_value = $query->param('имя_меню');
JavaScripting: Вы можете provide -onChange, -onFocus, -onMouseOver, -onMouseOut, and -onBlur parameters to register JavaScript event handlers.
Создание списка с возможностью прокрутки
Стиль с именованными параметрами
print $query->scrolling_list(-name=>'имя_списка',
-values=>['eenie','meenie','minie','moe'],
-default=>['eenie','moe'],
-size=>5,
-multiple=>'true',
-labels=>\%labels);
Старый стиль
print $query->scrolling_list('имя_списка',
['eenie','meenie','minie','moe'],
['eenie','moe'],5,'true',
\%labels);
scrolling_list() создает список с возможностью прокрутки.
- Первый и второй аргументы (-name, -values)are the list name and values, respectively. As in the popup menu, the second argument should be an array reference or hash reference. In the latter case, the values of the hash are used as the human-readable labels in the list.
- Необязательный третий аргумент (-default)can be either a reference to a list containing the values to be selected by default, or can be a single value to select. If this argument is missing or undefined, then nothing is selected when the list first appears.
- Необязательный четвертый аргумент (-size) is the display size of the list.
- Необязательный пятый аргумент (-multiple) can be set to true to allow multiple simultaneous selections.
- The option sixth шестой аргумент (-labels) can be used to assign user-visible labels to the list items different from the ones used for the values as above. This is equivalent to passing a hash reference to -values. In this example we assume that an associative array
%labelshas already been created.
When this form is processed, all selected list items will be returned as a list under the parameter name 'list_name'. Значения выбранных элементов могут быть возвращены вызовом:
@selected = $query->param('имя_списка');
JavaScripting: Вы можете provide -onChange, -onFocus, -onMouseOver, -onMouseOut and -onBlur parameters to register JavaScript event handlers.
Создание группы связанных выключателей
Стиль с именованными параметрами
print $query->checkbox_group(-name=>'имя_группы',
-values=>['eenie','meenie','minie','moe'],
-default=>['eenie','moe'],
-linebreak=>'true',
-labels=>\%labels);
Старый стиль
print $query->checkbox_group('имя_группы',
['eenie','meenie','minie','moe'],
['eenie','moe'],'true',\%labels);
Только для браузеров HTML 3
print $query->checkbox_group(-name=>'имя_группы',
-values=>['eenie','meenie','minie','moe'],
-rows=>2,-columns=>2);
checkbox_group() создает список выключателей, которые связаны одним и тем же именем.
- Первый и второй аргументы (-name, -values) - имя выключателя и значения, соответственно. As in the popup menu, the second argument should be an array reference or a hash reference. These values are used for the user-readable labels printed next to the checkboxes as well as for the values passed to your script in the query string.
- Необязательный третий аргумент (-default) can be either a reference to a list containing the values to be checked by default, or can be a single value to checked. If this argument is missing or undefined, then nothing is selected when the list first appears.
- Необязательный четвертый аргумент (-linebreak) can be set to true to place line breaks between the checkboxes so that they appear as a vertical list. Otherwise, they will be strung together on a horizontal line. When the form is procesed, all checked boxes will be returned as a list under the parameter name 'имя_группы'. Значения выключателей "on" могут быть возвращены вызовом:
- Необязательный пятый аргумент (-labels) is a reference to an hash of checkbox labels. This allows you to use different strings for the user-visible button labels and the values sent to your script. In this example we assume that an associative array
%labelshas previously been created. This is equivalent to passing a hash reference to -values. - Необязательный параметр -nolabels can be used to suppress the printing of labels next to the button. This is useful if you want to capture the button elements individually and use them inside labeled HTML 3 tables.
- Browsers that understand HTML 3 tables (such as Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters cause checkbox_group() to return an HTML 3 compatible table containing the checkbox group formatted with the specified number of rows and columns. Вы можете provide just the -columns parameter, если вы желаете; checkbox_group will calculate the correct number of rows for you.
Чтобы включить row and column headings в возращаемую таблицу, вы можете использовать параметры -rowheaders и -colheaders. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpetation of the checkboxes -- they're still a single named unit.
When viewed with browsers that don't understand HTML 3 tables, the -rows and -columns parameters will leave you with a group of buttons that may be awkwardly formatted but still useable. Однако, if you add row and/or column headings, the resulting text will be very hard to read.
Когда форма обработана, список of checked buttons в группе может быть возвращен like this:
@turned_on = $query->param('имя_группы');
Эта функция actually возвращает массив of button elements. Вы можете capture the array and do interesting things with it, such as incorporating it into your own tables or lists. The -nolabels option is also useful in this regard:
@h = $query->checkbox_group(-name=>'выбор',
-value=>['fee','fie','foe'],
-nolabels=>1);
create_nice_table(@h);
JavaScripting: Вы можете provide an параметр -onClick, чтобы зарегистрировать некоторый код JavaScript to be performed every time the user clicks on any of the buttons in the group.
Создание одиночного выключателя
Список именованных параметров
print $query->checkbox(-name=>'имя_выключателя',
-checked=>'checked',
-value=>'ВКЛЮЧЕН',
-label=>'Включи меня');
Старый стиль
print $query->checkbox('имя_выключателя',1,'ВКЛЮЧЕН','Включи меня');
checkbox() используется, чтобы создать изолированный выключатель, который логически не связан с какими-либо другими.
- Первый параметр (-name - необходимое имя для выключателя. Он будет также использоваться для the user-readable label printed next to the checkbox.
- Необязательный второй параметр (-checked specifies that the checkbox is turned on by default. Псевдонимы для этого параметра -selected и -on.
- Необязательный третий параметр (-value specifies the value of the checkbox when it is checked. If not provided, the word "on" is assumed.
- Необязательный четвертый параметр (-label assigns a user-visible label to the button. If not provided, будет использоваться имя выключателя.
Значение выключателя может быть возвращено, используя:
$turned_on = $query->param('имя_выключателя');
JavaScripting: Вы можете provide an параметр -onClick, чтобы зарегистрировать некоторый код JavaScript to be performed every time the user clicks on the button.
Создание группы переключателей
Стиль с именованными параметрами
print $query->radio_group(-name=>'имя_группы',
-values=>['eenie','meenie','minie'],
-default=>'meenie',
-linebreak=>'true',
-labels=>\%labels);
Старый стиль
print $query->radio_group('имя_группы',
['eenie','meenie','minie'],'meenie',
'true',\%labels);
Только для браузеров совместимых с HTML 3
print $query->radio_group(-name=>'имя_группы',
-values=>['eenie','meenie','minie','moe'],
-rows=>2,-columns=>2);
radio_group() создает набор логически связанных переключателей. Turning one member of the group on turns the others off.
- Первый аргумент (-name - имя группы, и оно необходимо.
- Второй аргумент (-values is the list of values for the radio buttons. The values and the labels that appear on the page are identical. Pass an array reference in the second argument, either using an anonymous array, as shown, or by referencing a named array as in
\@foo. You may also use a hash reference чтобы produce human-readable labels that are different from the values that will be returned as parameters to the CGI script. - Необязательный третий параметр (-default is the value of the default button to turn on. If not specified, the first item will be the default. Specify some nonexistent value, such as "-" if you don't want any button to be turned on.
- Необязательный четвертый параметр (-linebreak can be set to 'true' to put line breaks between the buttons, creating a vertical list.
- Необязательный пятый параметр (-labels specifies an associative array containing labels to be printed next to each button. If not provided the button value will be used instead. This example assumes that the associative array
%labelshas already been defined. This is equivalent to passing a hash reference to -values. - Необязательный параметр -nolabels can be used to suppress the printing of labels next to the button. This is useful if you want to capture the button elements individually and use them inside labeled HTML 3 tables.
- Браузеры, которые понимают таблицы HTML 3 (такие как Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters cause radio_group() to return an HTML 3 compatible table containing the radio cluster formatted with the specified number of rows and columns. Вы можете provide just the -columns parameter, если вы желаете; radio_group will calculate the correct number of rows for you.
Чтобы включить row and column headings в возвращаемую таблицу, вы можете использовать параметры -rowheader и -colheader. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpetation of the radio buttons -- they're still a single named unit.
When viewed with browsers that don't understand HTML 3 tables, the -rows and -columns parameters will leave you with a group of buttons that may be awkwardly formatted but still useable. Однако, if you add row and/or column headings, the resulting text will be very hard to read.
Когда форма обработана, выбранный переключатель может быть возвращен, используя:
$which_radio_button = $query->param('имя_группы');
Эта функция actually возвращает массив of button elements. Вы можете capture the array and do interesting things with it, such as incorporating it into your own tables or lists The -nolabels option is useful in this regard.:
@h = $query->radio_group(-name=>'выбор',
-value=>['fee','fie','foe'],
-nolabels=>1);
create_nice_table(@h);
JavaScripting: Вы можете provide an параметр -onClick, чтобы зарегистрировать некоторый код JavaScript to be performed every time the user clicks on any of the buttons in the group.
Создание A Submit Button
Стиль с именованными параметрами
print $query->submit(-name=>'имя_кнопки',
-value=>'значение');
Старый стиль
print $query->submit('имя_кнопки','значение');
submit() создаст the query submission button. Каждая форма should have one of these.
- Первый аргумент (-name необязателен. Вы можете give the button a name, если вы имеете несколько submission buttons в своей форме и вы хотите to distinguish between them.
- Второй аргумент (-value также необязателен. This gives the button a value that will be passed to your script in the query string, and will also appear as the user-visible label.
Вы можете figure out which of several buttons was pressed by using different values for each one:
$which_one = $query->param('имя_кнопки'); - Вы можете использовать -label, как псевдоним для -value. Я always get confused about which of
-nameи-valuechanges the user-visible label на кнопке.
JavaScripting: Вы можете provide an параметр -onClick, чтобы зарегистрировать некоторый код JavaScript to be performed every time the user clicks on the button. Вы не можете prevent a form from being submitted, однако. Вы должны provide an -onSubmit handler to the form itself to do that.
Создание A Reset Button
print $query->reset
reset() создает the "reset" button. It undoes whatever changes the user has recently made to the form, but does not necessarily reset the form all the way to the defaults. Смотрите defaults() for that. It takes the optional label for the button ("Reset" by default). JavaScripting: Вы можете provide an -onClick parameter, чтобы зарегистрировать некоторый код JavaScript code to be performed every time the user clicks on the button.
Создание A Defaults Button
print $query->defaults('button_label')
defaults() создает "reset to defaults" button. It takes the optional label for the button ("Defaults" by default). When the user presses this button, the form will automagically be cleared entirely and set to the defaults you specify in your script, just as it was the first time it was called.
Создание A Hidden Field
Стиль с именованными параметрами
print $query->hidden(-name=>'hidden_name',
-default=>['значение1','значение2'...]);
Старый стиль
print $query->hidden('hidden_name','значение1','значение2'...);
hidden() produces a text field that can't be seen by the user. It is useful for passing state variable information from one invocation of the script to the next.
- Первый аргумент (-name) is required and specifies the name of this field.
- Второй и последующие аргументы specify the value for the hidden field. This is a quick and dirty way of passing Perl arrays through forms. If you use the стиль с именованными параметрами, you must provide the parameter -default and an array reference here.
Hidden fields used to behave differently from all other fields: the provided default values always overrode the "sticky" values. This was the behavior people seemed to expect, однако it turns out to make it harder to write state-maintaining forms such as shopping cart programs. Therefore I have made the behavior consistent with other fields.
Just like all the other form elements, the value of a hidden field is "sticky". If you want to replace a hidden field with some other values after the script has been called once you'll have to do it manually before writing out the form element:
$query->param('hidden_name','new','values','here');
print $query->hidden('hidden_name');
Fetch the value of a hidden field this way:
$hidden_value = $query->param('hidden_name');
-or (for values created with arrays)-
@hidden_values = $query->param('hidden_name');
Создание a Clickable Image Button
Стиль с именованными параметрами
print $query->image_button(-name=>'имя_кнопки',
-src=>'/images/NYNY.gif',
-align=>'MIDDLE');
Старый стиль
print $query->image_button('имя_кнопки','/source/URL','MIDDLE');
image_button() produces an inline image that acts as a submission button. When selected, the form is submitted and the clicked (x,y) coordinates are submitted as well.
- Первый аргумент(-name is required and specifies the name of this field.
- Второй аргумент (-srcspecifies the URL of the image to display. It must be one of the types supported by inline images (например, GIF), but can be any local or remote URL.
- Третий аргумент (-alignis anything you might want to use in the ALIGN attribute, such as TOP, BOTTOM, LEFT, RIGHT or MIDDLE. This field is optional.
When the image is clicked, the results are passed to your script in two parameters named "button_name.x" and "button_name.y", where "button_name" is the name of the image button.
$x = $query->param('button_name.x');
$y = $query->param('button_name.y');
JavaScripting: Текущие версии JavaScript do not honor the -onClick handler, unlike other buttons.
Создание a JavaScript Button
Стиль с именованными параметрами
print $query->button(-name=>'кнопка1',
-value=>'Нажми меня',
-onClick=>'doButton(this)');
Старый стиль
print $query->image_button('кнопка1','Нажми меня','doButton(this)');
button() создает кнопку JavaScript. Когда the button is pressed, the JavaScript code pointed to by the -onClick parameter is executed. Это работает только с Netscape 2.0 и выше. Другие браузеры не распознают JavaScript и, вероятно, не смогут даже показать кнопку.
- Первый аргумент(-name is required and specifies the name of this field.
- Второй аргумент (-value gives the button a value, and will be used as the user-visible label on the button.
- Третий аргумент (-onClick is any valid JavaScript code. It's usually a call to a JavaScript function defined somewhere else (see the start_html() method), but can be any JavaScript you like. Multiple lines are allowed, but you must be careful not to include any double quotes in the JavaScript text.
Смотрите JavaScripting за большей информацией.
Controlling HTML Autoescaping
По умолчанию, если вы используете специальный символ HTML, такой как >, < или & как метку или значение кнопки, it will be escaped using the appropriate HTML escape sequence (например, >). This lets you use anything at all for the text of a form field without worrying about breaking the HTML document. Однако, it may also interfere with your ability to use special characters, such as Á as default contents of fields. Вы можете turn this feature on and off with the method autoEscape().
Используйте
$query->autoEscape(undef);
to turn automatic HTML escaping off, and
$query->autoEscape('true');
to turn it back on.
Импортирование методов CGI
A large number of scripts allocate only a single query object, use it to read parameters or to create a fill-out form, and then discard it. For this type of script, it may be handy to import CGI module methods into your name space. The most common syntax for this is:
use CGI qw(:standard);
This imports the standard methods into your namespace. Now instead of getting parameters like this:
use CGI;
$dinner = $query->param('entree');
Вы можете do it like this:
use CGI qw(:standard);
$dinner = param('entree');
Similarly, instead of creating a form like this:
print $query->start_form, "Check here if you're happy: ", $query->checkbox(-name=>'happy',-value=>'Y',-checked=>1), "<P>", $query->submit, $query->end_form;
Вы можете create it like this:
print start_form, "Check here if you're happy: ", checkbox(-name=>'happy',-value=>'Y',-checked=>1), p, submit, end_form;
Even though there's no CGI object in view in the second example, state is maintained using an implicit CGI object that's created automatically. The form elements created this way are sticky, just as before. If you need to get at the implicit CGI object directly, вы можете refer to it as:
$CGI::Q;
The use CGI statement используется, чтобы импортировать имена методов в текущее пространство имен. There is a slight overhead for each name you import, but ordinarily is nothing to worry about. Вы можете import selected method names like this:
use CGI qw(header start_html end_html);
Ordinarily, однако, you'll want to import groups of methods using export tags. Export tags refer to sets of logically related methods which are imported as a group with use. Tags are distinguished from ordinary methods by beginning with a ":" character. Этот пример импортирует методы dealing with the CGI protocol (param() and the like) as well as shortcuts that generate HTML 2-compliant tags:
use CGI qw(:cgi :html2);
Currently существует 8 семейств методов, определенных в CGI.pm. They are:
:cgi
These are all the tags that support one feature or another of the CGI protocol, including param(), path_info(), cookie(), request_method(), header() and the like.
:form
These are all the form element-generating methods, including start_form(), textfield(), etc.
:html2
These are HTML 2-defined shortcuts such as br(), p() and head(). It also includes such things as start_html() and end_html() that aren't exactly HTML 2, but are close enough.
:html3
These содержит различные теги HTML 3 для таблиц, кадров, super- and subscripts, апплетов и других объектов.
:netscape
These are Netscape extensions not included in the HTML 3 category including blink() и center().
:html
These are all the HTML generating shortcuts, comprising the union of html2, html3, и netscape.
:multipart
These are various functions that simplify creating documents of the various multipart MIME types, and are useful for implementing server push.
:standard
This is the union of html2, form, and :cgi (everything except the HTML 3 and Netscape extensions).
:all
This импортирует все общедоступные методы в ваше пространство имен!
Pragmas
В дополнение к importing individual methods and method families, use CGI recognizes several pragmas, all proceeded by dashes.
-any
Когда вы используете use CGI -any, then any method that the query object doesn't recognize will be interpreted as a new HTML tag. This allows you to support the next ad hoc Netscape or Microsoft HTML extension. Например, to support Netscape's latest tag, <GRADIENT> (which causes the user's desktop to be flooded with a rotating gradient fill until his machine reboots), вы можете использовать something like this:
use CGI qw(-any); $q=new CGI; print $q->gradient({speed=>'fast',start=>'red',end=>'blue'});Since using any causes any mistyped method name to be interpreted as an HTML tag, use it with care or not at all.
-compile
This causes the indicated autoloaded methods to be compiled up front, rather than deferred to later. Это полезно для скриптов, которые run for an extended period of time under FastCGI or mod_perl, and for those destined to be crunched by Malcom Beattie's Perl compiler. Используйте ее совместно с методами или семействами методов, которые вы планируете использовать.
use CGI qw(-compile :standard :html3);
или даже
use CGI qw(-compile :all);
Заметьте, что использование прагмы -compile таким способом будет всегда have the effect of importing the compiled functions into the current namespace. Если вы хотите компилировать без импортирования, используйте метод compile() вместо этого.
-autoload
Overrides the autoloader so that any function in your program that is not recognized is referred to CGI.pm for possible evaluation. This allows you to use all the CGI.pm functions without adding them to your symbol table, which is of concern for mod_perl users who are worried about memory consumption. Warning: when -autoload is in effect, вы не можете использовать "poetry mode" functions without the parenthesis). Use hr() rather than hr, or add something like use subs qw/hr p header/ to the top of your script.
-nph
This makes CGI.pm produce a header appropriate for an NPH (no parsed header) script. You may need to do other things as well to tell the server that the script is NPH. Смотрите обсуждение скриптов NPH ниже.
-newstyle_urls
Separate the name=value pairs in CGI parameter query strings with semicolons rather than ampersands. Например:
?name=fred;age=24;favorite_color=3
Semicolon-delimited query strings are always accepted, but will not be emitted by self_url() and query_string() unless the -newstyle_urls pragma is specified.
-no_debug
This turns off the command-line processing features. If you want to run a CGI.pm script from the command line to produce HTML, and you don't want it pausing to request CGI parameters from standard input, then use this pragma:
use CGI qw(-no_debug :standard);
Смотрите отслеживание (debugging) за большими подробностями.
-private_tempfiles
CGI.pm can process uploaded file. Ordinarily it spools the uploaded file to a temporary directory, then deletes the file when done. Однако, this opens the risk of eavesdropping as described in the file upload section. Another CGI script author could peek at this data during the upload, even if it is confidential information. On Unix systems, the -private_tempfiles pragma will cause the temporary file to be unlinked as soon as it is opened and before any data is written into it, eliminating the risk of eavesdropping.
Special Forms for Importing HTML-Tag Functions
Many of the methods generate HTML tags. As described below, tag functions automatically generate both the opening and closing tags. Например:
print h1('Level 1 Header');
produces
<H1>Level 1 Header</H1>
There will be some times when you want to produce the start and end tags yourself. In this case, вы можете использовать the form start_Itag_name and end_Itag_name, as in:
print start_h1,'Level 1 Header',end_h1;
With a few exceptions (described below), start_tag_name and end_Itag_name functions are not generated automatically when you use CGI. Однако, вы можете specify the tags you want to generate start/end functions for by putting an asterisk in front of their name, or, alternatively, requesting either "start_tag_name" or "end_tag_name" in the import list.
Пример:
use CGI qw/:standard *table start_ul/;
In this example, the following functions are generated в дополнение к the standard ones:
start_table()(generates a <TABLE> tag)end_table()(generates a </TABLE> tag)start_ul()(generates a <UL> tag)end_ul()(generates a </UL> tag)
PRETTY-PRINTING HTML
По умолчанию, all the HTML produced этими функциями comes out as one long line без возвратов карретки или indentation. This is yuck, but it does reduce the size of the documents by 10-20%. To get pretty-printed output, please use CGI::Pretty, a subclass contributed by Brian Paulsen.
Optional Utility Functions
В дополнение к the standard imported functions, there are a few optional functions that you must request by name if you want them. They were originally intended for internal use only, but are now made available by popular request.
escape(), unescape()
use CGI qw/escape unescape/;
$q = escape('This $string contains ~wonderful~ characters');
$u = unescape($q);
These functions escape and unescape strings according to the URL hex escape rules. Например, the space character will be converted into the string "%20".
escapeHTML(), unescapeHTML()
use CGI qw/escapeHTML unescapeHTML/;
$q = escapeHTML('This string is <illegal> html!');
$u = unescapeHTML($q);
These functions escape and unescape strings according to the HTML character entity rules. Например, the character < will be escaped as <.
Ordinarily CGI.pm autoloads most of its functions on an as-needed basis. This speeds up the loading time by deferring the compilation phase. Однако, если you are using mod_perl, FastCGI or another system that uses a persistent интерпретатор Perl, you will want to precompile the methods at initialization time. To accomplish this, call the package function compile() like this:
use CGI ();
CGI->compile(':all');
The arguments to compile() are a list of method names or sets, and are identical to those accepted by the use operator.
Отслеживание (debugging)
Если вы are running the script from the command line or in the Perl debugger, вы можете pass the script a list of keywords or parameter=value pairs on the command line or from standard input (you don't have to worry about tricking your script into reading from environment variables). Вы можете pass keywords like this:
my_script.pl keyword1 keyword2 keyword3
or this:
my_script.pl keyword1+keyword2+keyword3
or this:
my_script.pl name1=value1 name2=value2
or this:
my_script.pl name1=value1&name2=value2
или даже by sending newline-delimited parameters to standard input:
% my_script.pl first_name=fred last_name=flintstone occupation='granite miner' ^D
When debugging, вы можете использовать quotation marks and the backslash character to escape spaces and other funny characters in exactly the way you would in the shell (which isn't surprising since CGI.pm uses "shellwords.pl" internally). This lets you do this sort of thing:
my_script.pl 'name 1=I am a long value' name\ 2=two\ words
If you run a script that uses CGI.pm from the command line and fail to provide it with any arguments, it will print out the line
(offline mode: enter name=value pairs on standard input)
then appear to hang. In fact, the library is waiting for you to give it some parameters to process on its standard input. If you want to give it some parameters, enter them as shown above, then indicate that you're finished with input by pressing ^D (^Z on NT/DOS systems). If you don't want to give CGI.pm parameters, just press ^D.
Вы можете suppress this behavior in any of the following ways:
1. Call the script with an empty parameter.
Пример:
my_script.pl ''
2. Redirect standard input from /dev/null or an empty file.
Пример:
my_script.pl </dev/null
3. Include "-no_debug" in the list of symbols to import on the "use" line.
Пример:
use CGI qw/:standard -no_debug/;
Dumping Out All The Name/Value Pairs
Метод dump() produces a string consisting of all the query's name/value pairs formatted nicely as a nested list. This is useful for debugging purposes:
print $query->dump
Produces something that looks like this:
<UL>
<LI>name1
<UL>
<LI>value1
<LI>value2
</UL>
<LI>name2
<UL>
<LI>value1
</UL>
</UL>
Вы можете достичь того же эффекта включением объекта CGI прямо в стоку, как в:
print "<H2>Current Contents:</H2>\n$query\n";
Переменные сессии HTTP
Некоторые из более полезных переменных окружения могут быть fetched through this interface. The methods are as follows:
Accept()
Возвращает список типов MIME, которые удаленный браузер принимает. Если вы дадите этому методу один аргумент corresponding to a MIME type, as in
$query->Accept('text/html'), он вернет a floating point value corresponding to the browser's preference for this type from 0.0 (don't want) to 1.0. Glob types (например, text/*) in the browser's accept list are handled correctly. Заметьте the capitalization of the initial letter. This avoids conflict with the Perl built-in accept().auth_type()
Возвращает the authorization type, if protection is active. Пример "Basic".
Возвращает the "magic cookie" maintained by Netscape 1.1 и выше в сыром состоянии. Вы вероятно захотите использовать cookie() instead, which gives you a high-level interface to the cookie functions. Called with no parameters, raw_cookie() возвращает the entire cookie structure, which may consist of several cookies appended together (вы можете recover individual cookies by splitting on the "; " sequence. Called with the name of a cookie, возвращает the unescaped value of the cookie as set by the server. This may be useful for retrieving cookies that your script did not set.
Возвращает дополнительную информацию о пути из URL скрипта. Например, fetching
/cgi-bin/your_script/additional/stuffwill result in$query->path_info()returning"/additional/stuff". В дополнение к reading the path information, вы можете set it by giving path_info() an optional string argument. The argument is expected to begin with a "/". Если not present, one will be added for you. The new path information will be returned by subsequent calls to path_info(), and will be incorporated into the URL generated by self_url().path_translated()
As per path_info() но возвращает дополнительную информацию о пути translated into a physical path, например,
"/usr/local/etc/httpd/htdocs/additional/stuff". Вы не можете change the path_translated, nor will setting the additional path information change this value. The reason for this restriction is that the translation of path information into a physical path is ordinarily done by the server in a layer that is inaccessible to CGI scripts.query_string()
Возращает строку запроса, годную для состояния поддержки.
referer()
Возвращает URL страницы, которую браузер просматривал до fetching your script. Not available для всех браузеров.
remote_addr()
Возвращает адрес IP удаленного хоста, разделенный точками.
remote_ident()
Возвращает the identity-checking information from the remote host. Only available, если удаленный хост has the identd daemon turned on.
remote_host()
Возращает или имя удаленного хоста или адрес IP, если первый не имеется в наличии.
remote_user()
Возвращает имя given by the remote user during password authorization.
request_method()
Возвращает метод HTTP, использованный to request your script's URL, обычно один из
GET, POSTилиHEAD.script_name()
Возвращает имя скрипта, как частичный URL, для self-refering скриптов.
server_name()
Возвращает имя сервера WWW, под которым запускается скрипт.
server_software()
Возвращает имя и версию программного обеспечения сервера.
virtual_host()
Когда using the virtual host feature of some servers, возвращает the name of the virtual host the browser is accessing.
server_port()
Возвращает коммуникационный порт, который сервер использует.
user_agent()
Возвращает идентификатор программного обеспечения браузера удаленного хоста, например, "Mozilla/1.1N (Macintosh; I; 68K)"
user_name()
Пытается получить имя удаленного пользователя, используя множество переменных окружения. Это работает только со старыми браузера такими как Mosaic. Netscape does not reliably report имя пользователя!
http()
Called with no arguments возвращает список переменных окружения HTTP, включая такие вещи как HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the like-named HTTP header fields in the request. Called with the name of an HTTP header field, возвращает его значение. Capitalization and the use of hyphens versus underscores are not significant.
Например, все три из этих примеров эквивалентны:
$requested_language = $q->http('Accept-language'); $requested_language = $q->http('Accept_language'); $requested_language = $q->http('HTTP_ACCEPT_LANGUAGE');https()
The same as http(), но operates on the HTTPS environment variables present when the SSL protocol is in effect. Может использоваться, чтобы определить, включен ли SSL.
HTTP Cookies
Браузеры Netscape версии 1.1 и выше и все версии Internet Explorer поддерживают так называемые "cookie", разработанные чтобы поддерживать состояние внутри сессии браузера. CGI.pm имеет несколько методов, которые поддерживают cookie.
Cookie - это пары имя=значение, сильно похожие на именованные параметры в строке запроса CGI. Скрипты CGI создают одно или более cookie и посылают их браузеру в заголовке HTTP. Браузер поддерживает список cookie, которые принадлежат определенному серверу Web, и возвращает их в скрипт CGI во время последующего взаимодействия.
В дополнение к обязательной паре имя=значение, каждое cookie имеет несколько необязательных атрибутов:
срок истечения
Это строка времени/даты (в специальном формате GMT), которая указывает, когда cookie истекает. Cookie будет сохраняться и возвращаться в ваш скрипт до того времени, когда эта дата истечения будет достигнута, если пользователь выходит из браузера и перезапускает его. Если дата истечения не определена, cookie будет оставаться активным до того времени, когда пользователь покинет браузер.
Отрицательные сроки истечения (например, "-1d") велят некоторым браузерам удалить cookie из его постоянного хранилища. Это плохо документированная особенность.
домен
Это частичное или полное имя домена, для которого cookie действительно. Браузер будет возвращать cookie любому хосту, который совпадает с частичным именем домена. Например, если вы определяете имя домена ".capricorn.com", тогда браузер вернет cookie серверам Web running на любой из машин "www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com" и т.п. Имя домена должно содержать по крайней мере два периода, чтобы препятствовать попыткам совпадений с доменами верхнего уровня вроде ".edu". Если не определен никакой домен, тогда браузер будет возвращать cookie только серверам на хосте, откуда создано cookie.
путь
Если вы provide a атрибут пути cookie, браузер will check it against your script's URL before returning the cookie. Например, если вы определяете путь "/cgi-bin", тогда cookie будет возвращено в каждый из скриптов "/cgi-bin/tally.pl", "/cgi-bin/order.pl", и "/cgi-bin/customer_service/complain.pl", но не в скрипт "/cgi-private/site_admin.pl". По умолчанию путь установлен в "/", который велит cookie быть посланным любому скрипту CGI на вашем сайте.
флаг "безопасный"
Если атрибут "безопасный" установлен, cookie будет послан вашему скрипту, только если запрос CGI происходит на безопасном канале, таком как SSL.
Интерфейс к HTTP cookie - метод cookie():
$cookie = $query->cookie(-name=>'sessionID',
-value=>'xyzzy',
-expires=>'+1h',
-path=>'/cgi-bin/database',
-domain=>'.capricorn.org',
-secure=>1);
print $query->header(-cookie=>$cookie);
cookie() создает новое cookie. Его параметры включают:
-name
Имя cookie (необходимо). Это может быть вообще любая строка. Хотя Netscape ограничивает свои имена cookie безпробельными альфачисловыми символами, CGI.pm убирает это ограничение при помощи escaping и unescaping cookie за кулисами.
-value
Значение cookie. Это может быть любое скалярное значение, ссылка на массив или даже ссылка на ассоциативный массив. Например, вы можете сохранить целый ассоциативный массив в cookie таким образом:
$cookie=$query->cookie(-name=>'семейная информация', -value=>\%childrens_ages);-path
Необязательный частичный путь, для которого это cookie будет действительно, как описано выше.
-domain
Необязательный частичный домен, для которого это cookie будет действительно, как описано выше.
-expires
Необязательная дата истечения для этого cookie. Формат описан в разделе по методу header():
"+1h" один час с настоящего момента
-secure
Если установлен в true, это cookie будет использоваться только внутри безопасной сессии SSL.
Cookie, созданное методом cookie() должно быть включено в заголовок HTTP в строке, возвращаемой методом header():
print $query->header(-cookie=>$my_cookie);
Чтобы создать множество cookie, дайте методу header() ссылку на массив:
$cookie1 = $query->cookie(-name=>'название_загадки',
-value=>"Вопрос Сфинкса");
$cookie2 = $query->cookie(-name=>'ответы',
-value=>\%answers);
print $query->header(-cookie=>[$cookie1,$cookie2]);
Чтобы вернуть cookie, запросите его по имени вызовом метода cookie() без параметра -value:
use CGI;
$query = new CGI;
%answers = $query->cookie('ответы');
# $query->cookie(-name=>'ответы') тоже работает!
Чтобы вернуть имена всех cookie, переданных вашему скрипту, вызовите cookie() без каких-либо параметров. Это позволит вам повторять через все cookie:
foreach $name ($query->cookie()) { print $query->cookie($name) }
Пространства имен cookie и CGI - отдельные. Если вы имеете параметр, названный 'ответы', и cookie, названное 'ответы', значения, возвращенные методами param() и cookie() независимы друг от друга. Однако, можно просто превратить параметр CGI в cookie, и наоборот:
# превращение параметра CGI в cookie
$c=$q->cookie(-name=>'ответы',-value=>[$q->param('ответы')]);
# наоборот
$q->param(-name=>'ответы',-value=>[$q->cookie('ответы')]);
Смотрите пример скрипта cookie.cgi за некоторыми идеями того, как эффективно использовать cookie.
ЗАМЕЧАНИЕ: Существуют некоторые ограничения на cookie. Вот, что утверждает RFC2109, раздел 6.3:
Practical user agent implementations have limits on the number and size
of cookies that they can store. In general, user agents' cookie support
should have no fixed limits. They should strive to store as many
frequently-used cookies as possible. Furthermore, general-use user
agents should provide each of the following minimum capabilities
individually, although not necessarily simultaneously:
* at least 300 cookies
* at least 4096 bytes per cookie (as measured by the size of the
characters that comprise the cookie non-terminal in the syntax
description of the Set-Cookie header)
* at least 20 cookies per unique host or domain name
User agents created for specific purposes or for limited-capacity
devices should provide at least 20 cookies of 4096 bytes, to ensure
that the user can interact with a session-based origin server.
The information in a Set-Cookie response header must be retained in its
entirety. If for some reason there is inadequate space to store the
cookie, it must be discarded, not truncated.
Applications should use as few and as small cookies as possible, and
they should cope gracefully with the loss of a cookie.
К сожалению, некоторые браузеры appear to have limits that are more restrictive than those given in the RFC. If you need to store a lot of information, it's probably better to create a unique session ID, store it in a cookie, and use the session ID to locate an external file/database saved on the server's side of the connection.
Поддержка кадров (frame)
CGI.pm содержит поддержку кадров HTML, особенности Netscape 2.0 и выше и Internet Explorer 3.0 и выше. Кадры поддерживаются двумя путями:
- Вы можете направить выходную информацию скрипта в новое окно или в заранее существующий именованный кадр, предоставив имя кадра как аргумент
-targetв методе заголовка. Например, следующий код создаст новое окно и демонстрирует выходную информацию скрипта:$query = new CGI; print $query->header(-target=>'_blank');
- Вы можете предоставить имя нового или заранее существующего кадра в методах startform() и start_multipart_form(), используя параметр
-target. Когда форма отправлена, выходная информация будет перенаправлена в указанный кадр:print $query->start_form(-target=>'результирующий_кадр');
Эффективное использование кадров может быть сложным. Создание подходящего набора кадров, в котором запрос и отклик демонстрируются рядом, потребует от вас разделить скрипт на три функциональных раздела. Первый раздел должен создать объявление <frameset> и выйти. Второй раздел ответственен за создание формы запроса и направление его в один кадр. Третий раздел ответственен за создание отклика и направление его в другой кадр.
Каталог примеров содержит скрипт, называющийся popup.cgi, который демонстрирует простое всплывающее окно. frameset.cgi представляет каркас ный скрипт для создания смежных наборов кадров запрос/результат.
Поддержка JavaScript
Версии Netscape 2.0 и выше содержат интерпретируемый язык, называемый JavaScript. Internet Explorer 3.0 и выше поддерживает тесно связанный диалект, называемый JScript. JavaScript - это не то же самое, что Java, и конечно совсем не то, что Perl, - большая жалость. JavaScript допускает вас к программному изменению содержимого заполняемых форм, созданию новых окон и всплывающих диалоговых окон изнутри самого Netscape. С точки зрения CGI-скриптинга, JavaScript вполне полезен для подтверждения заполняемых форм до их отправки.
Вам нужно знать JavaScript, чтобы использовать его. Руководство по Netscape JavaScript содержит хороший учебник и справочник по языку программирования JavaScript.
Обычный способ использования JavaScript - определить набор функций в блоке <SCRIPT> внутри заголовка HTML, а потом зарегистрировать обработчики событий в различных элементах страницы. События включают такие вещи, как прохождение мыши над элементом формы, щелчок по кнопке, изменение содержимого текстового поля или отправка формы. Когда происходит событие, включающее элемент, который зарегистрировал обработчик события, вызывается связанный с ним код JavaScript.
Элементы, которые могут регистрировать обработчики событий, включают <BODY> документа HTML, гипертектовые ссылки, все разнообразные элементы заполняемых форм и саму форму. Существует большое количество событий, и каждое применяется только к тем элементам, для которых оно уместно. Вот неполный список:
onLoad
Браузер загружает текущий документ. Действительно:
- только в разделе HTML <BODY>.
onUnload
Браузер закрывает текущую страницу или кадр. Действительно:
- только в разделе HTML <BODY>.
onSubmit
Пользователь нажал кнопку отправки формы. Это событие случается перед самой отправкой формы, и ваша функция может вернуть значение false, чтобы приостановить отправку. Действительно:
- только для форм.
onClick
Мышка щелкнула по элементу в заполняемой форме. Действительно для:
- кнопок (включая кнопки отправки, переустановки и кнопки-изображения)
- выключателей
- переключателей
onChange
Пользователь изменил содержимое поля. Действительно для:
- текстовых полей
- Text areas
- полей пароля
- файловых полей
- Popup Menus
- списков с возможностью прокрутки
onFocus
Пользователь выбрал поле, чтобы работать с ним. Действительно для:
- текстовых полей
- Text areas
- полей пароля
- файловых полей
- Popup Menus
- списков с возможностью прокрутки
onBlur
Пользователь отказался от выбора поля (ушел работать где-то еще). Действительно для:
- текстовых полей
- Text areas
- полей пароля
- файловых полей
- Popup Menus
- списков с возможностью прокрутки
onSelect
Пользователь изменил часть текстового поля, которая выделена. Действительно для:
- текстовых полей
- Text areas
- полей пароля
- файловых полей
onMouseOver
Мышь движется над элементом. Действительно для:
- текстовых полей
- Text areas
- полей пароля
- файловых полей
- Popup Menus
- списков с возможностью прокрутки
onMouseOut
Мышь покидает элемент. Действительно для:
- текстовых полей
- Text areas
- полей пароля
- файловых полей
- Popup Menus
- списков с возможностью прокрутки
Чтобы register a JavaScript event handler with an HTML element, just use the event name as a parameter when you call the corresponding CGI method. Например, to have your validateAge() код JavaScript executed every time the textfield named "age" changes, generate the field like this:
print $q->textfield(-name=>'age',-onChange=>"validateAge(this)");
This example assumes that you've already declared the validateAge() function by incorporating it into a <SCRIPT> block. The CGI.pm start_html() method provides a convenient way to create this section.
Similarly, вы можете create a form that checks itself over for consistency and alerts the user if some essential value is missing by creating it this way:
print $q->startform(-onSubmit=>"validateMe(this)");
Посмотрите скрипт javascript.cgi для демонстрации того, как это все работает.
The JavaScript "standard" is still evolving, which means that new handlers may be added in the future, or may be present in some browsers and not in others. You do not need to wait for a new version of CGI.pm to use new event handlers. Just like any other tag attribute they will produce syntactically correct HTML. For instance, if Microsoft invents a new event handler called onInterplanetaryDisaster, вы можете install a handler for it with:
print button(-name=>'bail out',-onInterPlanetaryDisaster=>"alert('uh oh')");
Ограниченная поддержка каскадных таблиц стилей
CGI.pm имеет ограниченную поддержку каскадных таблиц стилей HTML 3 (css). Чтобы включить таблицу стилей в ваш документ, передайте методу start_html() параметр -style. Значение этого параметра может быть скаляром, в этом случае он будет включается прямо в раздел <STYLE>, или он может быть ссылкой на хеш. В последнем случае вам следует снабдить хеш одним или более -src и -code. -src указывает на URL, где может быть найдена внешне определенная таблица стилей. -code указывает на скалярное значение, которое нужно включить в раздел <STYLE>. Определения стилей в -code перекрывают сходно называющиеся в -src, отсюда и название "каскадные".
Вы можете также определить тип MIME таблицы стилей, включением необязательного параметра -type в хеш, указанный при помощи -style. Если он не определен, тип устанавливается по умолчанию в 'text/css'.
Чтобы сослаться на стиль в теле вашего документа, добавьте параметр -class к любому элементу HTML:
print h1({-class=>'Фантазия'},'Добро пожаловать на вечеринку');
Или определите стили на лету параметром -style:
print h1({-style=>'Color: red;'},'Добро пожаловать в ад');
Вы можете также использовать новый элемент span(), чтобы применить стиль к разделу текста:
print span({-style=>'Color: red;'},
h1('Добро пожаловать в ад'),
"Куда делась та корзинка?");
Заметьте, что вы должны импортировать определения ":html3", чтобы получить методы span() и style().
Вы не сможете сделать много с этим, если вы не поймете спецификации CSS. Более интуитивная subclassable библиотека для каскадных таблиц стилей в Perl is in the works, но до того времени, пожалуйста, прочитайте спецификацию CSS по адресу http://www.w3.org/pub/WWW/Style/, чтобы узнать, как использовать эти особенности. Вот окончательный пример, чтобы вы начали.
use CGI qw/:standard :html3/;
#вот таблица стилей, включенная прямо в страницу
$newStyle=<<END;
<!--
P.Tip {
margin-right: 50pt;
margin-left: 50pt;
color: red;
}
P.Alert {
font-size: 30pt;
font-family: sans-serif;
color: red;
}
-->
END
print header();
print start_html(-title=>'CGI со стилем',
-style=>{-src=>'http://www.capricorn.com/style/st1.css',
-code=>$newStyle});
print h1('CGI со стилем'),
p({-class=>'Tip'},
"Лучше прочитайте спецификацию каскадных \
таблиц стилей перед тем, как играть с этим!"),
span({-style=>'color: magenta'},"Смотри, мам, нету рук!",
p(),"Whooo wee!");
print end_html;
Использование скриптов NPH
NPH, or "no-parsed-header", scripts bypass the server completely by sending the complete HTTP header directly to the browser. This has slight performance benefits, but is of most use for taking advantage of HTTP extensions that are not directly supported by your server, such as server push and PICS headers.
Servers use a variety of conventions for designating CGI scripts as NPH. Many Unix servers look at the beginning of the script's name for the prefix "nph-". The Macintosh WebSTAR server and Microsoft's Internet Information Server, in contrast, try to decide whether a program is an NPH script by examining the first line of script output.
CGI.pm supports NPH scripts with a special NPH mode. When in this mode, CGI.pm will output the necessary extra header information when the header() and redirect() methods are called.
Important: If you use the Microsoft Internet Information Server, you must designate your script as an NPH script. Otherwise many of CGI.pm's features, such as redirection and the ability to output non-HTML files, will fail.
There are a number of ways to put CGI.pm into NPH mode:
In the use statement:
Simply add "-nph" to the list of symbols to be imported into your script:
use CGI qw(:standard -nph)
By calling the nph() method:
Call nph() with a non-zero parameter at any point after using CGI.pm in your program.
CGI->nph(1)
By using -nph parameters in the header() and redirect() statements:
print $q->header(-nph=>1);
Продвинутые приемы
Скрипт, который сохраняет некоторую информацию в файл и восстанавливает ее
Этот скрипт будет сохранять свое состояние в файл of the user's choosing, когда нажата кнопка "сохранить", и будет восстанавливать его состояние, когда нажата кнопка "восстановить". Заметьте, что it's very important to check the file name for shell metacharacters so that the script doesn't inadvertently open up a command or overwrite someone's file. For this to work, the script's current directory must be writable by "nobody".
#!/usr/local/bin/perl
use CGI;
$query = new CGI;
print $query->header;
print $query->start_html("Save and Restore Example");
print "<H1>Save and Restore Example</H1>\n";
# Here's where we take action on the previous request
&save_parameters($query) if $query->param('action') eq 'сохранить';
$query = &restore_parameters($query) if $query->param('action') eq 'восстановить';
# Here's where we create the form
print $query->startform;
print "Popup 1: ",$query->popup_menu('popup1',['eenie','meenie','minie']),"\n";
print "Popup 2: ",$query->popup_menu('popup2',['et','lux','perpetua']),"\n";
print "<P>";
print "Save/restore state from file: ",
$query->textfield('savefile','state.sav'),"\n";
print "<P>";
print $query->submit('action','сохранить'),
$query->submit('action','восстановить');
print $query->submit('action','usual query');
print $query->endform;
# Here we print out a bit at the end
print $query->end_html;
sub save_parameters {
local($query) = @_;
local($filename) = &clean_name($query->param('savefile'));
if(open(FILE,">$filename")) {
$query->save(FILE);
close FILE;
print "<STRONG>State has been saved to file $filename</STRONG>\n";
} else { print "<STRONG>Error:</STRONG> couldn't write to file $filename: $!\n" }
}
sub restore_parameters {
local($query) = @_;
local($filename) = &clean_name($query->param('savefile'));
if(open(FILE,$filename)) {
$query = new CGI(FILE); # Throw out the old query, replace it with a new one
close FILE;
print "<STRONG>State has been restored from file $filename</STRONG>\n";
} else { print "<STRONG>Error:</STRONG> couldn't restore file $filename: $!\n" }
return $query;
}
# Very important subroutine -- get rid of all the naughty
# metacharacters from the file name. If there are, we
# complain bitterly and die.
sub clean_name {
local($name) = @_;
unless ($name=~/^[\w\._-]+$/) {
print "<STRONG>$name has naughty characters. Only ";
print "alphanumerics are allowed. Вы не можете использовать \
absolute names.</STRONG>";
die "Attempt to use naughty characters";
}
return $name;
}
If you use the CGI save() and restore() methods a lot, you might be interested in the Boulderio file format. It's a way of transferring semi-strucured data from the standard output of one program to the standard input of the next. It comes with a simple Perl database, that позволяет вам сохранять и возвращать записи из базы данных DBM или DB_File, and is compatible with the format used by save() and restore(). Вы можете get more information on Boulderio from:
http://stein.cshl.org/software/boulder/
A Script that Uses Self-Referencing URLs to Jump to Internal Links
(Without losing form information).
Many people have experienced problems with internal links on pages that have forms. Jumping around within the document causes the state of the form to be reset. A partial solution is to use the self_url() method to generate a link that preserves state information. This script illustrates how this works.
#!/usr/local/bin/perl
use CGI;
$query = new CGI;
# We generate a regular HTML file containing a very long list
# and a popup menu that does nothing except to show that we
# don't lose the state information.
print $query->header;
print $query->start_html("Internal Links Example");
print "<H1>Internal Links Example</H1>\n";
print "<A NAME=\"start\"></A>\n"; # an anchor point at the top
# pick a default начальное значение;
$query->param('amenu','ФУ1') unless $query->param('amenu');
print $query->startform;
print $query->popup_menu('amenu',[('ФУ1'..'ФУ9')]);
print $query->submit,$query->endform;
# We create a long boring list for the purposes of illustration.
$myself = $query->self_url;
print "<OL>\n";
for (1..100) {
print qq{<LI>List item #$_<A HREF="$myself#start">Jump to top</A>\n};
}
print "</OL>\n";
print $query->end_html;
Multiple forms on the same page
There's no particular trick to this. Just remember to close one form before you open another one. Вы можете reuse the same query object or create a new one. Either technique works.
There is, однако, a problem with maintaining the states of multiple forms. Because the browser only sends your script the parameters from the form in which the submit button was pressed, the state of all the other forms will be lost. One way to get around this, suggested in this example, is to use hidden fields to pass as much information as possible regardless of which form the user submits.
#!/usr/local/bin/perl
use CGI;
$query=new CGI;
print $query->header;
print $query->start_html('Множество форм');
print "<H1>Множество форм</H1>\n";
# форма 1
print "<HR>\n";
print $query->startform;
print $query->textfield('текст1'),$query->submit('submit1');
print $query->hidden('текст2'); # pass information from the other form
print $query->endform;
print "<HR>\n";
# форма 2
print $query->startform;
print $query->textfield('текст2'),$query->submit('submit2');
print $query->hidden('текст1'); # pass information from the other form
print $query->endform;
print "<HR>\n";
print $query->end_html;
Subclassing CGI.pm
CGI.pm uses various tricks to work in both an object-oriented and function-oriented fashion. It uses even more tricks to load quickly, despite the fact that it is a humungous module. These tricks may get in your way when you attempt to subclass CGI.pm.
If you use standard subclassing techniques and restrict yourself to using CGI.pm and its subclasses in the object-oriented manner, you'll have no problems. Однако, если вы желаете to use the function-oriented calls with your subclass, follow this model:
package MySubclass;
use vars qw(@ISA $VERSION);
require CGI;
@ISA = qw(CGI);
$VERSION = 1.0;
$CGI::DefaultClass = __PACKAGE__;
$AutoloadClass = 'CGI';
sub new {
....
}
1;
The first special trick is to set the CGI package variable $CGI::DefaultClass to the name of the module you are defining. Если вы используете Perl 5.004 или выше, вы можете использовать специальный token "__PACKAGE__", чтобы возращать имя текущего модуля. Otherwise, just hard code the name of the module. This variable tells CGI what type of default object to create when called in the function-oriented manner.
The second trick is to set the package variable $AutoloadClass to the string "CGI". This tells the CGI autoloader where to look for functions that are not defined. Если вы желаете to override CGI's autoloader, set this to the name of your own package.
More information on extending CGI.pm can be found in my new book, The Official Guide to CGI.pm, which was published by John Wiley & Sons in April 1998. Check out the book's Web site, which contains multiple useful coding examples.
Использование CGI.pm с mod_perl и FastCGI
FastCGI
FastCGI is a protocol invented by OpenMarket that markedly speeds up CGI scripts under certain circumstances. It works by opening up the script at server startup time and redirecting the script's IO to a Unix domain socket. Every time a new CGI request comes in, the script is passed new parameters to work on. This allows the script to perform all its time-consuming operations at initialization time (including loading CGI.pm!) and then respond quickly to new requests.
FastCGI modules are available for the Apache and NCSA servers as well as for OpenMarket's own server. Чтобы use FastCGI with Perl you have to run a specially-modified version of the Perl interpreter. Precompiled Binaries and a patch kit are all available on OpenMarket's FastCGI web site.
To use FastCGI with CGI.pm, change your scripts as follows:
Old Script
#!/usr/local/bin/perl
use CGI qw(:standard);
print header,
start_html("CGI Script"),
h1("CGI Script"),
"Not much to see here",
hr,
address(a({href=>'/'},"home page"),
end_html;
New Script
#!/usr/local/fcgi/bin/perl
use CGI::Fast qw(:standard);
# Do time-consuming initialization up here.
while (new CGI::Fast) {
print header,
start_html("CGI Script"),
h1("CGI Script"),
"Not much to see here",
hr,
address(a({href=>'/'},"home page"),
end_html;
}
That's all there is to it. The param() method, form-generation, HTML shortcuts, etc., all work the way you expect.
mod_perl
mod_perl is a module for the Apache Web server that embeds a Perl interpreter into the Web server. It can be run in either of two modes:
- Server launches a new Perl interpreter every time it needs to interpret a Perl script. This speeds CGI scripts significantly because there's no overhead for launching a new Perl process.
- A "fast" mode in which the server launches your script at initialization time. Вы можете load all your favorite modules (like CGI.pm!) at initialization time, greatly speeding things up.
CGI.pm works with mod_perl, versions 0.95 и выше. If you use Perl 5.003_93 or higher, your scripts should run without any modifications. Users with earlier versions of Perl should use the CGI::Apache module instead. This example shows the change needed:
Old Script
#!/usr/local/bin/perl
use CGI qw(:standard);
print header,
start_html("CGI Script"),
h1("CGI Script"),
"Not much to see here",
hr,
address(a({href=>'/'},"home page"),
end_html;
New Script
#!/usr/bin/perl
use CGI::Apache qw(:standard);
print header,
start_html("CGI Script"),
h1("CGI Script"),
"Not much to see here",
hr,
address(a({href=>'/'},"home page"),
end_html;
}
Important configuration note: When using CGI.pm with mod_perl be careful not to enable either the PerlSendHeader or PerlSetupEnv directives. This is handled automatically by CGI.pm and by Apache::Registry.
mod_perl comes with a small wrapper library named CGI::Switch that selects dynamically between using CGI and CGI::Apache. This library is no longer needed. Однако users of CGI::Switch can continue to use it without risk. Note that the "simple" interface to the CGI.pm functions does not work with CGI::Switch. You'll have to use the object-oriented versions (or use the sfio version of Perl!)
If you use CGI.pm in many of your mod_perl scripts, you may want to preload CGI.pm and its methods at server startup time. To do this, add the following line to httpd.conf:
PerlScript /home/httpd/conf/startup.pl
Create the file /home/httpd/conf/startup.pl and put in it all the modules you want to load. Include CGI.pm among them and call its compile() method to precompile its autoloaded methods.
#!/usr/local/bin/perl
use CGI ();
CGI->compile(':all');
Change the path to the startup script according to your preferences.
Миграция из cgi-lib.pl
To make it easier to convert older scripts that use cgi-lib.pl, CGI.pm provides a CGI::ReadParse() call that is compatible with cgi-lib.pl's ReadParse() subroutine.
When you call ReadParse(), CGI.pm создает an associative array named %in that contains the named CGI parameters. Multi-valued parameters are separated by "\0" characters in exactly the same way cgi-lib.pl does it. The function result is the number of parameters parsed. Вы можете использовать this to determine whether the script is being called from a fill out form or not.
To port an old script to CGI.pm, you have to make just two changes:
Old Script
require "cgi-lib.pl";
ReadParse();
print "The price of your purchase is $in{price}.\n";
New Script
use CGI qw(:cgi-lib);
ReadParse();
print "The price of your purchase is $in{price}.\n";
Like cgi-lib's ReadParse, pass a variable glob чтобы use a different variable than the default "%in":
ReadParse(*Q);
@partners = split("\0",$Q{'golf_partners'});
The associative array created by CGI::ReadParse() contains a special key 'CGI', which возвращает the CGI query object itself:
ReadParse();
$q = $in{CGI};
print $q->textfield(-name=>'wow',
-value=>'does this really work?');
This allows you to add the more interesting features of CGI.pm to your old scripts without rewriting them completely. As an added benefit, the %in variable is actually tie()'d to the CGI object. Changing the CGI object using param() will dynamically change %in, and vice-versa.
cgi-lib.pl's @in and $in variables are not supported. In addition, the extended version of ReadParse() that allows you to spool uploaded files to disk is not available. You are strongly encouraged to use CGI.pm's file upload interface instead.
Смотрите cgi-lib_porting.html за большими подробностями on porting cgi-lib.pl scripts to CGI.pm.
Использование особенности для выгрузки файлов
Особенность для выгрузки файлов работает не с каждой комбинацией браузера и сервера. Различные версии Netscape и Internet Explorer on the Macintosh, Unix and Windows platforms don't all seem to implement file uploading in exactly the same way. I've tried to make CGI.pm work with all versions on all platforms, but I keep getting reports from people of instances that break the file upload feature.
Known problems include:
- Large file uploads may fail when using SSL version 2.0. This affects the Netscape servers and possibly others that use the SSL library. I have received reports that WebSite Pro suffers from this problem. This is a documented bug in the Netscape implementation of SSL and not a problem with CGI.pm.
- If you try to upload a directory path with Unix Netscape, the browser will hang until you hit the "stop" button. I haven't tried to figure this one out since I think it's dumb of Netscape to allow this to happen at all.
- If you create the CGI object in one package (например, "main") and then obtain the filehandle in a different package (например, "фу"), the filehandle will be accessible through "main" but not "фу". Чтобы use the filehandle, try the following contortion:
$file = $query->param('file to upload'); $file = "main::$file"; ...I haven't found a way to determine the correct caller in this situation. I might add a readFile() method to CGI if this problem bothers enough people.
The main technical challenge of handling file uploads is that it potentially involves sending more data to the CGI script than the script can hold in main memory. For this reason CGI.pm создает temporary files in either the /usr/tmp or the /tmp directory. These temporary files have names like CGItemp125421, and should be deleted automatically.
Частые проблемы
Когда вы запускаете скрипт из командной строки, она говорит: "offline mode: enter name=value pairs on standard input". What do I do now?
This is a prompt to enter some CGI parameters for the purposes of debugging. Вы можете now type in some parameters like this:
first_name=Fred last_name=Flintstone city=Bedrock
End the list by typing a control-D (or control-Z on DOS/Windows systems).
If you want to run a CGI script from a script or batch file, and don't want this behavior, just pass it an empty parameter list like this:
my_script.pl ''
This will work too on Unix systems:
my_script.pl </dev/null
Another option is to use the "-no_debug" pragma when you "use" CGI.pm. This will suppress command-line debugging completely:
use CGI qw/:standard -no_debug/;
Вы не можете вернуть имя выгруженного файла, используя метод param()
Most likely the remote user isn't using version 2.0 (or higher) of Netscape. Alternatively she just isn't filling in the form completely.
When you accidentally try to upload a directory name, the browser hangs
This seems to be a Netscape browser problem. It starts to upload junk to the script, then hangs. Вы можете abort by hitting the "stop" button.
Вы можете читать имя выгруженного файла, но не можете возвращать данные
First check that you've told CGI.pm to use the new multipart/form-data scheme. If it still isn't working, there may be a problem with the temporary files that CGI.pm needs to create чтобы read in the (potentially very large) uploaded files. Internally, CGI.pm tries to create temporary files with names similar to CGITemp123456 in a temporary directory. To find a suitable directory it first looks for /usr/tmp and then for /tmp. If it can't find either of these directories, it tries for the current directory, which is usually the same directory that the script resides in.
If you're on a non-Unix system you may need to modify CGI.pm to point at a suitable temporary directory. This directory must be writable by the user ID under which the server runs (usually "nobody") and must have sufficient capacity to handle large file uploads. Open up CGI.pm, and find the line:
package TempFile;
foreach ('/usr/tmp','/tmp') { do {$TMPDIRECTORY = $_; last} if -d $_ && -w _ }
Modify the foreach() line to contain a series of one or more directories to store temporary files in.
Alternatively, вы можете just skip the search entirely and force CGI.pm to store its temporary files in some logical location. Do this at the top of your script with a line like this one: $TempFile::TMPDIRECTORY='/WWW_ROOT';
On Windows Systems, the temporary file is never deleted, but hangs around in \temp, taking up space.
Be sure to close the filehandle before your program exits. In fact, close the file as soon as you're finished with it, because the file will end up hanging around if the script later crashes.
Unix users don't have this problem, because well designed operating systems make it possible to delete a file without closing it.
When you press the "back" button, the same page is loaded, not the previous one.
Netscape 2.0's history list gets confused when processing multipart forms. If the script generates different pages for the form and the results, hitting the "back" button doesn't always return you to the previous page; instead Netscape reloads the current page. This happens even if you don't use an upload file field in your form.
A workaround for this is to use additional path information to trick Netscape into thinking that the form and the response have different URLs. I recommend giving each form a sequence number and bumping the sequence up by one each time the form is accessed:
my($s) = $query->path_info=~/(\d+)/; # get sequence $s++; #bump it up # Trick Netscape into thinking it's loading a new script: print $q->start_multipart_form(-action=>$q->script_name . "/$s");
Вы не можете найти the temporary file that CGI.pm создает
You're encouraged to copy the data into your own file by reading from the file handle that CGI.pm provides you with. In the future there may be no temporary file at all, just a pipe. Однако, for now, if you really want to get at the temp file, вы можете вернуть its path using the tmpFileName() method. Be sure to move the temporary file elsewhere in the file system if you don't want it to be automatically deleted when CGI.pm exits.
Server Push
CGI.pm provides three simple functions for producing multipart documents of the type needed to implement server push. To import these into your namespace, you must import the ":push" set. You are also advised to put the script into NPH mode and to set $| to 1 to avoid buffering problems.
Here is a simple script that demonstrates server push:
#!/usr/local/bin/perl
use CGI qw/:push -nph/;
$| = 1;
print multipart_init(-boundary=>'----------------here we go!');
while(1) {
print multipart_start(-type=>'text/plain'),
"The current time is ",scalar(localtime),"\n",
multipart_end;
sleep 1;
}
This script initializes server push by calling multipart_init(). It then enters an infinite loop in which it begins a new multipart section by calling multipart_start(), prints the current local time, and ends a multipart section with multipart_end(). It then sleeps a second, and begins again.
multipart_init()
multipart_init(-boundary=>$boundary);
Initialize the multipart system. The -boundary argument specifies what MIME boundary string to use to separate parts of the document. If not provided, CGI.pm chooses a reasonable boundary for you.
multipart_start()
multipart_start(-type=>$type)
Start a new part of the multipart document using the specified MIME type. If not specified, text/html is assumed.
multipart_end()
multipart_end()
End a part. You must remember to call multipart_end() once for each multipart_start().
Users interested in server push applications should also have a look at the CGI::Push module.
Avoiding Denial of Service Attacks
Потенциальная проблема с CGI.pm is that, by default, it attempts to process form POSTings no matter how large they are. Волный хакер could attack your site by sending a CGI script a huge POST of many megabytes. CGI.pm will attempt to read the entire POST into a variable, growing hugely in size until it runs out of memory. While the script attempts to allocate the memory the system may slow down dramatically. This is a form of denial of service attack.
Another possible attack is for the remote user to force CGI.pm to accept a huge file upload. CGI.pm will accept the upload and store it in a temporary directory even if your script doesn't expect to receive an uploaded file. CGI.pm will delete the file automatically when it terminates, but in the meantime the remote user may have filled up the server's disk space, causing problems for other programs.
The best way to avoid denial of service attacks is to limit the amount of memory, CPU time and disk space that CGI scripts can use. Some Web servers come with built-in facilities to accomplish this. In other cases, вы можете использовать the shell limit or ulimit commands to put ceilings on CGI resource usage.
CGI.pm also has some simple built-in protections against denial of service attacks, but you must activate them before вы можете использовать them. These take the form of two global variables in the CGI name space:
$CGI::POST_MAX
If set to a non-negative integer, this variable puts a ceiling on the size of POSTings, in bytes. If CGI.pm detects a POST that is greater than the ceiling, it will immediately exit with an error message. This value will affect both ordinary POSTs and multipart POSTs, meaning that it limits the maximum size of file uploads as well. You should set this to a reasonably high value, such as 1 megabyte.
$CGI::DISABLE_UPLOADS
If set to a non-zero value, this will disable file uploads completely. Other fill-out form values will work as usual.
Вы можете использовать these variables in either of two ways.
- On a script-by-script basis. Set the variable at the top of the script, right after the "use" statement:
use CGI qw/:standard/; use CGI::Carp 'fatalsToBrowser'; $CGI::POST_MAX=1024 * 100; # max 100K posts $CGI::DISABLE_UPLOADS = 1; # no uploads
- Globally for all scripts. Open up CGI.pm, find the definitions for $POST_MAX and $DISABLE_UPLOADS, and set them to the desired values. You'll find them towards the top of the file in a subroutine named initialize_globals.
Since an attempt to send a POST larger than $POST_MAX bytes will cause a fatal error, you might want to use CGI::Carp to echo the fatal error message to the browser window as shown in the example above. Otherwise the remote user will see only a generic "Internal Server" error message. Смотрите the manual page for CGI::Carp за большими подробностями.
An attempt to send a POST larger than $POST_MAX bytes will cause param() to return an empty CGI parameter list. Вы можете test for this event by checking cgi_error(), either after you create the CGI object or, if you are using the function-oriented interface, call param() for the first time. If the POST was intercepted, then cgi_error() will return the message "413 POST too large".
This error message is actually defined by the HTTP protocol, and is designed to be returned to the browser as the CGI script's status code. Например:
$uploaded_file = param('upload');
if(!$uploaded_file && cgi_error()) {
print header(-status=>cgi_error());
exit 0;
}
Some browsers may not know what to do with this status code. It may be better just to create an HTML page that warns the user of the problem.
Использование CGI.pm на платформах не-Unix
I don't have access to all the combinations of hardware and software that I really need to make sure that CGI.pm works consistently for all Web servers, so I rely heavily on helpful reports from users like yourself.
There are a number of differences in file name and text processing conventions on different platforms. By default, CGI.pm is set up to work properly on a Unix (or Linux) system. During load, it will attempt to guess the correct operating system using the Config module. Currently it guesses correctly; однако if the operating system names change it may not work right. The main symptom will be that file upload does not work correctly. If this happens, find the place at the top of the script where the OS is defined, and uncomment the correct definition:
# CHANGE THIS VARIABLE FOR YOUR OPERATING SYSTEM # $OS = 'UNIX'; # $OS = 'MACINTOSH'; # $OS = 'WINDOWS'; # $OS = 'VMS';
Other notes follow:
Windows NT
CGI.pm works well with WebSite, the EMWACS server, Purveyor and the Microsoft IIS server. CGI.pm must be put in the Perl 5 library directory, and all CGI scripts that use it should be placed in cgi-bin directory. You also need to associate the .pl suffix with Perl 5 using the NT file manager (Website, Purveyor), or install the correct script mapping registry keys for IIS. There are two ports of Perl for Windows, one done by the ActiveWare company, and the other by Gurusamy Sarathy. I have only tested CGI.pm with the former. The home site for the ActiveWare port is:
http://www.activeware.com/
The ActiveWare port comes in two parts. The first part is a standard standalone Perl interpreter. The second part is a small DLL library that implements a Perl ISAPI interface for IIS and other Web servers. As of build 307, the DLL library is seriously broken. It is seriously unreliable when used for any Perl CGI script, with or without CGI.pm. Symptoms include truncated CGI parameters, missing parameters, scrambled output, and failed file uploads. I strongly recommend that you use the standalone interpreter instead.
The Microsoft IIS server is broken with respect to the handling of additional path information. If you use the DLL version of ActiveWare Perl, IIS will attempt to execute the additional path information as a script. If you use the external Perl interpreter, the additional path information may contain incorrect information. This is not a bug in CGI.pm.
WebSite uses a slightly different cgi-bin directory structure than the standard. For this server, place the scripts in the cgi-shl directory. CGI.pm appears to work correctly in both the Windows95 and WindowsNT versions of WebSite.
Old Netscape Communications Server technical notes recommended placing perl.exe in cgi-bin. This a very bad idea because it opens up a gaping security hole. Put a C .exe wrapper around the Perl script until such time as Netscape recognizes NT file manager associations, or provides a Perl-compatible DLL library for its servers.
If you find that binary files get slightly larger when uploaded but that text files remain the same, then binary made is not correctly activated. Be sure to set the $OS variable to 'NT' or 'WINDOWS'. If you continue to have problems, make sure you're calling binmode() on the filehandle that you use to write the uploaded file to disk.
VMS
I don't have access to a VMS machine, and I'm not sure whether file upload works correctly. Other features are known to work.
Macintosh
Most CGI.pm features work with MacPerl version 5.0.6r1 or higher under the WebStar and MacHTTP servers. Чтобы install a Perl program to use with the Web, you'll need Matthias Nuuracher's PCGI extension, available at:
ftp://err.ethz.ch/pub/neeri/MacPerl/
Known incompatibilities between CGI.pm and MacPerl include:
- The Perl compiler will object to the use of -values in named parameters. Put single quotes around this parameter ('-values') or use the singular form ('-value') instead.
- File upload isn't working in my hands (Perl goes into an endless loop). Other people have gotten it to work.
Отношение этой библиотеки к модулям CGI
This library is maintained in parallel with the full featured CGI, URL, and HTML modules. I use this library to test out new ideas before incorporating them into the CGI hierarchy. I am continuing to maintain and improve this library чтобы satisfy people who are looking for an easy-to-use introduction to the world of CGI scripting.
The CGI::* modules are being reworked to be interoperable with the excellent LWP modules. Stay tuned.
Текущую версию CGI.pm можно найти на:
http://www.genome.wi.mit.edu/ftp/pub/software/WWW
You are encouraged to look at these other Web-related modules:
A module that simplifies the creation of HTML documents programatically.
CGI::Base,CGI::Form,CGI::MiniSrv,CGI::Request and CGI::URI::URL
Modules for parsing script input, manipulating URLs, creating forms and even launching a miniature Web server.
Modules for fetching Web resources from within Perl, writing Web robots, and much more.
You might also be interested in two packages for creating graphics on the fly:
A module for creating GIF images on the fly, using Tom Boutell's gd graphics library.
A library for creating Macintosh PICT files on the fly (which can be converted to GIF or JPEG using NetPBM).
For a collection of CGI scripts of various levels of complexity, see the companion pages for my book Как установить и поддерживать a World Wide Web Site
Информация о распространении:
Этот код охраняется авторскими правами 1995-1998 Линкольна Штейна. Он может свободно использоваться и модифицироваться, но я do request that this copyright notice remain attached to the file. You may modify this module as you желаете, but if you redistribute a modified version, please attach a note listing the modifications you have made.
Книга по CGI.pm
The Official Guide to CGI.pm, by Lincoln Stein, is packed with tips and techniques for using the module, along with information about the module's internals that can't be found anywhere else. It is available on bookshelves now, or can be ordered from amazon.com. Also check the book's companion Web site at:
http://www.wiley.com/compbooks/stein/
CGI.pm и проблема 2000 года
Версии CGI.pm до 2.36 страдали проблемой 2000 года в управлении cookie. Сроки истечения cookie выражались, используя два разряда, как диктовалось тогда текущим протоколом Netscape cookie. Протокол cookie с тех пор был подчищен. По моему убеждению, версии CGI.pm 2.36 и выше согласованы с 2000 годом.
Почтовый список CGI-Perl
The CGI Perl mailing list is defunct and is unlikely to be resurrected. Please address your questions to comp.infosystems.www.authoring.cgi if they relate to the CGI protocol or the usage of CGI.pm per gse, or to comp.lang.perl.misc for Perl language issues. Please read this documentation thoroughly, read the FAQs for these newsgroups and scan through previous messages before you make a posting. Respondents are not always friendly to people who neglect to do so!
Отчеты об ошибках
Отсылайте отчеты об ошибках и комментарии по адресу: lstein@cshl.org.
Когда отправляете отчеты об ошибках, пожалуйста, снабжайте их следующей информацией:
- версия CGI.pm (
perl -MCGI -e 'print $CGI::VERSION') - версия Perl (
perl -v) - название и версия вашего Web-сервера
- название и версия операционной системы, которую вы используете
- если применимо, название и версия браузера, который вы используете
- короткий пробный скрипт, который воспроизводит проблему (30 строк или меньше)
Очень важно, чтобы я получил эту информацию, чтобы помочь вам.
История редактуры
Версия 2.56
- Fixed bugs in file upload introduced in version 2.55
- Fixed long-standing bug that prevented two files with identical names from being uploaded.
Версия 2.55
- Fixed cookie regression test so as not to produce an error.
- Fixed path_info() and self_url() to work correctly together when path_info() modified.
- Removed manify warnings from CGI::{Switch,Apache}.
Версия 2.54
- This will be the last release of the monolithic CGI.pm module. Later versions will be modularized and optimized.
- DOMAIN tag no longer added to cookies by default. This will break some versions of Internet Explorer, but will avoid breaking networks which use host tables without fully qualified domain names. For compatibility, please always add the -domain tag when creating cookies.
- Fixed escape() method so that +'s are treated correctly.
- Updated CGI::Pretty module.
Версия 2.53
- Forgot to upgrade regression tests before releasing 2.52. NOTHING ELSE HAS CHANGED IN LIBRARY
Версия 2.52
- Spurious newline in checkbox() routine removed. (courtesy John Essen)
- TEXTAREA linebreaks now respected in dump() routine. (courtesy John Essen)
- Patches for DOS ports (courtesy Robert Davies)
- Patches for VMS
- More fixes for cookie problems
- Fix CGI::Carp so that it doesn't affect eval{} blocks (courtesy Byron Brummer)
Версия 2.51
- Fixed problems with cookies not being remembered when sent to IE 5.0 (and Netscape 5.0 too?)
- Numerous HTML compliance problems in cgi_docs.html; fixed thanks to Michael Leahy
Версия 2.50
- Добавлен новый метод Vars(), чтобы возвращать все параметры as a tied hash.
- Untainted tainted tempfile name so that script doesn't fail on terminal unlink.
- Made picking of upload tempfile name more intelligent so that doesn't fail in case of name collision.
- Fixed handling of expire times when passed an absolute timestamp.
Версия 2.49
- Fixes for FastCGI (globals not getting reset)
- Fixed url() to correctly handle query string and path under MOD_PERL
Версия 2.48
- Reverted detection of MOD_PERL to avoid breaking PerlEX.
Версия 2.47
- Patch to fix file upload bug appearing in IE 3.01 for Macintosh/PowerPC.
- Replaced use of $ENV{SCRIPT_NAME} with $ENV{REQUEST_URI} when running under Apache, to fix self-referencing URIs.
- Fixed bug in escapeHTML() which caused certain constructs, such as CGI->image_button(), to fail.
- Fixed bug which caused strong('CGI') to fail. Be careful to use CGI::strong('CGI') and not CGI->strong('CGI'). The latter will produce confusing results.
- Added upload() function, as a preferred replacement for the "filehandle as string" feature.
- Added cgi_error() function.
- Rewrote file upload handling to return undef rather than dieing when an error is encountered. Be sure to call cgi_error() to find out what went wrong.
Версия 2.46
- Fix for failure of the "include" tests under mod_perl
- Added end_multipart_form to prevent failures during qw(-compile :all)
Версия 2.45
- Multiple small documentation fixes
- CGI::Pretty didn't get into 2.44. Fixed now.
Версия 2.44
- Fixed file descriptor leak in upload function.
- Fixed bug in header() that prevented fields from containing double quotes.
- Added Brian Paulsen's CGI::Pretty package for pretty-printing output HTML.
- Removed CGI::Apache and CGI::Switch from the distribution.
- Generated start_* shortcuts so that start_table(), end_table(), start_ol(), end_ol(), and so forth now work (see the docs on how to enable this feature).
- Changed accept() to Accept(), sub() to Sub(). There's still a conflict with reset(), but this will break too many existing scripts!
Версия 2.43
- Fixed problem with "use strict" and file uploads (thanks to Peter Haworth)
- Fixed problem with not MSIE 3.01 for the power_mac not doing file uploads right.
- Fixed problem with file upload on IIS 4.0 when authorization in use.
- -content_type and '-content-type' can now be provided to header() as synonyms for -type.
- CGI::Carp now escapes the ampersand BEFORE escaping the > and < signs.
- Fixed "not an array reference" error when passing a hash reference to radio_group().
- Fixed non-removal of uploaded TMP files on NT platforms which occurs when server runs on non-C drive (thanks to Steve Kilbane for finding this one).
Версия 2.42
- Too many screams of anguish at измененом поведении url(). Is now back to its old behavior by default, with options to generate all the variants.
- Added regression tests. "make test" now works.
- Documentation fixes.
- Fixes for Macintosh uploads, but uploads STILL do not work pending changes to MacPerl.
Версия 2.41
- url() method now includes the path info. Use script_name() to get it without path info().
- Changed handling of empty attributes in HTML tag generation. Be warned! Use
table({-border=>undef}) rather than table({-border=>''}).
- Changes to allow uploaded filenames to be compared to other strings with "eq", "cmp" and "ne".
- Changes to allow CGI.pm to coexist more peacefully with ActiveState PerlEX.
- Changes to prevent exported variables from clashing when importing ":all" set in combination with cookies.
Версия 2.40
- CGI::Carp patched to work better with mod_perl (thanks to Chris Dean).
- Uploads of files whose names begin with numbers or the Windows \\UNC\shared\file nomenclature should no longer fail.
- The <STYLE> tag (for cascading style sheets) now generates the required TYPE attribute.
- Server push primitives added, thanks to Ed Jordan.
- Table and other HTML 3 functions are now part of the :standard set.
- Small documentation fixes.
TO DO:
- Do something about the DTD mess. The module should generate correct DTDs, or at least offer the programmer a way to specify the correct one.
- Split CGI.pm into CGI processing and HTML-generating modules.
- More robust file upload (?still not working on the Macintosh?).
- Bring in all the HTML 4 functionality, particular the accessibility features.
Версия 2.39
- file uploads failing because of VMS patch; fixed.
- -dtd parameter was not being properly processed.
Версия 2.38
I finally got tired of all the 2.37 betas and released 2.38. The main difference between this version and the last 2.37 beta (2.37b30) are some fixes for VMS. This should allow file upload to work properly on all VMS Web servers.
Версия 2.37, various beta versions
- Added a CGI::Cookie::parse() method for lucky mod_perl users.
- No longer need separate -values and -labels arguments for multi-valued form elements.
- Added better interface to raw cookies (fix courtesy Ken Fox, kfox@ford.com)
- Added param_fetch() function for direct access to parameter list.
- Fix to checkbox() to allow for multi-valued single checkboxes (weird problem).
- Added a compile() method for those who want to compile without importing.
- Documented the import pragmas a little better.
- Added a -compile switch to the use clause for the long-suffering mod_perl and Perl compiler users.
- Fixed initialization routines so that FileHandle and type globs work correctly (and hash initialization doesn't fail!).
- Better deletion of temporary files on NT systems.
- Added documentation on escape(), unescape(), unescapeHTML() and unescapeHTML() subroutines.
- Added documentation on creating subclasses.
- Fixed problem when calling $self->SUPER::foo() from inheriting subclasses.
- Fixed problem using filehandles from within subroutines.
- Fixed inability to use the string "CGI" as a parameter.
- Fixed exponentially growing $FILLUNIT bug
- Check for undef filehandle in read_from_client()
- Now requires the UNIVERSAL.pm module, present in Perl 5.003_7 or higher.
- Fixed problem with uppercase-only parameters being ignored.
- Fixed vanishing cookie problem.
- Fixed warning in initialize_globals() under mod_perl.
- File uploads from Macintosh versions of MSIE should now work.
- Pragmas now preceded by dashes (-nph) rather than colons (:nph). Старый стиль is supported for backward compatability.
- Can now pass arguments to all functions using {} brackets, resolving historical inconsistencies.
- Removed autoloader warnings about absent MultipartBuffer::DESTROY.
- Fixed non-sticky checkbox() when -name used without -value.
- Hack to fix path_info() in IIS 2.0. Doesn't help with IIS 3.0.
- Parameter syntax for debugging from command line now more straightforward.
- Added $DISABLE_UPLOAD to disable file uploads.
- Added $POST_MAX to error out if POSTings exceed some ceiling.
- Fixed url_param(), which wasn't working at all.
- Fixed variable suicide problem in s///e expressions, where the autoloader was needed during evaluation.
- Removed excess spaces between elements of checkbox and radio groups
- Can now create "valueless" submit buttons
- Can now set path_info as well as read it.
- ReadParse() now возвращает a useful function result.
- import_names() now allows you to optionally clear out the namespace before importing (for mod_perl users)
- Made it possible to have a popup menu or radio button with a value of "0".
- link() changed to Link() to avoid overriding native link function.
- Takes advantage of mod_perl's register_cleanup() function to clear globals.
- <LAYER> and <ILAYER> added to :html3 functions.
- Fixed problems with private tempfiles and NT/IIS systems.
- No longer prints the DTD by default (I bet no one will complain).
- Allow underscores to replace internal hyphens in parameter names.
- CGI::Push supports heterogeneous MIME types and adjustable delays between pages.
- url_param() method added for retrieving URL parameters even when a fill-out form is POSTed.
- Got rid of warnings when radio_group() is called.
- Cookies now moved to their very own module.
- Fixed documentation bug in CGI::Fast.
- Added a :no_debug pragma to the import list.
Версия 2.36
- Expanded JavaScript functionality
- Preliminary поддержка каскадных таблиц стилей
- Security fixes for file uploads:
- Module will bail out if its temporary file already exists
- Temporary files can now be made completely private to avoid peeking by other users or CGI scripts.
- use CGI qw/:nph/ wasn't working correctly. Now it is.
- Cookie and HTTP date formats didn't meet spec. Thanks to Mark Fisher (fisherm@indy.tce.com) for catching and fixing this.
Версия 2.35
- Robustified multipart file upload against incorrect syntax in POST.
- Fixed more problems with mod_perl.
- Added -noScript parameter to start_html().
- Documentation fixes.
Версия 2.34
- Stupid typo fix
Версия 2.33
- Fixed a warning about an undefined environment variable.
- Doug's patch for redirect() under mod_perl
- Partial fix for busted inheritence from CGI::Apache
- Documentation fixes.
Версия 2.32
- Improved support for Apache's mod_perl.
- Changes to better support inheritance.
- Support for OS/2.
Версия 2.31
- New uploadInfo() method to obtain header information from uploaded files.
- cookie() without any arguments возвращает all the cookies passed to a script.
- Removed annoying warnings about $ENV{NPH} when running with the -w switch.
- Removed operator overloading throughout to make compatible with new versions of Perl.
- -expires now implies the -date header, to avoid clock skew.
- WebSite passes cookies in $ENV{COOKIE} rather than $ENV{HTTP_COOKIE}. We now handle this, even though it's O'Reilly's fault.
- Tested successfully against new sfio I/O layer.
- Documentation fixes.
Версия 2.30
- Automatic detection of operating system at load time.
- Changed select() function to Select() чтобы avoid conflict with Perl built-in.
- Added Tr() as an alternative to TR(); some people think it looks better that way.
- Fixed problem with autoloading of MultipartBuffer::DESTROY code.
- Added the following methods:
- virtual_host()
- server_software()
- Automatic NPH mode when running under Microsoft IIS server.
Версия 2.29
- Fixed cookie bugs
- Fixed problems that cropped up when useNamedParameters was set to 1.
- Prevent CGI::Carp::fatalsToBrowser() from crapping out when encountering a die() within an eval().
- Fixed problems with filehandle initializers.
Версия 2.28
- Added support for NPH scripts; also fixes problems with Microsoft IIS.
- Fixed a problem with checkbox() values not being correctly saved and restored.
- Fixed a bug in which CGI objects created with empty string initializers took on default values from earlier CGI objects.
- Documentation fixes.
Версия 2.27
- Small but important bug fix: the automatic capitalization of tag attributes was accidentally capitalizing the VALUES as well as the ATTRIBUTE names (oops).
Версия 2.26
- Изменено поведение методов scrolling_list(), checkbox() и checkbox_group() таким образом, что defaults are honored correctly. The "fix" causes endform() to generate additional <INPUT TYPE="HIDDEN"> tags -- don't be surpised.
- Fixed bug involving the detection of the SSL protocol.
- Fixed documentation error in position of the -meta argument in start_html().
- HTML shortcuts now generate tags in ALL UPPERCASE.
- start_html() now generates correct SGML header:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
- CGI::Carp no longer fails "use strict refs" pragma.
Версия 2.25
- Fixed bug that caused bad redirection on destination URLs with arguments.
- Fixed bug involving use_named_parameters() followed by start_multipart_form()
- Fixed bug that caused incorrect determination of binmode for Macintosh.
- Spelling fixes on documentation.
Версия 2.24
- Fixed bug that caused generation of lousy HTML for some form elements
- Fixed uploading bug in Windows NT
- Some code cleanup (not enough)
Версия 2.23
- Fixed an obscure bug that caused scripts to fail mysteriously.
- Fixed auto-caching bug.
- Fixed bug that prevented HTML shortcuts from passing taint checks.
- Fixed some -w warning problems.
Версия 2.22
- New CGI::Fast module for use with FastCGI protocol. Смотрите pod documentation for details.
- Fixed problems with inheritance and autoloading.
- Added TR() (<tr>) and PARAM() (<param>) methods to list of exported HTML tag-generating functions.
- Moved all CGI-related I/O to a bottleneck method so that this can be overridden more easily in mod_perl (thanks to Doug MacEachern).
- put() method as substitute for print() for use in mod_perl.
- Fixed crash in tmpFileName() method.
- Added tmpFileName(), startform() and endform() to export list.
- Fixed problems with attributes in HTML shortcuts.
- Functions that don't actually need access to the CGI object now no longer generate a default one. May speed things up slightly.
- Aesthetic improvements in generated HTML.
- New examples.
Версия 2.21
- Added the -meta argument to start_html().
- Fixed hidden fields (again).
- Radio_group() and checkbox_group() now return an appropriate scalar value when called in a scalar context, rather than returning a numeric value!
- Cleaned up the formatting of form elements to avoid unesthetic extra spaces within the attributes.
- HTML elements now correctly include the closing tag when parameters are present but null: em('')
- Added password_field() to the export list.
Версия 2.20
- Dumped the SelfLoader because of problems with running with taint checks and rolled my own. Performance is now significantly improved.
- Added HTML shortcuts.
- import() now adheres to the Perl module conventions, allowing CGI.pm to import any or all method names into the user's name space.
- Added the ability to initialize CGI objects from strings and associative arrays.
- Made it possible to initialize CGI objects with filehandle references rather than filehandle strings.
- Added the delete_all() and append() methods.
- CGI objects correctly initialize from filehandles on NT/95 systems now.
- Fixed the problem with binary file uploads on NT/95 systems.
- Fixed bug in redirect().
- Added '-Window-target' parameter to redirect().
- Fixed import_names() so that parameter names containing funny characters work.
- Broke the unfortunate connection between cookie and CGI parameter name space.
- Fixed problems with hidden fields whose values are 0.
- Cleaned up the documentation somewhat.
Версия 2.19
- Added cookie() support routines.
- Added -expires parameter to header().
- Added cgi-lib.pl compatability mode.
- Made the module more configurable for different operating systems.
- Fixed a dumb bug in JavaScript button() method.
Версия 2.18
- Fixed a bug that corrects a hang that occurs on some platforms when processing file uploads. Unfortunately this disables the check for bad Netscape uploads.
- Fixed bizarre problem involving the inability to process uploaded files that begin with a non alphabetic character in the file name.
- Fixed a bug in the hidden fields involving the -override directive being ignored when scalar defaults were passed.
- Added documentation on how to disable the SelfLoader features.
Версия 2.17
- Added support for the SelfLoader module.
- Added oodles of JavaScript support routines.
- Fixed bad bug in query_string() method that caused some parameters to be silently dropped.
- Robustified file upload code to handle premature termination by the client.
- Exported temporary file names on file upload.
- Removed spurious "uninitialized variable" warnings that appeared when running under 5.002.
- Added the Carp.pm library to the standard distribution.
- Fixed a number of errors in this documentation, and probably added a few more.
- Checkbox_group() and radio_group() now return the buttons as arrays, so that вы можете incorporate the individual buttons into specialized tables.
- Added the '-nolabels' option to checkbox_group() and radio_group(). Probably should be added to all the other HTML-generating routines.
- Added the url() method to recover the URL without the entire query string appended.
- Added request_method() to list of environment variables available.
- Would you believe it? Fixed hidden fields again!
Версия 2.16
- Fixed hidden fields yet again.
- Fixed subtle problems in the file upload method that caused intermittent failures (thanks to Keven Hendrick for this one).
- Made file upload more robust in the face of bizarre behavior by the Macintosh and Windows Netscape clients.
- Moved the POD documentation to the bottom of the module at the request of Stephen Dahmen.
- Added the -xbase parameter to the start_html() method, also at the request of Stephen Dahmen.
- Added JavaScript form buttons at Stephen's request. I'm not sure how to use this Netscape extension correctly, однако, so for now the form() method is in the module as an undocumented feature. Use at your own risk!
Версия 2.15
- Added the -override parameter to all field-generating methods.
- Documented the
user_name()andremote_user()methods. - Fixed bugs that prevented empty strings from being recognized as valid textfield contents.
- Documented the use of framesets and added a frameset example.
Версия 2.14
This was an internal experimental version that was never released.
Версия 2.13
- Fixed a bug that interfered with the value "0" being entered into text fields.
Версия 2.01
- Added -rows and -columns to the radio and checkbox groups. No doubt this will cause much grief because it seems to promise a level of meta-organization that it doesn't actually provide.
- Fixed a bug in the redirect() method -- it was not truly HTTP/1.0 compliant.
Версия 2.0
The changes seemed to touch every line of code, so I decided to bump up the major version number.
- Поддержка стиля вызовов методов с именованными параметрами. This turns out to be a big win for extending CGI.pm when Netscape adds new HTML "features".
- Изменено поведение of hidden fields back to the correct "sticky" behavior. This is going to break some programs, but it is for the best in the long run.
- Netscape 2.0b2 broke the file upload feature. CGI.pm now handles both 2.0b1 and 2.0b2-style uploading. It will probably break again in 2.0b3.
- There were still problems with library being unable to distinguish between a form being loaded for the first time, and a subsequent loading with all fields blank. We now forcibly create a default name for the Submit button (if not provided) so that there's always at least one parameter.
- More workarounds to prevent annoying spurious warning messages when run under the -w switch. -w is seriously broken in Perl 5.001!
Версия 1.57
- Support for the Netscape 2.0 "File upload" field.
- The handling of defaults for selected items in списках с возможностью прокрутки и multiple checkboxes is now consistent.
Версия 1.56
- Created true "pod" documentation for the module.
- Cleaned up the code to avoid many of the spurious "use of uninitialized variable" warnings when running with the -w switch.
- Added the
autoEscape()method. - Added string interpolation of the CGI object.
- Added the ability to pass additional parameters to the <BODY> tag.
- Added the ability to specify the status code in the HTTP header.
Bug fixes in version 1.55
- Every time self_url() was called, the parameter list would grow. This was a bad "feature".
- Documented the fact that вы можете pass "-" to radio_group() чтобы prevent any button from being highlighted by default.
Bug fixes in version 1.54
- The user_agent() method is now documented;
- A potential security hole in import() is now plugged.
- Changed name of import() to import_names() for compatability with CGI:: modules.
Bug fixes in version 1.53
- Fixed several typos in the code that were causing the following subroutines to fail in some circumstances
- checkbox()
- hidden()
- No features added
New features added in version 1.52
- Added backslashing, quotation marks, and other shell-style escape sequences to the parameters passed in during debugging off-line.
- Changed the way that the hidden() method works so that the default value always overrides the current one.
- Improved the handling of sticky values in forms. It's now less likely that sticky values will get stuck.
- If you call server_name(), script_name() and several other methods when running offline, the methods now create "dummy" values to work with.
Bugs fixed in version 1.51
- param() when called without arguments was returning an array of length 1 even when there were no parameters to be had. Bad bug! Bad!
- The HTML code generated would break if input fields contained the forbidden characters ">< or &. Вы можете now use these characters freely.
New features added in version 1.50
- import() method allows all the parameters to be imported into a namespace in one fell swoop.
- Parameters are now returned in the same order in which they were defined.
Bugs fixed in version 1.45
- delete() method didn't work correctly. This is now fixed.
- reset() method didn't allow you to set the name of the button. Fixed.
Bugs fixed in version 1.44
- self_url() didn't include the path information. This is now fixed.
New features added in version 1.43
- Added the delete() method.
New features added in version 1.42
- The image_button() method to create clickable images.
- A few bug fixes involving forms embedded in <PRE> blocks.
New features added in version 1.4
- New header shortcut methods
- redirect() to create HTTP redirection messages.
- start_html() to create the HTML title, complete with the recommended <LINK> tag that no one ever remembers to include.
- end_html() for completeness' sake.
- A new save() method that allows you to write out the state of an script to a file or pipe.
- An improved version of the new() method that allows you to restore the state of a script from a file or pipe. With (2) this gives you dump and restore capabilities! (Wow, вы можете put a "121,931 customers served" banner at the bottom of your pages!)
- A self_url() method that allows you to create state-maintaining hypertext links. В дополнение к allowing you to maintain the state of your scripts between invocations, this lets you work around a problem that some browsers have when jumping to internal links in a document that contains a form -- the form information gets lost.
- The user-visible labels в выключателях, переключателях, popup menus и списках с возможностью прокрутки have now been decoupled from the values sent to your CGI script. Your script can know a checkbox by the name of "cb1" while the user knows it by a more descriptive name. I've also added some parameters that were missing from the text fields, such as MAXLENGTH.
- A whole bunch of methods have been added to get at environment variables involved in user verification and other obscure features.
Bug fixes
- The problems with the hidden fields have (I hope at last) been fixed.
- Вы можете create multiple query objects and they will all be initialized correctly. This simplifies the creation of multiple forms on one page.
- The URL unescaping code works correctly now.
Линкольн Д. Штейн, lstein@cshl.org
Cold Spring Harbor Laboratory