Gallery2:How To Create Blocks - Gallery Codex
Personal tools

Gallery2:How To Create Blocks

From Gallery Codex

Creating New Blocks

Modules can provide blocks that can be placed anywhere in your Gallery layout. Think of Lego bricks, you can build your own layout by arranging blocks any way you want.

For a list of all existing blocks, please refer to Blocks in Theme Reference.

  • A minimal module block consists of an entry in modules/moduleid/templates/blocks/blocks.inc and a corresponding template file at modules/moduleid/templates/blocks/.
  • CSS links, JavaScript resources and any HTML <head> content can be added with Preloads.
  • Some standard data (default item, user) is loaded and ready to be accessed through template variables. See: Template Variables
  • Data can be loaded with Callbacks.
  • Blocks can be parametrized, a block can show for a specific item. The itemId can be passed as a parameter.
  • It is recommended to learn from existing blocks. Look for examples at modules/*/templates/blocks/, modules/*/Preloads.inc, and modules/*/Callbacks.inc.


Example of a Minimal Block

To create a block called Example in the test module:

  • Create a blocks.inc file at modules/test/templates/blocks/blocks.inc with the contents:
<?php
$blocks = array(
    'Example' => array(
        'description' => $gallery->i18n('Example block')));
?>
  • Create a block template at modules/test/templates/blocks/Example.tpl (filename must be 'blockname.tpl') with the contents:
  {if $user.isRegisteredUser}
    {g->text text="Hello %s" arg1=$user.userName}
  {else}
    {g->text text="Welcome! Login to see more photos!"}
  {/if}

Example With Block Parameters

Blocks.inc

The block parameters need to be specified in the blocks.inc file: 

<?php
$blocks = array(
    'Example' => array(
        'description' => $gallery->i18n('Example block'),
        'vars' => array(
            'someNumber' => array(
                'description' => $gallery->i18n('A number between 1 and 5'),
                'type' => 'choice',
                'default' => '5',
                'choices' => array(
                    '1' => 1,
                    '2' => 2,
                    '3' => 3,
                    '4' => 4,
                    '5' => 5)),
            'textToShow' => array(
                'description' => $gallery->i18n('The text to be shown'),
                'type' => 'text',
                'default' => ''),
            )));
?>

Block Template

  • The block parameters can be used in the template.
  • A default should be assigned to each parameter.
  • $item is a very common block parameter and it often makes sense to default it to $theme.item. You don't need to list this parameter in blocks.inc.
{assign var=someNumber value=$someNumber|default:5}
{if empty($item)} {assign var=item value=$theme.item} {/if}

{capture assign="defaultMessage"}{g->text text="This is an example block"}{/capture}
{assign var=textToShow value=$textToShow|default:$defaultMessage}

<div class="{$class}">
  <p>{$textToShow}</p>
  <p>{g->text text="You chose number %s!" arg1=$someNumber}
  {if $item.canContainChildren}
    {g->text text="This is an album!"}
  {/if}
</div>

Preloads

  • If your block depends on a CSS file or if you want to include a JavaScript file in the HTML <head> section instead of in your block, you can use a block preload.
  • There is a strict naming convention for preloads and preloads are called automatically if a block is part of any block list of a theme.
  • If you include a block manually (with {g->block ...} then the preload isn't called. You need to include any CSS/JavaScript manually too.

To create a preload for our Example block of the test module, create a Preloads.inc file at modules/test/Preloads.inc with the contents: 

<?php
class TestPreloads {
    function preload(&$template, $preload, $paramSet) {
	static $loaded;

	if (!empty($loaded[$preload])) {
	    return null;
	}

	$loaded[$preload] = 1;
	switch($preload) {
	case 'Example':
            /* To include a CSS file... */
	    $template->style('modules/test/MyCssFile.css');
            /* To include a JavaScript file... */
	    $template->javascript('modules/test/MyJavaScriptFile.js');
	    return null;
        case 'ExampleTwo':
            // Put here the preloads for another block of your module
	}

	return GalleryCoreApi::error(ERROR_BAD_PARAMETER);
    }
}
?>

Note:

  • The class name must match the module id. Format "${moduleid}Preloads"
  • List all blocks of your module in the switch statement of the preloads file.


Example With Parameters and A Callback

  • For documentation on callbacks, please see Callbacks.
  • We use the same blocks.inc as the one from the previous example with parameters

Block Template

{assign var=someNumber value=$someNumber|default:5}
{if empty($item)} {assign var=item value=$theme.item} {/if}

{capture assign="defaultMessage"}{g->text text="This is an example block"}{/capture}
{assign var=textToShow value=$textToShow|default:$defaultMessage}

{* Load some data *}
{g->callback type="test.LoadItemData" itemId=$item.id myLimit=$someNumber}

{if !empty($block.test.LoadItemData)}
<div class="{$class}">
  <p>{$textToShow}</p>
  <ul>
  {foreach from=$block.test.LoadItemData.items item=photo}
    <li>{g->text text="Photo name:"}{$photo.title}, {g->text text="Owner: %s" arg1=$photo.owner}</li>
  {/foreach}
  </ul>
</div>
{/if}

Note:

  • In this example we assume that the test module also has a callback with the name LoadItemData that loads some items and related data (owner name). If $itemId is the id of an album, it could load up to $someNumber child items of that album. It could also filter the children to only return photos (and no movies, mp3s, or other media).
Retrieved from "http://codex.galleryproject.org/index.php?title=Gallery2:How_To_Create_Blocks&oldid=16344"