Option

View as Markdown

Option

Option is the interface that the SDK calls to convert the content of a JSON Rich Text Editor (JSON RTE) field to HTML. Each of its three methods returns the HTML for one kind of JSON RTE item:

  • renderMark for formatting on a text node, such as bold or italic
  • renderNode for a block or inline node, such as a paragraph, heading, list, table or link
  • renderOptions for an entry or asset embedded in the rich text

DefaultOption is the implementation that the SDK provides. Pass a DefaultOption wherever a method takes an Option.

renderMark

renderMark returns the text of a JSON Rich Text Editor text node wrapped in the HTML for one formatting mark.

NameTypeDescription
markType (required)MarkType

Formatting mark to apply, such as BOLD.

Default: Not applicable
renderText (required)String

Text to wrap, which already carries earlier marks.

Default: Not applicable

Returns: String. The text wrapped in the mark's HTML.

Validation

  • There is no client-side validation. Option declares renderMark and checks nothing. See DefaultOption renderMark for what the SDK's implementation does with each value.

Behavior

  • NodeToHTML textNodeToHTML calls renderMark once for each mark key on a text node, in this fixed order: superscript, subscript, inlineCode, strikethrough, underline, italic, bold, break.
  • Each call receives the output of the call before it, so a later mark wraps an earlier one. For example, a node with italic and bold becomes the bold HTML around the italic HTML.
  • MarkType has eight values: BOLD, ITALIC, UNDERLINE, STRIKETHROUGH, INLINECODE, SUBSCRIPT, SUPERSCRIPT and BREAK.
  • MarkType is package-private, so code outside com.contentstack.sdk cannot name it and cannot call renderMark directly. Pass the Option to textNodeToHTML or SDKUtil.jsonToHTML, which call renderMark for you.

Example

Basic usage: apply marks through textNodeToHTML

import android.util.Log;

import com.contentstack.sdk.DefaultOption;
import com.contentstack.sdk.NodeToHTML;
import com.contentstack.sdk.Option;

import org.json.JSONException;
import org.json.JSONObject;

try {
    Option option = new DefaultOption();
    JSONObject textNode = new JSONObject()
            .put("text", "Summer sale")
            .put("underline", true)
            .put("bold", true);
    // textNodeToHTML calls option.renderMark for underline, then for bold
    String html = NodeToHTML.textNodeToHTML(textNode, option);
    Log.d("Contentstack", html); // <strong><u>Summer sale</u></strong>
} catch (JSONException e) {
    Log.e("Contentstack", e.getMessage());
}

renderNode

renderNode returns the HTML for one block or inline node of a JSON Rich Text Editor field, including its children.

NameTypeDescription
nodeType (required)String

Type of the node, such as p or h2.

Default: Not applicable
nodeObject (required)JSONObject

The node, with its attrs and children.

Default: Not applicable
callback (required)NodeCallback

Renders the node's children as HTML.

Default: Not applicable

Returns: String. The HTML for the node and its children.

Validation

  • There is no client-side validation. Option declares renderNode and checks nothing. See DefaultOption renderNode for what the SDK's implementation does with each node type.

Behavior

  • SDKUtil.jsonToHTML calls renderNode for every node that has a type, except reference nodes. It passes the node's type as nodeType.
  • For an embedded asset that jsonToHTML does not find under _embedded_items, it calls renderNode with img as nodeType and the reference node as nodeObject.
  • callback has one method, renderChildren(JSONArray nodeJsonArray), which renders the given child nodes with the same Option and returns their HTML. An implementation passes the node's children array to it to include the children in its output.
  • NodeCallback is package-private, so code outside com.contentstack.sdk cannot name it and cannot call renderNode directly. Pass the Option to SDKUtil.jsonToHTML, which calls renderNode for you.

Example

Basic usage: render nodes through jsonToHTML

import android.util.Log;

import com.contentstack.sdk.DefaultOption;
import com.contentstack.sdk.Option;
import com.contentstack.sdk.SDKUtil;

import org.json.JSONException;
import org.json.JSONObject;

try {
    Option option = new DefaultOption();
    // An entry with one JSON RTE field, "body", that holds a heading and a paragraph
    JSONObject entryJson = new JSONObject("{\"body\":{\"type\":\"doc\",\"children\":["
            + "{\"type\":\"h2\",\"attrs\":{},\"children\":[{\"text\":\"Features\"}]},"
            + "{\"type\":\"p\",\"attrs\":{},\"children\":[{\"text\":\"Fast and light\"}]}]}}");
    // jsonToHTML calls option.renderNode for the h2 node and the p node
    SDKUtil.jsonToHTML(entryJson, new String[]{"body"}, option);
    Log.d("Contentstack", entryJson.getString("body")); // <h2>Features</h2><p>Fast and light</p>
} catch (JSONException e) {
    Log.e("Contentstack", e.getMessage());
}

renderOptions

renderOptions returns the HTML for an entry or asset embedded in a JSON Rich Text Editor field.

NameTypeDescription
embeddedObject (required)JSONObject

JSON of the embedded entry or asset.

Default: Not applicable
metadata (required)Metadata

Details of the reference that embeds the item.

Default: Not applicable

Returns: String. The HTML for the embedded item.

Validation

  • There is no client-side validation. Option declares renderOptions and checks nothing. See DefaultOption renderOptions for what the SDK's implementation does with each value.

Behavior

  • SDKUtil.jsonToHTML calls renderOptions for a reference node only when it finds the embedded item under the entry's _embedded_items key. In this version of the SDK that lookup never succeeds, so jsonToHTML never calls renderOptions. See Embedded entries and assets on the Option class page.
  • When an implementation returns null, jsonToHTML uses the output of DefaultOption renderOptions for that item instead.
  • metadata contains the display style of the item, which Metadata getStyleType returns: BLOCK, INLINE, LINK, DISPLAY or DOWNLOAD.
  • renderOptions is the only Option method that your code can call directly, because its parameter types are public.

Example

Basic usage: render an embedded entry through the Option interface

import android.util.Log;

import com.contentstack.sdk.DefaultOption;
import com.contentstack.sdk.Metadata;
import com.contentstack.sdk.Option;

import org.json.JSONException;
import org.json.JSONObject;

import java.util.jar.Attributes;

try {
    Option option = new DefaultOption();
    JSONObject author = new JSONObject()
            .put("uid", "<ENTRY_UID>")
            .put("title", "Jane Doe")
            .put("_content_type_uid", "<CONTENT_TYPE_UID>");
    Metadata metadata = new Metadata("Jane Doe", "entry", "<ENTRY_UID>", "<CONTENT_TYPE_UID>",
            "INLINE", "", new Attributes());
    String html = option.renderOptions(author, metadata);
    Log.d("Contentstack", html); // <span>Jane Doe</span>
} catch (JSONException e) {
    Log.e("Contentstack", e.getMessage());
}