Отображение контента во фронт офисе

Опубликовано alex1cОпубликовано в рубрике prestashop, Руководство разработчика PrestaShop, Русская документация PrestaShop 1.6, Создание модулей PrestaShop

Отображение контента во фронт офисе

Как бы то ни было, модуль мало что делает. Чтобы отобразить что-то во фронт офисе, мы должны добавить поддержку нескольких хуков. Это делается путем реализации методов хуков, и это было фактически сделано в методе install(), который мы писали ранее, используя метод registerHook():

public function install()
{
  if (Shop::isFeatureActive())
    Shop::setContext(Shop::CONTEXT_ALL);
  return parent::install() &&
    $this->registerHook('leftColumn') &&
    $this->registerHook('header') &&
    Configuration::updateValue('MYMODULE_NAME', 'my friend');
}

Как вы можете видеть, мы делаем так, чтобы модуль подключался к хукам «leftColumn» и «header«. В дополнение к этому, мы добавим код для хука «rightColumn» .

Для привязки кода к хуку требуется специальный метод для каждого:

  • hookDisplayLeftColumn(): перехватит код в левом столбце — в нашем случае он выберет MYMODULE_NAME модуль и отобразит файлы шаблона модуля, mymodule.tpl, которые должны быть расположены в папке /views/templates/hook/ .
  • hookDisplayRightColumn(): будет просто делать то же самое, что hookDisplayLeftColumn(), но для правой колонки.
  • hookDisplayHeader(): добавит ссылку на файл CSS модуля, /css/mymodule.css
public function hookDisplayLeftColumn($params)
{
  $this->context->smarty->assign(
      array(
          'my_module_name' => Configuration::get('MYMODULE_NAME'),
          'my_module_link' => $this->context->link->getModuleLink('mymodule', 'display')
      )
  );
  return $this->display(__FILE__, 'mymodule.tpl');
}
  
public function hookDisplayRightColumn($params)
{
  return $this->hookDisplayLeftColumn($params);
}
  
public function hookDisplayHeader()
{
  $this->context->controller->addCSS($this->_path.'css/mymodule.css', 'all');
}  

Мы используем контекст ($this->context) изменить переменную Smarty: assign() метод Smarty позволяет нам установить переменную имени шаблона со значением MYMODULE_NAME сохраненную в таблице базы данных конфигурации.

header хук не является частью визуального заголовка, но позволяет нам вводить код в <head> тег сгенерированного файла HTML. Это очень полезно для файлов JavaScript или CSS. Чтобы добавить ссылку на наш CSS-файл на странице <head> тег, мы используем метод addCSS(), который генерирует правильные <link> теги в файле CSS, указанном в параметрах.

Сохраните файл, и вы уже можете подключить шаблон своего модуля к теме, переместить его и подключить (хотя на данный момент нет файла шаблона): перейдите на страницу «Позиции» в меню «Модули» и затем нажмите кнопку «Добавить модуль» (вверху справа).

В форме добавления:

  1. Найдите «My module» в «Module» выпадающем списке.
  2. Выберите «(displayLeftColumn) блоке левой колонки» в «Hook into» выпадающем списке.
  3. Жмите»Сохранить».

Бесполезно пытаться присоединить модуль к хуку, для которого не реализован метод.

Страница «Позиции» должна перезагрузиться со следующим сообщением: «Модуль подключен успешно» (или, возможно, «этот модуль уже был подключен к хуку»). Поздравляем! Прокрутите страницу «Позиции», и вы действительно должны увидеть свой модуль среди других модулей в списке «Левая колонка». Переместите его в верхнюю часть списка, перетащив строку модуля.

Модуль теперь прикреплен к левому столбцу … но без какого-либо шаблона для отображения не делает ничего полезного: если вы перезагрузите главную страницу, левый столбец просто отобразит сообщение, где должен быть модуль, говоря «Шаблон не найден для модуля mymodule ‘.

