How To Include A Custom Template Via Plugins
 

This tutorial will show you how to include custom templates within your vBulletin pages using plugins.

First of all, you need to create your custom template. Lets call this mytemplate for the sake of this tutorial.

Once you have created your template, and decided where you would like to have it placed, you can put the template variable $mytemplate there.

As vBulletin does not yet know what to do with this template variable, it simply ignores it when generating the page.

Next you need to create the plugins for the template, so that vBulletin knows what to do with it. You need to create two plugins, one to include the template, and one to cache it (saves a query).

The easiest way to do this, although not technically the best, is to create the first plugin in either the hook location global_start or parse_templates This allows the template to be used globally throughout your site. However, you can also create this plugin in the _complete hook for the location that you wish to have it displayed (eg postbit_complete memberinfo_complete etc).

The content of this first plugin will be as follows:This tells it that when it comes across $mytemplate, it is to fetch the template mytemplate and include it there. This plugin can be named anything that you want, and should be set to active.

The second plugin is always placed in the hook location cache_templates as this is the one that literally does what it says on the tin. It caches the template, preventing an extra query on each page that it is included on.

The content of this plugin will be as follows:This tells it to add mytemplate to the global templates array, which ensures that everywhere that it is used, it is cached. Again, this plugin can be named anything that you want, but not the same as the first one, and should be set to active.


Congratulations, your custom template is now included on your site without the need for any code modifications, and is already up and running.

If at any point you decide that you want to remove the custom template, either temporarily or permanently, you can simply disable the two plugins and it will again vanish.


My personal preference is to use the parse_templates hook for the first plugin as this enables the template to be used on every page on your site so you can move it about without having to edit the plugin. It is also useful if you wish to have it included on two or more pages.


The method explained in this tutorial is the exact same method as I have used for the following modifications:

• Additional Navbar In Footer
• Right side column on forum home only
• Left side column on forum home only

Thank you for this. I've been trying to split up some templates I've changed quite a lot into some easier chunks and wasn't sure how before I read this :)

One question though, can I use the same plugin to parse multiple templates or do they have to be individual?

eg, or is that impossible / unwise?

Yes that will work, however for the second one is better as otheriwse you are merging the array twice where you don't need to.

ah, thank you :) I hadn't realised that.

Question what if I wanted to replace a template al together?

Lets say, instead of calling forum_home, i want a plugin that will call forum_new instead ??

You would need to put a conditional in your forumhome template so that if the plugin was enabled then it would use the forum_new, and if it wasn't, or some other condition, then it would use forum_home

I've been trying to add a template in part of the forumhome_forumbit_x templates and it's not working. I've followed the instructions above (adding the parse plugin to parse_templates). I've also tried it out by adding it to another template such as the footer and it appears. Are there some templates that can't have another template added inside them?

You shouldn't be merging arrays for this, that's very wasteful of resources, just add to the array ;

.= instead of = right ?

ummm, no?

[] adds to the end of the array

Do you need the first plugin as well when using that code Paul?

I'm actually trying to do this...

My goal is to have a template custom_header with a variable $custom_header which will contain all of the code from $header with a slight change (removing code for a right column and a different logo) for a CMPS home page...

1.) I do add new template, and put the code I want in it, saving it as custom_header. It now appears under "Custom Templates"

2.) I make a plugin with starting at global_start

3.) I add the plugin "globaltemplates[] = 'custom_header';" starting in cache template

I enable both.

I get error:Parse error: syntax error, unexpected '[' in /home/uninsta1/public_html/bu/forums/global.php(346) : eval()'d code on line 55

Right above the logo in ALL pages (not just CMPS...)

Shortly thereafter forums don't show and errors occur in functions.php as well.

I disable plugins.

What should I try next?

if you don't put $ before globaltemplates[], that won't work...

Oh god, this is confusing. Is there any way of explaining this to someone illiterate in the technical coding world?

I want to incorporate my custom template into the forum and $mycustomtemplate isn't working.

Edit: Sorry for this post, I am an idiot. Worked it out. GREAT tutorial, this is EXACTLY what I was looking for ^_^

Thanks for this crucial and very helpful information. Should be in the vB manual!

A followup please: what exactly is "the technically best" way to do it?

Thanks.

I have this working completely, except in my hook I have $myvar = "test";

Now in my header template I have :
$myvar

Nothing happens. how can I get $myvar to be replaced with the dynamically created value from the hook?

Compliments to Kerry-Anne for posting this.

I'm new to vB, but a long time PHP guru and forum admin (including uBB and phpBB).

After reviewing some of the replies here I wish to add that the information presented here is not simply copy/paste, and requires basic knowledge of PHP as well as the hook and template system of vB. I noticed some of the more experienced PHP developers making suggestings and fixes here. I concur and wish to expand on that.

I tried the procedure, and with a few minor corrections got it to work with less overhead simply by optimizing the commands (using advice posted earlier plus new advice from me):

I can sum it up in 4 easy steps (vb 3.6.7+):

1) Create a custom template, i.e. "mytemplate" for purposes of these instructions

