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
feed-source | ||
---|---|---|
Required | Value type | EL-evaluated |
Yes | Collection, Data Item | Yes |
Defines the set of records presented as a feed. The Collection is expected to contain Data Items including certain field values, as specified in this command's main documentation. If the resolved value is a Data Item, it is treated as if it is a Collection with that Data Item as its only content. |
object-type | ||
---|---|---|
Required | Value type | EL-evaluated |
No | String | Yes |
Informs this command of the object type of the records in the feed. When new posts are made, this command will create new records of this type. If undefined, the object type of the Data Items in the resolved value of |
content-field | ||
---|---|---|
Required | Value type | EL-evaluated |
Yes | String | Yes |
Informs this command of the field that contains the body content for each record item presented in the feed. The resolved value is expected to be the API name of a HTML-formatted (ie. rich-text) text field. |
fields-set-on-create | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Map | Yes |
Defines a set of fields and values that will be set for the record created when a new post is made. The resolved value Map should contain field API names as keys and field values as the values. If undefined, the created record will only have the field specified with |
starting-post-id | ||
---|---|---|
Required | Value type | EL-evaluated |
No | String | Yes |
Defines an existing post in the feed that will be automatically highlighted right after the screen is loaded. The resolved value is expected to be the ID of a record in the displayed feed. |
view-only | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Boolean | Yes |
This attribute can be used to make it so that the feed can only be viewed - no posting, no commenting, no deleting. If the resolved value of this attribute is Boolean If undefined, value of |
deletion-disabled | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Boolean | Yes |
This attribute can be used to remove the feed viewers' capability of deleting posts. If the resolved value is Boolean If the attribute If undefined, value of |
view-only | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Boolean | Yes |
This attribute can be used to make it so that the feed can only be viewed - no posting, no commenting, no deleting. If the resolved value of this attribute is Boolean If undefined, value of |
deletion-disabled | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Boolean | Yes |
This attribute can be used to remove the feed viewers' capability of deleting posts. If the resolved value is Boolean If the attribute If undefined, value of |
comment-source | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Collection, Data Item | Yes |
Activates the commenting feature and defines the set of records presented as comments for the feed items. The Collection is expected to contain Data Items including certain field values, as specified in this command's main documentation. If the resolved value is a Data Item, it is treated as if it is a Collection with that Data Item as its only content. If undefined, the commenting feature is disabled. |
comment-object-type | ||
---|---|---|
Required | Value type | EL-evaluated |
No | String | Yes |
Informs this command of the object type of the comment records in the feed. When new comments are made, this command will create new records of this type. If undefined, the object type of the Data Items in the resolved value of |
comment-link-field | ||
---|---|---|
Required | Value type | EL-evaluated |
No | String | Yes |
Informs this command of the field that links each comment record to a post record in the feed. The resolved value is expected to be the API name of a relationship field. This attribute cannot be undefined if |
comment-content-field | ||
---|---|---|
Required | Value type | EL-evaluated |
No | String | Yes |
Informs this command of the field that contains the body content for each comment item presented in the feed. The resolved value is expected to be the API name of a HTML-formatted (ie. rich-text) text field. This attribute cannot be undefined if |
comment-fields-set-on-create | ||
---|---|---|
Required | Value type | EL-evaluated |
No | Map | Yes |
Defines a set of fields and values that will be set for the record created when a new comment is made. The resolved value Map should contain field API names as keys and field values as the values. If undefined, the created record will only have the field specified with |
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
.