CONTENTS OF THIS FILE

  • Introduction
  • Features
  • Requirements
  • Installation
  • Configuration
  • Building Blocks
  • Drush Commands
  • FAQ
  • Roadmap
  • Bonus Features
  • Similar Projects
  • Maintainers

INTRODUCTION

Codit: Blocks allows for creation of simple or complex blocks with custom
callback, access, and caching available for each block. Like all Codit based
modules, this is done entirely through code and no admin.

FEATURES

  • Blocks can be added quickly through code by adding a block directory and
    template, then flushing cache. Or use a drush codit-blocks-add.
  • Block Callback Function - Used for doing any heavy processing for the block.
    The code is contained in an anonymous function to reduce collision risk.
    Anything returned by the function gets passed to the template.
  • Access Function - Used to restrict access based on specific permission, role,
    user, field value or any combination thereof.
  • Caching - Caching of any Codit: Block's block can be done on a site-wide,
    per page, per path, per user, per role, per permission, per field value or
    any combination thereof.
  • Any block placed on a node or taxonomy term page has immediate access to that
    node object or taxonomy term.
  • 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.

REQUIREMENTS

Dependency: Codit: Local
Dependency: Codit

INSTALLATION

  • If Codit and Codit: Local have already been installed on your site, then this
    submodule is ready to be enabled. Once enabled, if you use drush to create
    your blocks, then you need to do nothing more.
  • If you do not use drush to add a block, then you must copy the contents of
    the codit_block/boilerplate into codit_local

CONFIGURATION

  • No configuration is needed. You simply create blocks and position them with
    Context, Panels, or the native block admin.

BUILDING BLOCKS

Drush Steps (recommended):

  1. drush codit-blocks-add {blockname} - This one command has created the block
    directory in codit_local/blocks/block_bin/ and created the template file and
    _callback.inc.
  2. Your new block is now registered as a block. You can move on down to
    'Your Block is Ready.'

Manual Steps

  1. Codit: Blocks are created by copying the _a_sample_block directory inside
    codit_local/blocks/block_bin and naming it with the new block name (delta).
    example: cp -r codit_local/blocks/block_bin/_a_sample_block codit_local/blocks/block_bin/cool_block
    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.
  2. Rename the tpl.php file in the directory to match the block name.
    example: rename _sample_block.tpl.php codit_blocks_cool_block.tpl.php
    Note: This tpl can also be copied *(not moved)* to the theme for overriding.
  3. Open the tpl and alter extract($blockdata_a_sample_block); to be
    extract($blockdata_cool_block); then save the file.
  4. Flush the cache and your new block 'cool block' will be registered with the
    the system. You can move on down to 'Your Block is Ready.'

Your Block is Ready

  1. Place your block using Context, Panels or the native Drupal block admin.
    Whichever system you normally use, should be fine.
  2. Alter the Block Callback function to pass DATA to the block
    (optional, but recommended)
    a) If your block requires any processing of php, this should be done in the
    _callback function located in _callback.inc in the block directory.
    Anything $_callback() returns will be passed to the tpl (pass multiple
    items in an associative array).
    b) Open codit_local/blocks/block_bin/{block_name}/_callback.inc
    c) Process any data needed for your block. 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.
    d) 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.
  3. (optional) Address any caching needed in $_cache_id() in _callback.inc
    a) Open codit_local/blocks/block_bin/{block_name}/_callback.inc
    b) Alter the function $_cache_id() to return a unique cache ID. Code hints are
    in the function to get you started.
    c) If the block needs its cache to expire, the duration of how long before it
    expires can be set by appending the duration in seconds in a pipe attached
    to the cache_id.
    Example: For a block to be cached with the id of 'this_is_my_block' and
    cached for an hour, have the $_cache return 'this_is_my_block|3600'
    d) To disable Codit: Block caching temporarily, use
    ?{your debug slug}=blocks-no-cache on the url and it will bypass caching.
  4. (optional) Address any access restrictions in $_access() in _callback.inc
    a) Open codit_local/blocks/block_bin/{block_name}/_callback.inc
    b) 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.
  5. Edit your tpl to format the output of the content of your block.

