Gallery API Changes

bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Mon, 2005-01-17 09:18

Notice:
This thread will no longer be kept up to date. The API changes documentation and announcement has been moved to http://codex.gallery2.org/index.php/Gallery2:Api .

This is a new thread for developers so that we can let you know of changes to the Gallery 2 API. Hopefully this will save you time hunting around for what changed when you cvs update and the module you're developing suddenly breaks :-)

I'd like to keep this topic readable, so if you have questions, feel free to reply here but I'll roll the answers into my existing post and then delete the question.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Mon, 2005-01-17 09:27

GalleryCoreApi 1.1 => 2.0

I just made a change so that now Factory registrations happen once, at module install time. This will aid performance since now we won't have to load up the various modules to find out what factory implementations they have.

This resulted in two changes to the GalleryCoreAPI. The registerFactoryImplementation method now takes a relative path to the implementation class, and id of the module that owns the implementation. The hints are now also mandatory. Its definition looks like this:

function registerFactoryImplementation(
    $classType, $className, $implId, $implPath,
    $implModuleId, $hints);

I also added the new unregisterFactoryImplementationsByModuleId method:

function unregisterFactoryImplementationsByModuleId($moduleId);

This is used when we uninstall a module to remove all of its implementations. To work with the new API, you should make the following changes to your modules:

Module constructor:

  • Remove "performFactoryRegistrations" from the $this->setCallbacks() list
  • setRequiredCoreApi is now 2, 0

If you have factory registrations:

  • Move the factory registrations into your upgrade method. Create one of those, if you don't already have one.
  • Delete your performFactoryRegistrations() method

In the upgrade method, the pattern I chose was to delete all existing registrations and then re-register them all. This makes it easier during the upgrade process if you have a lot of factory methods. Here's an example from the EXIF module for one such registration:

$ret = GalleryCoreApi::unregisterFactoryImplementationsByModuleId($this->getId());
if ($ret->isError()) {
    return $ret->wrap(__FILE__, __LINE__);
}

$ret = GalleryCoreApi::registerFactoryImplementation(
    'ExifInterface_1_0', 'ExifExtractor', 'Exif',
    'modules/exif/classes/ExifExtractor.class', 'exif', null);
if ($ret->isError()) {
    return $ret->wrap(__FILE__, __LINE__);
}

[/]

[/]

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Mon, 2005-01-24 07:19

GalleryCoreApi 2.1 => 3.0

GalleryCoreApi::activatePlugin() and GalleryCoreApi::deactivatePlugin() now return an array where the second argument is a set of View redirect parameters. This matches the API in GalleryPlugin; we should have updated this when we updated the GalleryPlugin API but we forgot. This is not a commonly used method outside of the framework code, but it's not backwards compatible so it requires a bump in the Core API major number.

GalleryModule 0.8 => 0.9

GalleryModule::performFactoryRegistrations is back, but a little different this time. It turns out that there was a problem with my last attempt to put factory registrations into the database, where registrations were not being removed for deactivated modules. The correct fix for this is to remove factory registrations when modules are deactivated, and add them back when they are re-activated.

Now, the way that it works is that GalleryModule::activate() will call performFactoryRegistrations() where your module will register all of its factory implementations. Take a look at the comment module in CVS to see an example of this.

 
signe
signe's picture

Joined: 2003-07-27
Posts: 2322
Posted: Sat, 2005-02-12 07:43

GalleryCoreApi 3.0 => 3.1
function fetchChildAlbumItemIds($item, $offset=null, $count=null)

fetchChildAlbumItemIds is used to get the list of sub-albums from a given item

GalleryCoreApi 3.1 => 3.2
function removePluginParameterByValue($pluginType, $pluginId, $parameterName, $parameterValue)

removePluginParameterByValue is used to ... remove a plugin parameter by its value instead of by its itemid. This is particularly useful in situations where the value might contain an itemid that has been deleted, but it could be contained under multiple itemids, or an unknown itemid.

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Fri, 2005-02-18 20:00

GalleryCoreApi 3.2 => 3.3
Added function removeOnLoadHandlers($handlerIds)
Removes given factory impl ids from onLoadHandlers field of all entities (used when a module is uninstalled).

GalleryModule 0.9 => 0.10
Added function getOnLoadHandlerIds()
Lists handlerIds module may register; used at module uninstall time to call above core api.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Sat, 2005-02-19 05:42

