Option
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.
| Name | Type | Description |
|---|---|---|
| markType (required) | MarkType | Formatting mark to apply, such as BOLD. |
| renderText (required) | String | Text to wrap, which already carries earlier marks. |
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.
| Name | Type | Description |
|---|---|---|
| nodeType (required) | String | Type of the node, such as p or h2. |
| nodeObject (required) | JSONObject | The node, with its attrs and children. |
| callback (required) | NodeCallback | Renders the node's children as HTML. |
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.
| Name | Type | Description |
|---|---|---|
| embeddedObject (required) | JSONObject | JSON of the embedded entry or asset. |
| metadata (required) | Metadata | Details of the reference that embeds the item. |
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());
}