vb.org Archive - [HOW TO - vB4] Rendering templates and registering variables

vb.org Archive (https://vborg.vbsupport.ru/index.php)

- vBulletin 4 Articles (https://vborg.vbsupport.ru/forumdisplay.php?f=242)

- - [HOW TO - vB4] Rendering templates and registering variables - a short guide (https://vborg.vbsupport.ru/showthread.php?t=228078)

[HOW TO - vB4] Rendering templates and registering variables - a short guide

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:

HTML Code:

{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->render());

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

HTML Code:

{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:

HTML Code:

{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'
));

.
.
Hope this helps!
-cel

----
Addendum - There are now two blog posts on vb.com related to this topic:
http://www.vbulletin.com/forum/entry...in-4-templates
http://www.vbulletin.com/forum/entry...-4-based-files

Great article, cellarius! Thanks for taking the time to write this out.

I saw the same questoins over and over again, and you and others heroically answering the same time and again, so I thought this might come in handy. That's the system as I managed to grasp it up to now, and I myself learned while typing it down. However, I'd happily add any suggestions and improvements :)

Thanks for the write up, Cellarius. :)

Btw, shouldn't {vb:raw my_array.value1} be {vb:raw my_array.key1} in the third codebox ?
(which would output "value1")

Quote:

Originally Posted by Shadab (Post 1915746)

Thanks for the write up, Cellarius. :)

Btw, shouldn't {vb:raw my_array.value1} be {vb:raw my_array.key1} in the third codebox ?
(which would output "value1")

Of course, thanks for pointing this out. Corrected.

--------------- Added [DATE]1258449197[/DATE] at [TIME]1258449197[/TIME] ---------------

There's two blog posts on this on vb.com:
http://www.vbulletin.com/forum/entry...-4-based-files
http://www.vbulletin.com/forum/entry...in-4-templates

Quote:

Originally Posted by cellarius (Post 1915752)

Of course, thanks for pointing this out. Corrected.

Not a problem!

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Another note; on multidimensional arrays...
Suppose you have a nested / multidimensional array set, like:

PHP Code:


		
			
// Array declaration & assignment



$multiDim = array(

    'level1' => array(

        'foo'    => 'one',

        'bar'    => 'two',

        'baz'    => 'three',

        'qux'    => 'four'

    ),

    'test' => 'testval'

);



// Variable Registration



vB_Template::preRegister(

    'header', array('multiDim' => $multiDim)

);

You can chain the array 'keys' like in the second example:

HTML Code:

{vb:raw multiDim.test} <!-- Output: testval -->

{vb:raw multiDim.level1.baz} <!-- Output: three -->

Hi,

How do i add a variable in form home template?

Im trying to do this:

Display stats on the forumhome yes/no

Display chatbox stats on the forumhome.
Don't forget to add the $mgc_cb_evo_stats variable in the FORUMHOME template where you want to display them otherwise they won't appear.
Warning : Add 4 sql queries on the forumhome.
For the users of a vBulletin version prior to 3.7.2, you will have to manually add the $mgc_cb_evo_stats var in the FORUMHOME template where you want the stats to appear.

How do i get this done guys?

Thanks in advance!

You did not like my answer in the other thread?

Quote:

Originally Posted by cellarius (Post 1915869)

You are posting this question in the vB4 subforum, so I gather you want to do this in vB4. If the mod's php code is not altered to adapt to vB4, there is no way of showing the variable in the template at this time. In vB4, variables need to be registered to be available in templates.

The mod clearly has not been updated for vB4. This very likely is not only a template rendering question, and this is not the place to discuss the porting of other peoples modifications. If you want to try anyway, the answer is in the article, look at the "Save into an array and preregister to use in an existing/stock template" part.

Quote:

Originally Posted by cellarius (Post 1915974)

You did not like my answer in the other thread?

The mod clearly has not been updated for vB4. This very likely is not only a template rendering question, and this is not the place to discuss the porting of other peoples modifications. If you want to try anyway, the answer is in the article, look at the "Save into an array and preregister to use in an existing/stock template" part.

I don't know about whether this is a rendering question or not. All i know is i have to alter something. Since you where kind enough to help me out by pointing me to this thread, i dropped the question here too, after reading what has been said up here.

Now i just read that part where you pointed me out, it doesn't say what file i have to open and at what line i have to insert some code.

Isn't that how it works?

Sorry for being honest, but this is not how it works and it is quite obvious that you do not know what you are doing.

Of course "something" has to be done, but I do not know that mod, and therefore can not tell you what exactly will have to be done to make it vB4 compatible. It's not like there is a file in every mod that needs tampering that could be pointed out to you, where you do some mechanical search and replace and everything is fine. That's just not how it works, and this thread is not about updating the particular mod you are so interested in, but about helping coders to update their work. What has to be done is different for every single one of the hundreds of mods out there, and this article tries to provide just some of the many tools needed for that work.

