0byt3m1n1

Path: /data/applications/aps/gallery/2.2-08/htdocs/modules/core/classes/ [ Home ]
File: GalleryEmbed.class
<?php
/*
 * Gallery - a web based photo album viewer and editor
 * Copyright (C) 2000-2007 Bharat Mediratta
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA  02110-1301, USA.
 */

/**
 * Access point for external application in which Gallery is embedded.
 * See http://codex.gallery2.org/index.php/Gallery2:Embedding for more information
 * on embedding / integration.
 * Three interaction modes:
 *  1) GalleryEmbed::init(array(..)) followed by GalleryEmbed::handleRequest()
 *  2) GalleryEmbed::init(array(.., 'fullInit' => true)) followed by other
 *     GalleryEmbed/G2 calls, end with GalleryEmbed::done() <-- REQUIRED
 *  3) Single GalleryEmbed::logout(array(..)) call
 *
 * All of these methods should be accessed in a static sense, ie: GalleryEmbed::handleRequest();
 *
 * @package GalleryCore
 * @subpackage Classes
 * @author Alan Harder <alan.harder@sun.com>
 * @author Andy Staudacher <ast@gmx.ch>
 * @version $Revision: 15718 $
 * @static
 */
class GalleryEmbed {

    /**
     * Return the major and minor version of the Embedding API.
     * Make sure to specify the 'apiVersion' parameter in the GalleryEmbed::init call!
     *
     * @see GalleryCoreApi::getApiVersion, the same rules and notes apply to the Embedding API
     * @return array major number, minor number
     */
    function getApiVersion() {
	return array(1, 2);
    }

    /**
     * Return whether the supplied Embedding API version is compatible or not
     *
     * @param array $apiVersion int major, int minor
     * @return boolean
     */
    function isCompatibleWithEmbedApi($apiVersion) {
	return GalleryUtilities::isCompatibleWithApi($apiVersion, GalleryEmbed::getApiVersion());
    }

    /**
     * Initialize Gallery; must be called before most GalleryEmbed methods can be used.
     * This method should only be called once during the lifetime of the request.
     *
     * @param array $initParams (optional--required before calling handleRequest) (
     *   'embedUri' => URI to access G2 via CMS application
     *                 (example: /portal/index.php?module=gallery2)
     *   'g2Uri'    =  URL path to G2
     *                 (example: /gallery2/, see extended docs for special character '|')
     *   'loginRedirect' => (optional) URI for redirect to CMS login view (example: /cms/index.php)
     *   'embedSessionString' => (optional) To support cookieless browsing, pass in key=value for
     *                CMS session key and session id value to be added as query parameter in urls
     *   'gallerySessionId' => (optional) To support cookieless browsing, pass in G2 session id
     *                    (when cookies not in use, CMS must track this value between requests)
     *   'activeUserId' => (optional) external user id of active user
     *                                (empty string for anonymous/guest user)
     *   'activeLanguage' => (optional) language code in use for this session
     *   'fullInit' => (optional) call GalleryInitSecondPass
     *                            (only use when not calling handleRequest)
     *   'apiVersion' => (optional) array int major, int minor (check if your integration is
     *                   compatible)
     * )
     * @return object GalleryStatus a status object
     */
    function init($initParams=array()) {
	/* GDC as static var replacement for better testability */
	static $firstCacheKey = 'GalleryEmbed::initFirstPass';
	static $secondCacheKey = 'GalleryEmbed::initSecondPass';

	/* Only InitFirstPass if not already done so in a prior call */
	if (!GalleryDataCache::containsKey($firstCacheKey)) {
	    GalleryEmbed::_saveState();
	    if (isset($initParams['embedUri'])) {
		$initParams['baseUri'] = $initParams['embedUri'];
		unset($initParams['embedUri']);
	    }
	    $ret = GalleryInitFirstPass($initParams);
	    if ($ret) {
		return $ret;
	    }
	    GalleryDataCache::put($firstCacheKey, true);
	}

	if (isset($initParams['apiVersion'])) {
	    if (!GalleryEmbed::isCompatibleWithEmbedApi($initParams['apiVersion'])) {
		return GalleryCoreApi::error(ERROR_PLUGIN_VERSION_MISMATCH, __FILE__, __LINE__,
					     'Embedding API version is incompatible');
	    }
	}

	global $gallery;
	$gallery->setConfig('login', false);
	if (isset($initParams['loginRedirect'])) {
	    $gallery->setConfig('loginRedirect', array('href' => $initParams['loginRedirect']));
	}

	if (isset($initParams['activeUserId'])) {
	    $ret = GalleryEmbed::checkActiveUser($initParams['activeUserId']);
	    if ($ret) {
		return $ret;
	    }
	}

	if (empty($initParams) || (isset($initParams['fullInit']) && $initParams['fullInit'])) {
	    /* Only InitSecondPass if not already done so in a prior call */
	    if (!GalleryDataCache::containsKey($secondCacheKey)) {
		$ret = GalleryInitSecondPass();
		if ($ret) {
		    return $ret;
		}
		GalleryDataCache::put($secondCacheKey, true);
	    }
	}

	return null;
    }

