Story Element Types

A story element is a block-level component of the text flow in a story. Examples of story elements include:

Headings
Ordinary paragraphs
Specially-formated paragraphs such as fact boxes and pull quotes
Images, videos and audio recordings
Embeds
Related stories

Story element types are defined in XML files, one type per file. Standard story element types are included in the Content Store distribution, but you can modify them and/or create additional ones of your own. Here is a story element type definition for a paragraph:

<?xml version="1.0" encoding="UTF-8"?>
<story-element-type xmlns="http://xmlns.escenic.com/2008/content-type"
                    xmlns:ui="http://xmlns.escenic.com/2008/interface-hints"
                    name="paragraph">
  <ui:label>Paragraph</ui:label>
  <ui:icon>paragraph</ui:icon>
    <field name="paragraph" type="basic" mime-type="text/plain">
      <annotation name="bold"/>
      <annotation name="italic"/>
      <annotation name="underline"/>
      <annotation name="strike"/>
      <annotation name="subscript"/>
      <annotation name="superscript"/>

      <annotation name="inline_link">
        <allow-story-element-type>
          <ref-story-element-type name="external_link"/>
        </allow-story-element-type>
        <ui:style>
          {
            color: blue;
            text-decoration: underline;
          }
        </ui:style>
      </annotation>

      <annotation name="internal_link">
        <allow-story-element-type>
          <ref-story-element-type name="internal_link"/>
        </allow-story-element-type>
        <ui:style>
          {
            color: green;
            text-decoration: underline;
          }
        </ui:style>
      </annotation>

      <annotation name="note">
        <allow-story-element-type>
          <ref-story-element-type name="note"/>
        </allow-story-element-type>
        <ui:style>{ background-color: yellow; }</ui:style>
      </annotation>

      <ui:summary-field/>
    </field>
</story-element-type>

The above definition says that a paragraph element:

Will be called Paragraph in CUE (<ui:label>Paragraph</ui:label>)
Will be represented by the paragraph icon in CUE
Has one field (called paragraph) that may contain plain text (type="basic" mime-type="text/plain")
Can be formatted by applying various annotations (inline formatting instructions) to the contained text. The ui:annotation elements specify which formats are allowed in paragraphs.

In CUE the specified annotations appear as buttons on a formatting bar. This bar appears whenever the user selects some of the text in the paragraph:

The bold, italic, underline, strike, subscript and superscript annotations are built in to CUE, with predefined rendering and button icons. You can, however, define your own additional annotations, like the inline_link, internal_link and note annotations in the above example. For more about this, see Custom Annotations.

Here is another story element type, this one for images:

<?xml version="1.0" encoding="UTF-8"?>
<story-element-type xmlns="http://xmlns.escenic.com/2008/content-type"
                    xmlns:ui="http://xmlns.escenic.com/2008/interface-hints"
                    name="image">
    <ui:label>Image/Gallery</ui:label>
    <ui:icon>photo</ui:icon>

    <field name="alignment" type="enumeration" >
      <ui:label>Alignment</ui:label>
      <ui:editor-style>buttons</ui:editor-style>
      <enumeration value="left">
        <ui:label>Left</ui:label>
      </enumeration>
      <enumeration value="center">
        <ui:label>Center</ui:label>
      </enumeration>
      <enumeration value="right">
        <ui:label>Right</ui:label>
      </enumeration>
    </field>

    <field name="caption" type="basic" mime-type="text/plain">
      <ui:label>Caption</ui:label>
    </field>
    <field name="copyright" type="basic" mime-type="text/plain">
      <ui:label>Copyright</ui:label>
    </field>

    <field name="relation" type="link">
        <relation>com.escenic.content-item</relation>
        <constraints>
            <allow-content-types>
                <ref-content-type name="picture"/>
            </allow-content-types>
          <required>true</required>
        </constraints>
    </field>
</story-element-type>

Elements of this type consist of three fields:

The first field is labelled Alignment and is rendered as three buttons, one for each possible value.
The second field is labelled Caption and may contain plain text (type="basic" mime-type="text/plain"), which in this case may not be formatted since no ui:annotation elements are specified.
The third field has no label and is a rendered in CUE as a drop zone into which an image may be dragged.

type="link", means that the third field can only contain a link to an object. <relation>com.escenic.content-item</relation> means that it can only contain a link to a CUE content item (not an image dragged from the desktop, for example), and the constraints element narrows things down even further, so that CUE users are only allowed to drop content items of the type picture in this field.

This example illustrates the use of the ui:style and ui:title-field elements in story element types:

<?xml version="1.0" encoding="UTF-8"?>
<story-element-type
  xmlns="http://xmlns.escenic.com/2008/content-type"
  xmlns:ui="http://xmlns.escenic.com/2008/interface-hints" name="headline">
    <ui:label>Headline</ui:label>
    <ui:icon>headline</ui:icon>
    <field name="headline" type="basic" mime-type="text/plain">
        <ui:title-field/>
    </field>
    <ui:style>
      .story-element-headline [contenteditable='true'] {
        font-size: 2.5em;
      }
    </ui:style>
</story-element-type>

If used, the ui:style element must appear as a child of the story-element-type element. It controls the appearance of the story element type in CUE. For more information on how to use the ui:style element, see style.

If used, the ui:title-field element must appear as a child of the story-element-type element. It indicates that this story element type can be used by CUE to automatically fill a story's slug field (the field pointed to by a story content type's ui:title-field element. For more information about this, see Native CUE Stories.

Story element type definitions are defined using XML elements from the same namespace as the content-type resource. Whereas the root of a content-type resource is a content-types element, the root element of a story element type definition is a story-element-type element. So for a complete, formal description of the file format, start here.