Stub files 1.x
From b2evolution manual
[edit] 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!
[edit] 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 lookup 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.server.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).
[edit] 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 (this is for version 0.9). 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...
[edit] What parameters can I set in a stub file?
Basically, you can override any of the URL_Parameters.
[edit] 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.
[edit] 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 $blog = 2; // Select which blog you want to display here. $skin = 'custom'; // Force the skin you want to display for this blog on this URL. $show_statuses = array(); // This is the way to show published posts to everybody, protected posts to members and private posts to yourself $blogroll_blog = 4; // This is the blog to be used as a blogroll (set to 0 if you don't want to use this feature) $blogroll_cat = ''; // This is the list of categories to restrict the blogroll to (cats will be displayed recursively) Example: $blogroll_cat = '4,6,7'; $blogroll_catsel = array( ); // This is the array if categories to restrict the blogroll to (non recursive) Example: $blogroll_catsel = array( 4, 6, 7 ); $timestamp_min = ''; // Here you can set a limit before which posts will be ignored $timestamp_max = 'now'; // Here you can set a limit after which posts will be ignored include(dirname(__FILE__)."/b2evocore/_blog_main.php"); ?>
[edit] How to call a blog through xyz.php instead of index.php?blog=x
This man page refers to b2evolution 0.9.2
Let's assume you have a default installation of b2evolution:
Blog All can be accessed through index.php?blog=1 Blog A can be accessed through index.php?blog=2 Blog B can be accessed through index.php?blog=3 The Linkblog can be accessed through index.php?blog=4
[edit] Let's start with Blog A
Let's start with blog A, because it is the easiest. b2evolution ships with an alternative file to call blog A! In your URL, try replacing the end index.php?blog=2 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=2.
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=2 !
That's because b2evo doesn't know (yet) that you want to use a_stub.php instead of index.php?blog=2. You must set this up in the admin, under blogs then Blog A. Under "Preferred access type:", you must select "Explicit reference to stub file (Advanced)" and then name the stub file name in "Stub name:"; 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=2.
[edit] Now with Blog B
Try the same operations as above on blog B (blog number 3) 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 acces 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 happends 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=2 and blog #2 is blog A, not blog B. (You can see the blog numbers in the admin, under Blogs).
To correct that, you must open the file b_stub.php with a text editor and find the following line: $blog = 2; // 2 is for "demo blog A" or your upgraded blog (depends on your install)
Replace this line with: $blog = 3;
Take special care not to forget the $ sign in front of $blog, as well as the semi column ( ; ) at the end of the line. The white space and the comment after // can be omitted. 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. For more information on this, see StubFiles.