Gallery2:Themes:Reference:Callbacks

Callbacks are mainly used to load data in theme blocks.

In general, callbacks can be used to load any data from template (.tpl) files. Since most template files are used to display data that has been loaded by the theme (themes/*/theme.inc) or by a view, callbacks are mainly used to load data for blocks only.

Example

• modules/exif/templates/blocks/ExifInfo.tpl is the template used to display and format the EXIF information for a specific image.
• ExifInfo.tpl loads the EXIF data for the image with a callback call:

 {g->callback type="exif.LoadExifInfo" itemId=$item.id}

• The {g->callback } tag instructs Gallery to invoke a callback
• type=exif.LoadExifInfo instructs Gallery what exact callback is requested. The type is always of the form moduleId . CallbackName
  • In this case, moduleId is exif - It instructs Gallery to look in modules/exif/Callbacks.incs for the callback name.
  • In this case, CallbackName is LoadExifInfo
• You can pass any number of parameters to the callback function. In this case, we pass itemId=$item.id to instruct the callback to load the EXIF data for the item with a specific id.
• Finally, the callback is invoked, it processes the request and stores the result by convention in a template variable at $block.moduleId.CallbackName, in this case $block.exif.LoadExifInfo
• In the template (ExifInfo.tpl), we can then use the loaded data, e.g. by displaying $block.exif.LoadExifInfo.exifData

Existing Callbacks

• albumselect.LoadAlbumData [albumTree=true]
  • Load album tree into $block.albumselect.LoadAlbumData (keys tree, titles, params)
  • If albumTree parameter is passed, also generate unique id for this tree (key albumTreeName)

• cart.LoadCart
  • Load cart data into $block.cart.ShowCart (keys unique, total)

• comment.AddComment [itemId=..]
  • Prepare Add Comment form

• comment.LoadComments [itemId=..] [show=..]
  • Load comments into $block.comment.LoadComments (keys comments, commenters, can, item, totalComments)
  • itemId = load comments for this item
  • show = maximum number of comments to load

• core.LoadLanguageSelector
  • Load language list and active language into $block.core.LanguageSelector (keys list, language)

• core.ShouldShowEmergencyEditItemLink [permissions=..] [checkBlocks=..]
  • Set $block.core.ShouldShowEmergencyEditItemLink to true/false by checking each specified block list for core.ItemLinks block; if not found then set the flag to true
  • Old checkSidebarBlocks/checkAlbumBlocks/checkPhotoBlocks parameters are deprecated; use parameter like checkBlocks="sidebar,album" instead

• core.LoadPeers [item=..] [windowSize=..] [loadThumbnails=..] [addEnds=..]
  • Load data about peers (window around given item plus first/last if addEnds is true) into $block.core.LoadPeers (keys peers, peerCount, thisPeerIndex, parent)
  • windowSize defaults to 7, loadThumbnails defaults to false, addEnds defaults to true

• core.LoadValidationPlugins [level=..] [key=..]
  • Load template data for registered ValidationPlugins (captcha) into $blocks.core.ValidationPlugins
  • If level is omitted then core module's validation.level parameter is used
  • key (some unique string for this validation request) is needed when medium security level may be used

• customfield.LoadCustomFields [itemId=..]
  • Load 'detail' custom fields for given item into $block.customfield.LoadCustomFields.fields

• exif.LoadExifInfo
  • Load EXIF data for given item into $block.exif.LoadExifInfo (keys exifData, mode)
  • Whether to load summary or detail info is determined by checking a flag stored in the session

• imageblock.LoadImageBlock [parameters..]
  • Load image block data into $ImageBlockData (keys blocks, show; etc)
  • See Image Block Site Admin for list of available parameters
  • repeatBlock=.. will repeat the given blocks parameter that many times (eg. blocks=recentImage|recentImage is the same as blocks=recentImage repeatBlock=2)

• keyalbum.LoadKeywords [onlyPublic=..] [maxCloudFontEnlargement=..]
  • Load data for all keywords in the gallery into $block.keyalbum.keywords
  • Results are cached for a day
  • onlyPublic is boolean to specify whether to load all keywords or just from public items
  • maxCloudFontEnlargement is how many pixels bigger the font size should be for the most common keyword (max value for "weight" in results)

• members.LoadMembers
  • Load members data into $block.members.LoadMembers (keys canViewList, count)

• quotas.LoadQuotas
  • Load quota and disk usage info into $block.quotas.LoadQuotas

• rating.LoadRating [itemId=..]
  • Load rating data for given item into $block.rating.RatingData and $block.rating.RatingValues

• rss.FeedList [number=..]
  • Load RSS feed data into $block.rss

Creating New Callbacks

Let's expand on the example by looking closer at the code that is actually processing the callbacks.

• By convention, the class declared in modules/exif/Callbacks.inc must be ExifCallbacks, it has always be of the form moduleIdCallbacks
• The callback class is expected to implement a single function to process all callback calls:

  /**
   * @param array $params The parameters passed to the callback (in our example, only $params['itemId'] is defined)
   * @param object GallerySmarty $smarty A reference to the smarty object
   * @param string $callback The callback name, in our example it's ''LoadExifInfo'')
   * @param int $userId The userId of the acting user (use this userId in permission checks, etc.)
   * @return object GalleryStatus (return null; at the end of the function)
   */
  function callback($params, &$smarty, $callback, $userId=null) { ... }

• Typically, the code in the callback(...) function does the following things:
  • Identify the exact callback name since the callback function could be called for either exif.LoadExifInfo or any other callback of the exif module.
  • Load the requested data
  • Assign the requested data to a template variable
• Here's an abbreviated example:

class ExifCallbacks {
  function callback($params, &$smarty, $callback, $userId=null) {
      /* 1. Identify the exact callback */
      switch ($callback) {
	case 'LoadExifInfo':
            /* 2. Load the requested data */
	    GalleryCoreApi::requireOnce('modules/exif/classes/ExifHelper.class');
            $exifData = ExifHelper::getExifData($params['itemId']);

            /* 3. Assign the requested data to a template variable */
            $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;
  }
}

• Please remember that exif and LoadExifInfo are just used as an example for $moduleId and $callback. Be sure to change the values to your own moduleId / callback name in your own code.