add some examples for Properties object

docsforadobe · Aug 21, 2020 · 91685dc · 91685dc
1 parent 5483724
commit 91685dc
Showing 1 changed file with 85 additions and 15 deletions.
diff --git a/docs/general/properties.rst b/docs/general/properties.rst
@@ -51,19 +51,37 @@ Properties.clearProperty()
 Properties.doesPropertyExist()
 *********************************************
 
-``app.properties.doesPropertyExist()``
+``app.properties.doesPropertyExist(property)``
 
 **Description**
 
-*add description here*
+Checks whether a given property exists in preferences.
 
 **Parameters**
 
-*add parameters here*
+============  ==========  ===================
+parameter     type        description
+============  ==========  ===================
+``property``  ``String``  A property to check
+============  ==========  ===================
 
 **Returns**
 
-*add return value/type here*
+``Boolean``.
+
+**Example**
+
+Check whether labels with indices 10 and 99 exist in preferences:
+
+.. code:: javascript
+
+    var property = 'BE.Prefs.LabelNames.10';
+    var exists = app.properties.doesPropertyExist(property);
+    alert('Property "' + property + '" exists: ' + exists.toString());
+
+    property = 'BE.Prefs.LabelNames.99';
+    exists = app.properties.doesPropertyExist(property);
+    alert('Property "' + property + '" exists: ' + exists.toString());
 
 ----
 
@@ -72,19 +90,38 @@ Properties.doesPropertyExist()
 Properties.getProperty()
 *********************************************
 
-``app.properties.getProperty()``
+``app.properties.getProperty(property)``
 
 **Description**
 
-*add description here*
+Returns a property value.
 
 **Parameters**
 
-*add parameters here*
+============  ==========  =============================
+parameter     type        description
+============  ==========  =============================
+``property``  ``String``  A property to get a value for
+============  ==========  =============================
 
 **Returns**
 
-*add return value/type here*
+``String``.
+
+**Example**
+
+Get label name at a given index:
+
+.. code:: javascript
+
+    var labelIndex = 0;
+    var property = 'BE.Prefs.LabelNames.' + labelIndex;
+
+    if (app.properties.doesPropertyExist(property)) {
+        alert(app.properties.getProperty(property));
+    } else {
+        alert('Property "' + property + '" does not exist');
+    }
 
 ----
 
@@ -97,15 +134,15 @@ Properties.isPropertyReadOnly()
 
 **Description**
 
-*add description here*
+Checks whether a given property can be overwritten by the user. Returns `false` if such property does not exist.
 
 **Parameters**
 
-*add parameters here*
+``property`` as a string.
 
 **Returns**
 
-*add return value/type here*
+``Boolean``.
 
 ----
 
@@ -114,16 +151,49 @@ Properties.isPropertyReadOnly()
 Properties.setProperty()
 *********************************************
 
-``app.properties.setProperty()``
+``app.properties.setProperty(property, value, persistent, createIfNotExist)``
 
 **Description**
 
-*add description here*
+Set property value.
 
 **Parameters**
 
-*add parameters here*
+====================  ===========  ================================================
+parameter             type         description
+====================  ===========  ================================================
+``property``          ``String``   A property to create
+``value``             ``Any``      A value for a property
+``persistent``        ``Boolean``  Whether if should be persistent between sessions
+``createIfNotExist``  ``Boolean``  Should create, if such property does not exist
+====================  ===========  ================================================
 
 **Returns**
 
-*add return value/type here*
+``null``.
+
+**Example**
+
+Change label name:
+
+.. code:: javascript
+
+    var labelIndex = 0;
+    var property = 'BE.Prefs.LabelNamesX.' + labelIndex;
+    
+    var newValue = 'Changed via Script';
+    var persistent = true;
+    var createIfNotExist = true;
+
+    if (app.properties.doesPropertyExist(property)) {
+        if (app.properties.isPropertyReadOnly(property)) {
+            alert('Could not rename property "' + property + '" because it is read-only.');
+        } else {
+            var oldValue = app.properties.getProperty(property);
+            app.properties.setProperty(property, newValue, persistent, createIfNotExist);
+            alert('Value changed from "' + oldValue + '" to "' + newValue + '"');
+        }
+    } else {
+        app.properties.setProperty(property, newValue, persistent, createIfNotExist);
+        alert('Created new property "' + property + '" with value "' + newValue + '"');
+    }