Document.pm

NAME Communiware::Document

SYNOPSYS

        my $doc = new Communiware::Document(protocol=>'HTTP', request=>$req);
        $doc->charset($document_item_charset);
        exec_template($doc, $template_name);
        $doc->header->prepare($apache);
        $apache->send_http_header;
        $apache->print($doc->content);

in exec_template:

        $doc->set_content($content);

in the handler of DE MailTo:

        my $doc = new Communiware::Document(protocol=>'Email', request=>$req);
        $doc->charset($needed_charset);
        exec_template($doc, $template_name);
        $doc->convert('text/plain') if ...;
        ...
        print SENDMAIL $doc->header->as_text, $doc->content;

in Context::document with argument:

        $doc->update_last_modified($self->get('LASTCHANGE'));

DESCRIPTION

Объект Communiware::Document - это один из ответов на запрос. У документа есть заголовок, соответствующий протоколу, по которому ответ будет отдан (Communiware::Header::HTTP, Communiware::Header::Email) и тело.

Все методы, у которых явно не указано возвращаемое значение, возвращают себя. Для выстраивания в цепочки.

new

        $doc = new Communiware::Document($protocol);

Создает новый документ с заголовком, рассчитанным на отдачу по протоколу $protocol (на данный момент поддерживаются 'HTTP' и 'Email').

clone

        $new_doc = $doc->clone;

Копирующий конструктор. Полезен перед convert, если хочется сохранить оригинал.

set_header

        $doc->set_header($header_name, $content);

Враппер к методу set заголовка. Устанавливает заголовок С<$header_name> в значение $content. Предыдущее значение, если было, удаляется.

add_header

        $doc->add_header($header_name, $content);

Враппер к методу add заголовка. Добавляет заголовок $header_name со значением $content. Если заголовок $header_name может быть в одном ответе в нескольких экземплярах (или иметь несколько значений), появится дополнительный заголовок (дополнительное значение), если нет - будет переписан имевшийся.

remove_header

        $doc->remove_header($header_name);

Враппер к методу remove заголовка. Удаляет все заголовки с именем $header_name.

clear_headers

        $doc->clear_headers;

Враппер к методу clear заголовка. Чистит заголовок в девственное состояние.

set_content

        $doc->set_content($content);

Делает содержимое документа (семантически) равным $content. Вообще говоря, результат метода content может не совпадать с $content (charset).

add_to_content

        $doc->add_to_content($content_chunk);

Добавляет к содержимому документа $content_chunk. Добавление может различаться в зависимости от MIME-типа (так, для HTML может добавлять перед закрывающим тегом элемента BODY).

update_last_modified

        $doc->update_last_modified($new_last_modified);

Освежает момент последнего изменения документа (т.е. если переданное время больше текущего момента последнего изменения, оно становится текущим). Аргумент в формате коммуниверной даты.

charset

        $charset = $doc->charset([$charset]);

Возвращает кодировку документа. Если вызван с аргументом $charset, предварительно ее устанавливает в указанное значение, что может повлечь изменение содержимого и заведомо повлечет изменение заголовка.

type

        $mime_type = $doc->type([$mime_type]);

Возвращает MIME-тип документа. Если вызван с аргументом $mime_type, предварительно его устанавливает в указанное значение, что повлечет изменение заголовка. Менять тип документу с заполненным содержимым нельзя.

convert

        $doc->convert($mime_type);

Преобразует документ в MIME-тип $mime_type. Вообще говоря, с потерей форматирования.

content

        $content = $doc->content;

Возвращает содержимое документа. Это содержимое, вообще говоря, не совпадает с тем, что было выставлено set_content, поэтому перед выдачей ответа клиенту следует провести цикл set_content-content.

header

        $header = $doc->header;

Возвращает объект заголовка.

request

        $request = $doc->request;

Возвращает объект запроса, в ответ на который создается данный документ.

content_type

        $self->header->set('Content-Type',$self->content_type);

Returns correct MIME content-type for given mime-type and charset.

DOCUMENT PREPARATION FUNCTIONS

Following methods are not methods of Document object. They are just functions which perform document making.

escapeHTML

escapeHTML(string)

Escapes some dangerous symbols into HTML entities.

escapeURI

escapeURI(string)

Escapes some symbols as %hexcode

tag

        tag($name,{attr=>value,attr->value},$content)

Constructs HTML element. 


=cut

sub tag {
my ($elem, $attrs, $content) = @_;
$content ||= '';
        # Make head
        my $out = "<$elem";
        while (my ($attr, $val) = each %$attrs) {
                next unless $attr;
                $val = '' unless defined $val;
                $val = untag_html($val, 'a') unless lc(substr($attr, 2, 0) eq 'on');
                $out .= " $attr=\"$val\"";
        }
        if ($HTML::Tagset::emptyElement{$elem}) {
                $out .= "/>";
        }
        else {
                $out .= ">$content</$elem>";
        }
        return $out;
}
        
=head2 hidden_field
 $html = hidden_field ($name,$value)

Because Communiware excessively uses <input type=hidden> in its interactive parts, special helper procedure is provided to generate this particular tag.

It gets just two args - name of input element, and its value or list of values.

popup_menu

  $html = popup_menu($name,$choices,$value_col,$label_col,$def_val,%options)

Generates HTML <select> tag with name $name and list of options from the $choices which should be reference to list of hashes just like Communiware::Filter::fetchall_arrayref returns.

Names of hash elements which should be used as values and labels are passed as two subsequent parameters.

Next parameter should be default value (no element would be marked as SELECTED if this value is undefined), and rest of parameters is interpreted as hash of options to pass to select tag.

untag_html

See Communiware::Format::untag_html

format

        $formatted_text = $doc->format(\@values, \@type, $format);
        $formatted_text = $doc->format(\@values, \@type, 
                {DATE=>$strftime_format, STRING=>$sprintf_format, ...});

Converts @values to visual representation according to their @type. Usually @values and @type are results of a call to context's get_typed. Merges list of formatted values, if there is list, by commas.

Default values for formats are `%s' for strings, `%g' for numbers, `%c' for dates and `p' for richtexts. Scalar format means same value for all types.

Takes into account accuracy of dates, added to their type as third element.

html_error_out

        html_error_out($error_message)

Constructs HTML element span with class formError and puts content into it. May be used dynamic elements to put errors directly to generated html. 


=cut

sub html_error_out { tag('span', {class=> 'formError'}, join(q{}, '[', @_, ']')); }

html_warn_out

        html_warn_out($warning_message)

Constructs HTML element span with class formError and puts content into it. May be used dynamic elements to put warning messages directly to generated html. 


=cut

sub html_warn_out { tag('span', {class=> 'formError'}, join(q{}, '[', @_, ']')); }

1;

16 октябрь 2007 13:44