Cheddar

Task Entities Guide

Cheddar features advanced text features in tasks. These are represented in the API as task entities. Task entities work similar to Twitter's tweet entities.

Let's look at this task:

**Remember** to buy milk #groceries

This task uses the Markdown bold syntax to bold Remember. There is also a hashtag, #groceries. The truncated API representation of this task looks like this:

{
  "text": "**Remember** to buy milk #groceries",
  "display_text": "Remember to buy milk #groceries",
  "display_html": "<strong>Remember</strong> to buy milk <a href="#tag-groceries" class="tag">#groceries</a>",
  "entities": [
    {
      "type": "double_emphasis",
      "text": "**Remember**",
      "indices": [0, 12],
      "display_text": "Remember",
      "display_indices": [0, 8]
    },
    {
      "type": "tag",
      "text": "#groceries",
      "indices": [25, 35],
      "display_text": "#groceries",
      "display_indices": [21, 31],
      "tag_name": "groceries"
    }
  ],
  "tags": [
    {
      "id": 3,
      "name": "groceries"
    }
  ]
}

Here's what the various keys contain:

text The original text the user typed in the box.
display_text The text that should be displayed. This will not containn any Markdown specific characters.
display_html An HTML version of the display text with the proper tags around the entities.
entities An array of each entity object. More detail below.
tags A array of tags contained in the task.

See the tasks documentation for the full description of a task.


Entities

There are several entity types (that we'll get to in a minute). All entities share these attributes:

type The type of the entity. The full list is below.
text The original text the user typed in the box for this entity.
indices The indices of where the entity falls in the task's text attribute.
display_text The display version of the entity.
display_indices The indices of where the entity falls in the task's display_text attribute.

Other attributes are contained for some entity types. These are covered in the types section.


Types

There are several types of entities. Other types may be added in the future.

Tags

This is also known as a hashtag. This is indicated with the following as its type value:

"tag"

Syntax

Hashtags have the same syntax as they do on Twitter. Prefix some text with a # (hash). The full definition can be found here.

Buy a new rug at #ikea

Additional Attributes

tag_name The tag's text without the # prefix.

If you need the tag's id, you can reference it in the "tags" array.


This is indicated with the following as its type value:

"link"

Syntax

Links can be detected or added using Markdown. For detection, the user has to simply type the link:

Check out http://nothingmagical.com

For Markdown, the user may use the standard Markdown link notation, links with a title, and Markdown's autolinking (including email addresses):

Read [Sam's blog](http://blog.samsoff.es)
Learn [Ruby](http://mislav.uniqpath.com/poignant-guide/book/chapter-1.html "Why's (Poignant) Guide to Ruby")
Get invited to <http://dribbble.com>
Email <support@cheddarapp.com>

Additional Attributes

url The address the link links to. For email links, this will be prefixed with mailto:.
title
optional
The title of the link. This will be omitted if it is empty.

Emphasis

This is also known as italic. This is indicated with the following as its type value:

"emphasis"

Syntax

Make something italic by surrounding it with * (asterisk) or _ (underscore).

Read *Steve Jobs*
Listen to _Empire! Empire!_

Additional Attributes

This type doesn't contain any additional attributes.


Double Emphasis

This is also known as bold. This is indicated with the following as its type value:

"double_emphasis"

Syntax

Make something bold by surrounding it with ** (two asterisks) or __ (two underscores).

Make it **really** awesome
Something __accurate__ for Chapter 1

Additional Attributes

This type doesn't contain any additional attributes.


Triple Emphasis

This is also known as bold italic. This is indicated with the following as its type value:

"triple_emphasis"

Syntax

Make something bold italic by surrounding it with *** (three asterisks) or ___ (three underscores).

Never say ***never***
Go camping ___soon___

Additional Attributes

This type doesn't contain any additional attributes.


Strikethrough

This is indicated with the following as its type value:

"strikethrough"

Syntax

To strikethrough text, surround it with ~~ (two tildes).

Find a ~~good~~ great restaurant

Additional Attributes

This type doesn't contain any additional attributes.


Code

This is indicated with the following as its type value:

"code"

Syntax

You can reference code by surrounding it by a ` (back-tick).

Change the links to `#0881b3`

Additional Attributes

This type doesn't contain any additional attributes.


Emoji

Emoji is automatically handled. You should always treat text coming from the Cheddar API as UTF-16. Note that in some languages the length of an emoji character will be two instead of one. We treat them as one character for the sake of indicies. Here's a useful blog post on the topic.

Cheddar also supports the named-emoji syntax. These will be converted into character in the "display_text" and "display_html" attributes.