Yellow Data

What is Yellow Data?

Yellow Data can be used to save information in Sophora documents without locking or changing their state.

Imagine a published document that should automatically be enriched with additional background information while a user has opened it in the Sophora DeskClient: Without using Yellow Data the Sophora Importer would need to lock, modify, save, and then unlock the document. The document's state would result in the "in progress" state, and the user that has opened the document before that process would have lost their document lock. The user would need to reopen the document, and they would also have to publish it again, if the Importer did not do that. In the end, the user is likely to be annoyed, and each republish results in a new document version. By using Yellow Data the document is still published after adding the information without locking the document in the first place.

You can configure Yellow Data properties to be visible like normal properties in the document editor (see Introduction of the Document Model). These are called virtual properties.

Note that Yellow Data will be not versioned, unlike regular document properties.

Yellow Data Types

Sophora has some built-in Yellow Data types: Sticky Notes and Merge Info. See below on how to implement custom types.

Sticky Notes

See the user documentation on Sticky Notes for further information. Technically, Sticky Notes are Yellow Data of the type sophora-nt:stickyNote. To import Sticky Notes via Sophora XML please see the section "Sticky Notes of a Document" in the Importer documentation.

Merge Info

See the user documentation about merging of document content for further information. Technically, Merge Info are Yellow Data of the type sophora-nt:mergeInfo. To import Merge Info via Sophora XML please see the section "Mergeable Properties and Child Nodes" in the Importer documentation.

Creating Custom Yellow Data Types

1. To create a custom Yellow Data type you need to create a custom node type with properties to hold your data (see example below). You may use single value properties of type boolean, date, double, long, and string. Multi value properties are not supported.
2. Finally assign the sophora-mix:yellowData mixin to the node type.

<'sophora-content'='http://www.subshell.com/sophora-content/1.0'>
<'sophora-content-nt'='http://www.subshell.com/sophora-content-nt/1.0'>

['sophora-content-nt:customYellowData']
  orderable
  - 'sophora-content:info' (string)

Now you can access the data via API, Importer or Delivery or display the custom properties in the document editor (see Configuring a Document's Properties and Childnodes).

Reading/Writing Yellow Data

Reading/Writing Using the DeskClient

With the exception of Sticky Notes users cannot directly edit Yellow Data in the document editor of the DeskClient. For custom Yellow Data types you may create a Client Script and use the ISophoraClient to modify the data (see next section).

Reading/Writing Using the Client API

The ISophoraClient interface provides the following methods to read/write Yellow Data:

YellowData saveYellowData(UUID documentUuid, YellowData data)
void deleteYellowData(UUID documentUuid, String dataId)
List<YellowData> getYellowData(UUID documentUuid)
List<YellowData> getYellowData(UUID documentUuid, String type)

Each YellowData object has a type, an identifier, a last modifier, a modification date, and a set of property values. The identifier can be any string, or it is a generated UUID if no identifier is specified. YellowData objects can be created using the following constructors:

YellowData(String nodeTypeName)
YellowData(String nodeTypeName, String id)
YellowData(String nodeTypeName, String id, String lastModifier, Calendar modificationDate, Set<IProperty> properties)

Example 1: Add/Overwrite Yellow Data on a Document

public static void main(String[] args) {
	SophoraClientFactory factory = new SophoraClientFactory("localhost:1199", "admin", "admin");
	ISophoraClient client = factory.createSophoraClient();
	try {
		client.login();

		UUID documentUuid = UUID.fromString("e6907385-410d-4611-a73b-736928fffe17");
		YellowData yellowData = new YellowData("sophora-content-nt:customYellowData", "custom-id-123");
		yellowData.setString("sophora-content:info", "My custom info");
		client.saveYellowData(documentUuid, yellowData);
	} finally {
		client.logout();
	}
}

Example 2: Read Yellow Data from a Document

public static void main(String[] args) {
	SophoraClientFactory factory = new SophoraClientFactory("localhost:1199", "admin", "admin");
	ISophoraClient client = factory.createSophoraClient();
	try {
		client.login();

		UUID documentUuid = UUID.fromString("e6907385-410d-4611-a73b-736928fffe17");
		List<YellowData> yellowData = client.getYellowData(documentUuid, "sophora-content-nt:customYellowData");
		for (YellowData data : yellowData) {
			System.out.println(data.getString("sophora-content:info"));
		}
	} finally {
		client.logout();
	}
}

Importing Custom Yellow Data

Custom Yellow Data can be imported via Sophora XML like any other child node. Note that all Yellow Data of a document are stored in the same child node sophora:yellowData of the type sophora-nt:yellowData.

Example Sophora XML

<?xml version="1.0" encoding="UTF-8"?>
<documents xmlns="http://www.sophoracms.com/import/3.7">
  <document nodeType="sophora-content-nt:story" externalID="e6907385-410d-4611-a73b-736928fffe17">
    <properties />
    <childNodes>
	  <childNode nodeType="sophora-nt:yellowData" name="sophora:yellowData">
        <properties />
        <childNodes>
          <childNode nodeType="sophora-content-nt:customYellowData" name="sophora:yellowDataEntry">
            <properties>
              <property name="sophora:dataId">
                <value>custom-id-123</value>
              </property>
              <property name="sophora-content:info">
                <value>My custom info</value>
              </property>
            </properties>
            <childNodes />
            <resourceList />
          </childNode>
        </childNodes>
        <resourceList />
      </childNode>
    </childNodes>
    <resourceList />
    <fields>
      <site></site>
      <structureNode></structureNode>
      <categories />
      <idstem></idstem>
      <forceLock>false</forceLock>
      <forceCreate>false</forceCreate>
      <channels>
        <enabledChannels />
        <disabledChannels />
      </channels>
    </fields>
    <instructions>
      <lifecycleActivities />
      <proposals />
      <stickyNotes />
    </instructions>
  </document>
</documents>

Reading Yellow Data in Delivery

All Yellow Data are replicated automatically to the staging slaves if the containing document is in the "published" state. Affected HTML cache entries are invalidated in this case as if the document had been changed (see the section "Details about Cache Update" of the Delivery Caching documentation.)

The Yellow Data of a document can be accessed by the node function ${documentMap.yellowData['typeName']} or by using the IContentMapContext method List<YellowData> getYellowData(UUID documentUuid, String type) when you create your own models. Please see the sections "Default function of the Sophora Content Map" and "Implementing Custom Functions" in the Template Development documentation.