How to embed Conversations in a page
Occasionally, you may find that your Space would work best with Conversations from other Things embedded in some Pages. For example, your Page might be a list of related Things, and you want drop-downs to open the Conversations directly there, instead of forcing your members to click through to those Things in order to comment.
Querki currently has a "low-level API" for this, which is a bit wordy but quite powerful. We plan to eventually add a somewhat easier-to-use "high-level API"; yell if you particularly need this.
Low-level API
The low-level API allows you to:
- Fetch the Conversations for a given Thing;
- Display those Conversations directly or fetch the individual Comments and render those;
- Sort the Conversations based on how recently they were active;
- Display the New Conversation prompt, so that your members can add Conversations about this Thing.
Putting it all together, the result looks something like this:
[[My Target Thing -> ""
[[_thingConversations -> _if(_not(_isEmpty), _sort(_latestCommentTime) -> _take(2) -> _data(""replyprompt"", ""Click here to respond to this conversation"") -> _data(""replylinkclass"", ""_smallSubtitle""))]]
<div class="_newConversationsData" data-thingid="[[_oid]]" data-convwhere="above" data-replyprompt="Click me to reply to this new Conversation" data-replylinkclass="_smallSubtitle" data-startlinkprompt="Click to start a new Conversation" data-startlinkclass="_smallSubtitle"></div>
""]]
Below, we'll go through this in detail.
Specifying the Thing
[[My Target Thing -> ""
All of this is a QL Expression, and a fairly advanced one -- the low-level API is mainly intended for power users who know QL well. The crucial bit is that you have to start with a Thing as the context of your expression. You can do so explicitly like this, but more often you will be in the middle of a larger QL Expression, starting with _instances or some other function that produces a bunch of Things.
Fetching the Conversations
The _thingConversations function receives a Thing, and produces all of the Conversations on that Thing.
Sorting the Conversations
You currently have four options of how to sort the Conversations:
- By default, these will be in order of when the Conversations started, with the oldest at the beginning.
- If you want the Conversation that started most recently at the top, put
_reverse after _thingConversations.
- If you want to sort the Conversations with the most recently active Conversation (that is, the one with the newest Comment) at the bottom, say
_sort(_latestCommentTime), as shown above.
- Finally, if you want the most recently active Conversation at the top, say
_sort(_desc(_latestCommentTime)).
Limiting the Number of Conversations
If you want to restrict the number of Conversations shown, say something like _take(2) as shown above.
Reply Formatting
Normally, Querki displays a Reply input box at the bottom of each Conversation. If you want to instead show a link, which your members click on in order to reply, add
_data(""replylinkclass"", ""_smallSubtitle"")
as shown above. By providing a replylinkclass, the UI will automatically show a Link; when the user clicks on the Link, the Reply input itself will pop up. The class allows you to format this Link (_smallSubtitle will display it in small print); if you don't want to provide a class, just leave this empty.
You can specify the text for this link, or for the normal Reply box prompt, with replyprompt:
_data(""replyprompt"", ""Click here to respond to this conversation"")
Finally, if you don't want people to be able to reply in this page at all, add:
_class(""suppressreplies"")
Note: if they receive an empty value, _data or _class will get cranky. Hence, the _if() clause above.
Allowing New Conversations
Displaying the New Conversation box works a bit differently:
<div class="_newConversationsData" data-thingid="[[_oid]]" data-convwhere="above" data-replyprompt="Click me to reply to this new Conversation" data-replylinkclass="_smallSubtitle" data-startlinkprompt="Click to start a new Conversation" data-startlinkclass="_smallSubtitle"></div>
The _newConversationsData class tells Querki that you want to show the New Conversation prompt.
Specifying the Thing
The only other required bit in New Conversations is the Thing Id:
data-thingid="[[_oid]]"
That _oid produces the OID of the current Thing, in a format that the UI can understand. This tells the Client which Thing we're creating Conversations for.
New Conversation Placement
When the user types in a comment, creating a new Conversation, the question is whether that Conversation belongs above or below the NewConversation gadget. By and large, if the NewConversation gadget is at the top, you want "below"; if it's at the bottom, you want "above". That looks like:
data-convwhere="above"
It defaults to "below", and will go there if this data field isn't present.
Reply Pass-throughs
If you specify data-replyprompt and/or data-replylinkclass, they will simply be passed through to the newly-created Conversations, and will act as discussed above. They should usually match the settings for any Conversations you are showing on this page.
Start Link
By default, the New Conversations input box will be displayed, just like it is at the bottom of most Querki pages. But you can put a link in front of this, if you want to save screen real estate, using these two fields:
data-startlinkprompt="Click to start a new Conversation" data-startlinkclass="_smallSubtitle"
These work largely the same as for the data-reply fields above. If data-startlinkprompt is provided, a link will be shown with the given text, and clicking on that link displays the New Conversations input. If data-startlinkclass is provided, that class will be applied to this link.
