(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).

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)
  }
})