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.
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.
There are several types of entities. Other types may be added in the future.
This is also known as a hashtag. This is indicated with the following as its type value:
"tag"
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
| 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"
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>
| 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. |
This is also known as italic. This is indicated with the following as its type value:
"emphasis"
Make something italic by surrounding it with * (asterisk) or _ (underscore).
Read *Steve Jobs* Listen to _Empire! Empire!_
This type doesn't contain any additional attributes.
This is also known as bold. This is indicated with the following as its type value:
"double_emphasis"
Make something bold by surrounding it with ** (two asterisks) or __ (two underscores).
Make it **really** awesome Something __accurate__ for Chapter 1
This type doesn't contain any additional attributes.
This is also known as bold italic. This is indicated with the following as its type value:
"triple_emphasis"
Make something bold italic by surrounding it with *** (three asterisks) or ___ (three underscores).
Never say ***never*** Go camping ___soon___
This type doesn't contain any additional attributes.
This is indicated with the following as its type value:
"strikethrough"
To strikethrough text, surround it with ~~ (two tildes).
Find a ~~good~~ great restaurant
This type doesn't contain any additional attributes.
This is indicated with the following as its type value:
"code"
You can reference code by surrounding it by a ` (back-tick).
Change the links to `#0881b3`
This type doesn't contain any additional attributes.
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.
