Codit Blocks

Drupal Documentation

The module Codit: Blocks handles several nice items related to blocks:

  • Blocks can be added quickly  through code (similar to custompage blocks, but without any admin or database changes) by adding a block directory and template, then flushing cache.
  • Any block can have a callback function that automatically takes what it returns and puts it in the $variables array for the tpl to access.  These callback functions should only return data, not markup.  Save the processing of turning data into markup for the tpl.   Callback function also easily handle caching and permissions access.
  • Can be used to override any block title, including the ability to disable all block titles except any that have been overridden.
  • Block placement can be handled by the Context module, Panels, or the block admin.
 

Make A New Block

  1. Open codit_local/blocks/block_bin
  2. Copy the directory _a_sample_block and name it with a meaningful block name (block delta).  You must use underscores not hyphens and keep it shorter than 32 characters.  Do not precede the name with an underscore, that is used to disable a block.
    example: 'new_block_name' 
  3. Rename the tpl in the new directory to match the block name you just created.
    example: 'new_block_name.tpl.php' 
  4. Flush cache and your new block will now be registered as block.  At this point, whatever is output in the tpl will be visible to all users including anonymous. 
  5. (optional) Make a blockdata callback function by adding your code inside of $_callback() in _callback.inc in that block directory. (see next section)
  6. (optional) Add an access callback by modifying $_access() in _callback.inc.  This will control who has the ability to see the display of this block.
  7. (optional) Add a caching callback by modifying $_cache_id() to return a unique cache id.

Alter the Block Callback function to pass DATA to the block (optional, but recommended)

  1. Open codit_local/blocks/block_bin/{block_name}/_callback.inc
  2. Alter the function $_callback()  as you need to in order to process any data
  3. This function will have access to the current entity ($o_entity) for the page that the block is on (node or term) and be able to alter it by reference.
  4. Whatever the $_callback function returns, will be available to the template in the $variables array
    example:  $variables['blockdata_new_block_name']
    Best practice is that this should be data, not markup.  Any markup should be done on the tpl.   Take this into consideration as you structure the items you are returning from the function.  It is best practice to have the function return an array or object so that you can pass multiple items to the tpl.

Alter the Access callback to restrict the visibility of the block to certain users or roles. (optional)

  1. Open codit_local/blocks/block_bin/{block_name}/_callback.inc
  2. Alter the function $_access() to do any role, permission or user processing to return TRUE when it should be visible and FALSE when it should not.  Code hints are in the function to get you started.

 

Alter the Cache ID callback to control what gets cached and where. (optional)

  1. Open codit_local/blocks/block_bin/{block_name}/_callback.inc
  2. Alter the function $_cache_id() to return a unique cache ID.    Code hints are in the function to get you started.

Alter the Name of a Block (optional)

  1. codit_local/blocks/config_blocks.inc
  2. Add an entry to the $_codit_blocks_block_title_override array with the block delta as the key and the actual title you want to be displayed.
    Reminder: When you enable this module, it shows all block titles by default. However by setting $_codit_blocks_block_title_override['show-block-titles'] = FALSE you can force it to not show any but the ones you have overriden. Many times it is more convenient to disable them all so that blocks  roll-up when they are empty, so it is best to ouput a title from the tpl rather than using Drupal's block title system. 
  3. To accommodate allowing block titles on blocks that have dynamic hashed block deltas. (example, the facet blocks built by apacheSOLR. You actually want those titles to show, rather than be hidden. To allow a given module to have all its blocks have titles, add a line like this to the  $_codit_blocks_block_title_override array 'module_name' => 'all',

Block Debugging

When debugging a block check the following:

  1. Check inside codit_local/blocks/block_bin.  The block directory name and tpl filename must match.
  2. Flush Cache.
  3. Make sure the $_access callback is returing TRUE.
  4. Use ?{debug-slug}=blocks to output the variables in question and see where they are coming from.

 

section: