Compared to my previous post this will be a short tutorial. The issue here is editing content. When you load a content object the text is formatted for display, with tappable areas containing extra information. Unfortunately this extra information is problematic when submitting edited content. So now we are adding methods to reload the content with the text formatted for editing. These methods are also used to lock the content so multiple people can't edit at the same time.


Before we look at the new methods, lets look at the changes to the content classes.

In JiveContentBody there is a new property: editableValue. This shows which type of formatting the text is using. YES for simple html tags suitable for editing and NO for the more complex html tags suitable for interactive display.

In JiveDocument there is a new property: editingBy. This shows who currently has the document locked for editing, if anyone. This is intended to be used as a quick check of lock ownership before you try to use any of the new apis. But this is time sensitive information. If you display a lock symbol on the content be sure to periodically update the content to maintain the validity of the lock display.


So what are the new methods?

In JivePlatformVersion there is a new version check method:

- (BOOL)supportsContentEditingAPI;


In Jive there are 4 new methods:

- (void) getEditableContent:(JiveContent *)content withOptions:(JiveReturnFieldsRequestOptions *)options onComplete:(JiveContentCompleteBlock)complete onError:(JiveErrorBlock)error;

- (void) lockContentForEditing:(JiveContent *)content withOptions:(JiveReturnFieldsRequestOptions *)options onComplete:(JiveContentCompleteBlock)complete onError:(JiveErrorBlock)error;

- (void) saveContentWhileEditing:(JiveContent *)content withOptions:(JiveMinorCommentRequestOptions *)options onComplete:(JiveContentCompleteBlock)complete onError:(JiveErrorBlock)error;

- (void) unlockContent:(JiveContent *)content onComplete:(JiveCompletedBlock)complete onError:(JiveErrorBlock)error;

The getEditableContent method gets the editable text without setting the lock.

The lockContentForEditing method returns the editable text and sets the lock. This method is reentrant, allowing you to reset the lock on the server. Be sure to do this periodically as the server does have a timeout.

The saveContentWhileEditing method publishes the content while continuing to edit. When used with the draft flag this can be used to implement an autosave feature.

The unlockContent method releases the lock, effectively canceling the edit session.


All of these methods will return an error if someone else is editing the content. But they will not prevent the same user from editing the content using 2 different programs. In this case the final edit will "win".


But wait, these methods either cancel the edit or continue editing. How do I publish my changes?

Using the existing updateContent methods. They have been updated to release the lock, if present, as part of the publish process.


Currently only JiveDocument supports locking, so why should I use the locking methods for other content types?

For forward compatibility. Just because document is the only content type that currently supports locking doesn't mean we won't add it to other types in the future.


So what is the flow for editing?

Editing API flow.gif


You say the display html has extra stuff in it compared to the editing html. Can you give me an example?

Display HTML

Editable HTML

<body><!-- [DocumentBodyStart:c4282aa4-ff2d-4941-9e7a-50618c508ce3] --><div class="jive-rendered-content"><p>just some text</p></div><!-- [DocumentBodyEnd:c4282aa4-ff2d-4941-9e7a-50618c508ce3] --></body><body><p>just some text</p></body>

If it is that different for a single line of text, imagine what it looks like with links and images.