Gallery:如何创建区块
= 区块的新建 =
模块提供的区块可以被放置在Gallery布局的任意位置。想想乐高（Lego）砖吧，通过任意布置区块，你可以创建自己的布局样式。
请参看外观主题中的区块，以获取现有的所有区块列表。.
- 最小化，模块区块由modules/moduleid/templates/blocks/blocks.inc中的入口点和modules/moduleid/templates/blocks/上的对应模板文件所构成。
- CSS链接，JavaScript源码及任何HTML <head>内容都可以使用Preloads进行添加。
- 一些标准数据（默认项目，用户）已加载并随时可通过模板变量进行访问。参见：模板变量
- 数据可通过Callbacks载入。
- 区块可被参量化，区块可为某特定项目进行显示。itemId可作为参量传输。
- 推荐从现有区块开始进行学习。可在modules/*/templates/blocks/，modules/*/Preloads.inc和modules/*/Callbacks.inc中找例子。
最小化区块示例
在测试模块中创建一个名为Example的区块：- 使用如下内容在modules/test/templates/blocks/blocks.inc中创建一个blocks.inc文件：
array(
'description' => $gallery->i18n('Example block')));
?>
- 使用如下内容在modules/test/templates/blocks/Example.tpl（文件名必须为'blockname.tpl'）中创建一个区块模板：
{if $user.isRegisteredUser}
{g->text text="Hello %s" arg1=$user.userName}
{else}
{g->text text="Welcome! Login to see more photos!"}
{/if}
区块参量示例
Blocks.inc
区块参量需要在blocks.inc文件中指定：
array(
'description' => $gallery->i18n('Example block'),
'vars' => array(
'someNumber' => array(
'description' => $gallery->i18n('介于1和5之间的一个数字'),
'type' => 'choice',
'default' => '5',
'choices' => array(
'1' => 1,
'2' => 2,
'3' => 3,
'4' => 4,
'5' => 5)),
'textToShow' => array(
'description' => $gallery->i18n('要显示的文本'),
'type' => 'text',
'default' => ),
)));
?>
区块模板
- 区块参量可用在模板中。
- 应为各参量分派默认值。
- $item是一很常见的区块参量，一般默认为$theme.item。你无需在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}{$textToShow}
{g->text text="You chose number %s!" arg1=$someNumber} {if $item.canContainChildren} {g->text text="This is an album!"} {/if}
预加载（Preload）
- 如果你的区块依靠CSS文件或想在HTML <head>部分包括进Javascript文件而不是在区块中的话，可以使用区块预加载。
- preload的命名惯例很严格，，而入某区块是某外观主题区块列表一部分的话，preload就会自动被呼叫。
- 如果你是手动包括区块的话（使用{g->block ...}），那么preload就不会被呼叫。你还需要手动包括CSS/JavaScript。
要为测试模块的Example区块创建preload的话，使用如下内容在modules/test/Preloads.inc中创建一个Preloads.inc文件：
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);
}
}
?>
注：
- 类别名称必须符合模块id.的格式，"${moduleid}Preloads"
- 在preload文件的分支语句中列出所有模块的区块。
参量和callback示例
- 有关callback的资料，请见Callbacks。
- 针对参量，我们使用前面例子中相同的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}
{* Load some data *}
{g->callback type="test.LoadItemData" itemId=$item.id myLimit=$someNumber}
{if !empty($block.test.LoadItemData)}
{$textToShow}
{foreach from=$block.test.LoadItemData.items item=photo}
- {g->text text="Photo name:"}{$photo.title}, {g->text text="Owner: %s" arg1=$photo.owner}
{/foreach}
{/if}
注：
- 在此例中，我们假设测试模块具有一名为LoadItemData''的callback，它会读取项目及相关数据（所有者名称）。如$itemId为某相册的id，它就能读至该相册的$someNumber子项目。它还能过滤子项目而仅返回图片（而不包括视频，mp3或其他媒体）。