This document is meant to guide Girder plugin developers in transitioning between major versions of Girder. Major version bumps contain breaking changes to the Girder core library, which are enumerated in this guide along with instructions on how to update your plugin code to work in the newer version.
Existing installations may be upgraded by running
pip install --upgrade --upgrade-strategy eager girder and
girder-install web. You may need to remove
from the installed girder package if you encounter problems while re-running
girder-install web. Note that the prerequisites may have changed in the latest
version: make sure to review System Prerequisites prior to the upgrade.
1.x → 2.x¶
The deprecated event
'assetstore.adapter.get'has been removed. Plugins using this event to register their own assetstore implementations should instead just call the
girder.utility.assetstore_utilities.setAssetstoreAdaptermethod at load time.
'model.upload.assetstore'event no longer supports passing back the target assetstore by adding it to the
event.infodictionary. Instead, handlers of this event should use
event.addResponsewith the target assetstore as the response.
userparameter of the
updateSizemethods in the collection, user, item, and folder models has been removed.
userparameter of the
isOrphanmethods in the file, item, and folder models has been removed.
Several core models supported an older, nonstandard kwarg format in their
filtermethod. This is no longer supported; the argument representing the document to filter is now always called
docrather than using the model name for the kwarg. If you were using positional args or using the
filterModeldecorator, this change will not affect your code.
Multiple configurable plugin loading paths are no longer supported. Use
girder-install plugin <your_plugin_path>to install plugins that are not already in the plugins directory. Pass
-sto that command to symlink instead of copying the directory. This also means:
plugins.plugin_install_pathconfig file settings are no longer supported, but their presence will not cause problems.
- All of the methods in
girder.utility.plugin_utilitiesno longer accept a
curConfigargument since the configuration is no longer read.
girder.utility.sha512_statemodule has been removed. All of its symbols had been deprecated and replaced by corresponding ones in
Web client changes¶
In version 1.x, running
npm installwould install our npm dependencies, as well as run the web client build process afterwards. That is no longer the case;
npm installnow only installs the dependencies, and the build is run with
npm run build.
- The old web client build process used to build all available plugins in the plugin directory.
npm run buildwill only build the core code. You can pass a set of plugins to additionally build by passing them on the command like, e.g.
npm run build -- --plugins=x,y,z.
grunt watchcommand has been deprecated in favor of
npm run watch. This also only watches the core code by default, and if you wish to also include other plugins, you should pass them in the same way, e.g.
npm run watch -- --plugins=x,y,z.
girder-install webcommand is now the recommended way to build web client code. It builds all enabled plugins in addition to the core code. The ability to rebuild the web client code for the core and all enabled plugins has been exposed via the REST API and the admin console of the core web client. The recommended process for administrators is to turn on all desired plugins via the switches, click the Rebuild web code button, and once that finishes, click the button to restart the server.
- The old web client build process used to build all available plugins in the plugin directory. Now, running
Jade → Pug rename: Due to trademark issues, our upstream HTML templating engine was renamed from Jade to Pug. In addition, this rename coincides with a major version bump in the language which comes with notable breaking changes.
Template files should now end in
.jade. This affects how they are imported as modules in webpack.
Jade-syntax interpolation no longer works inside string values of attributes. Use ES2015-style string templating instead. Examples:
Full list of breaking changes are listed here, though most of the others are relatively obscure.
Testing specs no longer need to manually import all of the source JS files under test. We now have better source mapping in our testing infrastructure, so it’s only necessary to import the built target for your plugin, e.g.
girderTest.addCoveredScripts([ '/static/built/plugins/jobs/templates.js', '/plugins/jobs/web_client/js/misc.js', '/plugins/jobs/web_client/js/views/JobDetailsWidget.js', '/plugins/jobs/web_client/js/views/JobListWidget.js' ]);
Build system overhaul: Girder web client code is now built with Webpack instead of uglify, and we use the Babel loader to enable ES2015 language support. The most important result of this change is that plugins can now build their own targets based on the Girder core library in a modular way, by importing specific components. See the plugin development guide for a comprehensive guide on developing web-client plugins in the new infrastructure.
Python client changes¶
Girder CLI: Subcommands are no longer specified with the
-coption. Instead, the subcommand is specified just after all the general flags used for connection and authentication. For example:
girder-cli --api-key=abcdefg --api-url=https://mygirder.org/api/v1 -c upload 1234567890abcdef ./foo
girder-cli --api-key=abcdefg --api-url=https://mygirder.org/api/v1 upload 1234567890abcdef ./foo
dryrunkwargs are no longer available in the
GirderClientconstructor because they only apply to uploading. If you require the use of a blacklist, you should now pass it into the
uploadmethod. These options can still be passed on the CLI, though they should now come after the
Legacy method names in the
GirderClientclass API have been changed to keep naming convention consistent.
All kwargs to
GirderClientmethods have been changed from snake_case to camelCase for consistency.
Listing methods in the
listItem) have been altered to be generators rather than return lists. By default, they will now iterate until exhaustion, and callers won’t have to pass
offsetparameters unless they want a specific slice of the results. As long as you are just iterating over results, this will not break your existing code, but if you were using other operations only available on lists, this could break. The recommended course of action is to modify your logic so that you only require iteration over the results, though it is possible to simply wrap the return value in a
list()constructor. Use caution if you use the
list()method, as it will load the entire result set into memory.
Built-in plugin changes¶
- Jobs: The deprecated
jobs.filterevent was removed. Use the standard
hideFieldsmethods on the job model instead.
- OAuth: For legacy backward compatibility, the Google provider was previously enabled by default. This is no longer the case.