GalleryCoreApi 3.3 => 3.4
Added function fetchLayoutId($item)
This just returns the right layout id for the item. If it's an album, it returns the album's layout. If it's an item, it returns the layout of its parent.

Deprecated fetchLayout($item) -- will be removed at next major api revision

GalleryLayout 0.8 => 0.9
Added the new 'peerThumbnails' datatype to GalleryLayout::loadLayoutTemplate() so that we can get thumbnails for the peers, too.

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Tue, 2005-03-08 18:44

GalleryCoreApi 3.4 => 4.0
Removed some obsolete apis:
fetchLayout, setItemProperty, removeItemProperty, removeItemProperties, fetchItemPropertyKeys, fetchItemProperty, fetchAllItemProperties

GalleryCoreApi 4.0 => 4.1
Added getThemeList (moved here from GalleryTheme class).
Other api changes of note:
Added GalleryTemplate::style()
Themes no longer have a theme.inc
Theme css now expected in themes/{themename}/theme.css

 
virshu
virshu's picture

Joined: 2003-09-13
Posts: 314
Posted: Sun, 2005-03-27 08:14

GalleryCoreApi 4.1 => 5.0
Mime handling functions (GalleryCoreApi::convertExtensionToMime, GalleryCoreApi::convertMimeToExtensions, GalleryCoreApi::getMimeType and GalleryCoreApi::isViewableMimeType) return list ($ret, $value)

GalleryCoreApi::getMimeTypeMap and GalleryCoreApi::convertMimeToExtension are now obsolete and have been removed

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Sat, 2005-04-09 22:30

GalleryCoreApi 5.0 => 5.1
ByteNik and bharat's ACL/permissions refactor.. added fetchAccessListIds, maybeCompactAccessLists and compactAccessLists apis.

 
signe
signe's picture

Joined: 2003-07-27
Posts: 2322
Posted: Sat, 2005-04-16 08:35

GalleryCoreapi 5.1 => 5.2
Add GalleryCoreApi::sendTemplatedEmail() to add the capability to send an email based on a smarty template.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Sun, 2005-04-17 03:01

GalleryCoreApi 5.2 => 5.3
Added GalleryCoreApi::convertToUtf8() to allow you to change the character set of a string.

 
virshu
virshu's picture

Joined: 2003-09-13
Posts: 314
Posted: Sun, 2005-04-17 18:16

GalleryCoreApi 5.3 => 5.4
Added GalleryCoreApi::fetchDescendentItemIds() to retrieve all descendents of a particular item (comes handy for recursive functions)

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Wed, 2005-04-20 22:02

GalleryCoreApi 5.4 => 5.5
Made $sourceEncoding parameter of convertToUtf8 optional.. it defaults to the character set of the currently selected locale.

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Wed, 2005-05-04 22:50

GalleryCoreApi 5.5 => 5.6
Added GalleryCoreApi::updateModificationTimestamp($entityId)... aka "touch"

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Fri, 2005-05-06 02:01

GalleryCoreApi 5.6 => 5.7
Added GalleryCoreApi::addMimeType($extension, $mimeType, $viewable)

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Sat, 2005-05-07 21:33

GalleryLayout 0.9 => 0.10 (this happened a while back, forgot to post it)
Refactored layout code to move the bulk of the loadTemplate logic into GalleryLayout. Now layouts can just implement loadAlbumTemplate() and loadItemTemplate() to render an album and an item. Renamed GalleryLayout::loadLayoutTemplate to GalleryLayout::loadCommonTemplateData and added more data types so that layouts have to do less work.

GalleryLayout 0.10 => 0.11
GalleryModule 0.10 => 0.11
Added GalleryPlugin::reactivate() (which affects both layouts and modules). This is used during the upgrade process to make sure that any deactivate/activate module and layout tasks happen properly at upgrade time.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Thu, 2005-05-12 18:14

GalleryCoreApi 5.7 => 5.8
Added GalleryCoreApi::isPluginCompatibleWithApis

 
signe
signe's picture

Joined: 2003-07-27
Posts: 2322
Posted: Sun, 2005-05-22 22:16

GalleryCoreApi 5.8 => 5.9
Added GalleryCoreApi::getToolkitPriorityById()

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Sun, 2005-05-29 15:27

