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">
      <ui:annotation name="bold"/>
      <ui:annotation name="italic"/>
      <ui:annotation name="underline"/>
      <ui:annotation name="strike"/>
      <ui:annotation name="subscript"/>
      <ui:annotation name="superscript"/>
      <ui:annotation name="link"/>
      <ui:annotation name="clean"/>
  </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:

graphics/inline-format-menu.png

Note that annotations themselves are not user-defined: CUE supports a limited set of inline formats, each with an associated button icon. For a list of supported annotation names, see ??.

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</ui:label>
    <ui:icon>photo</ui:icon>
    <field name="caption" type="basic" mime-type="text/plain">
      <ui:label>Caption</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>
        </constraints>
    </field>
</story-element-type>

Elements of this type consist of two fields:

  • One 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 other 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 second 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:label>Headline</ui:label>
    <ui:description>The headline field of a story line</ui:description>
  </field>
  <ui:style>
    .story-element-headline [contenteditable='true'] {
        font-size: 2.3em;
    }
  </ui:style>
  <ui:title-field />
</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.