Gallery2 is designed to be easily embedded in other applications. The GalleryEmbed class
in embed.php provides APIs to assist in processing G2 requests and keeping sessions,
user logins and user/group data in sync between G2 and the embedding application.
In this document "embedding application" is shortened to emApp.
This document contains instructions for:
A) Embedding G2 in another application using existing integration code
B) Writing the integration code to embed G2 in another PHP application


___ Embedding G2 in another application using existing integration code ___
\___________________________________________________________________/

1) Install (separately) G2 and the app in which G2 will be embedded.
2) Obtain and install the G2 integration code written specifically for the emApp.
This may be a module or plugin if the emApp supports them, or a simple php file.
3) Follow instructions with the integration code to initially synchronize users and groups.
This may be done as part of module/plugin installation or via special php files.
4) Login to G2 as a site administrator:
a) Make sure the registration module is deactivated or not installed
b) Set the G2 session lifetime to at least twice the lifetime of sessions in the emApp.
This is because a user may visit G2 and then continue to use the emApp but not visit
G2 pages.. a longer G2 session timeout will help ensure their session sticks around
until they do visit a G2 page again. Note that if the G2 session does timeout and
the user returns then a new session will be created with the correct user logged in.
Other data from the old session is lost but the user login is restored.
5) Test the integration
6) Once everything is working you can choose to disable direct access to G2 and only
allow access via the emApp. To do this set the embedOnly flag in your config.php.


___ Writing the integration code to embed G2 in another PHP application ___
\___________________________________________________________________/

First install (separately) G2 and the app in which G2 will be embedded.

Next you need an entry point in the emApp for all G2 requests, (similar to
main.php in G2 standalone). This may be a module or plugin if the application
supports these, or a plain php file. Determine the URI/path for your access
point and the G2 base directory, relative to your webserver document root.
Examples: __ access point __ __ G2 base dir __
a) appdir/gallery2.php appdir/gallery2
b) appdir/plugins/gallery2.php appdir/lib/gallery2
c) appdir/index.php?module=gallery2 gallery2
d) index.php?page=gallery albums
Use these to determine the following values:
embedURI = Filename (and any query parameters, but NO path) for access point
embedPath = URL path from document root to embedUri
relativeG2Path = Path from directory for access point to G2 base directory
For the above examples these settings are:
__ embedURI __ __ embedPath __ __ relativeG2Path __
a) gallery2.php /appdir gallery2
b) gallery2.php /appdir lib/gallery2
c) index.php?module=gallery2 /appdir ../gallery2
d) index.php?page=gallery / albums
You’ll also need a URI for a login page or main page of the app; G2 will
redirect here for access attempts without proper permissions.
Examples: / or /appdir/login.php

The code in the access point to handle a G2 request looks something like this:

require_once(dirname(__FILE__) . ’relative/path/to/gallery2/embed.php’);
$ret = GalleryEmbed::init(array(
’embedUri’ => {value}, embedPath => {value}, ’relativeG2Path’ => {value},
’loginRedirect’ => {value}, ’activeUserId’ => {value}));
if ($ret->isError()) {
// $ret->getAsHtml() has error details..
exit;
}

$g2data = GalleryEmbed::handleRequest();
if ($g2data[’isDone’]) {
exit; // G2 has already sent output (redirect or binary data)
}

// Use $g2data[’headHtml’] and $g2data[’bodyHtml’]
// to display G2 content inside embedding application
// if you don’t want to use $g2data[’headHtml’] directly, you can get the css,
// javascript and page title separately by calling...

if (isset($g2moddata[’headHtml’])) {
list($title, $css, $javascript) = GalleryEmbed::parseHead($g2moddata[’headHtml’]);
}

The ’activeUserId’ value passed to init() enables session synchronization by
making sure the active user in G2 matches the emApp user. The value is the
active emApp user id. Pass in an empty string for anonymous/guest user
(NOT the user id of the emApp’s anonymous user if it has an id).
To complete session sync add a hook/callback/event-handler for the logout
operation in the emApp:
require_once(dirname(__FILE__) . ’relative/path/to/gallery2/embed.php’);
$ret = GalleryEmbed::logout();
This hook is not required, but it resets the G2 session at logout so a session for
a logged-in user isn’t left on the server.

Next decide if you want to support cookieless browsing. Some extra steps are
required if G2 can’t count on cookies to track its session id. The emApp must
be able to provide a key=value string for its own session key and id, and have
an available API to store additional data in the session.
Here are the extra steps:
1) The input array for the GalleryEmbed::init() call must also contain:
’embedSessionString’ => {key=value}, ’gallerySessionId’ => {value}
(omit gallerySessionId when the value is not yet known)
2) After the init() call:
$gallerySessionId = GallerEmbed::getSessionId();
{store value in emApp’s session}

Other optional tasks:
1) Prior to the handleRequest() call set GalleryCapabilities.
Check modules/core/classes/GalleryCapabilities.class for available settings;
also see the settings made by default in GalleryEmbed::init().
Example: GalleryCapabilities::set(’showSidebar’, false);
2) Check for ’sidebarHtml’ in content returned from handleRequest().
If the example GalleryCapabilities setting shown above is used then handleRequest()
may return ’sidebarHtml’ (when a core.ShowItem page is being viewed). You can include
this content in a block on the emApp sidebar.

Next add hooks to keep users in sync between G2 and the emApp.
The code in each case will look like this:
require_once(dirname(__FILE__) . ’relative/path/to/gallery2/embed.php’);
$ret = GalleryEmbed::init();
if ($ret->isError()) {
// $ret->getAsHtml() has error details..
}
// Call GalleryEmbed as required..
// ..
$ret = GalleryEmbed::done();
if ($ret->isError()) {
// $ret->getAsHtml() has error details..
}
You’ll need hooks to call GalleryEmbed::createUser(), ::updateUser() and ::deleteUser()
for user creation, updates and deletes, respectively. There may be two create hooks
if the emApp supports both new user registration and an admin function to create new
users directly.

If the emApp supports user groups then add hooks to keep groups in sync. Synchronizing
groups is optional, even if the emApp supports groups. The process is the same as above,
using GalleryEmbed::createGroup, ::updateGroup, ::deleteGroup(), ::addUserToGroup() and
::removeUserFromGroup(). Note that G2 does not support nested groups.. if the emApp does
then the hooks will have to expand the groups into the list of users and update the G2
groups accordingly.