Difference between revisions of "Gallery2:API Changes From 2.2 To 2.3" - Gallery Codex
Personal tools

Difference between revisions of "Gallery2:API Changes From 2.2 To 2.3"

From Gallery Codex

(7.33 => 7.34)
(7.50 => 7.51)
Line 178: Line 178:
== 7.50 => 7.51 ==
== 7.50 => 7.51 ==
* Added optional "text" parameter to {g->itemLink} to override the link.text value.
* Added optional "text" parameter to {g->itemLink} to override the link.text value.
* Added optional "postSprintfArg1" parameter to {g->text} which attempts specific translation of string after sprintf using this value; if no specific translation found it falls back to normal translation of string with %s in it, doing sprintf afterwards.
* $ItemEditItem.typeName which is available to ItemEditOptions now includes untranslated values in indexes 2,3 of the array.
= GalleryModuleApi =
= GalleryModuleApi =

Revision as of 09:38, 9 April 2008

This is the history of API changes since the Gallery 2.2 official release.


7.18 => 7.19

  • Added GalleryCoreApi::getCodeBasePath
  • GalleryTemplate::javascript and GalleryTemplate::style ignore duplicates

7.19 => 7.20

  • Localizations now get installed into g2data/locale at plugin install time. Individual plugins should move all their locale files into their po directory. So if you have a module named foo with a spanish translation, right now you have modules/foo/locale/es/LC_MESSAGES/modules_foo.mo which you want to svn mv to modules/foo/po/es.mo.

7.20 => 7.21

  • Added GalleryDataCache::getTemplatePath(), putTemplatePath(), and resetTemplatePathMap() and new persistent cache-key "template-map"
  • Changed translator hint system:
{g->text text="B <!-- Button label for Bold -->"}

is now:

{g->text text="B" hint="Button label for Bold"}
$module->translate(array('text' => 'B', 'hint' => 'Button label for Bold'));

7.21 => 7.22

  • GalleryStorage::getUniqueId now takes the name of a sequence to use. The only legal value at the moment is DATABASE_SEQUENCE_ID which is also the default. However, in the future we'll be introducing more sequence types.

7.22 => 7.23

  • Removed GalleryDataCache::getTemplatePath, etc that was recently added in 7.21.
  • Unit tests now use GalleryStatus as a return code to make them more like other Gallery code. This means:
    • setUp() returns a GalleryStatus on failure or null on success
    • tearDown() returns a GalleryStatus on failure or null on success
    • testXxx() test functions return a GalleryStatus on failure, but it's ok to not return anything on success.
  • This means that you no longer have to do "print $ret->getAsHtml()" in setUp methods (which we had to do in the past to keep errors in tearDown from stomping on errors in setUp).
  • You no longer have to do "return $this->failWithStatus($ret)" in your tests. Just "return $ret".

7.23 => 7.24

  • Add a new method 'setMaintenanceMode' which allows the application to programmatically set Gallery into or out of maintenance mode.

7.24 => 7.25

  • GalleryCoreApi::addMapEntry and GalleryCoreApi::updateMapEntry now have an extra optional parameter that you can use to specify whether you'd like to use a non-transactional connection. This is useful for situations where you want to make sure the change happens regardless of whether or not the main transaction is going to get rolled back (implemented mainly so that we can do this in the upcoming event logging code). The default is to use the regular connection (transactional or not).

7.25 => 7.26

  • Added GalleryCoreApi::addEventLogEntry which lets you put messages into the Event Log for Site Admins.
  • Gallery::Error event can now return 'errorHandled' => true in its result array to let the framework know that it has handled the error and so the error doesn't get logged in the Event Log
  • $cFormat parameter for $module->translate and $gallery->i18n changed.

Old code:

$module->translate('this is 5% faster', false);
$gallery->i18n('this is 5% faster', false);

New code:

$module->translate(array('text' => 'this is 5% faster', 'cFormat' => false));
$gallery->i18n(array('text' => 'this is 5% faster', 'cFormat' => false));
  • The translator 'hint' mentioned above in 7.21 now also works with $gallery->i18n.
  • Strings for translation in PHP comments are no longer extracted.

Old code:

/* Specific translations: _('Move Album') _('Move Photo') _('Move Movie') */

New code:

