Doc ctx.isNewInstance for "save" hooks

[crandmck]

Per #515

[crandmck]

Added notes to:

• http://docs.strongloop.com/display/LB/Operation+hooks#Operationhooks-beforesave
• http://docs.strongloop.com/display/LB/Operation+hooks#Operationhooks-aftersave

@bajtos Based on strongloop/loopback#838 (comment) it seems that ctx.isNewInstance is only implemented (currently) for memory, MongoDB, and MySQL connectors. Is that correct? If so, then I will add a note to the docs.

[bajtos]

In http://docs.strongloop.com/display/LB/Operation+hooks#Operationhooks-aftersave

• Undefined for prototype.save.

The value is undefined for updateOrCreate, prototype.updateAttributes, updateAll too. It is also undefined whenever a connector does not support this feature yet, for example most community-contributed connectors don't.

In general, the value true or false is set when we are certain whether the operation is UPDATE or CREATE. The value is undefined when we are not certain, either because of the nature of the operation (e.g. updateOrCreate) or because the connector does provide this information.

Based on strongloop/loopback#838 (comment) it seems that ctx.isNewInstance is only implemented (currently) for memory, MongoDB, and MySQL connectors. Is that correct? If so, then I will add a note to the docs.

Yes, it's correct. Yes, please add the note.

[bajtos]

In general, the value true or false is set when we are certain whether the operation is UPDATE or CREATE. The value is undefined when we are not certain, either because of the nature of the operation (e.g. updateOrCreate) or because the connector does provide this information.

Let me clarify this more.

The value reported in the "before save" hook depends only on the operation being invoked, the connectors are not involved here. For example updateOrCreate (when id is set) and prototype.save (when id is set) cannot tell what will be the result of the operation (CREATE or UPDATE), thus "isNewInstance" is undefined.

The value reported in the "after save" hook depends on the operation and connector support. For example, "create" always report "isNewInstance:true", we don't need any extra information from the connector for this. However, "updateOrCreate" requires the connector to tell loopback what was the result of the operation. If the connector does not provide this information, the value of "isNewInstance" is undefined.

[crandmck]

OK, I think I've captured your comments above in:

• http://docs.strongloop.com/display/LB/Operation+hooks#Operationhooks-beforesave
• http://docs.strongloop.com/display/LB/Operation+hooks#Operationhooks-aftersave

Please take a final look and close if it looks OK.

Also, we'll need to update the note in after save about which connectors support it when other connectors add support. If there is an open issue for each connector, then we could add a note to update docs when it's fixed or add a linked issue for the doc update. Otherwise, we are sure to forget it, and the note will eventually be outdated when the connectors add support. Please advise.

[bajtos]

Please take a final look and close if it looks OK.

I amended the text to make the description more accurate, see http://docs.strongloop.com/pages/diffpagesbyversion.action?pageId=3835717&selectedPageVersions=61&selectedPageVersions=60

Also, we'll need to update the note in after save about which connectors support it when other connectors add support. If there is an open issue for each connector, then we could add a note to update docs when it's fixed or add a linked issue for the doc update.

I am afraid we don't have an open issue for each connector, I guess we are waiting for demand from community.

Otherwise, we are sure to forget it, and the note will eventually be outdated when the connectors add support. Please advise.

Perhaps we can rephrase the note in such way that it won't need update? How about the following?

The initial implementation of "ctx.isNewInstance" included only support for memory,
MongoDB, and MySQL connectors. You can check whether your connector supports
this feature by testing the value returned in "after save" hook. Please report a GitHub
issue in the connector project if the feature is not supported.

Example:

MyModel.observe('after save', function(ctx, next) {
  console.log('isNewInstance?', ctx.isNewInstance);
  next();
});
// It's important to provide a value for the id property
// Include also values for any required properties
MyModel.updateOrCreate({ id: 123 }, console.log);