Отображение контента

Теперь, когда у нас есть доступ к левому столбцу, мы должны отобразить что-то там, чтобы клиент мог видеть.

Видимая часть модуля определена в .tpl файлах, помещенных в определенные папки видов:

  • /views/templates/front/: front office features.
  • /views/templates/admin/: back office features.
  • /views/templates/hook/: features hooked to a PrestaShop (so can be displayed either on the front office or the back office).

Файлы шаблонов могут иметь любое имя. Это один файл и хорошая практика, дать ему то же имя, что и папка и основной файл: mymodule.tpl.

В этом уроке модуль будет подключен к левому столбцу. Поэтому файлы TPL, вызываемые из хука столбца, должны быть помещены в /views/templates/hook/ для правильной работы.

 

Как было сказано ранее, контент, который будет отображаться в теме, должен храниться в .tpl файлах шаблонов, помещенных в папку: /views/templates/front/. Файлы шаблонов могут иметь любое имя. Это один файл и хорошая практика, дать ему то же имя, что и папка и основной файл: mymodule.tpl.

Мы создадим файл mymodule.tpl , который будет передан как параметр в метод display() в коде нашего модуля в метод hookDisplayHome() . При вызове шаблона из хука PrestaShop ищет этот файл шаблона в папке /views/templates/hook/ (в папке модуля), которую вы должны создать самостоятельно.

В PrestaShop 1.4 файлы шаблонов модуля должны были помещаться в корень папки модуля.

По соображениям совместимости файлы шаблонов все еще могут находиться в корневой папке в PrestaShop 1.5 и 1.6, хотя теперь рекомендуются подпапки /views/templates/. Если вы хотите, чтобы ваш модуль также работал в PrestaShop 1.4, вы должны хранить файлы в корне.

Вот наш файл шаблона, расположенный по адресу /views/templates/hook/mymodule.tpl:

mymodule.tpl
<!-- Block mymodule -->
<div id="mymodule_block_home" class="block">
  <h4>Welcome!</h4>
  <div class="block_content">
    <p>Hello,
       {if isset($my_module_name) && $my_module_name}
           {$my_module_name}
       {else}
           World
       {/if}
       !       
    </p>   
    <ul>
      <li><a href="{$my_module_link}" title="Click this link">Click me!</a></li>
    </ul>
  </div>
</div>
<!-- /Block mymodule -->

Это обычный код HTML … за исключением нескольких вызовов Smarty:

  • Код {l s='xxx' mod='yyy'} вызов — это специфичный для PrestaShop метод, который позволяет вам зарегистрировать строку на панели перевода модуля. Параметр s это строка, в то время как параметр mod должен содержать идентификатор модуля (в данном случае, «mymodule«). Мы используем этот метод только здесь для удобства чтения, но на практике его следует использовать во всех строках шаблона.
  • Код {if}, {else} и {/if} — это условные выражения Smarty. В нашем примере мы проверяем, что $my_module_name Smarty переменная существует (используя код функции PHP isset() ) и что она не пуста. Если все будет хорошо, мы отобразим содержимое этой переменной; если нет, мы показываем «Мир», чтобы увидеть «Hello World».
  • Переменная {$my_module_link} в ссылке href атрибута: это переменная Smarty, которую мы создадим позже, укажет на корневой каталог PrestaShop.

В дополнение к этому мы создадим файл CSS и сохраним его как /css/mymodule.css в папке модуля (или в любой подпапке, в которой вы хотите сохранить CSS):

div#mymodule_block_home p {
  font-size: 150%;
  font-style:italic;
}

Сохраните файл шаблона в папке модуля /views/templates/hook/ и файл CSS в папке /css/ , перезагрузите домашнюю страницу своего магазина: содержимое шаблона должно появиться поверх левого столбца, прямо под логотипом магазина (если вы действительно переместили его вверху хука «Левая колонка» во время включения).