    /**
     * Complete the G2 transaction.
     *
     * @return object GalleryStatus a status object
     */
    function done() {
	global $gallery;
	$session =& $gallery->getSession();
	$ret = $session->save();
	if ($ret) {
	    return $ret;
	}
	if ($gallery->isStorageInitialized()) {
	    $storage =& $gallery->getStorage();
	    $ret = $storage->commitTransaction();
	    if ($ret) {
		return $ret;
	    }
	}
	GalleryEmbed::_restoreState();
	return null;
    }

    /**
     * Process the G2 request.
     * Return value contains 'isDone'=>true if output has already been sent
     * (redirect, or output from G2 immediate view like core.DownloadItem) and
     * CMS should not send any additional output.  If isDone is false then check
     * headHtml and bodyHtml keys for content to display via CMS.
     * Include activeUserName parameter if integration is not calling GalleryEmbed::login()
     * at CMS login time.
     * themeData is set if isDone is false and populated with the corresponding template variable.
     *
     * @return array ('isDone' => boolean,
     *                [optional: 'headHtml' => string, 'bodyHtml' => string,
     *                           'sidebarBlocksHtml' => array('blockHtml', 'blockHtml'),
     *                           'themeData' => mixed theme data]
     */
    function handleRequest() {
	$result = GalleryMain(true);
	GalleryEmbed::_restoreState();
	return $result;
    }

    /**
     * Ensure G2 session has same active user as CMS session.
     * No need to call directly if activeUserId is passed to init().
     *
     * @param string $activeUserId external user id of active user
     *               (null or empty for anonymous/guest user)
     * @return object GalleryStatus a status object
     * @access private
     */
    function checkActiveUser($activeUserId) {
	global $gallery;
	$session =& $gallery->getSession();

	$idInSession = $session->get('embed.id.externalUser');
	if ($idInSession === $activeUserId) {
	    return null;
	}

	$language = $session->get('core.language');
	if (empty($activeUserId)) {
	    if ($session->isPersistent()) {
		/* Logout */
		$ret = $session->reset();
		if ($ret) {
		    return $ret;
		}
	    }
	    $session->put('embed.id.externalUser', $activeUserId);
	} else {
	    /* Set G2 active user */
	    list ($ret, $user) =
		GalleryCoreApi::loadEntityByExternalId($activeUserId, 'GalleryUser');
	    if ($ret) {
		return $ret;
	    }
	    $gallery->setActiveUser($user);
	    $session->put('embed.id.externalUser', $activeUserId);
	}

	/* The session language has precedence over the user default language */
	if (!empty($language)) {
	    $session->put('core.language', $language);
	}

	return null;
    }

