Вопрос по сайту (площадке), который Вы намерены добавить в систему

Необходимое окружение

Для работы Perl-модуля требуется наличие следующих сторонних модулей, доступных в библиотеке CPAN или в виде пакетов для большинства ОС:

• JSON (также рекомендуется JSON::XS)
• LWP::UserAgent
• MIME::Base64

Установка из CPAN:

perl -MCPAN -e shell

cpan> install JSON
cpan> install JSON::XS
cpan> install LWP::UserAgent
cpan> install MIME::Base64

Установка из пакетов Debian:

apt-get install libjson-perl libjson-xs-perl libmime-base64-perl libwww-perl

Подключение модуля (обязательный шаг)

Для подключения модуля SAPE необходимо разместить в исходном коде вашего сайта следующий Perl-код:

"$ENV{DOCUMENT_ROOT}/ХЕШ_ПОЛЬЗОВАТЕЛЯ/SAPE.pm" =~ /^(.+)$/;
require $1;

Сразу после этого становятся доступны классы SAPE::Client и SAPE::Context, отвечающие за вывод, соответственно, гипертекстовых ссылок (в том числе в блочном формате) и контекстных ссылок.

Вывод гипертекстовых ссылок

Для работы с гипертекстовыми ссылками используется класс SAPE::Client:

my $sape = new SAPE::Client;

Список допустимых аргументов конструктора класса (все аргуменыты необязательыне):

my $sape = new SAPE::Client (
   user => '', # хэш пользователя, по умолчанию определяется из пути к модулю
   host => '', # имя хоста сайта, по умолчанию $ENV{HTTP_HOST}
   request_uri => '', # адрес запрашиваемой страницы, по умолчанию $ENV{REQUEST_URI}
   multi_site => 1, # включить поддержку нескольких сайтов в одной директории
   verbose => 1, # выводить ошибки в HTML-код
   charset => '', # кодировка: windows-1251 (по умолчанию), utf8, koi8-r и т.д.
   socket_timeout => 6, # таймаут при получении данных от сервера SAPE
   force_show_code => 1, # всегда показывать код SAPE (иначе видно только роботу)
   db_dir => '', # директория для файлов данных, по умолчанию директория с модулем
   ignore_case => 1, # регистронезависимый режим работы - на свой страх и риск!
   show_counter_separately => 1, # показывать ли JS-код отдельно от ссылок
);

Вывод ссылок в обычном формате

Для получения простого (не блочного) списка ссылок следует вызывать метод return_links():

my $links = $sape->return_links; # сохранить HTML-код ссылок в переменную $links
                                 # для использования, например, в шаблонизаторе

или, к примеру:

print $sape->return_links; # вывести HTML-код ссылок

Список допустимых аргументов метода return_links (все аргументы необязательные):

$sape->return_links(
   $n, # число выводимых ссылок, undef - все ссылки
   as_block => 1, # вызвать return_block_links с теми же параметрами
);

Пример 1: вывод всех ссылок

$sape->return_links(undef); # то же, что и $sape->return_links, - вывести все ссылки

Пример 2: вывод нескольких ссылок

$sape->return_links(1); # вернуть только 1 ссылку
$sape->return_links(3); # вернуть ещё 3 ссылки
$sape->return_links; # вернуть оставшиеся ссылки

Пример 3: вывод ссылок в блочном формате (см. ниже)

$sape->return_links(undef, as_block => 1); # аналог вызова метода return_block_links

Вывод ссылок в блочном формате

Для вывода ссылок в блочном виде используется метод return_block_links() (вызывается автоматически из return_links(), если в настройках сайта установлено блочное отображение или передан параметр as_block => 1).
Список допустимых аргументов метода return_block_links() (все аргументы необязательные):

$sape->return_block_links(
   $n, # число выводимых ссылок, undef - все ссылки
   block_no_css => 1, # запретить автоматический вывод CSS в коде страницы
   block_orientation => 1, # ориентация блока: 1 - горизонтальная, 0 - вертикальная
   block_width => 'auto', # ширина блока в CSS: 'auto', '[?]px', '[?]%' и т.д.
);

