opendev/gerrit
Code Issues Proposed changes

PolyGerrit: Update documentation

Browse Source 
Updating documentation based on @Matthias Sohn feedback in

I1a98a2b8660ce4a1700766dc722d587817ede884

Change-Id: I72768e6bd96264aec7852a825fa940b9f2c02605
This commit is contained in:
Paladox none
2018-01-02 18:25:50 +00:00
parent 8b3455518a
commit fd6115e80d
1 changed files with 17 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
Documentation/pg-plugin-migration.txt
View File

@@ -7,18 +7,17 @@ feedback] if something's not right.
[[migration]] [[migration]]
== Incremental migration of existing GWT UI plugins == Incremental migration of existing GWT UI plugins
link:pg-plugin-dev.html[PolyGerrit plugin API] operates different concepts and link:pg-plugin-dev.html[PolyGerrit plugin API] is based on different concepts and
provides different type of API compared to ones available to GWT provides a different type of API compared to the one available to GWT
plugins. Depending on the plugin, it might require significant modifications to plugins. Depending on the plugin, it might require significant modifications to
existing UI scripts to fully take advantage of benefits PolyGerrit API existing UI scripts to fully take advantage of the benefits provided by the PolyGerrit API.
provides.
To make migration easier, PolyGerrit recommends incremental migration To make migration easier, PolyGerrit recommends an incremental migration
strategy. Starting with a .js file that works for GWT UI, plugin author can strategy. Starting with a .js file that works for GWT UI, plugin author can
incrementally migrate deprecated APIs to new plugin API. incrementally migrate deprecated APIs to the new plugin API.
The goal for this guide is to provide migration path from .js-based UI script to The goal for this guide is to provide a migration path from .js-based UI script to
.html-based. a html based implementation
NOTE: Web UI plugins distributed as a single .js file are not covered in this NOTE: Web UI plugins distributed as a single .js file are not covered in this
guide. guide.
@@ -54,10 +53,10 @@ public class SamplePluginModule extends AbstractModule {
=== Step 1: Create `sampleplugin.html` === Step 1: Create `sampleplugin.html`
As a first step, create starter `sampleplugin.html` and include UI script in the As a first step, create `sampleplugin.html` and include the UI script in the
module file. module file.
NOTE: GWT UI ignore .html since it's not supported. NOTE: GWT UI ignores html files which it doesn't support.
``` java ``` java
@Override @Override
@@ -108,20 +107,20 @@ callbacks
- `plugin.deprecated.install()` enables deprecated APIs (onAction(), popup(), - `plugin.deprecated.install()` enables deprecated APIs (onAction(), popup(),
etc) before `sampleplugin.js` is loaded etc) before `sampleplugin.js` is loaded
So the purpose is to share plugin instance between .html-based and .js-based This means the plugin instance is shared between .html-based and .js-based
code, making it possible to gradually and incrementally transfer code to new API. code. This allows to gradually and incrementally transfer code to the new API.
=== Step 2: Create cut-off marker in `sampleplugin.js` === Step 2: Create cut-off marker in `sampleplugin.js`
Commonly, window.Polymer is being used to detect in GWT UI script if it's being Commonly, window.Polymer is being used to detect in GWT UI script if it's being
executed inside PolyGerrit. This could be used to separate code that was already executed inside PolyGerrit. This could be used to separate code that was already
migrated to new APIs from the one that hasn't been migrated yet. migrated to new APIs from old not yet migrated code.
During incremental migration, some of the UI code will be reimplemented using During incremental migration, some of the UI code will be reimplemented using
PolyGerrit plugin API. However, old code still could be required for the plugin the PolyGerrit plugin API. However, old code still could be required for the plugin
to work in GWT UI. to work in GWT UI.
To handle this case, add following code to be the last thing in installation To handle this case, add the following code at the end of the installation
callback in `sampleplugin.js` callback in `sampleplugin.js`
``` js ``` js
@@ -143,11 +142,10 @@ non-deprecated counterparts. Duplicated pieces could be kept under cut-off
marker to work in GWT UI. marker to work in GWT UI.
If some data or functions needs to be shared between code in .html and .js, it If some data or functions needs to be shared between code in .html and .js, it
could be stored on `plugin` (aka `self`) object that's shared between both could be stored in the `plugin` (aka `self`) object that's shared between both
=== Step 4: Cleanup === Step 4: Cleanup
Once deprecated APIs are migrated, `sampleplugin.js` will only contain Once deprecated APIs are migrated, `sampleplugin.js` will only contain
duplicated code that's required for GWT UI to work. With sudden but inevitable duplicated code that's required for GWT UI to work. As soon as GWT support is removed from Gerrit
GWT code removal from Gerrit that file can be simply deleted, along with script that file can be simply deleted, along with the script tag loading it.
tag loading it.