    /**
     * Login the specified user in the G2 session.
     * This method is not usually needed (passing activeUserId to init() or calling
     * checkActiveUser will login the user as needed); this method included for completeness.
     *
     * @param string $extUserId external user id
     * @return object GalleryStatus a status object
     */
    function login($extUserId) {
	global $gallery;
	list ($ret, $user) = GalleryCoreApi::loadEntityByExternalId($extUserId, 'GalleryUser');
	if ($ret) {
	    return $ret;
	}
	$gallery->setActiveUser($user);
	$session =& $gallery->getSession();
	$session->put('embed.id.externalUser', $extUserId);

	$ret = $session->regenerate();
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Reset the G2 session.  Do not call init() before this method.
     *
     * Specify embedUri (the same embedUri as the one from ::init())
     *
     * @param array $params ('embedUri' => string the embedUri (e.g. /cms/index.php))
     * @return object GalleryStatus a status object
     */
    function logout($params=array()) {
	require_once(dirname(__FILE__) . '/GalleryCoreApi.class');
	require_once(dirname(__FILE__) . '/GallerySession.class');
	$hasSession = GalleryUtilities::getCookieVar(SESSION_ID_PARAMETER);
	if (empty($hasSession)) {
	    $hasSession = GalleryUtilities::hasRequestVariable(SESSION_ID_PARAMETER);
	}
	if (!empty($hasSession)) {
	    GalleryEmbed::_saveState();
	    $ret = GalleryInitFirstPass($params);
	    if ($ret) {
		return $ret;
	    }
	    global $gallery;
	    $session =& $gallery->getSession();
	    $ret = $session->reset();
	    if ($ret) {
		return $ret;
	    }
	    /* Commit the transaction */
	    $ret = GalleryEmbed::done();
	    if ($ret) {
		return $ret;
	    }
	}
	return null;
    }

    /**
     * Retrieve G2 session id.  This method can be called after init() or handleRequest().
     *
     * @return string session id
     */
    function getSessionId() {
	global $gallery;
	$session =& $gallery->getSession();
	return $session->getId();
    }

    /**
     * Save any state we'd like to restore after G2 processing.
     */
    function _saveState() {
	if (isset($GLOBALS['ADODB_FETCH_MODE'])) {
	    GalleryDataCache::put('GalleryEmbed::ADODB_FETCH_MODE', $GLOBALS['ADODB_FETCH_MODE']);
	}
    }

    /**
     * Restore state before returning control to embedding app.
     */
    function _restoreState() {
	if (GalleryDataCache::containsKey('GalleryEmbed::ADODB_FETCH_MODE')) {
	    $GLOBALS['ADODB_FETCH_MODE'] = GalleryDataCache::get('GalleryEmbed::ADODB_FETCH_MODE');
	}
    }

    /**
     * Create a G2 user.
     *
     * @param string $extUserId external user id
     * @param array $args user data (username required; others optional)
     *              ['username' => string, 'email' => string, 'fullname' => string,
     *               'language' => string, 'password' => string,
     *               'hashedpassword' => string, 'hashmethod' => string,
     *               'creationtimestamp' => integer]
     * @return object GalleryStatus a status object
     */
    function createUser($extUserId, $args) {
	if (empty($extUserId) || empty($args['username'])) {
	    return GalleryCoreApi::error(ERROR_BAD_PARAMETER);
	}
	list ($ret, $user) = GalleryCoreApi::newFactoryInstance('GalleryEntity', 'GalleryUser');
	if ($ret) {
	    return $ret;
	}
	if (!isset($user)) {
	    return GalleryCoreApi::error(ERROR_MISSING_OBJECT);
	}

	$ret = $user->create($args['username']);
	if ($ret) {
	    return $ret;
	}
	GalleryEmbed::_setUserData($user, $args, true);
	$ret = $user->save();
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::addMapEntry(
	    'ExternalIdMap',
	    array('externalId' => $extUserId,
		  'entityType' => 'GalleryUser', 'entityId' => $user->getId()));
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Update a G2 user.
     *
     * @param string $extUserId external user id
     * @param array $args user data
     *              ['username' => string, 'email' => string, 'fullname' => string,
     *               'language' => string, 'password' => string,
     *               'hashedpassword' => string, 'hashmethod' => string,
     *               'creationtimestamp' => integer]
     * @return object GalleryStatus a status object
     */
    function updateUser($extUserId, $args) {
	list ($ret, $user) = GalleryCoreApi::loadEntityByExternalId($extUserId, 'GalleryUser');
	if ($ret) {
	    return $ret;
	}
	list ($ret, $lockId) = GalleryCoreApi::acquireWriteLock($user->getId());
	if ($ret) {
	    return $ret;
	}

	GalleryEmbed::_setUserData($user, $args);
	$ret = $user->save();
	if ($ret) {
	    GalleryCoreApi::releaseLocks($lockId);
	    return $ret;
	}
	$ret = GalleryCoreApi::releaseLocks($lockId);
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Set values in user object based on given args.
     *
     * @param object GalleryUser $user
     * @param array $args additional user data
     * @access private
     */
    function _setUserData(&$user, $args, $create = false) {
	if (!empty($args['password'])) {
	    $user->changePassword($args['password']);
	} elseif (isset($args['hashmethod']) && $args['hashmethod'] == 'md5'
		&& !empty($args['hashedpassword'])) {
	    $user->setHashedPassword($args['hashedpassword']);
	} elseif ($create) {
	    /* Create a random password */
	    $user->changePassword('G' . rand(100000,999999) . '2');
	}

	if (isset($args['username'])) {
	    $user->setUserName($args['username']);
	}
	if (isset($args['email'])) {
	    $user->setEmail($args['email']);
	}
	if (isset($args['fullname'])) {
	    $user->setFullName($args['fullname']);
	}
	if (isset($args['language'])) {
	    list ($languageCode) = GalleryTranslator::getSupportedLanguageCode($args['language']);
	    $user->setLanguage($languageCode);
	}
	if (isset($args['creationtimestamp'])) {
	    $user->setCreationTimestamp($args['creationtimestamp']);
	}
    }

    /**
     * Delete a G2 user.
     *
     * @param string $extUserId external user id
     * @return object GalleryStatus a status object
     */
    function deleteUser($extUserId) {
	list ($ret, $user) = GalleryCoreApi::loadEntityByExternalId($extUserId, 'GalleryUser');
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::deleteEntityById($user->getId());
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::removeMapEntry(
	    'ExternalIdMap',
	    array('externalId' => $extUserId, 'entityType' => 'GalleryUser'));
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Create a G2 group.
     *
     * @param string $extGroupId external group id
     * @param string $groupName group name
     * @return object GalleryStatus a status object
     */
    function createGroup($extGroupId, $groupName) {
	if (empty($extGroupId) || empty($groupName)) {
	    return GalleryCoreApi::error(ERROR_BAD_PARAMETER);
	}
	list ($ret, $group) = GalleryCoreApi::newFactoryInstance('GalleryEntity', 'GalleryGroup');
	if ($ret) {
	    return $ret;
	}
	if (!isset($group)) {
	    return GalleryCoreApi::error(ERROR_MISSING_OBJECT);
	}

	$ret = $group->create($groupName);
	if ($ret) {
	    return $ret;
	}
	$ret = $group->save();
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::addMapEntry(
	    'ExternalIdMap',
	    array('externalId' => $extGroupId,
		  'entityType' => 'GalleryGroup', 'entityId' => $group->getId()));
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Delete a G2 group.
     *
     * @param string $extGroupId external group id
     * @return object GalleryStatus a status object
     */
    function deleteGroup($extGroupId) {
	list ($ret, $group) = GalleryCoreApi::loadEntityByExternalId($extGroupId, 'GalleryGroup');
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::deleteEntityById($group->getId());
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::removeMapEntry(
	    'ExternalIdMap', array('externalId' => $extGroupId, 'entityType' => 'GalleryGroup'));
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Update a G2 Group.
     *
     * @param string $extGroupId external group id
     * @param array $args group data
     *              ['groupname' => string]
     * @return object GalleryStatus a status object
     */
    function updateGroup($extGroupId, $args) {
	list ($ret, $group) = GalleryCoreApi::loadEntityByExternalId($extGroupId, 'GalleryGroup');
	if ($ret) {
	    return $ret;
	}
	list ($ret, $lockId) = GalleryCoreApi::acquireWriteLock($group->getId());
	if ($ret) {
	    return $ret;
	}

	if (isset($args['groupname'])) {
	    $group->setGroupName($args['groupname']);
	}
	$ret = $group->save();
	if ($ret) {
	    GalleryCoreApi::releaseLocks($lockId);
	    return $ret;
	}
	$ret = GalleryCoreApi::releaseLocks($lockId);
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Add a user to a G2 group.
     *
     * @param string $extUserId external user id
     * @param string $extGroupId external group id
     * @return object GalleryStatus a status object
     */
    function addUserToGroup($extUserId, $extGroupId) {
	list ($ret, $user) = GalleryCoreApi::loadEntityByExternalId($extUserId, 'GalleryUser');
	if ($ret) {
	    return $ret;
	}
	list ($ret, $group) = GalleryCoreApi::loadEntityByExternalId($extGroupId, 'GalleryGroup');
	if ($ret) {
	    return $ret;
	}
	/* First check if the user is not already a member of the group */
	list ($ret, $membership) = GalleryCoreApi::fetchGroupsForUser($user->getId());
	if ($ret) {
	    return $ret;
	}
	/* Only add user to group if not already done so */
	if (!isset($membership[$group->getId()])) {
	    $ret = GalleryCoreApi::addUserToGroup($user->getId(), $group->getId());
	    if ($ret) {
		return $ret;
	    }
	}
	return null;
    }

    /**
     * Remove a user from a G2 group.
     *
     * @param string $extUserId external user id
     * @param string $extGroupId external group id
     * @return object GalleryStatus a status object
     */
    function removeUserFromGroup($extUserId, $extGroupId) {
	list ($ret, $user) = GalleryCoreApi::loadEntityByExternalId($extUserId, 'GalleryUser');
	if ($ret) {
	    return $ret;
	}
	list ($ret, $group) = GalleryCoreApi::loadEntityByExternalId($extGroupId, 'GalleryGroup');
	if ($ret) {
	    return $ret;
	}
	$ret = GalleryCoreApi::removeUserFromGroup($user->getId(), $group->getId());
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Perform a search across all available searchable modules.
     *
     * @param string $searchString search criteria
     * @param int $resultsPerModule (optional) max number of results to return from each module,
     *            defaults to 3
     * @return array object GalleryStatus a status object
     *               array of {module_id} => results array plus 'name' key with module name
     * @see GallerySearchInterface_1_0::search for contents of results arrays
     */
    function searchScan($searchString, $resultsPerModule=3) {
	global $gallery;

	$session =& $gallery->getSession();
	$ret = $session->start();
	if ($ret) {
	    return array($ret, null);
	}
	$session->doNotUseTempId();

	GalleryCoreApi::requireOnce('modules/search/classes/SearchUtilities.class');
	$searchInstances = $searchResults = array();
	list ($ret, $ids) =
	    GalleryCoreApi::getAllFactoryImplementationIds('GallerySearchInterface_1_0');
	if ($ret) {
	    return array($ret, null);
	}

	foreach ($ids as $id => $className) {
	    list ($ret, $searchInstances[$id]) =
		GalleryCoreApi::newFactoryInstance('GallerySearchInterface_1_0', $className);
	    if ($ret) {
		return array($ret, null);
	    }
	}
	foreach ($searchInstances as $id => $instance) {
	    list ($ret, $searchInfo) = $instance->getSearchModuleInfo();
	    if ($ret) {
		return array($ret, null);
	    }
	    $options = array();
	    foreach ($searchInfo['options'] as $option => $info) {
		if ($info['enabled']) {
		    $options[$option] = true;
		}
	    }
	    list ($ret, $searchResults[$id]) =
		$instance->search($options,
				  SearchUtilities::sanitizeSearchCriteria($searchString),
				  0, $resultsPerModule);
	    if ($ret) {
		return array($ret, null);
	    }
	    $searchResults[$id]['name'] = $searchInfo['name'];
	}
	return array(null, $searchResults);
    }

    /**
     * Search specific module.
     *
     * @param string $searchString search criteria
     * @param string $moduleId id of module to search
     * @param int $offset start index
     * @param int $count number of results to retrieve
     * @return array object GalleryStatus a status object
     *               results array plus 'name' key with module name
     * @see GallerySearchInterface_1_0::search for contents of results array
     */
    function search($searchString, $moduleId, $offset, $count) {
	global $gallery;

	$session =& $gallery->getSession();
	$ret = $session->start();
	if ($ret) {
	    return array($ret, null);
	}
	$session->doNotUseTempId();

	GalleryCoreApi::requireOnce('modules/search/classes/SearchUtilities.class');
	list ($ret, $searchInstance) =
	    GalleryCoreApi::newFactoryInstanceById('GallerySearchInterface_1_0', $moduleId);
	if ($ret) {
	    return array($ret, null);
	}
	if (!isset($searchInstance)) {
	    return array(GalleryCoreApi::error(ERROR_MISSING_OBJECT), null);
	}
	list ($ret, $searchInfo) = $searchInstance->getSearchModuleInfo();
	if ($ret) {
	    return array($ret, null);
	}
	$options = array();
	foreach ($searchInfo['options'] as $option => $info) {
	    if ($info['enabled']) {
		$options[$option] = true;
	    }
	}
	list ($ret, $searchResults) =
	    $searchInstance->search($options,
				    SearchUtilities::sanitizeSearchCriteria($searchString),
				    $offset, $count);
	if ($ret) {
	    return array($ret, null);
	}
	$searchResults['name'] = $searchInfo['name'];
	return array(null, $searchResults);
    }

    /**
     * Parse html (headHtml) for css links, javascript and page title
     *
     * @param string $headhtml
     * @return array(string title, array (string css1, string css2, ...),
     *               array (string javascript1, string javascript2, ...))
     */
    function parseHead($headhtml) {
	$title = '';
	$css = array();
	$javascript = array();

	/* Only one title allowed */
	if (preg_match("|<title(?:\s[^>]*)?>(.*)</title>|Usi", $headhtml, $regs)) {
	    $title = $regs[1];
	}

	/* More than one script section allowed */
	if (preg_match_all(
		"|<script(?:\s[^>]*)?(?:\ssrc=[\"\'].+[\"\'])?(?:\s[^>]*)?>.*</script>|Usi",
		$headhtml, $regs, PREG_PATTERN_ORDER)) {
	    foreach ($regs[0] as $script) {
		$javascript[] = $script;
	    }
	}

	/* More than one style allowed */
	if (preg_match_all("/<link .*\/>|<style(?:\s[^>]*)?>.*<\/style>/Usi",
			   $headhtml, $regs, PREG_PATTERN_ORDER)) {
	    foreach ($regs[0] as $style) {
		$css[] = $style;
	    }
	}

	return array($title, $css, $javascript);
    }

    /**
     * Get HTML for an image block
     *
     * @param array $params ('blocks' => string, 'show' => string, (optional)'heading' => int,
     *        (optional)'itemId' => int, (optional)'maxSize' => int, (optional)'exactSize' => int,
     *        (optional)'itemFrame' => frameId, (optional)'albumFrame' => frameId)
     * 'blocks' is a pipe (|) separated list, of one or more possible blocks which are:
     * randomImage|recentImage|viewedImage|randomAlbum|recentAlbum|viewedAlbum|specificItem
     * dailyImage|weeklyImage|monthlyImage|dailyAlbum|weeklyAlbum|monthlyAlbum
     * 'show' is a pipe (|) separated list of one or more possible choices which are:
     * title|date|views|owner|heading|fullSize or just 'none'
     * If you choose 'blocks' => 'specificItem', you must specify 'itemId' too.
     * example: GalleryEmbed::getImageBlock(array('blocks' => 'randomImage',
     *                                            'show' => 'title|date'));
     * itemFrame/albumFrame may require CSS to be displayed.
     * See Image Block Site Admin page for info on optional parameters.
     * @return array object GalleryStatus
     *               string html content
     *               string head content or null if none required
     */
    function getImageBlock($params) {
	global $gallery;
	$moduleId = 'imageblock';
	$blockHtml = $headHtml = null;

	$session =& $gallery->getSession();
	$ret = $session->start();
	if ($ret) {
	    return array($ret, null, null);
	}
	$session->doNotUseTempId();

	/* Load the module list */
	list ($ret, $moduleStatus) = GalleryCoreApi::fetchPluginStatus('module');
	if ($ret) {
	    return array($ret, null, null);
	}

	if (isset($moduleStatus[$moduleId]) && !empty($moduleStatus[$moduleId]['active'])
		&& $moduleStatus[$moduleId]['active']) {
	    /* Load the G2 templating engine */
	    GalleryCoreApi::requireOnce('modules/core/classes/GalleryTemplate.class');
	    $template = new GalleryTemplate(dirname(__FILE__) . '/../../..');
	    $template->setVariable('l10Domain', 'modules_' . $moduleId);

	    if (!isset($params['maxSize'])) {
		$params['maxSize'] = null;
	    }

	    /* Generate the imageblock */
	    GalleryCoreApi::requireOnce(
		'modules/imageblock/classes/ImageBlockHelper.class');
	    $ret = ImageBlockHelper::loadImageBlocks($template, $params);
	    if ($ret) {
		return array($ret, null, null);
	    }

	    if ($template->hasVariable('ImageBlockData')) {
		$ImageBlockData =& $template->getVariableByReference('ImageBlockData');
		$ImageBlockData['forceFullUrl'] = 1;
		$tpl = 'modules/imageblock/templates/ImageBlock.tpl';
		/* Render and get the imageblock html */
		list ($ret, $blockHtml) = $template->fetch("gallery:$tpl");
		if ($ret) {
		    return array($ret, null, null);
		}
		/* Check for any css required for imageframes */
		$head = $template->getVariable('head');
		if (!empty($head['tpl'])) {
		    list ($tpl) = each($head['tpl']);
		    list ($ret, $headHtml) = $template->fetch("gallery:$tpl");
		    if ($ret) {
			return array($ret, null, null);
		    }
		}
	    }
	} else {
	    return array(GalleryCoreApi::error(ERROR_CONFIGURATION_REQUIRED), null, null);
	}
	return array(null, $blockHtml, $headHtml);
    }

    /**
     * Add an externalId<->entityId map entry for existing G2/emApp users/groups
     * example: GalleryEmbed::addExternalIdMapEntry($uid, $g2user->getId(), 'GalleryUser');
     *
     * @param string $externalId the user/group id in the embedded application
     * @param int $entityId the entityId of the user/group in G2
     * @param string $entityType 'GalleryUser' for user mapping, 'GalleryGroup' for group mapping
     * @return object GalleryStatus
     */
    function addExternalIdMapEntry($externalId, $entityId, $entityType) {
	$ret = GalleryCoreApi::addMapEntry(
	    'ExternalIdMap',
	    array('externalId' => $externalId,
		  'entityType' => $entityType,
		  'entityId' => $entityId));
	if ($ret) {
	    return $ret;
	}
	return null;
    }

    /**
     * Get the complete externalId<->entityId map (for users and groups),
     * the return array is organized by externalId or by entityId
     *
     * @param string $key 'externalId' or 'entityId', array is organized by this key
     * @return array object GalleryStatus
     *               array(externalId|entityId => array(externalId => int/string,
     *                                                  entityId => int, entityType => string))
     */
    function getExternalIdMap($key) {
	/* Input validation */
	if ($key != 'externalId' && $key != 'entityId') {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER), null);
	}
	list ($ret, $results) = GalleryCoreApi::getMapEntry('ExternalIdMap',
	    array('entityId', 'externalId', 'entityType'));
	if ($ret) {
	    return array($ret, null);
	}

	$map = array();
	while ($result = $results->nextResult()) {
	    $entry = array('externalId' => $result[1],
			   'entityId' => $result[0], 'entityType' => $result[2]);
	    if ($key == 'externalId') {
		$map[$result[1]] = $entry;
	    } else if ($key == 'entityId') {
		$map[$result[0]] = $entry;
	    }
	}
	return array(null, $map);
    }

    /**
     * Check if externalId is mapped to a G2 user/group.
     * If GalleryStatus is a success, the externalId is mapped. Else, check for the status code.
     * ERROR_MISSING_OBJECT -> externalId is not mapped to a G2 entity.
     * other error codes -> unexpected behavior / bug.
     *
     * @param string $externalId the user/group id in the embedded application
     * @param string $entityType 'GalleryUser' for user mapping, 'GalleryGroup' for group mapping
     * @return object GalleryStatus
     */
    function isExternalIdMapped($externalId, $entityType) {
	list ($ret, $results) = GalleryCoreApi::getMapEntry('ExternalIdMap',
	    array('entityId'), array('externalId' => $externalId, 'entityType' => $entityType));
	if ($ret) {
	    return $ret;
	}
	if (!($result = $results->nextResult())) {
	    return GalleryCoreApi::error(ERROR_MISSING_OBJECT, __FILE__, __LINE__,
					"$externalId $entityType");
	}
	return null;
    }
}
?>