Как вы можете видеть, тема применяет собственный CSS к добавляемому шаблону:

  • Наш <h4> Title становится заголовком блока, созданным так же, как и другие названия блоков.
  • Наш <div class="block_content"> блок имеет тот же стиль, что и другие блоки на странице.

Это не очень, но работает так, как мы этого хотим.

Отключить кеш

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

Smarty кэширует скомпилированную версию домашней страницы по соображениям производительности. Это очень полезно для промышленных сайтов, но бесполезно для сайтов тестирования, где вы можете перегружать страницу регулярно, чтобы увидеть влияние ваших изменений.

При редактировании или отладке темы на тестовом сайте вы всегда должны отключать кеш, чтобы заставить Smarty перекомпилировать шаблоны при каждой загрузке страницы.
С этой целью перейдите в меню «Расширенные параметры», выберите страницу «Производительность», затем в разделе «Smarty»:

  • Кэш шаблонов. Выберите «Disable the cache».
  • Кеш. Отключите его.
  • Отладочная консоль. Вы также можете открыть консоль, если хотите узнать больше о внутренних функциях Smarty.

НЕ отключайте кеш и не включайте консоль отладки на промышленном сайте, так как это сильно замедляет его!
Вы всегда должны выполнять все свои тесты на тестовом сайте, в идеале, на своем собственном компьютере, а не в Интернете.

Подключение шаблона к теме

Ссылка, отображаемая модулем, пока не ведет никуда. Давайте создадим файл display.php с минимальным содержимым и поместим его в корневую папку модуля.

display.php
Welcome to this page!

Нажмите «Click me!». Link: результирующая страница — это только необработанный текст, без чего-либо из темы. Мы хотели бы, чтобы этот текст был встроен в тему, поэтому давайте посмотрим, как это сделать.

Как и следовало ожидать, мы должны создать файл шаблона, чтобы использовать стиль темы. Давайте создадим файл display.tpl который будет содержать основные «Welcome to my shop!» строки, и будет вызван display.php. Этот файл display.php  будет переписан в интерфейсный контроллер, чтобы правильно внедрить наш основной шаблон в заголовок, колонтитул темы, столбцы и т.д.

Вы должны стремиться использовать явные и узнаваемые имена для ваших файлов шаблонов, чтобы их можно было быстро найти в бэк-офисе, что полезно при использовании инструмента перевода.

Вот два наших файла:

display.php
<?php
class mymoduledisplayModuleFrontController extends ModuleFrontController
{
  public function initContent()
  {
    parent::initContent();
    $this->setTemplate('display.tpl');
  }
}
display.tpl
Welcome to my shop!

Давайте исследовать display.php, наш первый контроллер PrestaShop, хранящийся в папке /controllers/front основной папки модуля:

  • Контроллер фроненда должен быть классом, который расширяет класс ModuleFrontController.
  • Этот контроллер должен иметь один метод: initContent(), Который вызывает метод родительского класса initContent() …
  • …который затем вызывает метод setTemplate() с нашим display.tpl файлом.

setTemplate() это метод, который позаботится о встраивании нашего однострочного шаблона в полномасштабную страницу с правильным заголовком, нижним колонтитулом и боковыми панелями.

До PrestaShop 1.4 разработчики, которые хотели внедрить шаблонный файл в тему сайта, должны были использовать PHP include() вызывающий включение каждой части страницы. Вот эквивалентный код для display.php:

display.php
<?php
// This file must be placed at the root of the module's folder.
global $smarty;
include('../../config/config.inc.php');
include('../../header.php');
$smarty->display(dirname(__FILE__).'/display.tpl');
include('../../footer.php');
?>

Как вы можете видеть, это уже не нужно, поскольку в PrestaShop 1.5: вы можете и должны использовать внешний контроллер, и оба контроллера (Controller) и его шаблон (View) должны иметь одно и то же имя: display.php привязан к display.tpl.