GalleryModule 0.11 => 0.12
GalleryLayout 0.11 => 0.12
Naming convention change for views/controllers, now using "." as the separator, like "core.ShowItem". Bumped module/layout api versions and the version of every module/layout when updating all view/controller references to the new format. Old format is still accepted for now, so existing links for imageblock:External will still work, but it's a good idea to update them.

 
valiant

Joined: 2003-01-04
Posts: 32509
Posted: Sun, 2005-05-29 21:49

GalleryCoreApi 5.9 => 6.0
Removed GalleryUrlGenerator::getCookiePath()

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Mon, 2005-06-06 06:30

GalleryLayout 0.12 => 1.0

Note that this is not a backwards compatible change. I've removed the 'url' value from the item links, so if in your template when you're building item links you were doing this:

<a href="{$link.url}">{$link.text}</a>

You should now do this instead:

<a href="{g->url params=$link.params}">{$link.text}</a>

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Wed, 2005-06-08 20:13

GalleryCoreApi 6.0 => 6.1
Added optional $permission parameter for GalleryCoreApi::fetchParents() to return only ancestors with the given permission.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Sat, 2005-06-11 21:21

GalleryCoreApi 6.1 => 6.2
hasItemPermission() now takes $userId
getPermissions() now takes $userId
studyPermissions now takes $userId
fetchChildCounts now takes $userId
fetchDescendentCounts now takes $userId
fetchChildItemIds now takes $userId

GalleryModuleApi 0.12 => 1.0
getItemLinks() now takes $wantsDetailedLinks and $permissions
getItemSummaries() now takes $permissions
loadItemDetails() now takes $permissions

GalleryLayoutApi 1.0 => 1.1
loadCommonTemplateData() takes new 'childItemLinksDetailed' data type

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Sat, 2005-06-18 08:27

GalleryCoreApi 6.2 => 6.3
Added optional $headers parameter to sendTemplatedEmail.

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Mon, 2005-07-11 03:09

GalleryCoreApi 6.3 => 6.4
Added optional $fixBroken parameter to rebuildDerivativeCacheIfNotCurrent.
(Change made by valiant)

GalleryModuleApi 1.0 => 1.1
Added $isDuringInstallOrUpgrade parameter to onLoad handlers.
(Change made by valiant)

GalleryModuleApi 1.1 => 2.0
GalleryLayoutApi 1.1 => GalleryThemeApi 2.0
Removed removeItemParameter and added removeParameter.
The actual api change is small but requires a major version bump as an api was removed.. but since we just put in major theme changes, this seems like a good time for major version bumps anyway.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7994
Posted: Tue, 2005-07-19 00:58

GalleryThemeApi 2.0 => GalleryThemeApi 2.1
Added the permissions datatype to GalleryTheme::loadCommonTemplateData so which makes the item permissions avialable to the theme in a Smarty digestable format. (That means, we changed the dot in a permission to an underscore: core.addDataItem becomes core_addDataItem so when you use it in your template it'd be $theme.permissions.core_addDataItem)

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Mon, 2005-08-08 00:06

GalleryCoreApi 6.4 => 6.5
Added convertFromUtf8() (valiant)
Added optional $userId parameter to fetchChildAlbumItemIds and fetchChildDataItemIds (mindless)

GalleryCoreApi 6.5 => 6.6
Added optional $userId parameter to fetchAlbumTree (mindless)

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Fri, 2005-08-12 19:10

GalleryCoreApi 6.6 => 6.7
Added optional $selfId parameter to checkPathCollision and getLegalPathComponent

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Sat, 2005-08-27 18:09

GalleryCoreApi 6.7 => 6.8
Added fetchPluginList.. just exposing a function that already exists in GalleryPluginHelper_simple so the upgrader can call it.

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Sat, 2005-10-01 00:09

GalleryThemeApi 2.1 => 2.2
GalleryTheme::getSettings now also returns the $params data which is useful for themes overriding this function.

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Mon, 2005-10-17 14:55

GalleryModuleApi 2.0 => 2.1
Added getModuleEntityTypes so modules can specify types of entities to be deleted upon module uninstall.

 
valiant

Joined: 2003-01-04
Posts: 32509
Posted: Wed, 2005-11-02 13:01

Notice:
This thread will no longer be kept up to date. The API changes documentation and announcement has been moved to http://codex.gallery2.org/index.php/Gallery2:Api .