Ricos Documents API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Convert site visitor input between Ricos document and Markdown formats

In this scenario, your app or site allows site visitors to create and edit content. They can choose whether to create the content using a rich content viewer or in a Markdown editor. They can toggle between the two formats while editing the content.

When the site visitor toggles from rich content to Markdown

1. Call Validate Document, specifying:

   • The site visitor's current Ricos document.
   • The plugins your rich content viewer supports.
   • fixDocument set to true.

2. Call Convert from Ricos Document, specifying:

   • The validDocument value from the previous step's response.
   • The target format MARKDOWN.

   Use the response to populate your Markdown editor.

When the site visitor toggles from Markdown to rich content

Call Convert to Ricos Document, specifying:

• The site visitor's current Markdown content.
• The plugins your rich content viewer supports.

Use the response to populate your rich content editor.

Let site visitors download files from a Ricos document

Your app or site displays Ricos documents to site visitors. Some documents contain file nodes, such as PDFs or audio files, that site visitors can download. Private files can't be downloaded from their regular URL, so your app generates a temporary download URL when a site visitor asks for the file.

To let site visitors download a file from a Ricos document:

1. Find the file node in the Ricos document and read its fileData.src.id.

2. When the site visitor clicks the file's download button, call Generate File Download URL, specifying the file ID as fileId.

3. Redirect the site visitor's browser to downloadUrls[0].url from the response. The browser downloads the file as an attachment.

   The URL expires after 10 hours, so generate a new URL each time a site visitor downloads the file instead of storing it.

Let site visitors add files to a Ricos document

Your app or site lets site visitors create rich content, such as comments or forum posts, and attach files like PDFs to it. The files are stored in the site's Media Manager and referenced from file nodes in the Ricos document.

To let a site visitor add a file to a Ricos document:

1. When the site visitor selects a file, call Generate File Upload URL, specifying the file's mimeType and fileName. To keep the file from being publicly accessible, specify private as true.

2. Send a PUT request to uploadUrl from the response, with the file content as the request body and a Content-Type header matching mimeType. If you didn't specify fileName, add the file name as the filename query parameter. The upload URL expires after 24 hours.

3. From the upload response, take file.id and add a file node to the Ricos document with fileData.src.id set to this ID. If the file is private, also set fileData.src.private to true. For example:

   Copy