Skip to content
  • Documentation >
  • API >
  • Field Type >
  • Field Types reference >
  • RichText Field Type

RichText Field Type

The RichText Field Type is available via the RichText Field Type Bundle provided by the ezplatform-richtext package.

This Field Type validates and stores structured rich text, and exposes it in several formats.

Name Internal name Expected input
RichText ezrichtext mixed

PHP API Field Type

Value object

EzSystems\EzPlatformRichText\eZ\FieldType\RichText\Value offers the following properties:

Property Type Description
xml DOMDocument Internal format value as an instance of DOMDocument.

Input expectations

Type Description
string XML document in one of the Field Type's input formats as a string.
DOMDocument XML document in one of the Field Type's input formats as a DOMDocument object.
EzSystems\EzPlatformRichText\eZ\FieldType\RichText\Value An instance of the Field Type's Value object.
Input formats

The Field Type expects an XML value as input, in the form of a string, DOMDocument object, or Field Type's Value object. The Field Type's Value object must hold the value in the Field Type's internal format. For a string of a DOMDocument object, if the input does not conform to this format, it is converted into it.

Legacy eZXML format

The Legacy eZXML format is also supported by the RichText Field Type, but can be used only for migration, in compatibility with the legacy XML format. For more information about migrating eZXML content, see Migrating from eZ Publish Platform.

Internal format

As its internal format, the RichText Field Type uses a custom flavor of the DocBook format.

1
2
3
4
5
6
7
8
9
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:ezxhtml="http://ez.no/xmlns/ezpublish/docbook/xhtml"
         xmlns:ezcustom="http://ez.no/xmlns/ezpublish/docbook/custom"
         version="5.0-variant ezpublish-1.0">
    <title ezxhtml:level="2">This is a title.</title>
    <para ezxhtml:class="paraClass">This is a paragraph.</para>
</section>
XHTML5 edit format

The XHTML5 format is used by the Online Editor.

1
2
3
4
5
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://ez.no/namespaces/ezpublish5/xhtml5/edit">
    <h2>This is a title.</h2>
    <p class="paraClass">This is a paragraph.</p>
</section>

Custom DocBook format

Caution

The custom DocBook format described below is subject to change and is not covered by backwards compatibility promise.

You can use the {{ product_nam_base_ }} flavor of the DocBook format in PHP API and in REST API requests by providing the DocBook content as a string.

The following example shows how to pass DocBook content to a create struct:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
$contentCreateStruct = $contentService->newContentCreateStruct( $contentType, "eng-GB" );

$inputString = <<<DOCBOOK
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:ezxhtml="http://ez.no/xmlns/ezpublish/docbook/xhtml"
         xmlns:ezcustom="http://ez.no/xmlns/ezpublish/docbook/custom"
         version="5.0-variant ezpublish-1.0">
    <title ezxhtml:level="2">This is a title.</title>
    <para ezxhtml:class="paraClass">This is a paragraph.</para>
</section>
DOCBOOK;

$contentCreateStruct->setField( "description", $inputString );

When creating RichText content with the REST API, use the xml key of the fieldValue tag:

1
2
3
4
5
6
7
<fieldValue>
    <value key="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ezxhtml="http://ez.no/xmlns/ezpublish/docbook/xhtml" xmlns:ezcustom="http://ez.no/xmlns/ezpublish/docbook/custom" version="5.0-variant ezpublish-1.0"&gt;
&lt;title ezxhtml:level="2"&gt;This is a title.&lt;/title&gt;
&lt;/section&gt;
    </value>
</fieldValue>

DocBook elements

The RichText format enriches DocBook with the following custom elements:

  • section - main element of a RichText Field
  • ezembed - holds embedded images
  • ezembedinline - holds embedded Content items
  • eztemplate - holds custom tags, including built-in custom tags for embedded Facebook, Twitter and YouTube content
  • eztemplateinline - holds inline custom tags
  • ezconfig - contains configuration for custom tags and other elements
  • ezvalue - contains values for other elements, such as ezconfig or ezembed
  • ezattribute - contains attributes for other elements, such as ezconfig or ezembed

Unsupported DocBook elements

Some DocBook elements are not supported by RichText. Refer to ezpublish.rng for a full list.

Online Editor elements

Elements of the Online Editor correspond to the following sample DocBook code blocks.

Text formatting

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<para xml:id="anchor" ezxhtml:class="ez-has-anchor">Anchor text</para>
<para ezxhtml:class="" ezxhtml:textalign="center">Center aligned</para>
<para ezxhtml:class="" ezxhtml:textalign="left">Left aligned <emphasis role="strong">bold</emphasis>
    <emphasis>italic </emphasis>
    <emphasis role="underlined">underlined </emphasis>
    <subscript>subscript </subscript>
    <superscript>superscript </superscript>
    <emphasis role="strikedthrough">crossed out</emphasis>
</para>
<blockquote>
    <para ezxhtml:class="" ezxhtml:textalign="left">This is a block quote.</para>
</blockquote>

Heading

1
<title ezxhtml:level="1">My heading</title>

Code block

1
<programlisting><![CDATA[Code sample here]]></programlisting>

Unordered list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<itemizedlist>
    <listitem>
        <para>1st level bullet point</para>
    </listitem>
    <listitem>
        <para>1st level bullet point
            <itemizedlist>
                <listitem>
                    <para>2nd level bullet point</para>
                </listitem>
                <listitem>
                    <para>2nd level bullet point</para>
                </listitem>
            </itemizedlist>
        </para>
    </listitem>
</itemizedlist>

Ordered list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<orderedlist>
    <listitem>
        <para>1st level numbered point</para>
    </listitem>
    <listitem>
        <para>1st level numbered point
            <orderedlist>
                <listitem>
                    <para>2nd level numbered point</para>
                </listitem>
            </orderedlist>
        </para>
    </listitem>
</orderedlist>

Embedded content

1
<ezembedinline xlink:href="ezcontent://58" view="embed-inline"/>

Inline embedded content

1
<link xlink:href="ezlocation://60" xlink:show="none">embed inline</link>

Image

1
2
3
4
5
<ezembed xlink:href="ezcontent://67" view="embed" ezxhtml:class="ez-embed-type-image">
    <ezconfig>
        <ezvalue key="size">medium</ezvalue>
    </ezconfig>
</ezembed>

Table

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<informaltable width="100%" border="1">
    <thead>
        <tr>
            <th scope="col"></th>
            <th colspan="2" scope="col">This is a merged table cell</th>
            <th scope="col"></th>
            <th scope="col"></th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <th scope="row"></th>
            <td></td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th scope="row"></th>
            <td colspan="2"></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th scope="row"></th>
            <td colspan="2"></td>
            <td></td>
            <td></td>
        </tr>
    </tbody>
</informaltable>