Including Custom PHP in Templates.

[raywjohnson]

We've created a new package that is intended to facilitate the replacement of custom PHP modules with custom Display Template modules. It also demonstrates how to create custom API functions in general. You will find this package attached below.

Steps to replace a PHP module Module

Edit the api/main.php file

1. Find the customWidgetHtml function
2. Copy your php code from the module into the function.
3. Change the code to generate a string value instead of echoing content and set that to the $myhtml parameter.

If you have more than one PHP module you can copy the function, give it a new name, and copy/edit the code above for each module.

4. Upload this package directory into core/packages

Create a custom template

1. Go to the style editor in the admincp and select add a new template for the site style you are using.
2. Give it a name like 'customtemplatemodule'
3. copy the following into the template changing the name to match the function name(s) in the api/main.php:

{vb:data result, localapi:main, customWidgetHtml}
{vb:raw result.html}

4. Do this for each PHP module you are replacing.

Adding Your Code to a Page

1. Go to sitebuilder.
2. Edit the page that you want to display the module on.
3. Add a "Display Template" Module to replace the PHP Module
4. Set the template name to 'customtemplatemodule' or whatever you named your new template.
5. Remove the old PHP module template
6. Save the Page.

---

Note you can return html and display it from the API in this way. It's the quickest and easiest way of porting from an existing PHP module to a Template module. But it isn't necesarily the best way. The API functions are intended to return data that can be inserted into the markup in the templates. And alternative example is provided in the sample class. You can uncomment the function if you want to try it out. The template to use this to provide the same result as the sample html return is:

{vb:data result, localapi:main, dataOnly}
<p>{vb:var result.hello}</p><p></b>{vb:var result.hellobold}</b></p>

As above save that as a custom template and create a Display Template Module that uses it.

[raywjohnson]

Yep. That should work.

So this line determines the path, script, method, and return var

{vb:data result, localapi:main, dataOnly}

Breakdown

vb:data result : result contains the returned data (associative array / json.object)

localapi:main : the path and script: i.e. /core/packages/localapi/api/main.php

dataOnly : the method to call

So you can put the scripts all in the same package, or a new package for each, up to you.

Example:

{vb:data retval, package2:stuff, getData}

/core/packages/package2/api/stuff.php : method getData : returns data to variable retval

[eolesen]

Is there an easy way to reference within a localAPI script some standard vBulletin variables like the username, usergroup, user ID?

I'm currently using:

 global $vbulletin;  
   $userid = $vbulletin->userinfo[userid];
   $username = $vbulletin->userinfo[username];

but shouldn't those already be stored as globals I can grab inside the localapi shell? Are there other secret variables we can pull short of having to invoke them as above in each function?

[eolesen]

Can I safely have more than one PHP file being used i.e. main.php for common functions, jellydonut.php for something task specific, lasagna.php for something else task specific, and simply change out the php file reference in the custom tag e.g.

{vb:data result, localapi:main, dataOnly}

{vb:data result, localapi:jellydonut somethingSweet}

{vb:data result, localapi:lasagna, itsHotAndMessy}

OK... I figured out you CAN have multiple PHP files inside the localAPI folder, but the (one of many, apparently) undocumented step is that the class declaration in the top line of each additional PHP file in the API subfolder has to be modified to form a new API class.

Continuing the example above, you can have files main.php, lasagna.php and jellydonut.php

For lasagna.php:

class localapi_Api_[b]Lasagna[/b] extends vB_Api

If it's done right, you'll see the separate PHP files listed as API classes under "List API Extensions and PHP Hooks"

Localapi_Api_JellyDonut
[b]Localapi_Api_Lasagna[/b]
Localapi_Api_Main

In the user defined style template, it would be called like this:

{vb:data result, localapi:[b]lasagna[/b], itsHotAndMessy}
{vb:raw result.html}

This makes it a lot easier to debug when you have lots of functions... for our site we have what will work out to be around 30 or 40 custom functions. Being able to group them into category files has made it 10000% easier to debug as new functions are ported over.

My suggestion is to add each function into "main.php" until it's debugged and solid, and then move the function into its eventual home.