if (false) {
    /* Specific translations: */ _('Move Album'); _('Move Photo'); _('Move Movie');

7.26 => 7.27

  • New parameter $requiredEntityType for loadEntitiesById: GalleryCoreApi::loadEntitiesById($ids, $requiredEntityType)
Add $requiredEntityType to all loadEntitiesById calls, e.g. GalleryCoreApi::loadEntitiesById($userId, 'GalleryUser'); to load a user object.

7.27 => 7.28

  • Existing theme blocks can now be renamed or removed without breaking Gallery. Bug #1636339

7.28 => 7.29

  • fetchLanguageCodeForUser($userId) has been added to the GalleryCoreApi

7.29 => 7.30

Added optional $sessionPermissions parameter to permission-check related core API functions similar to the existing param for fetchAccessListIds(). The default behavior is unchanged. The new parameter allows to check for permissions ignoring inherited through the active session.

  • fetchPermissionsForItems($itemIds, $userId=null, $sessionPermissions=true)
  • getPermissions($itemId, $userId=null, $sessionPermissions=true)
  • studyPermissions($itemIds, $userId=null, $sessionPermissions=true)
  • hasItemPermission($itemId, $permission, $userId=null, $sessionPermissions=true)

7.30 => 7.31

  • Added a new variable, $gallery->getConfig('data.gallery.version') which provides the location of the 'versions.dat' file.
  • Changed the way the Admin maintenance screen will handle notifying the administrator if the task expects to be in maintenance mode and is not. Previously, the message would be displayed as part of the task status area, now it will be displayed at the top of the page and the task status area will not be overriden.

7.31 => 7.32

  • ItemAdd has been refactored to use a progress-bar
    • ItemAddPlugin::handleRequest($form, $item, &addController) has a new parameter $addController, a reference to an instance of ItemAddController to be used for post-processing of added items.
    • New method postprocessItems($form, &$status) has been added to ItemAddController
    • See: Gallery2:ItemAdd
  • Cleaned up GalleryCoreApi::fetchPluginList($pluginType) - It returns now a list of all installed plugins. Until now, it returned a list of all active plugins plus some other plugins (any state, even uninstalled) which were at some point active.

7.32 => 7.33

  • Database export / import add two new methods to the GalleryStorage.class: getDatabaseExporter and getDatabaseImporter.
  • Added method GalleryStorage::getTableVersions(); Examine the schema table and return the version of all the Gallery tables.
  • Added method GalleryStorage::updateTableInfo($moduleId); Loads the Maps.inc and Entities.inc into the schema table for the specified module id.

7.33 => 7.34

  • GalleryCoreApi::registerEventListener and GalleryModule::registerEventListeners are now deprecated. Use GalleryCoreApi::registerFactoryImplementation('GalleryEventListener', ...) in YourModule::performFactoryRegistrations instead.
  • Added optional $useNonTransactionalConnection parameter to GalleryStorage::getAffectedRows().
  • GalleryEvent::setEntity($entity) now assigns the entity by reference. Before this change entities would only be passed by reference in PHP 5. With this change entities are passed by reference in PHP 4 as well.

7.34 => 7.35

  • Added GalleryCoreApi::installTranslationsForLocale
  • Added GalleryTranslator::getActiveLanguageCode

7.35 => 7.36

  • Added {g->itemLink} custom smarty tag. Used by core.ItemLinks block; can also be used by themes directly to render item actions (data from modules' getItemLinks functions).
  • Allowing for periods in directory (album) names. The following methods got a new optional parameter to differentiate between files and directories, defaulting to files for backwards compatibility.
    • GalleryCoreApi::getLegalPathComponent() (param $forDirectory)
    • GalleryPlatform::isLegalPathComponent() (param $forDirectory)
    • GalleryPlatform::legalizePathComponent() (param $forDirectory)
    • GalleryItem::create() (param $canContainChildren)
    • GalleryFileSystemEntity::create() (param $isDirectory)

7.36 => 7.37

  • Added methods to allow access to the factory implementation hints for a classType and implementation id. These were required to allow the notification module to dynamically add or remove events that notification module handler was listening for.
    • GalleryCoreApi::getFactoryDefinitionHints() ($classType, $implId)
    • GalleryCoreApi::updateFactoryDefinitionHints() ($classType, $implId, $hints)

7.37 => 7.38

  • Added the validateConnection method to GalleryStorage. It will determine if the connections (nonTransactional and Transactional) are still valid and reconnect the connections ifthey are not. Typical usage would be to do a checkpoint, perform a long running non database task, and then validate the connections.
    • GalleryStorage::validateConnection ()
    • GalleryStorageExtras::validateConnection ()

7.38 => 7.39

  • Created a new API method registerFactoryImplementationForRequest, which allows a module to register an event listener for a request.
    • GalleryCoreApi::registerFactoryImplementationForRequest ()

7.39 => 7.40

  • Added event Gallery::LoadThemeAndParameters allowing non-core code to override the theme and its parameters
  • Added GalleryViewTestCase and UnitTestTemplate

7.40 => 7.41

  • Added lib/yui/yahoo-dom-event.js and lib/yui/utilities.js as part of an upgrade to YUI 2.3.1.

7.41 => 7.42

  • Allowing array of permission-ids for $permission parameter for various core API functions. Affected GalleryCoreApi functions:
    • fetchAccessListIds
    • fetchChildItemIdsWithPermission
    • fetchLinkableChildItemIdsWithPermission
    • fetchAllItemIds
    • fetchParents
    • buildItemQuery

7.42 => 7.43

  • Api changes in preparation of the Language Manager Installation. The following methods were moved from GalleryTranslator to GalleryCoreApi
    • getLanguageDescription
    • getSupportedLanguages
  • Added the following fields to the ViewableTreeChange event:
    • applyToChildren: flag to indicate this change was applied to child items
    • changeType: add or remove action on the permission
    • permission: the permission that was being added or removed
  • New method GalleryUrlGenerator::assertIsInternalUrl($returnUrl) to verify that a specific string does not redirect to an URL outside of Gallery.

7.43 => 7.44

  • GalleryCoreApi::removeAllMapEntries now has a new optional parameter: $useNonTransactionalConnection. If you set this to true, the data you remove will happen outside of the current transaction and will happen much faster in most databases since it'll use TRUNCATE instead of DELETE FROM. If you're going to use this in your plugin code, you should consider doing it only after calling $storage->checkPoint() so that you can be sure that if something goes wrong and we have to rollback, we're not damaging data integrity.

7.44 => 7.45

  • Added optional parameter to GalleryCoreApi::getMimeType($filename, $requestMimeType=null)

7.45 => 7.46

  • Added GalleryTranslator::getLanguageCodeFromLocale($locale)
  • Added GalleryTranslator::getLanguageAndCountryFromLanguageCode($languageCode)

7.46 => 7.47

  • Added GalleryTemplate::mime($name, $content, $isHttpEquiv=false)
  • Added GalleryStorage::getFunctionSql() for 'RANDOM_INTEGER'

7.47 => 7.48

  • Added GalleryCoreApi::fetchWebFile now allows the specification of post data and will use the POST method if the post data is supplied
  • Add wrapping of the php function gethostbyname to GalleryPhpVm.class
  • Created a new method GalleryPhpVm::defined($name) which wraps the php function 'defined' to facilitate testing

7.48 => 7.49

  • Added Gallery::BeforeDisplay event which is dispatched right before we render the page. Listeners can use this to add data to the <head> element with calls like GalleryTemplate::link or GalleryTemplate::javascript, or listeners can register trailer callbacks to be run at the end of the page render.

7.49 => 7.50

  • Added GalleryRepository::downloadAndUnpackPackages which given a list of package files, will contact the repository and download the files as a single request.
  • Added GalleryRepositoryUtilities::unpackPackage which includes the specified package file and calls the expand functions. Having it as a method in GalleryUtilities allows it to be mocked up for unit tests.

7.50 => 7.51

  • Added optional "text" parameter to {g->itemLink} to override the link.text value.
  • Added optional "postSprintfArg1" parameter to {g->text} which attempts specific translation of string after sprintf using this value; if no specific translation found it falls back to normal translation of string with %s in it, doing sprintf afterwards.
  • $ItemEditItem.typeName which is available to ItemEditOptions now includes untranslated values in indexes 2,3 of the array.


3.5 => 3.6

  • Added GalleryModule::setTemplateVersion() and ::getTemplateVersion() to support the functionality allowing themes to override module templates. Module constructors should do $this->setTemplateVersion(1); (and require Module API 3.6). The template version number should be incremented by one whenever a new version of the module includes changes to any tpl file that would make existing theme overrides incompatible with the module.

3.6 => 3.7

  • Data returned from GalleryModule::getItemAdminViews may now include a 'script' key to specify an onclick action for the link. The 'view' key is no longer required, but generally should still be included so a CSS class for a link icon can be added.

3.7 => 3.8

  • Added GalleryView::_permissionCheck. Views can optionally use this function to process PERMISSION_DENIED or MISSING_OBJECT errors; when guest users encounter these they are redirected to the login page (after login they are redirected back again). Example (in a view's loadTemplate function):
 $ret = $this->_permissionCheck(GalleryCoreApi::assertHasItemPermission($itemId, 'core.view'));
 if ($ret) {
   return array($ret[0], $ret[1]);  /* Split array to pass our code audit */

3.8 => 3.9

  • Added an optional parameter to GalleryView::getItem($checkPermission=true) and the method enforces that active user has the core.view permission for the requested/returned item.
  • Added GalleryController::getItem($checkPermission=true) similar to GalleryView::getItem($checkPermission=true), but it doesn't default the itemId if it wasn't specified.
  • Added a fallback block (Missing.tpl) to show if the requested block is missing. Developers can now delete obsolete blocks


2.5 => 2.6

  • Added $theme.themeId as an available template variable, containing the id of the theme in use.
  • Added ability for themes to override module templates. Example:

First look in modules/foo/module.inc and find the setTemplateVersion line near the top. If there is no such line, the version is 0 (zero). Copy bar.tpl to:


..and edit the copy to fit the theme. It is not necessary for a theme to require theme API 2.6 to include template overrides. If the theme is used on an older version of Gallery the overrides will not be used.


1.2 => 1.3

  • Added method setThemeForRequest($themeId, $themeParams=null) to override the theme for the current request.

1.3 => 1.4

  • Added method getBlock($moduleId, $blockName, $parameters=array()) to fetch any module block
  • Changed return value of parseHead(), returning <meta> elements too:
    • New return value: array($title, array($css1, $css2, ...), array($javascript1, $javascript2, ...), array($meta1, $meta2, ...));