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:
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 noui: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.