In a nutshell

A Stub File is used to anchor a particular blog in a particular location of your website.

For example, if you want your blog about beer to be located at http://example.com/beverages/alcoholic/beers.php you would create a stub file named beers.php in the folder /beverages/alcoholic/ of your website.

Inside of beers.php you would specify the ID # of your beers blog and you’d basically have that blog where you want it. (You also need to tell b2evo in the Blog Settings > URLs, otherwise generated links will point to the wrong place).

Introducing Stub Files

Please follow me on this:

Blogs are actually just textual data in a database.

But that’s not how you want to look at it. You want to see a web page, right ?

For this, you will use a skin. Skins basically provide a layout to display the textual data that comes out of the database.

But that’s not enough!

How do you call a particular blog and have it displayed in a particular skin?

The simplest way to call up a blog-display is to call index.php?blog=x where x is the ID of the blog you want to display. This will look up the blog in the database, retrieve the default skin configured for that blog and do the display based on that.

There are variations on what parameters you can pass to index.php. For example you could call a blog by index.php/urlname and use the blog’s URL name instead of its ID. You can also call index.php with no parameter at all, then the default blog will be displayed (with its default skin).

Now if you want more flexibility, what you do is create a stub file.

A stub file is a .php file onto which the webserver can hit, at any URL you may fancy. That stub file will in turn call b2evo to do the displaying job for a particular blog, and using a particular skin, based on the parameters you set inside of the stub file.

If you want your blog to be accessed at http://www.example.com/this/is/a/fancy/path/my_blog.php, then you just put a stub file called my_blog.php in the /this/is/a/fancy/path folder. (Note: on many apache installations, you will be able to omit the .php at the end of the URL, but you still have to name your file something.php).

Can I use multiple stub files for the same blog?

Yes, you can create several stub files for the same blog if you want. They’ll all work and display your blog in different locations of your site. However, when b2evo creates navigation links and especially permalinks, it will refer to the one and only stub file you have configured in the backoffice (unless you override this default behaviour in customized skins, but that’s another subject).

Stub files let you set dozens of different parameters to fine tune how you want to display your blog. An example of a stub file is provided as a_stub.php . If you duplicate and rename a_stub.php 10 times, you’ll have 10 different ways of calling blog_a with it’s default skin. If you modify the 10 copies, you’ll have 10 different displays.

The first thing you’ll want to do is display another blog besides blog a. But you could also force the display to a specific skin, or use another linkblog, or decide to display posts in the future, or change the sorting order of your posts, etc…

What parameters can I set in a stub file?

Basically, you can override any of the URL Parameters.

Quick recap

index.php requires no file editing but will only display the blogs with their backoffice default config. Stub files must be edited but let you display your blog in an extremely wide variety of ways and at any location you want in your website.

What does a stubfile look like?

A stub file is nothing more than a placeholder.

A stub file is a .php file onto which the webserver can hit, at any URL you may fancy. That stub file will in turn call b2evo to do the displaying job for a particular blog, and using a particular skin, based on the parameters you set inside of the stub file.

In other words, if you want to use skins, or if you want your visitors to be able to choose their own skin, or if you want to be able to switch skins, you can create stubfiles for every blog and every scenario you want to show.

A stub file is nothing more and nothing less than a bunch of parameters and a final line that calls another file.

<?php
# First, select which blog you want to display here!
# You can find these numbers in the back-office under the Blogs section.
# You can also create new blogs over there. If you do, you may duplicate this file for the new blog.
$blog = 1;

# You could *force* a specific skin here with this setting: (otherwise, default will be used)
# $skin = 'basic';

# This setting retricts posts to those published, thus hiding drafts.
# You should not have to change this.
$show_statuses = array();

# Here you can set a limit before which posts will be ignored
# You can use a unix timestamp value or 'now' which will hide all posts in the past
$timestamp_min = '';

# Here you can set a limit after which posts will be ignored
# You can use a unix timestamp value or 'now' which will hide all posts in the future
$timestamp_max = 'now';

# Additionnaly, you can set other values (see URL params in the manual)...
# $order = 'ASC'; // This for example would display the blog in chronological order...

/**
 * That's it, now let b2evolution do the rest! :)
 */
require_once dirname(__FILE__).'/conf/_config.php';

require $inc_path.'_blog_main.inc.php';
?>

How to call a blog through xyz.php instead of index.php?blog=x

Let’s assume you have a default installation of b2evolution:

Blog A can be accessed through index.php?blog=1
Blog B can be accessed through index.php?blog=2
The Linkblog can be accessed through index.php?blog=3

Let’s start with Blog A

Let’s start with blog A, because it is the easiest and b2evolution ships with an alternative file to call blog A!

In your URL, try replacing the end index.php?blog=1 with a_stub.php. You should access the exact same page. That’s because b2evolution ships with the file a_stub.php which is preconfigured for acting as if index.php was called with parameter blog=1.

However, if you now click on an internal link on this page, say "Last comments", you will notice that b2evo throws you back to index.php?blog=1 !

That’s because b2evo doesn’t know (yet) that you want to use a_stub.php instead of index.php?blog=1. You must set this up in the admin, under blogs then Blog A. Under "Blog base URL:", you must select "Relative to baseurl:" and enter the correct URL; here you should enter a_stub.php. Validate your changes.

Now, you can refresh the blog page and click on some links. You will notice that you now stay on a_stub.php and no longer get redirected to index.php?blog=1.

Now with Blog B

Try the same operations as above on blog B (blog number 2) and try to associate it with a stub file named b_stub.php. You will notice that you get a "404 Page not found" error from your webserver!

That is because b2evolution does not ship with a file named b_stub.php ! Now try to duplicate the file a_stub.php as b_stub.php on your webserver.

What happens if you access this page?

You will notice that you no longer get an error, but b_stub.php displays Blog A just as a_stub.php did! This is not what you wanted!
This happens because b_stub.php contains preset parameters so that you don’t have to pass these on the URL. In this case, it contains a hardcoding for blog=1 and blog #1 is blog A, not blog B. (You can see the blog numbers in the admin, under Blog Settings).

To correct that, you must open the file b_stub.php with a text editor and find the following line:
$blog = 1;

Replace this line with:
$blog = 2;

Take special care not to forget the $ sign in front of $blog, as well as the semi column ( ; ) at the end of the line.
Save the file (and upload it to your webserver if necessary).

Calling b_stub.php should now work as expected.
The file b_stub.php is what we call a Stub File. You may have noticed that it also lets you set other parameters than just the blog number.