Put in there "Hello World!" or any HTML so you know its working when it displays.

2) Add a new plugin, suggested name is "mytemplate_plugin" for easy reference

Pick hook as "global_start" if you want your template available in any other, or select the appropriate hook depending on where you want your template to display. The latter is the better choice if you are customizing a specific feature of vB.

Set plugin PHP code: $mytemplate_plugin = fetch_template('mytemplate_plugin_home');

3) Create another plugin, suggested name is: "Cached - mytemplate_plugin"

Pick hook as "cache_template" (located within vBulletin; General hooks in pulldown)

Set plugin PHP code: $globaltemplates[]='mytemplate_plugin';

4) In whatever template you wish (based on step 2) place the variable $mytemplate_plugin where you want your custom template to display. If successful, you'll see your "Hello World!" or your HTML as in step 1.

Folks, that's all there is to it. Notice no need for eval or array_merge.

This approach follows a simple naming convention that's easy to understand long after you implement and forget, and uses the most efficient PHP to get the job done, and will work perfectly without have to hack any native vB code. Yes, there are a million ways to skin a cat, this is one, but if you start doing alot of customization of this type, keeping the naming convention and optimizing the PHP code will save valuable server resources.

Compliments to all who posted.

Thanks for your time and if I missed something, please let me know.

-jim

The original post indicates that by attaching the "eval(.." plugin to the "parse_templates" hook, the template will be available to all other templates. I have not found that to be the case. I made a custom template, followed the above instructions precisely, and tried to use my custom template in FORUMDISPLAY and SHOWTHREAD - neither worked. It does work when I attach it to the "forumdisplay_complete" hook and the "showthread_complete" hook.

I want to be able to eval it in a single plugin, and make that template available to absolutely every other template - is there a way I can do that with a single hook?

This is just what i have been looking for. I now have my affiliates on a seperate template from my forum home :D

Like Jingman stated - none of your solutions working if new template is added to FORUMDISPLAY, no matter of the hook location...

Any other thoughts?

Thanks

Both Methods, original and that of iVox, seem to make my template appear, however they do not seem to parse the template. I have conditionals in my template, and they appear like ".(($post[field5]) ? (" on the page.

What can be done to fix this?

didn't work for me in 3.6.8

then.. if I want to use a Custom Templare, I should make all that ceremony?

Hi Kerry-Anne

My template will have a few variables generated for it. Which plugin carries the code to process them?

This I got errors with due to an unexpected "[". If it worked then this would've been the ideal statement to use. Has anyone else had this issue on vB3.8x?

it should be:

Hello

I need a code which i forgot. ill try try to explain it.
for e.g.
If i wanted to add the line aaa under the line yyy in the footer or forumhome.
what could shall i use??

thanks

Hi, I'm in the same position,

I can't get my own variable content to show in the template.

Is there a template variable assignment statement , like in smarty ?


Alex
:)

I got this working OK, I just declared the variable assignments in the global_start hook, so it was in scope for the entire board.

Thanks to Kerry-Anne for posting this, it saved me lots of time.

this is exactly, what I'v been wondering about

thanx a lot :)

This was really extrmely helpful. Thanks a lot.

this help a lot thanks

Can these instructions be take a little further so the following can be done. When making a template, can that template include a variable that can be entered somewhere in the admincp? For example I want the temple to show "THIS". The only thing is I do not want to go to the template all the time and edit "THIS". Can I make a little addition to the admin CP so I can specify what "THIS" is?

Also, can all these template hooks, templates and all related to me showing "THIS" be saved in one package like a mod is so It can be uploaded to another forum easily?

Thanks

Thanks for this guide. Indeed good tutorial.

I've crossed into weird thing though (vbulletin version 3.8.2), maybe someone came aross it & can give few tips on what i could have missed - i can't get rid of "uncached template" warning eventhough I have plugin on "cache_templates" adding it to $globaltemplates[], so not sure what am i missing.

what hook are you using and whats the plugincode?
nobody can help you without that infos;)

2 plugins:
1] location: "global_start"
name: "alt_lp_template"
with followign code:
2] location: "cache_templates"
name: "Tempalte Cache"
with followign code:
and on forum i keep getting "uncached template" warning for "alternate_view".
Note this template was added to master style.

EDIT: what's more weird, i know it's cached, as later on i can access it from $vbulletin->templatecache['alternate_view']

You have to make it this way:
to cache it:
and save the content from the template into a variable:
Now you can use $varname

thanks, that solved it, wrote under cache name the var name instead... silly me :p

Excellent Post. Including my Javascript php file worked in parse_templates rather than cache_templates.

Hi Everyone,
Lets say I set some variable:

$domain = "testsub.domain.com";

from within a global_start plugin. SHOULD I be able to use this in any template??

I seem to have very mixed results. Some pages with links that contain this domain are just broken...

Any ideas?

No, some templates are called from functions/methods, so you would have to create plugins to make your variable in the scope there.

You could write your variable into $vbulletin['myvarname'] = 'foo.bar.tld'; because $vbulletin should be everywhere in the scope.

I hope you can understand what i mean