[Админам]

Introduction

Starting with vB4, templates no longer get output using eval:

PHP Code:

eval('$mytemplate = "' . fetch_template('mytemplate') . '";'); 


is outdated.
What's more: Variables and arrays from plugins that are executed on a page no longer can automatically be accessed in the templates of that page. They need to be registered first.

Basic functionality to render templates and register all variables/arrays you want to use inside

PHP Code:

/* Some Code, setting variables, (multidimensional) array */
$my_var = "abc";
$my_array = array(
        'key1' => 'value1',
        'key2' => array(' 
                'key21' => 'value21',
                'key22' => 'value22'
        ')
    );

/* render template and register variables */
$templater = vB_Template::create('mytemplate');
    $templater->register('my_var', $my_var);
    $templater->register('my_array', $my_array);
$templater->render(); 


• The first line provides the template that is to be rendered, using the new vB_Template class (vB_Template::create). The method gets passed the name of the template as an argument.
• The following two lines register a variable and an array that we want to use in our template. Arguments passed are 1. the name you want to use to access the variable, and 2. the variable from the code you want to register. You can register as many variables/arrays as you want. Just remember you have to register every variable and array that you want to use in your custom template in this way. If you don't register them, they will not be available.
• The fourth line renders the template ($templater->render()).

In the template you know will be able to use the registered variables/arrays in this way:

{vb:raw my_var}
{vb:raw my_array.key1}
{vb:raw my_array.key2.key21}

Note the last one: multidimensional arrays are perfectly possible.

Now, with the result of the rendering we can do several things:

Output template directly - custom pages

PHP Code:

$templater = vB_Template::create('mytemplate');
    $templater->register_page_templates(); 
    $templater->register('my_var', $my_var);
    $templater->register('my_array', $my_array);
print_output($templater->rend 


This immediatly outputs the template. Use this if you have created your own page, for example.
Note the second line, which is special for this type of use:

PHP Code:

$templater->register_page_templates(); 


This auto-registers the page level templates header, footer and headinclude that you will use in the template of your custom page.

Use a template hook

PHP Code:

$templater = vB_Template::create('mytemplate');
    $templater->register('my_var', $my_var);
    $templater->register('my_array', $my_array);
$template_hook[forumhome_wgo_pos2] .= $templater->render(); 


The template will be shown using the choosen template hook (for example: $template_hook[forumhome_wgo_pos2]). See the dot before the = in the last line? The hook may be used by other modifications, too, so we don't want to overwrite it, but rather append our code to it, conserving everything that might already be there.

Save into a variable for later use in custom template

PHP Code:

$templater = vB_Template::create('mytemplate');
    $templater->register('my_var', $my_var);
    $templater->register('my_array', $my_array);
$mytemplate_rendered = $templater->render(); 


Now we have saved the rendered template into a variable. This variable in turn we can later on register in another template, if we want:

PHP Code:

$templater = vB_Template::create('my_other_template');
     $templater->register('my_template_rendered', $my_template_rendered);
 print_output($templater->render()); 


Again, inside my_other_template we now could call

{vb:raw my_template_rendered}

If you're running the first template call inside a loop, you may want to use .= instead of = in the last line, so that the results of every loop get added instead of overwriting the existing. But that depends, of course.

Save into an array and preregister to use in an existing/stock template

PHP Code:

$templater = vB_Template::create('mytemplate');
    $templater->register('my_var', $my_var);
    $templater->register('my_array', $my_array);
$templatevalues['my_insertvar'] = $templater->render();
vB_Template::preRegister('FORUMHOME', $templatevalues); 


• This is another, more flexible method to save the rendered template into a variable for future use in an already existing template. In this example, we want to show our own rendered template on forumhome.
• Problem is: We have no direct way to register variables for already existing templates like FORUMHOME. It's created and rendered in the files, and we don't want to mess there.
• To help with this, a new method was created for vB_Template class, called preRegister. Using this, we can pass our data to FORUMHOME before it is rendered. Note that the data needs to be saved into an array ($templatevalues['my_insertvar']), a simple variable will throw an error. In the last line the array is preregistered; you need to pass as arguments 1. the name of the existing template and 2. the array that contains the data. Again, this can be done for as many arrays as needed.
• Of course, the preRegister functionality can be used for any kind of variables or arrays, no matter whether you have saved a rendered template (like in our example) into it or it contains just a simple boolean true/false statement.

To access the data inside the template it was preregistered for use:

{vb:raw my_insertvar}

Note: it is not {vb:raw templatevalues.my_insertvar}!

Essentially the same as what I put for preRegister would be the following two lines. They could replace the last two lines in the above php codebox:

PHP Code:

$my_insertvar = $templater->render();
vB_Template::preRegister('FORUMHOME',array('my_insertvar ' => $my_insertvar)); 


Of course you could add further pairs to that array if you need to preregister more than one variable.

Bonus track: ...whatever you do, cache your templates!
Now you know how to get your templates on screen - once you succeeded in doing that, make sure to do it in a fast and ressource saving manner: make use of vB's template cache. To see whether your templates are cached or not, activate debug mode by adding $config['Misc']['debug'] = true;to your config.php (don't ever use that on your live site!). Among the debug info is a list of all templates called, and non-cached templates will show up in red.

To cache your templates, add a plugin at hook cache_templates with the following code:

PHP Code:

// for a single template
$cache[] = 'mytemplate'; 

// for more than one templates in one step
$cache = array_merge((array)$cache,array(
    'mytemplate',
    'myothertemplate',
    'mythirdtemplate'
)); 


Источник

Для тех, кому жаль колесо своей мыши - перевод статьи здесь
P.S. тема создана в этом разделе с целью её редактирования. После перевода - будет перемещена в нужный раздел!

Оперативненько! Большое спасибо!

Желающие перевести статью приглашаются в соответствующую тему

Перевод статьи
оригинал: http://vbsupport.ru/forum/showthread...ht=custom+page

От переводчика.
Некоторые части оригинального текста я считаю излишне детализированными для людей которые решились писать собственные модули или страницы под vB4. Так, например, объяснение операции «.=» … Но, коль уж автор оригинального текста сделал свою статью т.с. чайникоориентированной — я оставил некоторые заметки разъясняющие упущенные моменты.

Введение
Начиная с vB4, нет необходимости получать вывод шаблона используя ф-ю eval:

PHP Code:

eval('$mytemplate = "' . fetch_template('mytemplate') . '";'); 


данный метод устарел.

Что взамен: переменные и массивы из плагинов, которые выполняются на странице не могут быть автоматически доступны в шаблоне страницы. Вначале они должны быть зарегистрированы.

Базовый функционал рендеринга шаблонов и регистрации всех переменных/массивов, которые вы хотите использовать, выглядит следующим образом

PHP Code:

/* Некоторый код, настройки, (многоуровневый массив) array */ 
$my_var = "abc"; 
$my_array = array( 
    'key1' => 'value1', 
    'key2' => array('  
            'key21' => 'value21', 
            'key22' => 'value22' 
    ') 
); 

/* рендеринг шаблона и регистрация переменных */ 
$templater = vB_Template::create('mytemplate'); 
//Статический метод create вернет экземляр класса vB_Template.  Mytemplate — имя вашего шаблона
$templater->register('my_var', $my_var); 
//регистрируем переменные. Первый аргумент имя переменной, второй — значение.
$templater->register('my_array', $my_array); 
$templater->render(); //рендерим шаблон 


Первая строка обеспечивает доступ к шаблону, который необходимо вывести (отрендерить). Используеться конструктор класса new vB_Template (vB_Template::create). В качестве аргумента метод получает имя шаблона.
Следующие две строки регистрируют переменную и массив, которые вы хотите вывести в шаблоне. Вы можете использовать столько переменных/массивов, сколько захотите. Запомните, вы должны использовать данный метод (->register(имя, значение)) для регистрации каждой переменной или массива, которые хотите вывести в своем шаблоне. Если вы их не зарегистрируете — они не будут доступны.
Четвертая строка производит рендеринг шаблона.

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

{vb:raw my_var}
{vb:raw my_array.key1}
{vb:raw my_array.key2.key21}

Запомните еще одно: доступ к многоуровневым массивам также возможен (см. строки 3, 4).

Прим. Переводчика:
Чтобы вывести весь массив в шаблоне используйте след. код:
<vb:each from="my_array" key="name" value="value">
<p>{vb:raw src} - {vb:raw name}</p>
</vb:each>
Формально - это работает по принципу цикла

Теперь мы должны сделать несколько вещей с результатами рендеринга

Вывод шаблона на собственную страницу

PHP Code:

$templater = vB_Template::create('mytemplate'); 
$templater->register_page_templates();  
$templater->register('my_var', $my_var); 
$templater->register('my_array', $my_array); 
print_output($templater->render()); 


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

PHP Code:

$templater->register_page_templates(); 


Метод register_page_templates() автоматически регистрирует шаблоны образующие скелет страницы: шапка(header), подвал(footer) и т.н headinclude — содержимое тега head страницы

Прим. Переводчика
Для того, чтобы приведенный автором листинг заработал, необходимо проинклудить файл global.php
Т.е. для инициализации минимальной страницы создайте php-файл со след. содержимым:

PHP Code:

        require_once('./global.php');
        
        $my_var = 'Hello Word';
        
        $templater = vB_Template::create('mytemplate'); 
        $templater->register_page_templates();  
        $templater->register('my_var', $my_var); 
        print_output($templater->render()); 


Используйте hook-и для шаблона

PHP Code:

    $templater = vB_Template::create('mytemplate'); 
    $templater->register('my_var', $my_var); 
    $templater->register('my_array', $my_array); 
    $template_hook['forumhome_wgo_pos2'] .= $templater->render(); 


Шаблон может быть выведен используя hook(например: $template_hook[forumhome_wgo_pos2]). Видите точку перед знаком «=» в последней строке? Hook может быть использован вместе с другими, уже существующими, изменениями, но т. к. мы не хотим переписывать их — мы добавляем наш код в конец, сохраняя при этом все, уже имеющиеся, данные)

Прим. Переводчика
Описанная выше операция называется «конкатенация» (http://ru.wikipedia.org/wiki/%D0%9A%...86%D0%B8%D1%8F)
Существует некоторое количество переменных отвечающих за вывод таких частей страницы как header, footer, sidebar (интуитивно понятно что-есть-что; вышеупомянутый headinclude — тоже к ним относится). Чтобы добавить выводимый шаблон к этим, назовем их ключевыми, блокам страницы — необходимо сконкатенировать требуемую переменную и вывод рендеринга. Последняя строка будет иметь вид:

PHP Code:

    $headinclude .= $templater->render(); //добавляем в <head> страницы 


Если мы посмотрим в forum.php на строку 672, то увидим, как регистрируется массив $template_hook.
Здесь же отмечу, что данный метод действителен, если вы пишите плагин(модуль). Пуш данных в $template_hook для примера из "Вывод шаблона на собственную страницу" не отработает.

Сохранение результата рендеринга в переменнную для дальнейшего использования

PHP Code:

    $templater = vB_Template::create('mytemplate'); 
    $templater->register('my_var', $my_var); 
    $templater->register('my_array', $my_array); 
    $my_template_rendered = $templater->render(); 


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

PHP Code:

    $templater = vB_Template::create('my_other_template'); 
    $templater->register('my_template_rendered', $my_template_rendered); 
    print_output($templater->render()); 


Опять же, в шаблоне my_other_template мы можем использовать вызов:

{vb:raw my_template_rendered}

Если вы запустите первый шаблон внутри цикла, вы можете использовать «.=» вместо «=» (см. последнюю строку) — это соединит выводы рендеринга внутри цикла. Но, все зависит от того, какие цели вы преследуете.

Прим. Переводчика
Данный раздел, также, ориентирован на работу в плагине(модуле). Хотел бы обратить ваше внимание на систему событий расспределяющую выполнение модулей. Каждый модуль имеет поле "Местоположение модуля" - оно определяет в какой момент загрузки страницы будет запущен модуль. А работает это следующим образом:

PHP Code:

($hook = vBulletinHook::fetch_hook('hook_name')) ? eval($hook) : false; 


hook_name - есть "Местоположение модуля". vBulletinHook::fetch_hook "идет" в базу данных, забирает все модули назначенные на это "место", ставит их в порядке обозначенном в поле "Порядок выполнения" и помещает строку в eval. Т.е. инкапсуляции данных плагина нет - это означает, что любая переменная объявленная в плагине с меньшим порядковым номером будет доступна в плагине с большим порядковым номером. Сами же события, также, имеют подобную структуру: *_init, *_start, *_complete (или более широкую).

Сохранение в массив и пре-регистрация для использования в существующих/системных(existing/stock) шаблонах

PHP Code:

    $templater = vB_Template::create('mytemplate'); 
    $templater->register('my_var', $my_var); 
    $templater->register('my_array', $my_array); 
    $templatevalues['my_insertvar'] = $templater->render(); 
    vB_Template::preRegister('FORUMHOME', $templatevalues); 


Выше представлен иной, более гибкий, способ сохранения вывода рендеринга шаблона в переменную для дальнейшего использования в уже созданных шаблонах. В этом примере мы хотим вывести результат рендеринга нашего шаблона на главную страницу форума (forumhome).
Проблема состоит в том, что мы не можем зарегистрировать дополнительную переменную в уже созданном шаблоне, коим является FORUMHOME. Данное действие создается и рендерится в файлах, и мы не хотим устраивать там бардак. К нам на помощьприходит новый метод, объявленный в классе vB_Template и именуемый preRegister. Используя его мы можем передать наши данные в FORUMHOME до его рендеринга. Учтите, что данные нужно сохранить именно в массив, просто переменная вызовет ошибку. В последней строке производится пре-регистрация массива. Вы должны передать в качестве первого аргумента имя существующего шаблона, вторым аргументом будет массив с данными. Опять же, по мере необходимости даная операция может быть выполнена для нескольких массивов.
Метод preRegister может быть использован для любого вида переменных или массивов, абсолютно не важно,что вы туда поместили - результат рендеринга шаблона или простые значения true/false.
Для доступа к зарегистрированным данным в шаблоне используйте следующую конструкцию:

{vb:raw my_insertvar}

Обратите внимание: не  {vb:raw templatevalues.my_insertvar}!
По сути, то что я отправил в метод preRender может быть записано двумя строчками представлеными ниже. Они заменяют последние две строки в предыдущем php-боксе

PHP Code:

    $my_insertvar = $templater->render(); 
    vB_Template::preRegister('FORUMHOME',array('my_insertvar ' => $my_insertvar)); 


Конечно же, вы можете добавить большее количество значений в массив.

Бонус: … чтобы вы не делали — кешируйте ваши шаблоны
Теперь вы знаете как вывести шаблон на экран — это уже что-то. Теперь необходимо убедится в том, что все работает быстро и с экономией ресурсов. Используйте кеш шаблонов.
Чтобы узнать кешируется ваш шаблон или нет необходимо активировать режим debug. Для этого добавьте $config['Misc']['debug']=true; в ваш конфиг (config.php).
Внимание! Не используйте режим DEBUG на продакшн-сайте.
Среди технической информации, которая появится на страницах сайта, будет список используемых шаблонов для данной страницы. Шаблоны отмеченные красным не кешируются.
Для кеширования вашего шаблона добавьте модуль с hook-ом cache_templates со след. кодом:

PHP Code:

// один шаблон
$cache[] = 'mytemplate';  

// несколько шаблонов
$cache = array_merge((array)$cache,array( 
    'mytemplate', 
    'myothertemplate', 
    'mythirdtemplate' 
)); 


Прим. Переводчика
В последнем примере автор ссылается на сущность «plugin» и его атрибут «hook» — для русской локации форума это звучит как «модуль» и «Местоположение модуля»
Админка ? Продукты и модули ? Добавить новый модуль:
Продукт: vBulletin (или ваш, если таковой был создан)
Местоположение модуля: cache_templates
Порядок: (оставьте как есть)
Код PHP модуля:

PHP Code:

// for a single template 
$cache[] = 'mytemplate';  

// for more than one templates in one step 
$cache = array_merge((array)$cache,array( 
    'mytemplate', 
    'myothertemplate', 
    'mythirdtemplate' 
));