编辑“整合:Xaraya:技术文档”

Technical documentation of the Gallery2 integration module for Xaraya.

== Included Hooks ==
The gallery2 module provides create, update, delete API hooks and a search GUI hook. The API hooks are only provided for the roles module as they are used for the user/group management synchronization with G2.

All hooks should be activated, always. And thus, they are activated automatically during gallery2 module installation. If these hooks are not active, to activate them, go to Admin panel -> Modules -> Configure Hooks and click on the gallery2 link. Select the roles module to enable the user/group synchronization functionality .

== Authentication / Session management ==
Xaraya is responsible for the authentication and forwards the authenticated user to G2. Both, xaraya and G2, still have their own session management and cookies. The only difference is that G2 checks if there is already a xaraya session before it creates a session for the same user.

== User-/Group management ==
Both applications still have their own user-/group management. But G2 is not allowed to initiate a change. Everytime you create, update or delete a role (user/group) in xaraya, the gallery2 module instantaneously creates, updates or deletes the user/group in G2. Same for group memberships.
If you delete a user in xaraya, the G2 user receives a random password. That leaves the possibility to recall this role in xaraya. If you purge the role, it gets deleted in G2 too.

=== Initial user-/group synchronization ===
The initial user and group synchronization, that is the import of G2 users/groups into xaraya and the export/update of xaraya roles to G2, is based on the unique role name / G2 userName / groupName. There are 3 special groups and 1 special user that are mapped internally:
* xaraya: 'Everybody' is mapped to G2: 'Everybody' (default name)
* xaraya: 'Administrators' is mapped to G2: 'Site Admins' (default name)
* xaraya: 'Users' is mapped to G2: '?' (default name)
* xaraya: 'anonymous' is mapped to G2: 'guest' (default name)
* All other users/groups, including the admins, are mapped based on their unique username.

The import / export of G2 users/groups and xaraya roles happens right after you hit "Update Config" in the Modify Config view, but only if the config parameters you supplied are valid.

If there are conflicts, that is, if there exist xaraya roles and G2 users / groups with the same unique username before the initial synchronization, we update the G2 user data with the data we get from xaraya.

* NOTE: If you want some specific users / groups mapped, make sure they have the same unique username in xaraya and G2 before you configure this module!
* NOTE: All users have to member of the Users group in G2, but admins must not be members of the Users group in xaraya. We take care of this, so don't wonder if you see this "inconsistency" when you take a look at the databases.

We also drop pending users from G2. If they haven't yet registered with xaraya, the eventually will notice the change and sign up. :)

All subsequent synchronizations (login, logout, create, update, delete role) are based on a xaraya uid to G2 entityId mapping.

== Permissions/Privileges ==
You can manage G2 permissions in G2 and not with the roles / privileges modules of xaraya. But all xaraya user groups exist in G2 too. So just assign permissions to the default user group / admin group / everybody group in G2 and all registered users / administrators / everybody will have these permissions.

For more information, check the Gallery 2 documentation for permission management.

== Visual integration ==
No HTML frames are used. G2 generates the resulting HTML without the ...section and the and tags and returns it to our wrapper module. Then we put everything into an almost empty xaraya template. G2 returns the javascript, css and the page title too and we include everything in the created xaraya page.

If you want to customize the look, you can start by choosing one of the existing G2 themes. You can then customize the G2 templates, theme and stylesheets for detailled adjustments. G2 uses smarty as its templating engine, so perhaps you already know everything to create your very own look and feel of G2.


== Menu links ==
TODO: We will dynamically send all available menu links from G2 to xaraya, the goal is to have only the one and only xaraya menu.

== Search hook ==
TODO: We will add a search hook therewith you can search for G2 items, comments, ... from xaraya.

== URLs, direct and indirect requests ==
We configure G2 to run all requests through xaraya. The xaraya core sees that the request is intended for the gallery2 module and the gallery2 module passes the request to G2 itself.

The only exception are the download links/requests. G2 features an image firewall. Unlike ordinary gallery scripts, there's no way you can download any images from G2 than through the application. The developers of G2 spent a lot of effort in trying to reduce the time needed to process download requests. If all these download requests would run through the xaraya core before G2 received them, it'd be bloody slow. That's why all download links/requests go directly to G2, bypassing xaraya.

For now, xaraya short urls are not supported by this module. But you can activate the G2 Url rewrite module which generates also very nice URLs.

== Language Settings ==
Xaraya and G2 manage language settings the same way. There's a site wide language default, a user language setting and a language setting per session. A base module updateconfig hook synchronizes the site default language with G2 and on each request we hand over the current language setting of the active xaraya user to G2. If G2 has the language lang_COUNTRY installed, it sets the language accordingly, if not, it tries the fallback lang_ANYOTHERCOUNTRY, if that fails, it uses the old language setting.

[[Category:Integration:Xaraya]]