sfdc-feed-doclinker

An HTML content command that generates a component displaying a Chatter-like feed, only that the "posts" in the feed are formed out of the results of a Salesforce query. It also provides functionality for creating new records linked to specific points on a document displayed on the same screen. Due to this linking functionality, it is basically required that a document is displayed on the screen alongside this component, either in editable or non-editable form and within a container element that allows scrolling.  

The generated component consists of two parts, a text editor at the top for creating new posts, and the feed below it. It will also affect the display of the document content, but on screens only - nothing the component does should be visible on a PDF generated out of the document HTML, for example.

Setting up the feed

The feed that this commmand will be displaying is defined through the feed-source attribute. It accepts any Collection of Data Items generated by commands like query and relatedList, with each Data Item then becoming an item in the feed. The query to provide the source for the feed should contain the following fields:

• The system fields Id and CreatedDate.

• A rich-text field whose value is used as the content of the feed item. This command needs to be informed of this field through the content-field attribute.  

As this command also needs to be able to create new records, it should be given information of what kinds of records it is creating. The object type for the records is defined through the object-type attribute, which may be left undefined in which case the command will look into the feed-source Collection to see object type the items there represent (however, the Collection being empty will then produce an error). Additionally, the fields-set-on-create attribute may be used to have the new records have their fields set to specific values - by default, only the field specified with content-field is set. It would be a good idea to specify values for these attributes so that the records created are of the same kind as records already in the feed.  

Posting and creating links

The top part of the component allows users to post new items to feed: content for the item is typed into the text editor, and then the button below is pressed to post it, and create the corresponding record. If the user has clicked a location in the document that eligible for linking, the created post will be linked to that location. Document locations eligible for linking are as follows:

• Any non-editable element in the document HTML that has the attribute "id" defined. Clicking any such element will highlight it to show what exactly will be linked.

• Any editable content in the document HTML. If editable content is selected/highlighted, that particular selection is linked. If editable content is just clicked with no characters selected, the entire editable container element is linked.

The component indicates whether the new post would be linked or not through the label of the posting button, either "Share" or "Share & link", as well as the text "Linking post to location" or "Already linked" appearing next to the button if a link would be formed. The 'x' icon next to the text may be clicked to cancel the linking, and in the case of "Already linked", an eye icon is also there for locating the post already linked to the clicked location.

Links between the feed and the document

If a post done through this component is linked to docum ent location, the link is visible in both the post and the document. In the document you can see speech bubble icons showing the linked locations, and in the case of editable locations, the linked content is also highlighted. Clicking the speech bubble will highlight the linked post in the feed. The post itself contains a "Locate" command, which upon clicking will then highlight the linked location in the document.

This link between a post and a document location is formed by one containing information of the other. The specifics differ depending on whether the document location is editable or not.

• In case of non-editable locations and editable containers, the ID of the linked location is written into the post content, eg. "location:some-element-id". This component itself will not display this location-marking part of the posts, but it will be visible if this post-content field of the record is viewed through any other way, such as within Salesforce. Modifying the field value to remove this part will break the link. Similarly, changing the ID of the linked document element will break the link.

• In case of editable selections, the data of the linked post is written into the document content. A new span element wrapping the selection is created and holds data of the linked post, and also visually highlights the selection as the document is displayed on a screen. If the user deletes this span element in its entirety, the linked post no longer has anything to link to. This method of linking also necessitates the saving of the edited content as the user leaves the screen, as otherwise the data-containing span element will be gone and the link broken.  

Deleting posts

Users are able to delete posts if the view-only or deletion-disabled attributes do not resolve into Boolean true. Any post may be deleted by clicking the cross icon at the top-right corner, followed by clicking the "Delete post" command that appears. If the deleted post was linked to an editable selection, the link information is also removed from the document (and like with creating this link, this change also necessitates saving the document's edited content).  

Comments

Comments are an optional feature that allows each of the items in the feed to have their own sub-feed of comment items that users can view and create. This feature is activated by defining the comment-source attribute, through which this command receives the records to act as comments that have been posted before. Like feed-source, comment-source accepts any Collection of Data Items, with each Data Item then becoming a comment associated with one of the feed items. However, as each comment needs to be associated to a post in the feed, the records to act as comments have to be child records of the post records. The query to provide the source for the comments should contain the following fields:

• The system fields Id and CreatedDate.

• A rich-text field whose value is used as the content of the comment. This command needs to be informed of this field through the comment-content-field attribute.

• A relationship field linking the comment to one of the records acting as a feed item. This command needs to be informed of this field through the comment-link-field attribute.    

To create new comment records, this command also needs the object type of these records. This may be defined through the comment-object-type attribute, but like with object-type, this will default to the object type of comment-source's Data Items. The comment-fields-set-on-create is also analogous to fields-set-on-create - use it to set any necessary fields for the comment records this command creates.  

Attributes

Examples

The sfdc-feed-doclinker command is very similar to sfdc-chatter-doclinker, but as it doesn't use Chatter and its predefined records, this command requires a variety of attributes to be defined describing the records you wish to use in the feed. For example, if we were to present a feed made out of custom records called Dynamo_Message__c related to the template's main record, setting it up might look like this:

<query var="feed" select="SELECT Id, CreatedDate, Content__c FROM Dynamo_Message__c WHERE Related_to__c = '${id}'" /><setMap var="fieldsForNewPosts"><addMapEntry key="Related_to__c" value="${id}">...<dyn-sfdc-feed-doclinker feed-source="feed" object-type="'Dynamo_Message__c'" content-field="'Content__c'" fields-set-on-create="fieldsForNewPosts" />

Note that since the records are selected to the feed based on the Related_to__c field, fields-set-on-create is defined so that the Dynamo_Message__c records created by the command would be returned when that query is run again in the future for the same main record.

Adding the commenting feature to the feed requires defining the comment-source attribute. The Dynamo_Message__c records work as comments as well, as they have field Parent_Message__c that is a relationship to another Dynamo_Message__c record. Here is the previous example with additions bringing the comments:      

<query var="feed" select="SELECT Id, CreatedDate, Content__c FROM Dynamo_Message__c WHERE Related_to__c = '${id}'" /><toString var="feedMessageIds" value="${feed}" expr="'${x.Id}'"><query var="comments" select="SELECT Id, CreatedDate, Content__c FROM Dynamo_Message__c WHERE Parent_Message__c IN (${feedMessageIds})" /><setMap var="fieldsForNewPosts"><addMapEntry key="Related_to__c" value="${id}">...<dyn-sfdc-feed-doclinker feed-source="feed" object-type="'Dynamo_Message__c'" content-field="'Content__c'" fields-set-on-create="fieldsForNewPosts" comment-source="comments" comment-object-type="'Dynamo_Message__c'" comment-link-field="'Parent_Message__c'" comment-content-field="'Content__c'"/>

While fields-set-on-create is set, comment-fields-set-on-create is not, as the only condition for finding the comment records is the value of the Parent_Message__c field, which is automatically set by the command since it is specified as the comment-link-field.