← Back to branch summary

~ubuntu-branches/ubuntu/hardy/gallery2/hardy-security

« back to all changes in this revision

Viewing changes to docs/EMBEDDING

  • Committer: Bazaar Package Importer
  • Author(s): Michael C. Schultheiss
  • Date: 2006-04-16 16:42:35 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20060416164235-8uy0u4bfjdxpge2o
Tags: 2.1.1-1
http://bugs.debian.org/362936
http://bugs.debian.org/359000
http://bugs.debian.org/362152
* New upstream release (Closes: #362936)
  + Bugfixes for Postgres7 (Closes: #359000, #362152)

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/EMBEDDING
1
 
Gallery2 is designed to be easily embedded in other applications.  The GalleryEmbed class
2
 
in embed.php provides APIs to assist in processing G2 requests and keeping sessions,
3
 
user logins and user/group data in sync between G2 and the embedding application.
4
 
In this document "embedding application" is shortened to emApp.
5
 
This document contains instructions for:
6
 
A) Embedding G2 in another application using existing integration code
7
 
B) Writing the integration code to embed G2 in another PHP application
8
 
 
9
 
 
10
 
___ Embedding G2 in another application using existing integration code ___
11
 
   \___________________________________________________________________/
12
 
 
13
 
1) Install (separately) G2 and the app in which G2 will be embedded.
14
 
2) Obtain and install the G2 integration code written specifically for the emApp.
15
 
   This may be a module or plugin if the emApp supports them, or a simple php file.
16
 
3) Follow instructions with the integration code to initially synchronize users and groups.
17
 
   This may be done as part of module/plugin installation or via special php files.
18
 
4) Login to G2 as a site administrator:
19
 
   a) Make sure the registration module is deactivated or not installed
20
 
   b) Set the G2 session lifetime to at least twice the lifetime of sessions in the emApp.
21
 
      This is because a user may visit G2 and then continue to use the emApp but not visit
22
 
      G2 pages.. a longer G2 session timeout will help ensure their session sticks around
23
 
      until they do visit a G2 page again.  Note that if the G2 session does timeout and
24
 
      the user returns then a new session will be created with the correct user logged in.
25
 
      Other data from the old session is lost but the user login is restored.
26
 
5) Test the integration
27
 
6) Once everything is working you can choose to disable direct access to G2 and only
28
 
   allow access via the emApp.  To do this set the embedOnly flag in your config.php.
29
 
 
30
 
 
31
 
___ Writing the integration code to embed G2 in another PHP application ___
32
 
   \___________________________________________________________________/
33
 
 
34
 
First install (separately) G2 and the app in which G2 will be embedded.
35
 
 
36
 
Next you need an entry point in the emApp for all G2 requests, (similar to
37
 
main.php in G2 standalone).  This may be a module or plugin if the application
38
 
supports these, or a plain php file.  Determine the URI/path for your access
39
 
point and the G2 base directory, relative to your webserver document root.
40
 
Examples: __ access point __                   __ G2 base dir __
41
 
   a)     appdir/gallery2.php                  appdir/gallery2
42
 
   b)     appdir/plugins/gallery2.php          appdir/lib/gallery2
43
 
   c)     appdir/index.php?module=gallery2     gallery2
44
 
   d)     index.php?page=gallery               albums
45
 
Use these to determine the following values:
46
 
        embedURI = Filename (and any query parameters, but NO path) for access point
47
 
       embedPath = URL path from document root to embedUri
48
 
  relativeG2Path = Path from directory for access point to G2 base directory
49
 
For the above examples these settings are:
50
 
        __ embedURI __              __ embedPath __     __ relativeG2Path __
51
 
   a)   gallery2.php                /appdir             gallery2
52
 
   b)   gallery2.php                /appdir             lib/gallery2
53
 
   c)   index.php?module=gallery2   /appdir             ../gallery2
54
 
   d)   index.php?page=gallery      /                   albums
55
 
You'll also need a URI for a login page or main page of the app; G2 will
56
 
redirect here for access attempts without proper permissions.
57
 
Examples:  /  or  /appdir/login.php
58
 
 
59
 
The code in the access point to handle a G2 request looks something like this:
60
 
 
61
 
  require_once(dirname(__FILE__) . 'relative/path/to/gallery2/embed.php');
