Шаблонизатор Template Toolkit

25 дек 2015

  • Описание и ссылки на документацию(top)

    В A-Parser для форматирования запросов и результатов применяется шаблонизатор Template Toolkit. Шаблонизатор позволяет формировать конечную строку(например запросов или результатов) по правилам заданным в шаблоне. Template Toolkit имеет множество возможностей:
    • Поддержка условий и циклов
    • Поддержка обычных переменных(скаляров), массивов и хешей(ассоциативных массивов)
    • Поддержка методов для переменных(длина строки, поиск и замена, размер массива...)
    • Поддержка плагинов и фильтров(вывод и форматирование даты и времени, генерация HTML элементов...)
    Большим преимущества данного шаблонизатора является наличие полноценной документации на русском и английском языках, ниже представлены ссылки на наиболее важные разделы документации:
    • Введение - общая информация
    • Синтаксис - правила и стиль написания шаблонов
    • Директивы - условия, циклы, фильтры, плагины и макросы
    • Переменные - доступ и обновление значений переменных, массивов и хешей
    • Виртуальные методы - предустановленные функции по обработке переменных, массивов и хешей
    • Плагины и Фильтры - расширенные возможности шаблонизатора, A-Parser поддерживает следующие плагины:
      • Date - для генерации форматированных строк с датами
      • Dumper - вывод дампа структуры данных
      • Format - для создания форматирующих функций на основе синтаксиса printf
      • HTML - для создания HTML элементов и экранирования HTML кода
      • Math - для использования любых математических функций
      • String - реализует дополнительные методы для работы со строками
      • Table - для представления данных в виде таблицы
      • URL - для построения ссылок
      • Wrap - для форматирования абзацев

    Инструмент тестирования шаблонов(top)

    Для быстрой проверки шаблонов в A-Parser встроен инструмент Тестирование шаблонов, он содержит предустановленные результаты для всех парсеров по тестовым запросам, что позволяет выполнять шаблон форматирования без актуального парсинга
    [​IMG]

    • Тестирование шаблонов доступно для каждого парсера отдельно, для этого необходимо выбрать предустановленный проект
    • Результаты представлены в формате JSON, что позволяет при необходимости вносить изменения в исходные данные(подробнее о JSON на WikiPedia)
    • После изменения шаблона необходимо его применить - кнопка
      Запуск в правом верхнем углу
    • Если шаблон составлен некорректно то в поле Результат появится подробная ошибка
    • Предустановленные проекты нельзя сохранять, для сохранения изменений необходимо добавить новый проект(
      )

    Особенности работы шаблонов в A-Parser(top)


    Метод .format для массивов(top)

    В парсере большинство результатов представлено в виде массивов со вложенными элементами, выражаясь техническим языком - результаты представлены в виде массива хешей, где каждый хеш имеет фиксированные ключи. Разберем пример на парсере SE::Google SE::Google, в результатах он содержит массив serp c элементами link, anchor и snippet:
    Код:
    "serp" : [
       {
          "link" : "http://www.speedtest.net/",
          "anchor" : "Speedtest.net by Ookla - The Global Broadband Speed <b>Test</b>",
          "snippet" : "<b>Test</b> your Internet connection bandwidth to locations around the world with this <br>interactive broadband speed <b>test</b> from Ookla."
       },
       {
          "link" : "http://www.speakeasy.net/speedtest/",
          "anchor" : "Speakeasy Speed <b>Test</b>",
          "snippet" : "Speakeasy Speed <b>Test</b> - Broadband Speed <b>Test</b>. Go to MegaPath Speed <b>Test</b> ... <br>02:38:36 PM Your IP: The Speakeasy Speed <b>Test</b> requires Flash v7 or higher."
       },
       {
          "link" : "http://en.wikipedia.org/wiki/Test_cricket",
          "anchor" : "<b>Test</b> cricket - Wikipedia, the free encyclopedia",
          "snippet" : "<b>Test</b> cricket is the longest form of the sport of cricket. <b>Test</b> matches are played <br>between national representative teams with &quot;<b>Test</b> status&quot;, as determined by the&nbsp;..."
       }
    ]
    

    Для удобного обхода такого массива был создан метод .format который позволяет соединять все элементы массива по определенному формату, например все ссылки через перевод строки:
    Код:
    $serp.format('$link\n')
    Что в результате сохранит каждую ссылку с новой строки:
    Код:
    http://www.speedtest.net/
    http://www.speakeasy.net/speedtest/
    http://en.wikipedia.org/wiki/Test_cricket
    
    Сниппеты:
    Код:
    $serp.format('$snippet\n')
    Код:
    [lang=ru-RU]<b>Test</b> your Internet connection bandwidth to locations around the world with this <br>interactive broadband speed <b>test</b> from Ookla.[/lang][lang=en-US][code]<b>Test</b> your Internet connection bandwidth to locations around the world with this <br>interactive broadband speed <b>test</b> from Ookla.[/lang]
    [lang=ru-RU]Speakeasy Speed <b>Test</b> - Broadband Speed <b>Test</b>. Go to MegaPath Speed <b>Test</b> ... <br>02:38:36 PM Your IP: The Speakeasy Speed <b>Test</b> requires Flash v7 or higher.[/lang][lang=en-US]Speakeasy Speed <b>Test</b> - Broadband Speed <b>Test</b>. Go to MegaPath Speed <b>Test</b> ... <br>02:38:36 PM Your IP: The Speakeasy Speed <b>Test</b> requires Flash v7 or higher.[/lang]
    [lang=ru-RU]<b>Test</b> cricket is the longest form of the sport of cricket. <b>Test</b> matches are played <br>between national representative teams with &quot;<b>Test</b> status&quot;, as determined by the&nbsp;...[/lang][lang=en-US]<b>Test</b> cricket is the longest form of the sport of cricket. <b>Test</b> matches are played <br>between national representative teams with &quot;<b>Test</b> status&quot;, as determined by the&nbsp;...[/lang]
    
    Ссылки, анкоры и сниппеты одновременно:
    Код:
    $serp.format('Link: $link, Anchor: $anchor, Snippet: $snippet\n')
    Код:
    [lang=ru-RU]Link: http://www.speedtest.net/, Anchor: Speedtest.net by Ookla - The Global Broadband Speed <b>Test</b>, Snippet: <b>Test</b> your Internet connection bandwidth to locations around the world with this <br>interactive broadband speed <b>test</b> from Ookla.[/lang][lang=en-US]Link: http://www.speedtest.net/, Anchor: Speedtest.net by Ookla - The Global Broadband Speed <b>Test</b>, Snippet: <b>Test</b> your Internet connection bandwidth to locations around the world with this <br>interactive broadband speed <b>test</b> from Ookla.[/lang]
    [lang=ru-RU]Link: http://www.speakeasy.net/speedtest/, Anchor: Speakeasy Speed <b>Test</b>, Snippet: Speakeasy Speed <b>Test</b> - Broadband Speed <b>Test</b>. Go to MegaPath Speed <b>Test</b> ... <br>02:38:36 PM Your IP: The Speakeasy Speed <b>Test</b> requires Flash v7 or higher.[/lang][lang=en-US]Link: http://www.speakeasy.net/speedtest/, Anchor: Speakeasy Speed <b>Test</b>, Snippet: Speakeasy Speed <b>Test</b> - Broadband Speed <b>Test</b>. Go to MegaPath Speed <b>Test</b> ... <br>02:38:36 PM Your IP: The Speakeasy Speed <b>Test</b> requires Flash v7 or higher.[/lang]
    [lang=ru-RU]Link: http://en.wikipedia.org/wiki/Test_cricket, Anchor: <b>Test</b> cricket - Wikipedia, the free encyclopedia, Snippet: <b>Test</b> cricket is the longest form of the sport of cricket. <b>Test</b> matches are played <br>between national representative teams with &quot;<b>Test</b> status&quot;, as determined by the&nbsp;...[/lang][lang=en-US]Link: http://en.wikipedia.org/wiki/Test_cricket, Anchor: <b>Test</b> cricket - Wikipedia, the free encyclopedia, Snippet: <b>Test</b> cricket is the longest form of the sport of cricket. <b>Test</b> matches are played <br>between national representative teams with &quot;<b>Test</b> status&quot;, as determined by the&nbsp;...[/lang]
    
    В формате также можно использовать исходный запрос, что позволяет задать соответствие запрос - каждый элемент массива:
    Код:
    $serp.format('$query: $link\n')
    
    Код:
    test: http://www.speedtest.net/
    test: http://www.speakeasy.net/speedtest/
    test: http://en.wikipedia.org/wiki/Test_cricket
    

    Доступные переменные(top)


    При выполнении шаблона доступны следующие переменные:

    Дополнительные варианты использования шаблонов(top)

    Шаблоны при фильтрации результатов [​IMG]
    Проверка нахождения в ссылке исходного запроса как файла(исключает любые другие вхождения, например папки /index.php/)
    Шаблоны при использовании опции Parse custom result[​IMG]
    Сбор следующих 2ух слов в сниппетах идущих после запроса
    Обратите внимание что при фильтрации результатов и в опции Parse custom result отключена интерполяция переменных через символ $, шаблон необходимо указывать явно через теги [% %]

    Интерполяция переменных(top)

    По умолчанию шаблоны записываются между тегами [% и %], все что за пределами тегов - обычный текст, который будет передан в результат как есть
    • В A-Parser дополнительно включена интерполяция переменных, что позволяет обращаться к переменным в тексте через символ $
    • Помимо этого также интерполируется \n как явный перенос строки
    Пример:
    Код:
    Всего результатов по запросу $query: $totalcount\n
    
    На место $query и $totalcount подставятся значения соответствующих переменных, \n заменится на перенос строки
    Эквивалентная запись без использования интерполяции:
    Код:
    Всего результатов по запросу [% query %]: [% totalcount; "\n" %]
    

    Обратите внимание что в шаблонах переменные записываются без префикса $

    Настройка предустановленных макросов(top)

    В A-Parser можно настроить макросы и предустановленные переменные, которые будут доступны глобально для всех шаблонов, указать глобальные макросы можно в Настройки -> Дополнительные настройки:[​IMG]
    По умолчанию там уже содержится предопределение объекта $datefile, который используется для форматирования времени для имени файла результата