Пример 4: вывод всех ссылок в блочном формате

$sape->return_block_links; # все ссылки в виде одного блока

Пример 5: вывод ссылок в нескольких блоках

$sape->return_block_links(1); # вернуть только 1 ссылку в первом блоке
$sape->return_block_links; # вернуть оставшиеся ссылки во втором блоке

Пример 6: вывод блока ссылок с изменёнными параметрами

$sape->return_block_links(2, block_orientation => 0, block_width => '120px');
     # вернуть блок из 2 ссылок вертикальной ориентации шириной 120 пикселей

Вывод контекстных ссылок

Для работы с контекстными ссылками используется класс SAPE::Context:

my $sape_ctx = new SAPE::Context;

Список допустимых аргументов конструктора класса – тот же, что и у SAPE::Client.

Ссылки в конкретном фрагменте текста

Для вывода контекстных ссылок в определённом фрагменте текста следует вызывать метод replace_in_text_segment(), передавая в качестве параметра либо ссылку (ref) на переменную с текстом (оптимально для экономии памяти, замена будет произведена прямо внутри переменной), либо просто переменную с текстом (в этом случае текст с заменой будет возвращён в качестве результата вызова функции):

$sape_ctx->replace_in_text_segment(\$text); # все изменения - внутри переменной

или

$new = $sape_ctx->replace_in_text_segment($text); # изменения - в новую переменную

Рекомендуется использовать первый способ, если есть такая возможность.

Ссылки в коде страницы

Для вывода контекстных ссылок в пределах всей страницы, в том числе в нескольких местах на странице, следует вручную расставить в исходном коде страницы теги <sape_index> ... </sape_index>, заключив в них фрагменты страницы для вывода ссылок, либо ссылки будут выводиться внутри тега <body> ... </body>.

Существует два режима работы метода replace_in_page(), используемого для вывода ссылок.
 

1. Рекомендуется! Вызов метода с параметром аналогично вызову replace_in_text_segment() (ссылка на переменную для экономии памяти или просто переменная). Поиск тегов <sape_index> или <body> и вывод ссылок происходит в тексте, переданном в качестве параметра.

$sape_ctx->replace_in_page(\$html); # все изменения - внутри переменной

или

$new = $sape_ctx->replace_in_page($html); # изменения - в новую переменную

Разница между методами replace_in_text_segment() и replace_in_page() в том, что в первый передаются фрагменты текста для установки контекстных ссылок в них, а во второй – полностью HTML-документ с блоками <sape_index> ... </sape_index> или <body> ... </body>, причём автоматический вывод счётчика производится только в функции replace_in_page() (см. ниже).

2. Только для сайтов с CGI. Вызов метода без параметров. Переопределяется системная Perl-функция print, весь выводимый в ходе работы кода вашего сайта контент накапливается в буфере, происходит размещение ссылок внутри буфера и их вывод системными средствами.

$sape_ctx->replace_in_page; # переопределить print
print $html; # вывод кода страницы со ссылками - после окончания работы скрипта

Этот формат вызова реализован по аналогии с официальным клиентским кодом для платформы PHP, однако с ограничениями:

• не работает в mod_perl,
• может не работать в FastCGI,
• выводит полученный текст только по окончании работы скрипта, а не порциями, – этот режим не рекомендуется и реализован лишь для совместимости с модулем на PHP.

Вывод обязательного JavaScript-контента

Оба класса – SAPE::Client и SAPE::Context – поддерживают автоматический или принудительный вывод JavaScript-контента, поставляемого Sape (cчётчик Sape для подсчёта SapeRank, пользовательские счётчики). По умолчанию код JS выводится вместе со ссылками в методах класса SAPE::Client и только в методе replace_in_page() класса SAPE::Context. Однако если передан параметр show_counter_separately => 1 в конструктор класса, то счётчик необходимо выводить явным вызовом функции return_counter():

$counter_html = $sape->return_counter; # код счётчика - в переменной $counter_html

или

$counter_html = $sape_ctx->return_counter; # аналогично

Обратная связь

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

Задать вопрос разработчику клиентского кода можно напрямую на нашем форуме.