Сохраните оба файла в соответствующих папках и перезагрузите домашнюю страницу своего магазина, затем нажмите «Click me!» и voilà ! У вас есть ссылка. Всего лишь несколько строк, конечный результат уже намного лучше, при этом строка «Добро пожаловать» аккуратно помещается между заголовком, нижним колонтитулом и столбцами!

Это только первый шаг, но это дает вам представление о том, что возможно сделать, если вы будете следовать правилам включения шаблонов.

Использование Smarty

Smarty — это механизм шаблонов PHP, который используется в системе PrestaShop. Это бесплатный проект с открытым исходным кодом, размещенный в http://www.smarty.net/.

Он анализирует файлы шаблона .tpl , ищет динамические элементы для замены их контекстуальными эквивалентами, а затем отправляет сгенерированный результат в браузер. Эти динамические элементы обозначены фигурными скобками: { ... }. Программисты могут создавать новые переменные и использовать их в файлах TPL; PrestaShop добавляет собственный набор переменных.

Например, мы можем создать переменную $my_module_message в PHP прямо в методе hookDisplayLeftColumn() , и отобразить ее в нашем файле шаблона:

mymodule.php
public function hookDisplayLeftColumn($params)
{
    $this->context->smarty->assign(
        array(
            'my_module_name' => Configuration::get('MYMODULE_NAME'),
            'my_module_link' => $this->context->link->getModuleLink('mymodule', 'display'),
            'my_module_message' => $this->l('This is a simple text message') // Do not forget to enclose your strings in the l() translation method
        )
    );
    
    return $this->display(__FILE__, 'mymodule.tpl');
}

Оттуда мы можем попросить Smarty отобразить содержимое этой переменной в нашем файле TPL.

mymodule.tpl
{$my_module_message}

PrestaShop добавляет собственный набор переменных. Например, {$hook_left_column} будет заменен содержимым для левого столбца, что означает контент из всех модулей, которые были прикреплены к хуку левого столбца.

Все переменные Smarty являются глобальными. Поэтому вы должны обратить внимание на совпадение имени своей переменной с именем существующей переменной Smarty, чтобы избежать ее перезаписи. Хорошая практика — избегать слишком простых имен, таких как {products}, и дополнить префиксом вашего модуля или даже вашим собственным именем или инициалами, например: {$henryb_mymodule_products}.

Вот список переменных Smarty, которые являются общими для всех страниц:

Файл / папка

Описание
img_ps_dir URL for PrestaShop’s image folder.
img_cat_dir URL for the categories images folder.
img_lang_dir URL for the languages images folder.
img_prod_dir URL for the products images folder.
img_manu_dir URL for the manufacturers images folder.
img_sup_dir URL for the suppliers images folder.
img_ship_dir URL for the carriers (shipping) images folder.
img_dir URL for the theme’s images folder.
css_dir URL for the theme’s CSS folder.
js_dir URL for the theme’s JavaScript folder.
tpl_dir URL for the current theme’s folder.
modules_dir URL the modules folder.
mail_dir URL for the mail templates folder.
pic_dir URL for the pictures upload folder.
lang_iso ISO code for the current language.
come_from URL for the visitor’s origin.
shop_name Shop name.
cart_qties Number of products in the cart.
cart The cart.
currencies The various available currencies.
id_currency_cookie ID of the current currency.
currency Currency object (currently used currency).
cookie User cookie.
languages The various available languages.
logged Indicates whether the visitor is logged to a customer account.
page_name Page name.
customerName Client name (if logged in).
priceDisplay Price display method (with or without taxes…).
roundMode Rounding method in use.
use_taxes Indicates whether taxes are enabled or not.

Есть много других контекстных хуков. Если вам нужно отобразить все переменные Smarty текущей страницы, добавьте следующий вызов:

{debug}

Комментарии основаны на звездочке:

{* This string is commented out *}
{*
This string is too!
*}

В отличие от комментариев в HTML, код Smarty отсутствует в окончательном выходном файле.