62
 
  $ret = GalleryEmbed::init(array(
63
 
           'embedUri' => {value}, embedPath => {value}, 'relativeG2Path' => {value},
64
 
           'loginRedirect' => {value}, 'activeUserId' => {value}));
65
 
  if ($ret->isError()) {
66
 
    // $ret->getAsHtml() has error details..
67
 
    exit;
68
 
  }
69
 
 
70
 
  $g2data = GalleryEmbed::handleRequest();
71
 
  if ($g2data['isDone']) {
72
 
    exit; // G2 has already sent output (redirect or binary data)
73
 
  }
74
 
 
75
 
  // Use $g2data['headHtml'] and $g2data['bodyHtml']
76
 
  // to display G2 content inside embedding application
77
 
  // if you don't want to use $g2data['headHtml'] directly, you can get the css,
78
 
  // javascript and page title separately by calling...
79
 
  
80
 
  if (isset($g2moddata['headHtml'])) {
81
 
    list($title, $css, $javascript) = GalleryEmbed::parseHead($g2moddata['headHtml']);
82
 
  }
83
 
 
84
 
The 'activeUserId' value passed to init() enables session synchronization by
85
 
making sure the active user in G2 matches the emApp user.  The value is the
86
 
active emApp user id.  Pass in an empty string for anonymous/guest user
87
 
(NOT the user id of the emApp's anonymous user if it has an id).
88
 
To complete session sync add a hook/callback/event-handler for the logout
89
 
operation in the emApp:
90
 
  require_once(dirname(__FILE__) . 'relative/path/to/gallery2/embed.php');
91
 
  $ret = GalleryEmbed::logout();
92
 
This hook is not required, but it resets the G2 session at logout so a session for
93
 
a logged-in user isn't left on the server.
94
 
 
95
 
Next decide if you want to support cookieless browsing.  Some extra steps are
96
 
required if G2 can't count on cookies to track its session id.  The emApp must
97
 
be able to provide a key=value string for its own session key and id, and have
98
 
an available API to store additional data in the session.
99
 
Here are the extra steps:
100
 
1) The input array for the GalleryEmbed::init() call must also contain:
101
 
        'embedSessionString' => {key=value}, 'gallerySessionId' => {value}
102
 
   (omit gallerySessionId when the value is not yet known)
103
 
2) After the init() call:
104
 
        $gallerySessionId = GallerEmbed::getSessionId();
105
 
        {store value in emApp's session}
106
 
 
107
 
Other optional tasks:
108
 
1) Prior to the handleRequest() call set GalleryCapabilities.
109
 
   Check modules/core/classes/GalleryCapabilities.class for available settings;
110
 
   also see the settings made by default in GalleryEmbed::init().
111
 
   Example: GalleryCapabilities::set('showSidebar', false);
112
 
2) Check for 'sidebarHtml' in content returned from handleRequest().
113
 
   If the example GalleryCapabilities setting shown above is used then handleRequest()
114
 
   may return 'sidebarHtml' (when a core.ShowItem page is being viewed).  You can include
115
 
   this content in a block on the emApp sidebar.
116
 
 
117
 
Next add hooks to keep users in sync between G2 and the emApp.
118
 
The code in each case will look like this:
119
 
  require_once(dirname(__FILE__) . 'relative/path/to/gallery2/embed.php');
120
 
  $ret = GalleryEmbed::init();
121
 
  if ($ret->isError()) {
122
 
    // $ret->getAsHtml() has error details..
123
 
  }
124
 
  // Call GalleryEmbed as required..
125
 
  // ..
126
 
  $ret = GalleryEmbed::done();
127
 
  if ($ret->isError()) {
128
 
    // $ret->getAsHtml() has error details..
129
 
  }
130
 
You'll need hooks to call GalleryEmbed::createUser(), ::updateUser() and ::deleteUser()
131
 
for user creation, updates and deletes, respectively.  There may be two create hooks
132
 
if the emApp supports both new user registration and an admin function to create new
133
 
users directly.
134
 
 
135
 
If the emApp supports user groups then add hooks to keep groups in sync. Synchronizing 
136
 
groups is optional, even if the emApp supports groups. The process is the same as above,
137
 
using GalleryEmbed::createGroup, ::updateGroup, ::deleteGroup(), ::addUserToGroup() and
138
 
::removeUserFromGroup(). Note that G2 does not support nested groups.. if the emApp does 
139
 
then the hooks will have to expand the groups into the list of users and update the G2
140
 
groups accordingly.
141
 
 
142