Main.php functions
From b2evolution manual
The correct title of this article is _main.php functions. The missing underscore and the capital M are due to technical restrictions.
This page applies to b2evo 1.x. For versions 2.x and above please refer to TemplateTags.
Contents |
[edit] Intro
In addition to adding or deleting bits to your _main.php file and/or customizing the look with CSS you can also customize how many of the specific components look using parameters in the function calls. If you're not familiar with php, then it may look a little intimidating at first, but don't worry: it's very straightforward. For example <?php myfunction( 'foo', 'bar' ) ?> simply means "do the thing called myfunction and use 'foo' for the first parameter and 'bar' for the second." The trick is to know what parameters you can supply and in what order you need to supply them.
The _main.php file actually contains a mixture of XHTML markup and php code. Everything inside of the <?php ?> tag will be executed and will output something when the page is viewed. Everything outside of the php tags is XHTML code that will be sent to the browser just as it is. This page deals with <?php stuff inside php tags ?> and applies primarily to versions 0.9.1 and 0.9.2. Some backwards and forward compatibility exists, but nothing is certain.
For the purpose of this page I am starting with the _main.php file from the 'custom' skin in the "Sparkle" (0.9.2) release. When possible and reasonable I also include information about _main.php for versions greater than "Sparkle" (0.9.2).
[edit] Page Initialization
At the top of your _main.php file you should find a comment block with details and copyright information about the skin. You should then find one of these two lines, a security measure that prevents a user from viewing the .php file directly in a browser, depending on your version:
if( !defined('DB_USER') ) die( 'Please, do not access this page directly.' );
if( !defined('EVO_MAIN_INIT') ) die( 'Please, do not access this page directly.' );
[edit] The Header Section
[edit] Link your blog title to your blog
The custom skin gives us a blog title across the top of the blog.
<h1 id="pageTitle"><?php $Blog->disp( 'name', 'htmlbody' ) ?></h1>
We can link that blog title back to the blog.
<h1 id="pageTitle"><a href="<?php $Blog->disp( 'blogurl', 'raw' ) ?>"><?php $Blog->disp( 'name', 'htmlbody' ) ?></a></h1>
[edit] The Posts Loop
[edit] Single Page Titles
<h2><?php
single_cat_title();
single_month_title();
single_post_title();
arcdir_title();
last_comments_title();
profile_title();
?></h2>
[edit] single_cat_title()
This function displays "Category - foo" or "Categories - foo, bar" when a visitor selects a link to a particular category or categories. This function has two parameters: prefix, and display. The prefix parameter is what makes it say "Category - " or "Categories - ", which means you can change that text by providing whatever you'd like it to say instead. For example:
single_cat_title( 'Here be posts about ' );
There is no need to provide any information about the second parameter as the default value is htmlbody. If you look at the top of your _main.php file you will see the same function is called to create the <title> tag in your blog's <head> section. It defines the second parameter as "htmlhead" but, for the purpose of customizing what your visitor sees, the only parameter you will consider changing is the "prefix".
[edit] single_month_title()
This function displays a page title when a visitor has accessed a specific month in your archives. This function has 5 parameters:
- prefix - defaults to "Archives for: " and can be changed to suit your desires.
- display - defaults to htmlbody and should not be changed.
- linktoyeararchive defaults to true and can be changed to false if you do not want your title linked to the archives.
- blogurl defaults to (empty) and is used internally to generate specific links under specific conditions. You should not tinker with this one!
- params defaults to (empty) and is used internally to generate specific links under specific conditions. You should not tinker with this one!
single_month_title( 'I wrote this stuff back in ', 'htmlbody', false );
Note that the second parameter is declared to be "htmlbody" even though it defaults to that in order to force the "linktoyeararchive" parameter to change to false. Parameters must be provided in the order the function expects to see them.
Note that the first two parameters are enclosed in single quotation marks but the third (the term 'false') is not. True/False parameters do not need to be enclosed in single quotation marks. Almost everything else will.
[edit] single_post_title()
This function displays a single post's title when the visitor is on that specific single post page. This function is just like the "single_cat_title" function: it has two parameters (prefix and display), and you should only consider altering the 'prefix' value. The prefix parameter defaults to "Post Details: " with "Post Details" (possibly) translated to the language of your post or blog.
single_post_title( 'I call this one: ' );
[edit] arcdir_title()
This function displays a page title when the visitor has accessed a page in your archives. This function is just like the "single_cat_title" and "single_post_title" functions: it has two parameters (prefix and display), and you should only consider altering the 'prefix' value. The prefix parameter defaults to "Archive Directory" and is (possibly) translated to the language of your post or blog.
single_post_title( 'These are my archived files' );
[edit] last_comments_title()
This function displays a page title when the visitor has accessed the 'last comments', probably from a link in your sidebar. This function is just like the "single_cat_title" and "single_post_title" and "arcdir_title" functions: it has two parameters (prefix and display), and you should only consider altering the 'prefix' value. The prefix parameter defaults to "Last Comments" and is (possibly) translated to the language of your post or blog.
single_post_title( 'Read what my visitors have to say' );
[edit] profile_title()
This function displays a page title when a registered member has accessed their profile from the front (public) side of your blog. This function is similar to the "single_cat_title" and "single_post_title" and "arcdir_title" and "last_comments_title" functions: it has two parameters (prefix and display), and you should only consider altering the 'prefix' value. The prefix parameter defaults to "User Profile" and is (possibly) translated to the language of your post or blog.
single_post_title( 'The information this blog has about you' );
Note that profiles are not publicly accessible. Therefore this is ONLY seen by registered members of your blog, though a registered member can access his/her profile through the public side or the back office.
[edit] 'No Post' and 'Big Dates'
[edit] display_if_empty()
if( isset($MainList) ) $MainList->display_if_empty(); // Display message if no post
This function displays a message to visitors who come to a blog with no posts in it. There is only one parameter: message. The default value is "Sorry, there is no post to display..." and is (possibly) translated to the language of your post or blog. You can change this text and include html markup if you want to.
if( isset($MainList) ) $MainList->display_if_empty( '<h2>You got here before I posted anything!</h2><p>Come back later or subscribe to my rss feed</p>' ); // Display message if no post
[edit] date_if_changed()
$MainList->date_if_changed();
This function displays the date for each group of posts that happened on the same day. It is NOT the date and time of each post. It is the date for at least one post on any given day. This function has three parameters:
- before - defaults to <h2>
- after - defaults to </h2>
- format - defaults to the date and time stamp of the post or blog or locale.
You can customize both the tags and the format. Visit YOUR_BASEURL/admin/b2options.php?tab=regional&locale=_new_ for additional information on changing the date format.
$MainList->date_if_changed( '<h3 class="BigDate">', '</h3>', 'l F jS, Y' );
In this example your 'big date' would be enclosed in <h3> tags using your "BigDate" class (which you would have to add to your CSS file) and display "Saturday June 3rd, 2006".