Home

Welcome

Cha is a toolkit/framework for conversation UI. It is designed (as a goal) to work independent from chat technologies, such as Slack, Flowdock, Skype, etc.

TOC

• Using Cha
  • Cha Api
  • Cha Framework
  • I18n

Using Cha

Cha includes two sub modules, you can choose use one of them based on your needs

• Cha.Api
• Cha.Framework

Cha.Api

Module Cha.Api provides low level API to construct an independent message structure.

At current moment, Cha message structure leverages Slack message design

{
      "text": "", // a message text
      "parts":[ 
        {
          "title": "", //title of part
          "color": "", //color for the part
          "text": "", // main text for the part
          "title_link":"",
          "image_url":"",
          "thumb_url":"",
          "fields":[
             {
               "title":"",
               "value":"",
               "short":""
             }
           ],
          "actions":[
            {
              "name": "",
              "text": "",
              "style": "",
              "type": "button",
              "value": ""
            }
          ]
        }
      ]
}

You can refer to Slack doc for detail.

Cha.Api will turn this independent message structure to target structure.

Underlying Cha.Api using template technology based on Dustjs to do the translation. See template for slack.

Example

Example is based on `hubot.

NOTE: However Cha is chatops tool independent, see Scratch from Hubot project for how to configure Cha and Hubot

msgData =
      text: "This is text with list"
      parts:[
        title: "This is title 1"
        text: "This is part title 1"
        color: "good",
        fields:[
          {
            "title": "field 1",
            "value": "value 1"
          },
          {
            "title": "field 2",
            "value": "value 2"
          },
          {
            "title": "field 3",
            "value": "value 3"
          }
        ]
      ,
        title: "This is title 2"
        title_link: "http://example.com"
        text: "This is part title 2"
        color: "warn",
        actions:[
          name: "ok"
          text: "OK"
        ,
          name: "cancel"
          text: "Cancel"
        ]
      ]

msg = new robot.Cha.Api.Message(msgData)
# res is a hubot response object
res.send msg

You will get message like following api-example.png

Cha.Framework

Cha.Framework supports following advanced features

• Support customized templates.
  • Using template to turn a biz record to a message
• Support widgets
  • At current moment, only cha.api.widget.list and cha.api.widget.nlist are provided as examples
• Support labels
  • A basis to support I18N

Example

Example is based on `hubot.

NOTE: However Cha is chatops tool independent, see Cha and Hubot for how to configure Cha and Hubot

First of all, you need to define your Cha configuration, which is a yaml file.

labels:
  severity: Severity
  affectedService: Affected Service

style:
  colors:
    high: danger

templates:
  kick_off_warroom: |
    {
      "text": "Incident {@c}{id}{/c} kicked off the war room{~n}{>"cha.api.widget.list" items=users/}",
      "parts":[
        {
          "title": "{title}",
          "text": "{description}",
          "color": "{severity|color}",
          "fields": [
             {
               "title": "{@label t="severity"/}",
               "value": "{severity}"
             },
             {
               "title": "{@label t="affectedService"/}",
               "value": "{affectedService.name}"
             }
          ]
        }
      ]
    }

The configuration defines a Cha.Framework template, calls kick_off_warroom. It is purpose is to turn an Incident into a Cha.Api message.

name = "kick_off_warroom"
mode =
  title: "Digital banking slow"
  id: "IM1293"
  users: ['a','b','c']
  description: "Digital banking is very slow, timeout"
  severity: "high"
  submitter: "James, T, Cook"
  affectedService:
    id: "CI192283",
    name: "digital-banking"
msg = new robot.Cha.Framework.Message name, model
res.send msg

Cha.Framework will look for the template name kick_off_warroom to render the Incident model. See example framework-example.png

So you can use another template to render the same record in a different format, for example

msg = new robot.Cha.Framework.Message 'resolve_incident`, model
res.send msg

I18N

1. Create I18 file locales/{lng}/{ns}.json in project folder
   • lng: language project support
   • ns: namespace for translate
2. Set environments CHA_LOCALE and CHA_NAMESPACE for identifying which language and namespace will be used for I18n
3. Use {@t val="content" /} to internationalizaion in cha configuration(.yaml).

NOTE: by default CHA_LOCALE="en-US" and CHA_NAMESPACE="translation".It means CHA will load {project location}/locales/en-US/translation.json for internatinalization by default.

Example

Example is based on `hubot.

Define your Cha configuration, which is a yaml file.

labels:
  severity: Severity
  affectedService: Affected Service

style:
  colors:
    high: danger

templates:
  kick_off_warroom: |
    {
      "text": "{@t val="Incident"/} {@c}{id}{/c} {@t val="kicked off"/} {@t val="the war room"/}{~n}", 
      "parts":[
        {
          "title": "{title}",
          "text": "{description}",
          "color": "{severity|color}",
          "fields": [
             {
               "title": "{@label t="severity"/}",
               "value": "{severity}"
             },
             {
               "title": "{@label t="affectedService"/}",
               "value": "{affectedService.name}"
             }
          ]
        }
      ]
    }

Define your I18N json file locales\zh-CN\translation.json:

{
  "Incident": "事件",
  "kicked off": "创建",
  "the war room": "作战室",
}