html_notes and html_text launch update

tl;dr:

  • some HTML tags and characters sequences have new semantic meanings in task descriptions
  • rollout starts this Monday, 2022-09-26

Hey folks,

We’re excited to announce that the promised enhancements to rich text in task descriptions are imminent.

Current Behavior

New HTML Tags in Asana Rich Text

Added Behavior

Task descriptions in the Asana Web App UI will be structured into independently-draggable “blocks”

To represent this, several new whitespace standards have been introduced. Your API application doesn’t necessarily need to amend its whitespace behavior to account for this, but it should be aware that they will show up in task description content that has been edited on the Asana Web App. The UI “blocks” are divided between:

  • Each header (<h1>/<h2> tag)
  • Each horizontal rule (<hr> tag)
  • Each list item (<li> tag)
  • Each inline image (<img> tag)
  • Each media embed (<object> tag)

Special considerations:

  • Each sequence of content that includes none of these tags (implicitly a “paragraph block”)
  • Multiple “paragraph blocks” can exist in sequence. When this happens, a double-newline (\n\n) will indicate a division between two blocks. This contrasts with a single line break (\n), which indicates a new line within the same block.
  • If we need to represent multiple sequential line breaks within the same block, we use the unicode zero-width-space (\u200b) as a line’s content
  • Example: Line one\n\u200b\nLine three\n\nA separate block

Timeline

These enhancements will be launching in phases. These timings are estimates and subject to change, but our current plan is the following:

  • Block-level editing with headers and horizontal rules (<h1>, <h2>, <hr>)
    • begin rollout: 2022-09-26 (Monday)
    • generally available: end of October
  • Inline images (<img>)
    • begin rollout: Fall 2022
  • Media Embeds (<object>)
    • begin rollout: Fall 2022
  • Tables
    • begin rollout end of 2022

What’s Coming Next?

Once these features are live, we’ll be working to bring them to other rich text surfaces in the API in order to provide a more consistent experience.


Yours in Developer Relations,
Sasha, on behalf of the Asana API Team

6 Likes

Hey folks, reminder that this is beginning rollout today!

5 Likes

This whole acting like we are a WordPress document for a simple description field is awful…I should be able to update/move/edit more than one line at a time. Every time I hit enter, it creates a new text box - what is that about?

1 Like

Hey folks,

We’ve received some feedback about the new behavior. We’ll be making a change to how newlines are interpreted for the remainder of the rollout.

We originally announced v1 behavior on 2022-09-22. Today we’re modifying this with the announcement of v2 behavior.

Legacy Behavior

New HTML Tags in Asana Rich Text

v1 Behavior (announced 2022-09-22)

When an html_notes includes a double-newline (\n\n), the web UI gives this a special display treatment:

  • This is treated as a separator between “blocks”
  • Blocks group their associated text and provide a drag handle to allow reordering between blocks
  • Between one another, “blocks” have visual padding, but no editable empty line of text
  • API clients who wanted consecutive newlines (ex: to create an editable empty line between two lines of text) needed to include a zero-width space between newlines (\n\u200b\n) to distinguish it from a block separator (\n\n)

v2 Behavior Behavior

  • Any newline included by an API write is treated identically, with no special display behavior. Newlines put the following text on the next line of the editor.

Timeline

Completed

  • 22-09-22: we began rollout of v1 behavior to replace legacy behavior
  • 22-10-24: we completed rollout of v1 behavior, and legacy behavior was no longer available
  • 22-11-4: we began rollout of v2 behavior to replace v1 behavior

Upcoming

  • 22-11-22: we will complete rollout of v2 behavior to replace v1 behavior
3 Likes