Drush Commands

  • drush codit-blocks-add {blockname} --enable=FALSE
    Creates the block directory, callback file and tpl in codit_local/blocks/bloc_bin.
    and flushes the block cache to register the new block. The optional enabled
    flag can be set to false to start the block in the disabled state.
  • drush codit-blocks-disable {blockname}
    Disables the block if it is enabled and flushes the block cache to de-register
    the block.
  • drush codit-blocks-enable {blockname}
    If the block is currently disabled, it will enable it and flush the block
    cache to register it.
  • drush codit-blocks-cache-clear-block-list
    Clears the block cache to register or de-register blocks.
  • drush codit-blocks-list
    Clears the block list cache and lists the Codit: Blocks that are enabled.
  • drush codit-blocks-cache-flush
    Clears the cached data for all Codit: Blocks.
  • drush codit-blocks-local-init
    Sets up the blocks directory within Codit local if it does not exist. This is
    not needed if you use drush to add the first block.

FAQ

Q: A block is misbehaving, how do I remove it temporarily?
A: You have several options. The easiest is to add an underscore to the
front of the directory name. The underscore tells Codit: Blocks to ignore
it. The other option would be to remove it from output in Context, Panels or
the block admin.
Q: I created a block but it is not showing up. How should I debug?
A: There are several reasons why a block would not showing up:
  1. Check the watchdog log. Most errors will appear there.
  2. The name of the tpl file and the name of the block directory do not match.
    example: Directory name 'block_foo' needs to contain a tpl named
    'block_foo.tpl.php'
  3. The $_access() callback in _callback.inc is returning FALSE.
  4. The tpl is not outputting anything.
  5. The first time you loaded the block, nothing was output and that is now
    cached even though you changed the code. Flush cache.
  6. It is not properly placed using Context, Panels, or block admin.
Q: I moved the tpl to the theme and the block is not showing up. What is wrong?
A: The tpl for a block must reside in its directory inside
codit_local/blocks/block_bin/ You can COPY the tpl to your theme to override
it, but do not MOVE it to your theme.
Q: How can I change the displayed titles of blocks (optional)?
A: This is easy to set across the entire site:
  1. Open 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 overridden. Many
    times it is more convenient to disable them all so that blocks roll-up when
    they are empty, so it is best to output 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',
Q: Will this work with core Drupal Block caching enabled?
A: Yes, Codit Blocks will function with core drupal block caching enabled,
however, Codit: Blocks caching is much more granular and works best if core
block caching is disabled.

ROADMAP

  • Conversion to Drupal 8 such that migrating a block from D7 to D8 will be as
    simple as copy and paste of the block directory. (Assuming nothing used in
    that block is specific to D7.)

BONUS FEATURES

The following module is not required, but if you have it enabled it will
improve the experience:

  • Markdown - When the Markdown filter is enabled, display of the module help
    for any of the Codit modules and submodules will be rendered with markdown.

Similar Block Projects and how they differ

We have a choice of 4 modules to create custom blocks for a site:

See: rel="nofollow">Comparison of Drupal 7 block making methods.
Codit: Blocks is more robust in many ways, offering developers who code a lot
more control over their blocks.

  • Code - 100% code based. The only admin is whatever tool you use to place
    them (block admin, Context, Panels)
  • Caching - Simple yet highly capable caching ranging from sitewide to per
    user or per page, or even per-user-per-subpath on a block by block basis.
  • Individual Block User Access - Easy to define access based on role, user
    or any other custom criteria.
  • Editing Blocks - Only someone with developer access can modify these
    blocks.
  • Heavy PHP Processing - resides safe from collisions in an anonymous
    callback function that passes items to the template for the block.
  • Output - Use a block specific tpl.php for each block. It can be copied to
    the theme if needed to have different output on sites with multiple themes.

MAINTAINERS

Supporting organizations: 
Granted me time to release this module

Project Information

Downloads