Contents of /contributions/modules/multiblock/README

PROBLEM:
Drupal's block module is limited by the fact that a block can
only have one instance. Each block has a 1:1 relationship with
its region, weight, visibility (and other) settings. This means 
that it is impossible to have blocks in multiple regions or to
have blocks that have different settings on different pages.

SOLUTION:
multiblock module will keep track of multiple instances of blocks
and dispatch to their appropriate block hooks. Using this stratgey,
you would not enable any blocks that are implemented by other
modules. Instead, you will go to admin/build/multiblock and create
an "instance" of a block. Multiblock module will then implement this
block in its own block hook which will forward any hook_block calls
to the original module's hook. Using this method we can maintain
multiple instances of blocks with different settings but the same
implementation. This should not affect block-level caching. One
catch here is that the configure and save $op's for hook_block
are usually implemented to save only one set of data. This means
that for blocks that are unaware of multiblock you will only be
able to save CUSTOM data (this doesnt include visibility, weight,
region, etc.) for one set of data.

HOW TO USE IT:
1. Go to admin/build/multiblock
2. Select the type of block you want to create an instance of and
   type a unique title for that instance
3. Click "Add Instance"
4. Go to admin/build/block
5. Enable the block instance you have just created.

DEVELOPING MULTIBLOCK-ENABLED BLOCKS:
Multiblock should successfully clone any regular block created with
hook_block. However, if you clone a regular block that implements a
save or configure $op of hook_block, the custom block settings of
one block instance will overwrite the settings of another. To get
around this, you can make a block "multiblock enabled". To do this,
you have to first add an $op to your hook_block called 'mb_enabled'.
It should always return the string 'mb_enabled'. Once you do this,
the instances you create will get the block instance ID passed
in the $edit variable for the view, configure, and save $ops. This
will let you save and load different data to different instances
based on this instance ID. It is passed in with the
'multiblock_delta' key with the following format:
$edit['multiblock_delta'] = array(
          '#type' => 'value',
          '#value' => $block_id
      );
1	PROBLEM:
2	Drupal's block module is limited by the fact that a block can
3	only have one instance. Each block has a 1:1 relationship with
4	its region, weight, visibility (and other) settings. This means
5	that it is impossible to have blocks in multiple regions or to
6	have blocks that have different settings on different pages.
7
8	SOLUTION:
9	multiblock module will keep track of multiple instances of blocks
10	and dispatch to their appropriate block hooks. Using this stratgey,
11	you would not enable any blocks that are implemented by other
12	modules. Instead, you will go to admin/build/multiblock and create
13	an "instance" of a block. Multiblock module will then implement this
14	block in its own block hook which will forward any hook_block calls
15	to the original module's hook. Using this method we can maintain
16	multiple instances of blocks with different settings but the same
17	implementation. This should not affect block-level caching. One
18	catch here is that the configure and save $op's for hook_block
19	are usually implemented to save only one set of data. This means
20	that for blocks that are unaware of multiblock you will only be
21	able to save CUSTOM data (this doesnt include visibility, weight,
22	region, etc.) for one set of data.
23
24	HOW TO USE IT:
25	1. Go to admin/build/multiblock
26	2. Select the type of block you want to create an instance of and
27	type a unique title for that instance
28	3. Click "Add Instance"
29	4. Go to admin/build/block
30	5. Enable the block instance you have just created.
31
32	DEVELOPING MULTIBLOCK-ENABLED BLOCKS:
33	Multiblock should successfully clone any regular block created with
34	hook_block. However, if you clone a regular block that implements a
35	save or configure $op of hook_block, the custom block settings of
36	one block instance will overwrite the settings of another. To get
37	around this, you can make a block "multiblock enabled". To do this,
38	you have to first add an $op to your hook_block called 'mb_enabled'.
39	It should always return the string 'mb_enabled'. Once you do this,
40	the instances you create will get the block instance ID passed
41	in the $edit variable for the view, configure, and save $ops. This
42	will let you save and load different data to different instances
43	based on this instance ID. It is passed in with the
44	'multiblock_delta' key with the following format:
45	$edit['multiblock_delta'] = array(
46	'#type' => 'value',
47	'#value' => $block_id
48	);