The author of that mod will have to update his work, and you will have to be patient until he does - just like anyone else. If he decides not to do that you can pay someone to do it, or you can do it yourself if you have the skills. If that is not sufficient to you, you may ask in the thread for that modification, but be prepared that mod authors will be annoyed if dozens of users spam their threads with questions that go "are you not yet done", "when will you be updating this" and stuff.

Please read the announcement regarding this: https://vborg.vbsupport.ru/showthread.php?t=228073

Just wanted to thank you for this article.. I had been messing around on my own for a few hours on two of my mods that involved FORUMHOME and after reading your article (specially the last part) both my mods are now up and running smoothly on vb4 !!

CHEERS to Cellarius!

Quote:

Originally Posted by cellarius (Post 1916047)

I'm not trying to do an update. Nor am I trying to port or convert the mod to vb4. I, myself uses vb 3.8.4.

This mod has a few options. And one of the options out there tells you that if you activate 'this' option you have to add the $mgc_cb_evo_stats variable in the forumhome template.

Althought its about a particular mod, but I got the impression that this is something that is outside the scope of the mods explanation, looking at the explanation on how to do it, which is rather 'short'.

You misunderstood me, lets just leave it to that. Now if you don't mind, have a nice evening.

Quote:

Originally Posted by Jeweetog (Post 1916081)

I'm not trying to do an update. Nor am I trying to port or convert the mod to vb4. I, myself uses vb 3.8.4.

Then why in heaven do you post in an article that discusses vB4 programming techniques? If you need support for a mod the one and only place to go is the thread for this mod.

Just wanted to thank you guys both cellarius and Shadab, I've made a lot of progress on porting some major mods after reading what you have posted, I'm doing it for my own experience as I'm planning to finally make the move to vB after having the license for more than a year now lol (been running WBB2.x for ages)

hope that you guys to continue on posting more good stuff :)

Very nice job.
I wasn't aware of pre-registering. :)
Thanks.

Quote:

Originally Posted by Shadab (Post 1915830)

Not a problem!

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Another note; on multidimensional arrays...
Suppose you have a nested / multidimensional array set, like:

PHP Code:


		
			
// Array declaration & assignment

$multiDim = array(
    'level1' => array(
        'foo'    => 'one',
        'bar'    => 'two',
        'baz'    => 'three',
        'qux'    => 'four'
    ),
    'test' => 'testval'
);

// Variable Registration

vB_Template::preRegister(
    'header', array('multiDim' => $multiDim)
);

You can chain the array 'keys' like in the second example:

HTML Code:

{vb:raw multiDim.test} <!-- Output: testval -->

{vb:raw multiDim.level1.baz} <!-- Output: three -->

I have extended my example to provide for multidimensional arrays. Thanks for pointing this out :)

Can you give us a simple example of how to insert code to footer without fech from other template?

Try to insert $my_insertvar

PHP Code:


		
			
vB_Template::preRegister('footer',array('my_insertvar ' => $my_insertvar));

and call {vb:raw my_insertvar}.

hi cellarius, I don't want to call the var manually, I just want to inject code like my old example for 3.x:

hook: parse_templates

code: $vbulletin->templatecache['footer'] .= 'text added to footer';

Capiche?

Nope, that does not work. You would need to do a str_replace on something you know is there.

I figure out how to solve it:

hook: process_templates_complete

code: $footer .= 'text added to footer';

No idea if was the best solution, but that worked very well.

Quote:

Originally Posted by testebr (Post 1916821)

hook: process_templates_complete

code: $footer .= 'text added to footer';

Indeed, you can manipulate the already rendered template doing this. Also possible is str_replace:

PHP Code:


		
			
$search = "Terms of Service";
$replace = "Terms of Cooking Noodles";
$footer = str_replace($search,$replace,$footer);

Although this is a somewhat bad example, since "Terms of Service" is a phrase, of course, and will vary by language. Always make sure you use strings for replacement that are always present.

Attachment 106372

Using str_replace, you can also add stuff in the middle of the template like so:

PHP Code:


		
			
$search = "Terms of Service";
$replace = " and Terms of Cooking Noodles";
$footer = str_replace($search,$search.$replace,$footer);

Attachment 106374

Hi,

I'm trying to add something that requires PHP under the navbar. Back in vb 3.8.x I just used plugins for this. But, I'm not sure which hook to use if I want to display something under the navbar.

@David: This is not related to the topic of this article. You should open your own thread on this..

Also, I just added the bonus track about template caching.

Quote:

Originally Posted by cellarius (Post 1917658)

@David: This is not related to the topic of this article. You should open your own thread on this..

