Geeklog Forums

 ... Then we decided to examine a new approach where the two applications wouldn't be altered in their core functionality, where things were done with glue code and some hooking. We call this approach loose coupling/integration , leaving the core files of the two applications untouched. The difference to tight coupling is obvious.
In most cases, you want to integrate G2 into an existing website/solution. You want to integrate G2 in a CMS, or in a forum or a customized solution. So, the other application is assumed to be at least equally powerful concerning user/session management and has thus at least equal rights. Actually, G2 is the slave and the other application the master in this relationship.
Take a look at docs/EMBEDDING and embed.php ( GalleryEmbed ). What you do if you integrate G2 with another application is to replace the entry point of G2 (main.php) with a new file which you have to create. This new entry point is part of the other application. And a request goes like this:
1. Browser request index.php?module=gallery2 (just an example)
2. Other application handles session/auth management, parses GET/POST variables and redirects the request to the new G2 entry point.
3. The new G2 entry point includes embed.php from G2 (GalleryEmbed = embedding API, a G2 API subset).
4. You call GalleryEmbed::init(some configuration, activeUserId = ..., ...) to load/start G2
5. Call GalleryEmbed::handleRequest(); to handle the G2 request and receive the returned html for html body and head
6. Paste the returned html into templates of your application or print it out.

So much for the normal request. As you see, G2 doesn't start the communication. Your application always initiates the request because we assumed that calls for less requirements on the other application.
That's why user registration/login is disabled in G2 when embedded. You register/login in the other application. In step 4, the activeUserId is passed to G2. G2 knows that activeUserId is authenticated by the other application. All what G2 does is check the g2_externalIdMap table for a mapping of the externalUserId (activeUserId) with a registered G2 user. Then it loads this corresponding G2 user and from this point, everything works like a ordinary standalone G2 request.

The tricky part of this loose coupling apporach is the synchronization of users and user data. I said, that we deactivated login/register in G2. So, all we have to do is tell G2 when a user is created/updated/deleted in the other application. When a user gets created in the other map, G2 should get notified and passed the user data upon which G2 creates a corresponding G2 user and creates a mapping of the userId of the other application to the userId (entityId) of the corresponding G2 user. Update/delete are analogous. Central is the point, that G2 needs to be notified.
In very modern CMS, you can not only create modules, you can hook your functionality into core code/function. Core functions like "create user" of the CMS. This most often works by the use of events or hooks. Similar to G2, you can register your module as a listener to the "create user" events and every time a user registers/gets created, your code gets notified/activated. In this hooked function, you could call GalleryEmbed::init() and GalleryEmbed::createUser() each time you get notified of a new user and analogous functions, when when a user gets deleted /updated.

Advantages of loose coupled integration:
+ API level integration, no SQL required, no dependency on SQL level. Quite no projects guarantees backwards compatibility on the db schema level, there's a cause for APIs etc.
+ Files of G2 and the other applications stay untouched, no changes required to the vanilla distributions. Just get G2/the integration code/the other application and you're done. You can always upgrade to the newest version of G2 or the other application and or less dependent on a third party, the integration developers.
+ The integration developers don't have to "fork" G2 or the other project à la phpbb for *nuke CMS etc. There is far less code to write and to maintain.

We understand that this events/hooking isn't possible with a lot of other applications and we are on the search for solutions for these less powerful "partners". The simplest solution would be to just alter the core code, hack a call to your synchronization functions into these core functionality.
Solution for user creation for applications that don't feature events/hooks:
- Don't synchronize user creation at all.
- Just call GalleryEmbed::init(array(...,activeUserId => $ipbUserId)); as if you assumed that a corresponding user exists in G2. If no error is returned, this user exists in G2 and you can finish the G2 request with GalleryEmbed::handleRequest().
If an error is returned (missing object), you know that this user doesn't exist in G2. Then you first call GalleryEmbed::createUser() to create this user/mapping in G2, then you call GalleryEmbed::login() and finally you can handle the actual request by GalleryEmbed::handleRequest();

But what about user data creation / user deletion?
- Periodic synchronization executed as a cron command or manually executed.
- Hack the core code of the other app
- Open for your ideas

If you don't want to disable user registration / authentication (login) etc. in G2, then you don't have to. G2 issues events whenever a user gets created/modified/deleted and you could create a G2 module that listens to these events and synchronizes in the other way with another application.

 

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.