View source

'''Blocks Guide''' ([http://efiction.org/forums/index.php?topic=3113.0 source])
This is a re-write of the creating_blocks.htm included in your /docs folder. Hopeully this will help users to have a better understanding of blocks

'''What are Blocks?'''
Blocks are a major component of eFiction, the way your blocks are set affects how parts of your site (that are blocks) will display.

Some examples of blocks are the menu & login blocks. If you take a look at the eFiction demo (or your installation) you will see the menu (displaying Home, Browser Members, Search etc.) and login (or if you are already logged in, a message that says "you are logged in as penname".)

This is because your blocks are "Active". Block configuration can be accessed through the admin panel by going to Admin -> Blocks. They are displayed by using {blockname_title} and {blockname_content} in your .tpl files.

0 '''Inactive''' means that your block is off will not display anywhere
1 '''Active''' means that this block is on and will be displayed on all your pages
2 '''Index''' Only means that this block is on and will only display on your index

'''Installing/Activating Blocks'''
1. If you haven't already, unzip the folder for the block you have downloaded and upload it to /blocks. Your /blocks folder already comes with some blocks that can be activated by going to the next step.
2. Once you have done that, login to your eFiction site and go to Admin -> Blocks
3. The name of the folder of the block you just uploaded should display under Name.
4. Under Title, Status, and Admin it should say "Initialize Block", click Initalize Block.
5. Doing so will bring up the Title, Status and Option (if any). To have you block become activated (on), you need  to change the status of your block from Inactive to Active or Index Only and click Submit.

You have sucessfully installed a block.

'''Creating Blocks'''
Note: blockname does not need to be the same name as the block folder.

To create a block you will need a basic understanding of PHP for creating a basic block. This guide should help you with the basics.

There are two files needed for each block: blockname.php and 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 an array that is added to the $blocks array when the block is initiated.  As in the example below.

<?php
$blocks["categories"] = array("title" => "Main Categories", "status" => "0", "file" => "categories/categories.php");
?>

For your block you would need to change Main Categories to your block name, and adjust the status (0, 1, 2)  as well as categories/categories.php to the folder and the name of your blockname.php file.

The blockname.php is the file that displays what you are going to put in your block, and it's functions. Basically it creates the content that is displayed when you place {blockname_content} on your .tpl file.

The information in the $blocks array is stored in blocks_config.php.  When you change any of the settings for the blocks from the admin panel this is where the changes are made. Which is why your blocks_config.php needs to be CHMODed properly.

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:

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

There are two other optional files. The first is an admin file which will be accessed from the admin panel to make changes to the settings in the block. Creating an admin panel for your block will be in another guide/addition some other time.

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/$_GET[admin]/{$language}.php")) include("blocks/$_GET[admin]/{$language}.php");

The if(...) isn't technically necessary, but it will prevent errors if the file ends up missing.  For example, if the  site's language is set to Russian, but the block doesn't have a Russian translation (which would be ru.php). 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.