Strategy for Enabling/Disabling Plugins

[rkwright]

This issue is a Discussion

For quite a while Readium has supported a plugin framework centered on JavaScript. Although present, it has not been first-class citizen. One plugin, the Highlighter, was written early on, but there is no associated "bookmarking or annotation" plugin using it.
There is some usage (we think) of the highlight plugin and the framework out in the wild, but we have little solid evidence of how or how much it used.
Meanwhile, EvidentPoint worked with hypothes.is to enable their bookmarking/annotation support within the CloudReader. It is based on a wholly different framework for highlighting, which is not compatible with the existing framework.
So the question has arisen, how should Readium support Hypothes.is and/or the existing Highlighter plugin (which is disabled by default)?

At present, in the develop branch, in preparation for release 0.28 (which is intended to support Hypothes.is) the Hypothes.is plugin is enabled by default and the Readium Highlighter is disabled. At first, this seemed OK, we provide instructions on how to disable the Hypothes.is plugin so anyone deploying the CloudReader who has their own highlighter and/or doesn't want the Hypothes.is support can do so.
Unfortunately, it is a little more complex than that. As it stands the Hypothes.is support, as part of readium-shared-js, will be built and integrated into not only the CloudReader but also the Chrome app and the native SDK apps (the Launchers). It won’t work in the Chrome app or the Launchers but the code is there and even the UI.

This is clearly unacceptable, but how should it work? After some discussion, it seems that the requirements should be:

• The Hypothes.is framework and plugin should be present in the code base, but NOT enabled by default. So no functionality or UI are present by default on any of the platforms (JS, Chrome, native)
• The Readium plugin framework and Highlighter plugin should be present in the code base, but NOT enabled by default. So no functionality or UI are present by default on any of the platforms (JS, Chrome, native)
• The Hypothes.is highlighter, bookmarking and annotation capabilities SHOULD be enabled in the automated builds which are built and deployed to Firebase.
• How to enable the Hypothes.is capabilities should be clearly and prominently documented, both in the 0.28 release notes and in the READ.me of the readium-js-viewer.
• How to enable the Readium highlighter should also be clearly and prominently documented, both in the 0.28 release notes and in the READ.me of the readium-js-viewer.

The intent of this issue (discussion) is to elucidate how the above requirements can be met for the 0.28 release.

Related issue(s) and/or pull request(s)

#657

Test file(s)

None

Product

All

Additional information

None?

[danielweck]

As per last week's conference call:

1. disable all plugins (or to be precise: "do not enable" any plugin) via the plugins/plugin.cson configuration file in readium-shared-js ( https://github.com/readium/readium-shared-js/blob/develop/plugins/plugins.cson ), so that the build-output folder (which is used as-is by the ReadiumSDK launcher apps) is as "vanilla" as possible ( https://github.com/readium/readium-shared-js/tree/develop/build-output ).
2. Enable the Hypothesis plugin (or any other desired plugin) in the develop branch via TravisCI during the Continuous Integration build that is automatically triggered at each code push. As a result, the automated cloud reader deployment at Firebase and Surge continues to provide the Hypothesis annotations tool ( http://readium.firebaseapp.com and https://readium.surge.sh ), as well as the cloud-reader[-lite].zip archives (ready-made prerelease builds) which are conveniently offered to downloaders who do not want / cannot compile the app themselves ( https://github.com/readium/readium-js-viewer/releases/tag/0.28.0-alpha ).
3. The manual builds created from the master branch (tagged releases) are not affected, they do not contain any plugins ( https://github.com/readium/readium-js-viewer/releases/latest ), and the "stable" cloud reader app deployed at Surge does not offer the Hypothesis plugin ( https://readium-master.surge.sh ).

We are currently testing this strategy live:
https://travis-ci.org/readium/readium-js-viewer/builds/294962188
(waiting for the build to finish...)

[danielweck]

The TravisCI ad-hoc script to enable the Hypothesis plugin is super simple:
3ec7b42#diff-354f30a63fb0907d4ad57269548329e3

[danielweck]

The Hypothesis plugin was deactivated in this commit:
readium/readium-shared-js@b73ba7a#diff-e8c5eaf889e895e2bc68aef5eb21a4ac

[danielweck]

This is working correctly.
The Hypothesis plugin is enabled "dynamically" during the TravisCI build, as shown in the compiler logs:
https://travis-ci.org/readium/readium-js-viewer/jobs/294962191#L786
https://travis-ci.org/readium/readium-js-viewer/jobs/294962191#L1450

...and the Hypothesis plugin is activated at runtime in the cloud reader app, as expected:
https://readium.firebaseapp.com/?epub=epub_content%2Faccessible_epub_3&goto=%7B%22idref%22%3A%22id-id2611884%22%2C%22elementCfi%22%3A%22%2F4%2F2%5Bintroduction%5D%2F2%2F1%3A0%22%7D
https://readium.surge.sh/?epub=https%3A%2F%2Freadium.firebaseapp.com%2Fepub_content%2Faccessible_epub_3&goto=%7B%22idref%22%3A%22id-id2611884%22%2C%22elementCfi%22%3A%22%2F4%2F2%5Bintroduction%5D%2F2%2F1%3A0%22%7D