Update documentation

README.md

@@ -9,8 +9,8 @@ A plugin for ImageJ to provide macro extensions to access OMERO.
 
 1. Install the [OMERO.insight plugin](https://omero-guides.readthedocs.io/en/latest/fiji/docs/installation.html) (if you
    haven't already).
-2. Download the JAR file for this [library](https://github.com/GReD-Clermont/simple-omero-client/releases/tag/5.16.0/).
-3. Download the JAR file ([for this plugin](https://github.com/GReD-Clermont/omero_macro-extensions/releases/tag/1.3.3/)).
+2. Download the JAR file for this [library](https://github.com/GReD-Clermont/simple-omero-client/releases/tag/5.19.0/).
+3. Download the JAR file ([for this plugin](https://github.com/GReD-Clermont/omero_macro-extensions/releases/tag/1.4.0/)).
 4. Place these JAR files in your plugins folder.
 
 ## How to use
@@ -121,6 +121,16 @@ tagName = Ext.getName("tag", tagIds[0]);
 print(tagName);
 ```
 
+* Key-Value pairs:
+
+```
+kvpairs = Ext.list("kv-pairs");
+print(kvpairs);
+kvIds = split(kvpairs,",");
+kvName = Ext.getName("kvName", kvIds[0]);
+print(kvName);
+```
+
 ### Listing objects with a given name
 
 It is also possible to list objects with a specific name:
@@ -185,6 +195,26 @@ tagName = Ext.getName("tag", tagIds[0]);
 print(tagName);
 ```
 
+Key-Value pairs can also be listed for a given object:
+
+```
+pairs = Ext.list("kv-pairs", "image", imageIds[0]);
+print(pairs);
+pairIds = split(pairs,",");
+kvs = Ext.getName("kv-pair", pairIds[0]);
+print(kvs);
+```
+or:
+```
+kvpairs = Ext.getKeyValuePairs("image", imageIds[0]);
+print(kvpairs);
+```
+or for a given key:
+```
+values = Ext.getValues("image", imageIds[0], "key", defaultValue);
+print(values);
+```
+
 Similarly, a dataset ID can be used to retrieve its images:
 
 ```
@@ -222,7 +252,7 @@ imageName = Ext.getName("image", imageIds[0]);
 print(imageName);
 ```
 
-### Creating projects, datasets and tags
+### Creating projects, datasets, tags and key-value pairs
 
 Projects can be created with *Ext.createProject*:
 
@@ -242,6 +272,12 @@ Tags can be created with *Ext.createTag*:
 tagId = Ext.createTag(name, description);
 ```
 
+Key-value pairs can be created with *Ext.createKeyValuePair*:
+
+```
+pairId = Ext.createKeyValuePair(key, value);
+```
+
 ### Linking/unlinking objects
 
 Objects can be linked with *Ext.link*, e.g.:
@@ -253,7 +289,7 @@ Ext.link("dataset", datasetId, "tag", tagId);
 They can also be unlinked with *Ext.unlink*, e.g.:
 
 ```
-Ext.unlink("dataset", datasetId, "tag", tagId);
+Ext.unlink("dataset", datasetId, "kv-pair", pairId);
 ```
 
 ### Deleting objects
@@ -272,7 +308,10 @@ Pixel intensities can be retrieved from images:
 imageplusID = Ext.getImage(imageIds[0]);
 ```
 
-Images can also be cropped on import by specifying the ROI in one of two ways:
+Images can also be cropped on import. In this case, image properties containing the position of the crop in the original 
+image can be retrieved (IMAGE_POS_X, IMAGE_POS_Y, etc.).
+
+This crop can be done by specifying the ROI in one of two ways:
 1. using the ROI ID (as a String) from OMERO, for example:
 ```
 imageplusID = Ext.getImage(imageIds[0], Roi.getProperty("ROI_ID"));

src/main/resources/helper.md

@@ -47,16 +47,25 @@ Ext.list(type, parentType, parentId)
 
 Ext.getName(type, id)
 > Gets the name of the specified object, given its `type` and `id`.
+> In the case of key-value pairs, it returns keys and values separated by tabs, one pair per line.
 
 Ext.getImage(id)
 > Opens the image with the given `id`.  
 > Returns the image ID in ImageJ.
 
 Ext.getImage(id, region)
 > Opens a subregion of the image with the given `id`.
-> The region is specified as a string in the format "x:start:end,y:start:end,...".
+> The region is specified in one of two ways:
+> 1. using a ROI ID in OMERO
+> 2. as a string in the format "x:start:end,y:start:end,...".
 > Returns the image ID in ImageJ.
 
+Ext.getKeyValuePairs(type, id)
+> Returns the key-value pairs attached to the object with the given `type` and `id`.
+
+Ext.getValue(type, id, key, defaultValue)
+> Returns the value for the given key attached to the object with the given `type` and `id`.
+
 Ext.getROIs(imageId, toOverlay, property)
 > Retrieves the ROIs for the image with the given `imageId`.
 > These are added to the ROI manager by default.
@@ -74,6 +83,10 @@ Ext.getROIs(imageId, toOverlay, property)
 
 ### Saves data ###
 
+Ext.createKeyValuePair(key, value)
+> Creates a new key-value pair with the given `key` and `value`.  
+> Returns the new pair ID.
+
 Ext.createTag(name, description)
 > Creates a new tag with the given `name` and `description`.  
 > Returns the new tag ID.
@@ -110,7 +123,7 @@ Ext.link(type1, id1, type2, id2)
 > Possible types are:
 >   * Project and Dataset
 >   * Dataset and Image
->   * Tag and Project, Dataset or Image
+>   * Tag or KV-pair and Project, Dataset, Screen, Plate, Well or Image
 
 ### Removes data on OMERO ###