Also, I just added the bonus track about template caching.

Sure?
It's $cache[] = 'xxx'; and not $globaltemplate now;) ;)

Ah, damn, of course you're right. I had my example code for vB3 and the one I was about to change for vB4 side by side and then obviously copied/pasted the wrong one. Stupid me :)

Quote:

Originally Posted by cellarius (Post 1917809)

Ah, damn, of course you're right. I had my example code for vB3 and the one I was about to change for vB4 side by side and then obviously copied/pasted the wrong one. Stupid me :)

Yea, i know.
I made the mistake in all my add-ons on porting them to vB4:D

Thanks for the "cache your templates" info, I made use of this info after making my own Terms of Service and Privacy custom pages, very helpful, thank you.:up:

Quote:

Originally Posted by cellarius (Post 1916832)

Indeed, you can manipulate the already rendered template doing this. Also possible is str_replace:

PHP Code:


		
			
$search = "Terms of Service";
$replace = "Terms of Cooking Noodles";
$footer = str_replace($search,$replace,$footer);

PHP Code:


		
			
$search = "Terms of Service";
$replace = " and Terms of Cooking Noodles";
$footer = str_replace($search,$search.$replace,$footer);

Also can this be used on variables? ex: {vb:raw variable}

Attachment 106374

OK I'm trying to do the same thing but on showthread, from this example is $footer a var already being used of is this an additional variable made up int he plugin? Right now I'm using $vbulletin->templatecache['postbit'] with the <hookname>process_templates_complete, should this something diffrent?

<hookname>showthread_query</hookname>
$vbulletin->templatecache['postbit'] = str_replace($find, $replace, $vbulletin->templatecache['postbit']);

Also can this be used on variables? ex: {vb:raw variable}

This isn't working for me. I'm probably doing something wrong, but at the moment I have a custom php page (I created following another tutorial elsewhere) that is calling a custom template.

The code for the php page:

PHP Code:


		
			
<?php 

// ####################### SET PHP ENVIRONMENT ########################### 
error_reporting(E_ALL & ~E_NOTICE); 

// #################### DEFINE IMPORTANT CONSTANTS ####################### 

define('THIS_SCRIPT', 'test'); 
define('CSRF_PROTECTION', true);   
// change this depending on your filename 

// ################### PRE-CACHE TEMPLATES AND DATA ###################### 
// get special phrase groups 
$phrasegroups = array(); 

// get special data templates from the datastore 
$specialtemplates = array(); 

// pre-cache templates used by all actions 
$globaltemplates = array('TESTPAGE', 
); 

// pre-cache templates used by specific actions 
$actiontemplates = array(); 

// ######################### REQUIRE BACK-END ############################ 
require_once('./global.php'); 

// ####################################################################### 
// ######################## START MAIN SCRIPT ############################ 
// ####################################################################### 

$navbits = construct_navbits(array('' => 'Test Page')); 
$navbar = render_navbar_template($navbits); 

// ###### YOUR CUSTOM CODE GOES HERE ##### 
$pagetitle = 'My Page Title'; 

// ###### NOW YOUR TEMPLATE IS BEING RENDERED ###### 

$templater = vB_Template::create('TESTPAGE'); 
$templater->register_page_templates(); 
$templater->register('navbar', $navbar); 
$templater->register('pagetitle', 'Test Page'); 
print_output($templater->render()); 

?>

And the HTML template (called TESTPAGE):

HTML Code:

{vb:stylevar htmldoctype}

<html xmlns="http://www.w3.org/1999/xhtml" dir="{vb:stylevar textdirection}" lang="{vb:stylevar languagecode}" id="vbulletin_html">

  <head>

    <title>{vb:raw vboptions.bbtitle}</title>

    {vb:raw headinclude}

  </head>

  <body>

    

    {vb:raw header}

    

    {vb:raw navbar}

    

    <div id="pagetitle">

      <h1>{vb:raw pagetitle}</h1>

    </div>

    

    <h2 class="blockhead">Title</h2>

    <div class="blockbody">

      <div class="blockrow">

        Text

      </div>

    </div>

    

    {vb:raw footer}

  </body>

</html>

And the plugin in global_start:

PHP Code:


		
			
$templater = vB_Template::create('TESTPAGE'); 
print_output($templater->render());

Where have I gone wrong? I've spent a good half an hour going through the tutorial and trying various things but can't seem to get it working. It always makes the whole site blank, but if I call another template (e.g. contactus instead of TESTPAGE) it works fine, so the problem seems to lie with the plugin.

Any help greatly appreciated - thanks in advance :)

In the plugin change "THEMEFLARE" to "TESTPAGE" ....

Quote:

Originally Posted by Seven Skins (Post 1923650)

In the plugin change "THEMEFLARE" to "TESTPAGE" ....

