编辑“Gallery:整合的相关帮助指导”（章节）

==编写新的整合代码==
首先（单独）安装Gallery2以及用于嵌入Gallery2的应用程序。

对所有Gallery2请求而言，在emApp中你需要一个入口点（entry point），（类似于独立Gallery2中的main.php）。如果应用程序支持的话，可以是模块或插件，也可以是一个普通的php文件。决定访问点和Gallery基础目录（Gallery2 Base Directory）（与web服务器文档根目录比较而言）的URI/路径。举例：
{| border="1" width="480" cellpadding="5" cellspacing="0"
|-
! style="background:#ccc;" | 访问点( '''= embedUri ''' )
! style="background:#ccc;" | Gallery2基础目录( '''= g2Uri ''' )
|-
|/appdir/gallery2.php
|/appdir/gallery2
|-
|/appdir/plugins/gallery2.php
|/appdir/lib/gallery2/
|-
|/appdir/index.php?module=gallery2
|/gallery2/
|-
|/index.php?page=gallery
|/albums/
|}

你可以将这些路径作为至GalleryEmbed::init($embedUri, $g2Uri);的参量
* embedUri = 访问点的文档根目录的绝对URL路径+ 文件名称（以及所有查询参量，但不是路径）
* g2Uri =文档根目录至Gallery2目录的绝对URL路径 

请勿忘记打头的'/'! 完整URL也是被允许的，例如
{| border="1" cellpadding="5" cellspacing="0"
|-
! style="background:#ccc;" |访问点( = embedUri )
! style="background:#ccc;" | Gallery2基础目录( = g2Uri )
|-
|http://www.example.com/appdir/gallery2.php
|http://www.example.com/appdir/gallery2/
|-
|http://example.com/appdir/plugins/gallery2.php
|http://example.com/appdir/lib/gallery2/
|-
|http://example.com/index.php?module=gallery2
|http://photos.example.com/
|-
|}

正如你所看到的，Gallery2以及Gallery2在你网站上的整合位置可以在两个不同的子域上！你不应该使用两个完全不同的域，因为cookies（你是否登入）无法再两个不同的域中共享。但不同的子域则是可以的，不过你得在''站点管理（site admin） -> General''中对Gallery2的 cookie.path做适当的改动。
 
对于登入页面或app主页面你还需要一个URI；Gallery2会将无适当权限的访问尝试进行重新定向。

{| border="1" cellpadding="5" cellspacing="0"
|-
! style="background:#ccc;" | 举例
|-
|/
|-
| /appdir/login.php
|}

用以处理某Gallery2请求的访问点代码看起来是这样的：

 require_once(dirname(__FILE__) . 'relative/path/to/gallery2/embed.php');
 $ret = GalleryEmbed::init(array( 'embedUri' => {value}, 'g2Uri' => {value}, 'loginRedirect' => {value}, 'activeUserId' => {value}));
 if ($ret) {
   // $ret->getAsHtml()具有错误的详细信息
   exit;
 } 
 $g2data = GalleryEmbed::handleRequest(); 
 if ($g2data['isDone']) {
   exit; // Gallery2已发送了output（redirect或binary数据）
 } 
 // 使用$g2data['headHtml']以及$g2data['bodyHtml']
 // 来显示emApp中的Gallery2内容
 // 如果你不想直接使用$g2data['headHtml']，可以分别获取css，
 // javascript以及页面标题，通过呼叫…
 if (isset($g2moddata['headHtml'])) {
   list($title, $css, $javascript) = GalleryEmbed::parseHead($g2moddata['headHtml']);
 }

通过确保Gallery2中活动用户符合emApp用户，传送到init()的'activeUserId'值启用对话同步。该值为活动的emApp用户id。在匿名/游客用户（非具有id的emApp的匿名用户）的某为空字串中传送。要完成对话同步，请为emApp中的登出操作添加一个hook/callback/event-handler：

 require_once(dirname(__FILE__) . 'relative/path/to/gallery2/embed.php');
 $ret = GalleryEmbed::logout();

此hook非必须，但它能在登出时重置Gallery2对话，因此某登入用户的对话将不会遗留在服务器中。

接下来确定你是否想支持cookieless浏览方式。如果Gallery2无法依靠cookies来追踪其对话id的话，就需要完成额外的步骤。emApp必须能够为自己的对话key和id提供一个key=value字串，并要具有一个可用API来存储对话中的额外数据。以下为所需完成的额外步骤：

1. GalleryEmbed::init()呼叫的输入数组必须也含有：
 'embedSessionString' => {key=value}, 'gallerySessionId' => {value}
（当value未知时忽略gallerySessionId） <br>
2. 在init()呼叫之后：
 $gallerySessionId = GalleryEmbed::getSessionId(); // {存储emApp对话中的值}

其他可选任务：

1.在进行handleRequest()呼叫之前设定GalleryCapabilities。检查modules/core/classes/GalleryCapabilities.class来看看可用设定，并查看默认情况下GalleryEmbed::init()中所作的设定。例如：
 GalleryCapabilities::set('showSidebar', false);
2. 检查返回自handleRequest()内容中的'sidebarHtml'。如上述例子中的GalleryCapabilities设定被使用，那么handleRequest()就可能返回'sidebarHtml'（当某个core.ShowItem页面被查看时）。你可以将此内容包括在emApp边栏上的某个模块中。

接下来添加hook以使用户保持Gallery2和emApp的同步。各例中的代码看起来如下：
 require_once(dirname(__FILE__) . 'relative/path/to/gallery2/embed.php');
 $ret = GalleryEmbed::init();
 if ($ret) {
   // $ret->getAsHtml() has error details..
 }
 // Call GalleryEmbed as required..
 // ..
 $ret = GalleryEmbed::done();
 if ($ret->isError()) {
   // $ret->getAsHtml() has error details..
 }

你需要hook来呼叫GalleryEmbed::createUser()，::updateUser()和::deleteUser()来分别进行用户的创建，更新和删除。如果emApp支持新用户注册和管理员函数直接注册新用户的话，就有两create hook。

如果emApp支持用户组，那么就添加hook以保持这些组的同步。组的同步是可选的，尽管emApp对此支持。过程与前文所述相同，使用GalleryEmbed::createGroup，::updateGroup，::deleteGroup()，::addUserToGroup() 和::removeUserFromGroup()。注意Gallery2不支持巢式组。如果emApp支持的话，那么hook就必须将组扩展到用户列表并相应地更新gallery2的组。
说明	输入内容	输出结果
斜体	''斜体文字''	斜体文字
粗体	'''粗体文字'''	粗体文字
粗斜体	'''''粗斜体文字'''''	*粗斜体文字*