Writing transformations for chat

Chat web parts use jQuery templates to display their content. This includes on-line users lists, room lists, messages and other elements. In Kentico, the templates are stored as ordinary transformations that have their type set to jQuery.

You can find all transformations that Chat needs in Document types -> Chat - Transformations -> Transformations.

A jQuery transformation consists of HTML code and template tags that dynamically insert values of the object that is currently being processed. There are also tags that control the flow of the transformation.

Displaying data

An example transformation could look like this:

    <strong>${Nickname}</strong>: ${MessageText}

The example can be used to display a chat message. It displays the sender’s nickname in bold and the text of the message.

In this example, template tags are used to display data. Tags that display data should always start with a dollar sign ($), followed by the name of the variable that you want to display enclosed in brackets.

To learn what data you can display, see Chat transformations reference.

Creating conditions

You can also add conditional template tags that will control what content will be displayed based on a true/false condition.

A condition begins with the `` tag. As an argument, you can enter any statement that returns a boolean value (true or false). The following are examples of a valid conditional statement:

  • IsSystem
  • Nickname == ‘administrator’
  • ! IsCurrentUser

An if condition can have two branches - one that gets rendered when the condition is true, and one indicated by the tag `that gets rendered when the condition is false. You must always close the body of the condition with the{{/if}}` closing tag.

In the following example, we’ll add the recipient’s nickname in case the message is a whisper. Otherwise, the transformation will display only the standard nickname and text combination.

    {{if Whisper}}
        <strong>${Nickname} -> ${Recipient}</strong>: ${MessageText}
        <strong>${Nickname}</strong>: ${MessageText}

Conditional tags support multiple conditions joined by logical operators. The syntax is similar to that of C#, as you can see in the following example:

{{if IsSystem || Nickname == 'administrator' }}
        <strong>System message:</strong> ${MessageText}

Integrating macro expressions

You can insert K# macro expressions into templates and combine them with template tags.

By using localization macros in transformations, you can ensure that all elements will be displayed in the correct language. The elements that can be translated include:

  • system messages
  • notifications
  • buttons

All of these elements are already prepared in the form of resource strings.

The following code example shows how to inform that a message has been rejected using a resource string.

{{if Rejected}}
    <span class="Rejected">{$chat.messagerejected$}</span>

You can find the complete list of resource strings belonging to Chat in Chat transformations reference.

Inserting action commands

Users can perform actions on objects, provided they have permission to do so. For example, you can allow room administrators to reject messages directly in the list, or you can allow them to disable or delete rooms.

The following example shows how you can insert a command control for the reject message action. You need to insert the action command into the onclick attribute with the same syntax as if you were displaying a variable.

The if condition ensures that the action command will be rendered only if the current chat user has permission to reject the message, i.e., if the user is an administrator or a creator of the room.

{{if RejectMessage}}
    <a href="#" onclick="${RejectMessage}">Reject</a>

For a complete list of available commands, see Chat transformations reference.