Merge pull request #450 from will-moore/webpack_5_upgrade

Webpack 5 upgrade

README.rst

@@ -16,31 +16,6 @@ Requirements
 
 * OMERO 5.6.0 or newer.
 
-Build
-=====
-
-In order to build you need:
-
-* ``nodejs`` version 6.x
-* ``npm`` version equal or greater to 3.0!
-* ``apache ant``
-
-To build an uncompressed version, run:
-
-::
-
-    $ npm run debug
-
-
-To build an uglified version, run:
-
-::
-
-    $ npm run prod
-
-All builds will build into the build directory and deploy to the plugin directory
-which can then be used like any Django plugin.
-
 Install
 =======
 
@@ -142,54 +117,49 @@ The Z and/or T plane, X/Y center position and zoom can be defined by::
 Development
 ===========
 
-It is recommended to use the webpack dev-server to build and serve OMERO.iviewer
-as this will re-compile automatically when files are saved.
+In order to run and build you need:
 
-To build the bundle and start the webpack dev-server (localhost:8080):
+* ``nodejs`` version at least 10.13.0 - https://nodejs.org/en/download
+* ``apache ant`` for css compiling and tests
+
+To install node dependencies and build the JavaScript bundle:
 
 ::
 
-    $ npm run dev
+    $ cd omero-iviewer
+    $ npm install
 
-You will also need an OMERO.web install with ``omero_iviewer`` installed.
-To add your project to your local OMERO.web install, add the project
-to your ``PYTHONPATH`` and add to ``omero.web.apps``
+    # uncompressed build
+    $ npm run debug
 
-::
+    # OR compressed for production
+    $ npm run prod
 
-    $ export PYTHONPATH=$PYTHONPATH:/path/to/omero-iviewer/plugin
-    $ omero config append omero.web.apps '"omero_iviewer"'
 
-**Notes**:
+You will usually want to have OMERO.iviewer installed on a local omero-web server,
+to test the JavaScript built above. NB: first uninstall OMERO.iviewer if already installed,
+then:
 
-The webpack dev-server config expects a local OMERO server at http://localhost (default port 80).
-Should the server instance use a different port you will need to modify all
-proxy target entries in `webpack.dev.config.js <webpack.dev.config.js>`_:
+::
 
-.. code-block::
+    $ cd plugin
+    $ pip install -e .
 
-    devServer: {
-        proxy: {
-            '/iviewer/**': {
-                target: 'http://localhost:your_port'
-            },
-            '/api/**': {
-                target: 'http://localhost:your_port'
-            }, ...
-        }
-    }
+    # config
+    $ omero config append omero.web.apps '"omero_iviewer"'
+    $ omero config set omero.web.viewer.view omero_iviewer.views.index
 
-If you want to bind the webpack dev server to a port other than 8080
-you will need to change its port property in `webpack.dev.config.js <webpack.dev.config.js>`_:
+Now you can open Images from the webclient as normal.
 
-.. code-block::
 
-    devServer: {
-        port: your_port
-    }
+For iterative development, it is recommended to use the webpack dev-server to build and serve OMERO.iviewer
+as this will re-compile automatically when files are saved.
 
+The dev build of OMERO.iviewer will attempt to connect to a local OMERO server at http://127.0.0.1:4080.
+The web server at this location will need to have CORS enabled and you should
+login to the webclient there.
 
-The initial data type (e.g. image, dataset, well) and its respective ID can be set/changed
+The OMERO.iviewer will try to open an Image or other data from your local server, using IDs specified
 in `index-dev.html <src/index-dev.html>`_:
 
 .. code-block:: html
@@ -204,13 +174,45 @@ in `index-dev.html <src/index-dev.html>`_:
                 window.INITIAL_REQUEST_PARAMS = {
                         'VERSION': "DEV_SERVER",
                         'WEB_API_BASE': 'api/v0/',
-                        //'IMAGES': "1",
-                        'DATASET': "1",
+                        'IMAGES': "12345",
+                        // 'DATASET': "1",
                         //'WELL': "1"
                 };
             </script>
     ...
 
+Edit the `IMAGES` ID in that file and save, then start the dev server:
+
+::
+
+    $ npm run dev
+
+
+To connect to an omero-web server at a different URL or port, you will need to modify all
+proxy target entries in `webpack.dev.config.js <webpack.dev.config.js>`_:
+
+.. code-block::
+
+    devServer: {
+        proxy: {
+            '/iviewer/**': {
+                target: 'http://localhost:your_port'
+            },
+            '/api/**': {
+                target: 'http://localhost:your_port'
+            }, ...
+        }
+    }
+
+If you want to bind the webpack dev server to a port other than 8080
+you will need to change its port property in `webpack.dev.config.js <webpack.dev.config.js>`_:
+
+.. code-block::
+
+    devServer: {
+        port: your_port
+    }
+
 Testing
 =======