Oops... that's not the problem, I've checked and it is "TESTPAGE", just a typing error on my part. Thanks for helping :)

Edit: I've updated my original post.

I seemed to have gotten it to work. :D

Downloads.php

PHP Code:


		
			
<?php



// ####################### SET PHP ENVIRONMENT ###########################

error_reporting(E_ALL & ~E_NOTICE & ~8192);  



// Define the unique name for this script

define('THIS_SCRIPT', 'Downloads');



// List of templates used on this page

$globaltemplates = array(

    'DOWNLOADS_SHELL'

);



// List of action related templates used on this page

$actiontemplates = array();



require_once('./global.php');



// Navbar location

$navbits = construct_navbits(array('' => 'Downloads')); 

$navbar = render_navbar_template($navbits); 



// HTML stuff

$HTML = "<INSERT WHATEVER CODE YOU WANT>";



// Fetch and parse templates

$templater = vB_Template::create('DOWNLOADS_SHELL');

$templater->register_page_templates(); 

$templater->register('headinclude', $headinclude);

$templater->register('navbar', $navbar); 

$templater->register('header', $header);

$templater->register('HTML', $HTML);

$templater->register('footer', $footer);

print_output($templater->render());



?>

DOWNLOADS_SHELL

Code:

        {vb:raw headinclude}



        {vb:raw header}

        

        {vb:raw navbar}

        

        {vb:raw HTML}

        

        {vb:raw footer}

        

</body>

</html>

thank you very much..

Code:

eval( '$comment_boxes .= "' . fetch_template('App_Question_box') . '";' ) ;

i have this how can make this into the new vbulletin format im not understanding this :(

Quote:

Originally Posted by CrazyProgrammer (Post 1926545)

Code:

eval( '$comment_boxes .= "' . fetch_template('App_Question_box') . '";' ) ;

i have this how can make this into the new vbulletin format im not understanding this :(

You're gonna translate into something like this, but only you know the variables that will need to be registered:

PHP Code:


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

Alright, now I'm a bit stumped.
I cant seem to get the title of the page to register and it the pages don't work with subdomains.

Anyone got a clue?

Quote:

Originally Posted by sebz2009 (Post 1928081)

Alright, now I'm a bit stumped.
I cant seem to get the title of the page to register and it the pages don't work with subdomains.

Anyone got a clue?

I'm not sure I understand your problem. From what I try to gather I am also not sure if you're asking anything that is in correspondence with the article.

Alright, my bad. I got the title to work.

The bit about the subdomains does relate back to this.

I've made a custom page using this How-To.
When I load the page in the directory that global.php is in (the forum root directory) it loads absolutely fine.

What I'm trying to do is made this template appear in a sub domain (stats.example.com) rather than being in the root (example.com) where the forums live.

When I try running the code from the sub domain, it comes up and says that it doesn't know where "./global.php" is.
I change this to be "http://example.com/global.php".

That's fine, but then I get another error saying that it then can't find another .php file, etc, etc.

I'm just trying to figure out how I can get my custom page to load on a sub domain.

Ahm, just like I suspected.

Quote:

Originally Posted by sebz2009 (Post 1928314)

I've made a custom page using this How-To.

This tutorial is not about making custom pages, and has nothing to do with your problem. This one is.

Phrase Groups Available:

X vBulletin 3.8.12 by vBS Debug Information
Page Generation 0.02093 seconds Memory Usage 1,977KB Queries Executed 10 (?)
More Information
Template Usage: (1)ad_footer_end (1)ad_footer_start (1)ad_header_end (1)ad_header_logo (1)ad_navbar_below (3)bbcode_code_printable (6)bbcode_html_printable (21)bbcode_php_printable (15)bbcode_quote_printable (1)footer (1)gobutton (1)header (1)headinclude (6)option (1)pagenav (1)pagenav_curpage (2)pagenav_pagelink (1)post_thanks_navbar_search (1)printthread (40)printthreadbit (1)spacer_close (1)spacer_open Phrase Groups Available: global postbit showthread	Included Files: ./printthread.php ./global.php ./includes/init.php ./includes/class_core.php ./includes/config.php ./includes/functions.php ./includes/class_hook.php ./includes/modsystem_functions.php ./includes/class_bbcode_alt.php ./includes/class_bbcode.php ./includes/functions_bigthree.php Hooks Called: init_startup init_startup_session_setup_start init_startup_session_setup_complete cache_permissions fetch_threadinfo_query fetch_threadinfo fetch_foruminfo style_fetch cache_templates global_start parse_templates global_setup_complete printthread_start pagenav_page pagenav_complete bbcode_fetch_tags bbcode_create bbcode_parse_start bbcode_parse_complete_precache bbcode_parse_complete printthread_post printthread_complete
Messages: