Location: PHPKode > projects > Enigma > Enigma2/Enigma2_Upgrade_from_beta5/Blocks/Blocks.txt
*****************************************************************

 Blocks.txt

*****************************************************************
LSP: Lunabyte Systems Portal
Open-Source Project Inspired by Zef Hemel (hide@address.com)
*****************************************************************
Software Version:                  LSP 2.0 "Enigma 2"
Software by:                         Lunabyte Systems (http://www.lunabyte.net)
Copyright 2002-2005 by:       Lunabyte Systems (http://www.lunabyte.net)
Support, News, Updates at:    http://www.lunabyte.net
*****************************************************************
This program is free software; you may redistribute it and/or modify it
under the terms of the provided license as published by Lunabyte Systems.

This program is distributed in the hope that it is and will be useful,
but WITHOUT ANY WARRANTIES; without even any implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "LSP_license.txt" file for details of the LSP license.
The latest version can always be found at http://www.lunabyte.net.
*****************************************************************

This file is here to help explain what is needed to create a new block type 
for your Enigma Portal. This is only for selectable blocks, as you can still just
put code in a block as always via a "Custom" Block type.
So, this is mainly for mod writers.

In the past, if mod creators wanted to add features to the portal, they
would have to dump new php files inside the Sources directory and then
add to the gigantic action or op arrays that existed in the index.php file
of previous versions of Enigma and YaBB SE.

With Enigma 2.0 you are able to add new features to your portal without
having to edit the original installation files and there is no need for
adding to any internal arrays. If a request is made for a block, the
Blocks directory is automatically scanned for the corresponding Block_name.php
file and loaded as needed to excecute functions.


The following will need to be expanded as Enigma 2.0 expands and moves further
along in it's updates to a final release, but currently this will explain the
basics....


*** New Block Types ***

Any new blocks types added to your Enigma installation should be added as a
file inside the "Blocks" directory to prevent modification of the main code
base which will help maintain compatibility for future upgrades of the main
code and package.

To add a block type, follow the steps below.

1.	Generate your block code in a new file, and save it in the Blocks
	directory. Use one of the Block files as an example if you need to.
	Name your file in the same style as the others in this directory.
	
		Block_{BlockName}.php
		
	Replace {BlockName} with the actual name for your block.

2.	Inside the block file, the main function for the Block needs to be named
	in a similar manner.
	
		function Block_{BlockName}()
		
	Again, replace {BlockName} with the actual name.
	
3.	It is HIGHLY recommended that you use a new language file for any text that
	is displayed by your new block.  Block language files are located in the
	languages/portal/blocks path inside your theme(s) directory.  Create the
	language file with the following format:
	
		Block_{BlockName}.{language}.php
		
	Replace {BlockName} with the name used above and replace {language} with
	the language contained within the file.
	When adding variables to the new language file, use the format in the example
	below.

	$txt['{BlockName}_{#}'] = 'text to be displayed here';
	
	replace {BlockName} with the name from above and {#} with a digit.
	
	- or -
	
	$txt['{BlockName}_{description}'] = 'text to be displayed here';
	
	{description} can be replaced with a SHORT description of what the variable says.

	Enter your text to be displayed within the quotes, following the equal sign.
	Remember to escape single quotes with a backslash!  (   don't    would be     don\'t    )
	For examples, look at the other language files.

4.   If the new block is to use a template file, which will allow users to
	edit the layout and display of the Block Contents, you will need to
	set a variable telling the code to load a template file.
	In the line, immediately above the main function, enter:

		$blockTemplate = true;

	When the block contents are loaded for this block, the BlockSubs file
	will automatically check for a template file for the block.  If the file
	doesn't exist, an error message will be display in place of the block contents.
	The template file also needs to follow the block naming format and be placed
	inside the portal/blocks directory of your theme(s).

		Block_{BlockName}.template.php

	Again, replace {BlockName} with the name used previously.
	If no template file is to be used with this block, DO NOT set the $blockTemplate
	variable and no check will be run for the file.  The display will be output
	as it is coded in the Block file.

5.	Now you will need to add your new block to the select list for Blocks
	Management.  In order to do this, pen BlockTypes.php from the Blocks directory
	and add the name used above to the $blockTypes array.  (without to "Block_" prefix)
	Make sure the name for the block is unique. To make the addition, add another
	line inside the array statement following the format of the other lines.
	Refer to example below.

			//function installedBlocks()
			// {
			// 	$blockTypes = array(
			//		'polls',
			//		'{mynewblock}',
			//	);
			//
			// return $blockTypes;
			// }


6. 	Now you will need to add a variable to each of the BlocksTypes.(language).php files
	in your theme(s). BE SURE to follow the other block examples in the file.
	It is CRUCIAL that you have a variable named $txt['blk_{BlockName}'] = 'Block Name';
	in this file. Replace {BlockName} with the name used in all of the steps above.
	If you fail to do this, your block name will not show in the selection list,
	and it will only be a blank space.  If you only have one BlockTypes.(language).php
	file in your Theme, then that is the only place you will need to add any extra
	$txt variables at this time.

**Bonus Feature**

Another neat feature has been coded for blocks that have HTML forms in them.
If your block file displays a form and you need to create another function within the
block file for processing, you can use a couple of special methods for call the
function once the submit button is clicked and then return to the page the user
came from.

1. 	When creating the variables for display, make sure you create a query string variable
	to use for the page to return to after processing.  Follow this example:

   		$context['unique_name_here'] = $_SERVER['PHP_SELF'] . '?' . $_SERVER['QUERY_STRING'];

   		Replace "unique_name_here" with something that will suit the block and form you are
   		creating.

2.	The action for your form should be:
		
		action="', $scripturl, '?block=Block_currentblock;func=functiontocall"
		
		Replace "currentblock" with the block name of your block as used in the Block file
		creation steps and replace "functiontocall" with the function you create for
		processing the form.

3.	In your template or form display (if not using a template file), make sure you have
	a hidden form field with a name of "loc" and a value set with the context variable
	set in step 1.

4.	When creating your form processing function, do all your form processing and just before
	the end of the function, you'll need to enter the following line so that it will exit
	back to the page it came from:
	
			redirectexit($_REQUEST['loc'], false);

	The $_REQUEST['loc'] is the location that you set in step 1 and the "false" is important
	so that the $scripturl variable does not get added to the location when redirecting.


**More Bonus Features**

As if blocks hadn't grown and developed enough... we added some more helpful and handy features for
mod writers that are creating new blocks.

Does your new block need it's own permissions or settings?  Does your new block have custom error
messages that need language variables loaded?  Well, we've made some additions that will allow you
to add these features without having to modify any of the existing Enigma files.  You can create
some new files and drop them into a few existing directories and they will be loaded automatically when
needed.  We will not get too in depth in explantions below, but will specify the directory names
and what they are used for.  Please refer to the modules.txt file for formatting information since
they are identical with the exception of the directory names.

Inside the main Enigma "Blocks" directory are 2 new directories that are explained below.

	BlockPermissions - if your new block needs custom permission variables to check, put those
		files here.  (modules.txt file for formatting info)

	BlockSettings - need to add a custom setting to the Portal Settings page for your block?  Add
		it here. (modules.txt ;) )

Inside the languages directory of the default theme, in portal/blocks there are also some new directories
for autoloading.

	BlockAdminHelp - when creating Settings in the BlockSettings directory described above, put your
		help variables for those settings in this directory.

	BlockErrors - blocks that may have custom error messages will need a file in this directory.  This
		directory is the only one read on every page load, so be careful how much you put in it
		as it MAY slow down sites if there are too many files being read from here.

	BlockPermissions - put language vars in a file for the permissions described above.  Follow all the
		normal formats for files.

	BlockSettings - files containing language variables for settings described above.  Again, follow
		all of the normal formats.

And again, please refer to the modules.txt file in the modules directory for more information regarding usage
of each of these directories and formatting of files.

Return current item: Enigma