Creating Blocks

content of file: docs/creating_blocks.htm

For those that want to create their own blocks to share with others or just tweak the ones included already, here's the basics. There are two files needed for each block: blockname.php an init.php. Technically, if you added the block manually, you wouldn't need the init.php file. It is only used when the block is first initialized, and can be deleted afterward. Though I would suggest keeping a backup somewhere, just in case.

The init.php file is very simple composed simply of a mysql statement that adds the block tot he database. As in the example below.

<?php
dbquery("INSERT INTO ".TABLEPREFIX."fanfiction_blocks(`block_name`, `block_title`, `block_status`, `block_file`, `block_variables`) VALUES('categories', 'Main Categories', '0', 'categories/categories.php', '');");
?>

This also shows the basic parameters needed for a block: name, title, status, file, and variables. The title can be an empty string if you don't need a title for that particular block. If the block doesn't need any variables, that too can be left empty. The file should be a subfolder/file of the blocks folder for the sake of consistency. The status should generally start off as 0 for inactive. There are 3 status options for blocks:

Status	Associated .tpl file	Appears
0	Inactive	The block is off.	nowhere
1	Active	The block is on.	anywhere
2	Index only	index page only.	anywhere on the index page.

Any default configuration you want for the block can be included in the init.php as well. The variables are an array encoded using PHP's serialize function. For instance, the categories block currently has two options: one column and multiple columns. The default is a single column lists. If I were to change the init file as follows, the default would then become a multiple column list.

<?php
dbquery("INSERT INTO ".TABLEPREFIX."fanfiction_blocks(`block_name`, `block_title`, `block_status`, `block_file`, `block_variables`) VALUES('categories', 'Main Categories', '0', 'categories/categories.php', '".serialize(array("columns" => "1"))."');");
?>

When you change any of the settings for the blocks from the admin panel the information stored in the database about the block is updated.

The block.php file creates the content that is placed inside the {blockname_content} variable. This content is placed inside a variable $content which is then assigned to {blockname_content} So a very simple example of a block would be:

<?php
$content = "Hello World!";
?>

There are two other optional files. The first is an admin file which will be called from the admin panel to make changes to the settings in the block. Creating one of those is for another day.

The second file (or multiple files) is a language file that defines any text you use in your block. These files take the same format as the main language file in the languages folder and are named similarly. So for instance, an English language file would be named en.php. For Spanish, it would be es.php.

Most often, you might need to define some wording for your admin.php file. If you need to add a language file, use the following code in either admin.php or blockname.php

if(file_exists("blocks/categories/{$language}.php")) 
include_once("blocks/categories/{$language}.php");

The if(...) isn't technically necessary, but it will prevent errors if the file ends up missing. For instance, the site's language is set to Russian, but the block doesn't have a Russian translation. You might also want to include an else statement to load a default language file you have created if the site's chosen language is missing.

if(file_exists("blocks/categories/{$language}.php")) 
include_once("blocks/categories/{$language}.php");
else include_once("blocks/categories/en.php");

To keep your block files secure from hackers you are strongly encouraged to include this line at the top of each file just under the <?php

if(!defined("_CHARSET")) exit( );