js-options: doc

oxygen/js-options/README.md

@@ -1,6 +1,50 @@
-# Options 
+# Options (Work in Progress)
 This rambling shows how to add functionalities to the [OptionStorage](https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/ecss/extensions/api/OptionsStorage.html) mechanism.
 
+## Principle
+
+The idea is to add metadata to be able to do some kind of introspection and cleanup the options store when/if needed.
+
+## Usage [hello.js](hello.js)
+
+Instanciation (with a namespace set to 'hello':
+```javascript
+	var options = new Options(authorAccess, 'hello');
+```
+
+Setting options:
+```javascript
+	var options = new Options(authorAccess, 'hello');
+```
+
+These values can then be retrieved using options.getOption(key, defaultValue) but also as an object:
+```javascript
+	// Retrieve and display these options
+	var myOptions = options.getOptions();
+	for (var key in myOptions) {
+		var value = myOptions[key];
+		Packages.java.lang.System.out.println(key + ' ' + value);
+	}
+```
+
+Options can also be "per file" using methods containing the "SystemId" keyword in their names:
+```javascript
+	// Do the same with file specific options
+	options.setSystemIdOption('Hello', 'aligator');
+	options.setSystemIdOption('See you later', 'World');
+	var myOptions = options.getSystemIdOptions();
+	for (var key in myOptions) {
+		var value = myOptions[key];
+		Packages.java.lang.System.out.println(key + ' ' + value);
+	}
+```
+
+By default, the systemId is the current file system Id but it could be set up to any other file using the setSystemId() method.
+
+Internally, "per file" properties are stored in a namespace which is the concatenation of the options namespace and the SHA1 of the systemId 
+(such as "hello.1D4E43D67658FA9C7F17B230DB629D9DE3FA8001").
+
+
 ## Installation
 
 

oxygen/js-options/hello.js

@@ -1,13 +1,21 @@
 hello = function () {
 	include('options.js');
+	
+	// Instanciation
 	var options = new Options(authorAccess, 'hello');
+	
+	// Set up a couple of options
 	options.setOption('Hello', 'World');
 	options.setOption('See you later', 'aligator');
+	
+	// Retrieve and display these options
 	var myOptions = options.getOptions();
 	for (var key in myOptions) {
 		var value = myOptions[key];
 		Packages.java.lang.System.out.println(key + ' ' + value);
 	}
+	
+	// Do the same with file specific options
 	options.setSystemIdOption('Hello', 'aligator');
 	options.setSystemIdOption('See you later', 'World');
 	var myOptions = options.getSystemIdOptions();
@@ -15,6 +23,8 @@ hello = function () {
 		var value = myOptions[key];
 		Packages.java.lang.System.out.println(key + ' ' + value);
 	}
+	
+	// Display some file specific properties
 	Packages.java.lang.System.out.println('options.systemId: ' + options.systemId);
 	Packages.java.lang.System.out.println('options.systemIdDigest: ' + options.systemIdDigest);
 }