(JavaScript API 1.3 for Office) Custom Properties GetItemOrNull

Question

I've created this a couple days ago in which i needed help regarding how to add custom properties to a said document.

First of all, I'm running Word 1701(7766.2047).

---

Let's say I have a method In which I return a said custom property. First I'd check if the custom property has been created already. I would do this with a simple getItemOrNullObject(key) and..

• If returns null Then simply create it AND return it
• Else return it

It is of my understanding that I need to do a return context.sync().then for the object get actually loaded with data? Am I doing too much return context.sync() calls for nothing?

Word.run(function(context) {
  var customDocProps = context.document.properties.customProperties;
  context.load(customDocProps);
  return context.sync()
    .then(function() {
      var temp = customDocProps.getItemOrNullObject("X");
      return context.sync()
        .then(function() {
          if (!temp) {
            context.document.properties.customProperties.add("X", 1234);
            temp = customDocProps.getItemOrNullObject("X");
            return context.sync()
              .then(function() {
                return temp;
              });
          } else {
            return temp;
          }
        });
    });
});

The following code throws me an 'ReferenceError: 'Word' is undefined' at start but if I debug it it runs before it breaks

var customDocProps = context.document.properties.customProperties; context.load(customDocProps); return context.sync().{....}

---

Also have one more question. Say I want to update my custom property, would :

Word.run(function (context) {
        context.document.properties.customProperties.add("X", 56789);
        return context.sync();
    });

override the old value with the new one?

If you read this far thank you! Any help is appreciated. Cheers!

Answer 1

Thanks for asking this question.

Your code is correct except for one minor detail: All the *getItemOrNullObject methods do NOT return a JavaScript null, so your "if (!temp)" statement will not work as you expect. If you want to validate existence you need to call if(temp.isNullObject) instead.

Also a couple of suggestions:

1. customProperties.add() semantics is that if the property does exist, it will be replaced. So, If you want to create or change the property you don't need to check if it exists or not. If you want to read its current value you do. This answers your 2nd question.
2. I have a simplified and more efficient proposal for your code, if you are interested on loading a single property.

  Word.run(function (context) {
    var myProperty = context.document.properties.customProperties.getItemOrNullObject("X");
    context.load(myProperty);
    return context.sync()
      .then(function () {
        if (myProperty.isNullObject) {
          //this means the Custom Property does not exist....
          context.document.properties.customProperties.add("X", 1234);
          console.log("Property Created");
          return context.sync();
        }
        else
          console.log("The property already exists,  value:" + myProperty.value);
      })
  })
  .catch(function (e) {
      console.log(e.message);
    })

We will update the documentation as this seems to be confusing.

Thanks!

Answer 2

I use these function to get or set custom properties

// sets a custom property on the current Word file
function setDocProperty (propName, propValue, callback) {
  Word.run(context => {
    context.document.properties.customProperties.add(propName, propValue)
    return context.sync()
      .then(() => {
        callback(null)
      })
      .catch(e => {
        callback(new Error(e))
      })
  })
}

// gets a custom property from the current Word file
function getDocProperty (propName, callback) {
  Word.run(context => {
    var customDocProps = context.document.properties.customProperties
    // first, load custom properties object
    context.load(customDocProps)
    return context.sync()
      .then(function () {
        // now load actual property
        var filenameProp = customDocProps.getItemOrNullObject(propName)
        context.load(filenameProp)
        return context.sync()
          .then(() => {
            callback(null, filenameProp.value)
          })
          .catch(err => {
            callback(new Error(err))
          })
      })
      .catch(err => {
        callback(new Error(err))
      })
  })
}

You use them like this:

setDocProperty('docId', 28, () => {
  console.log('property set') 
})

getDocProperty('docId', (err, value) => {
  if (err) {
    console.log('Error getting property', err)
  } else {
    console.log('the property is ' + value)
  }
})