编辑“Gallery:主题:参考:回调”

Callback主要用于读取外观主题区块中的数据。

一般来说，callback用于模板文件（.tpl）的数据读取。因为大部分模板文件显示的数据都被外观主题（themes/*/theme.inc）或视图所读取了，因此callback主要用于区块的数据读取。

== 举例 ==
* 模块/exif/模板/区块/ExifInfo.tpl 为某一特定图片显示并格式化EXIF信息。
* ExifInfo.tpl使用callback呼叫为图片读取EXIF数据：
  {g->callback type="exif.LoadExifInfo" itemId=$item.id}
* ''{g->callback }''标签指示Gallery调用一个callback
* ''type=exif.LoadExifInfo'' 指示Gallery callback的实际请求。形式总是为''moduleId'' . ''CallbackName''
** 这种情况，''moduleId''为''exif'' – 它指示Gallery在modules/exif/Callbacks.incs中查询callback名称。
** 这种情况，''CallbackName''为''LoadExifInfo''
* 你可以向callback函数传送任意多的参量。这种情况下，我们传送''itemId=$item.id''来指示callback为特定id的项目读取EXIF数据。
* 最后，callback被调用，它处理请求并按约定将结果存储在''$block.moduleId.CallbackName''的一个模板变量中，''$block.exif.LoadExifInfo''
* 在模板中（ExifInfo.tpl），我们可以使用被读取的数据，例如通过显示''$block.exif.LoadExifInfo.exifData''

== 现有Callback ==

* '''albumselect.LoadAlbumData''' [albumTree=true]
** 将相册树载入$block.albumselect.LoadAlbumData（keys tree，titles，params）中
** 如果albumTree 参量被传送，也会为此tree（key albumTreeName）生成唯一的id

* '''cart.LoadCart'''
** 将cart数据载入$block.cart.ShowCart (keys unique，total)中

* '''comment.AddComment''' [itemId=..]
** 准备Add Comment表单

* '''comment.LoadComments''' [itemId=..] [show=..]
** 将comment（评论）载入$block.comment.LoadComments（keys comments，commenters，can，item，totalComments）中
** itemId = 为此项目读取评论
** show = 评论读取的最大限数

* '''core.LoadLanguageSelector'''
** 激活语言并载入$block.core.LanguageSelector（keys list，language）中

* '''core.ShouldShowEmergencyEditItemLink''' [permissions=..] [checkBlocks=..]
** 通过为core.ItemLinks区块检查各定义区块列表，设置$block.core.ShouldShowEmergencyEditItemLink为true/false；如未找到就设置flag为true
** 旧的checkSidebarBlocks/checkAlbumBlocks/checkPhotoBlocks参量被弃用；使用类似checkBlocks="sidebar,album"的参量

* '''core.LoadPeers''' [item=..] [windowSize=..] [loadThumbnails=..] [addEnds=..]
** 将peer数据（window around given item plus first/last if addEnds is true）载入i$block.core.LoadPeers（keys peers，peerCount，thisPeerIndex，parent）
** windowSize默认为7，loadThumbnails默认为false，addEnds默认为true

* '''core.LoadValidationPlugins''' [level=..] [key=..]
** 为已注册的ValidationPlugins（captcha）将模板数据载入$blocks.core.ValidationPlugins
** 如果忽略level那么核心模块的validation.level参量就会被使用
** 当可能使用中级别安全等级时，就需要key（密钥）（此验证请求的唯一字串）

* '''customfield.LoadCustomFields''' [itemId=..]
** 为给定项目将'细节'自定义字段载入$block.customfield.LoadCustomFields.fields

* '''exif.LoadExifInfo'''
**为给定项目将EXIF数据载入$block.exif.LoadExifInfo（keys exifData，mode）
** 是否读取摘要或细节信息是由检查存储在对话中的flag来决定的

* '''imageblock.LoadImageBlock''' [parameters..]
** 将图片区块数据载入$ImageBlockData（keys blocks，show等）
** 参见Image Block Site Admin（图片区块站点管理）中的可用参量列表
** repeatBlock=.. 重复给定区块参量相应的次数（如blocks=recentImage|recentImage与blocks=recentImage repeatBlock=2是一样的）

* '''keyalbum.LoadKeywords''' [onlyPublic=..] [maxCloudFontEnlargement=..]
** 为gallery中所有关键词将数据载入$block.keyalbum.keywords
** 结果将被缓存1日
** onlyPublic作为boolean来决定是载入读取关键词还是仅从公共项目读取
** maxCloudFontEnlargement则为最常见关键词的字体像素尺寸（结果中"weight"的最大值）

* '''members.LoadMembers'''
** 将会员数据载入$block.members.LoadMembers（keys canViewList，count）

* '''quotas.LoadQuotas'''
** 将quota和disk usage信息载入$block.quotas.LoadQuotas

* '''rating.LoadRating''' [itemId=..]
** 为给定项目将rating数据载入$block.rating.RatingData and $block.rating.RatingValues

* '''rss.FeedList''' [number=..]
** 将RSS feed数据载入$block.rss

== 新Callback的创建 ==
现在让我们在[[#Example|example]]上做个扩展，来更近一些看看实际处理callback的代码。
* 按照约定，在''modules/exif/Callbacks.inc''中声明的类别必须为''ExifCallbacks''，其形式总是为''moduleId''Callbacks
* callback类别被期望实现单个函数来对所有callback呼叫进行处理：
<pre>
  /**
   * @param array $params 传送到callback的参量（在我们的例子中仅定义了$params['itemId']）
   * @param object GallerySmarty $smarty smarty对象的参照
   * @param string $callback callback的名称（在我们的例子中是''LoadExifInfo''）
   * @param int $userId 动作用户的userId（在权限检查中使用此userId）
   * @return object GalleryStatus（在函数末尾返回null;）
   */
  function callback($params, &$smarty, $callback, $userId=null) { ... }
</pre>
* callback(...)函数中的代码具有如下典型的用处：
** 识别准确的callback名称，因为callback函数可被exif.LoadExifInfo或exif模块的其他任何callback所呼叫。
** 读取被请求的数据
** 将被请求的数据指派给一个模板变量
* 这里有一个简略的例子：
<pre>
class ExifCallbacks {
  function callback($params, &$smarty, $callback, $userId=null) {
      /* 1. 识别准确的callback名称 */
      switch ($callback) {
	case 'LoadExifInfo':
            /* 2. 读取被请求的数据 */
	    GalleryCoreApi::requireOnce('modules/exif/classes/ExifHelper.class');
            $exifData = ExifHelper::getExifData($params['itemId']);

            /* 3. 将被请求的数据指派给一个模板变量 */
            $block =& $smarty->_tpl_vars['block'];
            /* By convention, put the data into $block[$moduleId] (in this case, moduleId is 'exif') */
	    $block['exif']['LoadExifInfo'] = array('exifData' => $exifData,
						   'randomNumber' => rand()); // You can put any data into the template variable...
	    break;
	case 'SomeOtherCallbackName':
            ...
      }

      return null;
  }
}
</pre>
* 切记，在这里''exif''与''LoadExifInfo''仅作为$moduleId和$callback的示例。请在你的代码中将这些值改为你自己的moduleId或callback名称。

[[Category:Gallery 2:Development]]