Rich Text

A rich text field configurable with formatting options (headings, paragraphs, strong, ...). Use it for titles and various rich text needs.

The following defines a single heading (a blog post title):

Copy
      "title" : {
  "type" : "StructuredText",
  "config" : {
    "placeholder" : "Blog post title...",
    "single" : "heading1"
  }
}
    

The following defines a multi-line rich text field (e.g. a blog post rich text):

Copy
      "body" : {
  "type" : "StructuredText",
  "config" : {
    "placeholder" : "Type a text here...",
    "multi" : "heading1,heading2,strong,em,hyperlink"
  }
}
    

The following defines a single paragraph rich text field for a quote:

Copy
      "quote" : {
  "type" : "StructuredText",
  "fieldset" : "Quote",
  "config" : {
    "single" : "paragraph,strong,em",
    "placeholder" : "Type a quote..."
  }
}
    

Reference

type

string

StructuredText

fieldset

string

a user-friendly field label for the editor

config

object

objects listed below

config

placeholder

string

Sets an user-friendly placeholder for the editor

multi

string

coma-separated formatting options. If used, the field will allow multiple lines with listed formatting option.

single

string

coma-separated formatting options. If used, the field will allow single line with listed formatting option.

formatting options (for single or multi config)

heading1-6

heading 1 to heading 6

paragraph

normal text paragraph

strong

strong

em

emphasized

hyperlink

inline links to the web, to a repository content or to a media library item

image

inline image

embed

inline link to a service URL supporting oEmbed

list-item

unordered list

o-list-item

ordered list

preformatted

Preformatted Text

StructuredText can be queried with a full-text predicate. Here is a full-text query on content of type "blog-post".

Copy
      var terms = req.query.terms;
api.query([
  prismic.Predicates.at("document.type", "blog-post"),
  prismic.Predicates.fulltext("document", terms)
], { pageSize : 10, req: req }).then(function(blogPosts) {
  res.render('index', {
    blogPosts: blogPosts.results[0]
  });
});
    
Copy
      $terms = $_GET("terms");
$response = $api
    ->query(array(
        Predicates::at("document.type", "blog-post"),
        Predicates::fulltext("document", terms)),
    array("pageSize" => 10));
    
Copy
      Response response = api.query(
    Predicates.at("document.type", "blog-post"),
    Predicates.fulltext("document", terms)
).submit();
    
Copy
      var response = await api.Query(
    Predicates.at("document.type", "blog-post"),
    Predicates.fulltext("document", terms)
).Submit();
    
Copy
      response = api.query([
    Predicates.at("document.type", "blog-post"),
    Predicates.fulltext("document", terms)
]);
    

Orderings

Structured text fields can be used for orderings. Only the first text block will be used.

Copy
      var terms = req.query.terms;
api.query([
  prismic.Predicates.at("document.type", "blog-post"),
  prismic.Predicates.fulltext("document", terms)
], { pageSize : 10, orderings : '[my.blog-post.title]' }).then(function(response) {
  // Use response here, the blog posts are in response.results
});
    
Copy
      $terms = $_GET("terms");
$response = $api->query(
    array(Predicates::at("document.type", "blog-post"), Predicates::fulltext("document", terms)),
    array("pageSize" => 10, "orderings" => "[my.blog-post.title]")
);
    
Copy
      Response response = api.query(
    Predicates.at("document.type", "blog-post"),
    Predicates.fulltext("document", terms)
).orderings("my.blog-post.title").submit();
    
Copy
      var response = await api.Query(
    Predicates.at("document.type", "blog-post"),
    Predicates.fulltext("document", terms)
).Orderings("my.blog-post.title").Submit();
    
Copy
      response = api.query([
    Predicates.at("document.type", "blog-post"),
    Predicates.fulltext("document", terms)
], { "ordering": ["my.blog-post.title"]});
    

Retrieving Additional Information

To prevent having to perform multiple queries, you can use fetchLinks to retrieve fields from the linked documents. It can only be used on simple types such as Text, Date, Timestamp and Number.

It works for links within StructuredText just like link fragments. Usage is detailed in the Link documentation.

Since StructuredText is used for rich text needs, we've included an .asHtml method to transform it into HTML.

The following example displays the title of the blog post:

Copy
      // using jade templating system
!= blogPosts.getStructuredText('blog-post.title').asHtml(ctx.linkResolver)
    
Copy
      <?= $doc->getStructuredText("blog-post.title")->asHtml($resolver); ?>
    
Copy
      <h:outputText value="#{doc.getStructuredText("blog-post.title").asHtml(resolver)}" escape="false" /> 
    
Copy
      @Html.Raw(Model.Doc.GetStructuredText("blog-post.title").AsHtml(Model.Resolver))
    
Copy
      	<%= @document['blog-post.title'].as_html_safe(link_resolver()) %>

    

Display the rich text of the blog post:

Copy
      // using jade templating system
div.blog-body
  blogPosts.getStructuredText('blog-post.body').asHtml(ctx.linkResolver)
    
Copy
      <?= $doc->getStructuredText("blog-post.body")->asHtml($resolver); ?>
    
Copy
      <h:outputText value="#{doc.getStructuredText("blog-post.body").asHtml(resolver)}" escape="false" /> 
    
Copy
      @Html.Raw(Model.Doc.GetStructuredText("blog-post.body").AsHtml(Model.Resolver))
    
Copy
      <%= @document['blog-post.body'].as_html_safe(link_resolver()) %>

    

Display the quote:

Copy
      // using jade templating system
div.blog-body.quote
  blogPosts.getStructuredText('blog-post.quote').asHtml(ctx.linkResolver)
    
Copy
      <?= $doc->getStructuredText("blog-post.quote")->asHtml($resolver); ?>
    
Copy
      <h:outputText value="#{doc.getStructuredText("blog-post.quote").asHtml(resolver)}" escape="false" /> 
    
Copy
      @Html.Raw(Model.Doc.GetStructuredText("blog-post.quote").AsHtml(Model.Resolver))
    
Copy
      <%= @document['blog-post.quote'].as_html_safe(link_resolver()) %>
    

Advanced: You can customize the HTML output by passing an HTML serializer to the method:

Copy
      var htmlSerializer = function (element, content) {
  // Don't wrap images in a <p> tag
  if (element.type == "image") {
    return '<img src="' + element.url + '" alt="' + element.alt + '">';
  }
  // Add a class to hyperlinks
  if (element.type == "hyperlink") {
    return '<a class="some-link" href="' + element.url + '">' + content + '</a>';
  }
  // Return null to stick with the default behavior
  return null;
};
var html = doc.getStructuredText('blog-post.body').asHtml(ctx.linkResolver, htmlSerializer);
    
Copy
      $htmlSerializer = function($element, $content) use ($resolver) {
    // Don't wrap images in a <p> tag
    if ($element instanceof ImageView) {
         return '<img src="' + $element->getUrl() + '" alt="' + $element->getAlt() + '">';
    }
    // Add a class to hyperlinks
    if ($element instanceof DocumentLink) {
        return '<a class="some-link" href="' . $element->getUrl($linkResolver) . '">' . $element->getSlug() . '</a>';
    }
    // Return null to stick with the default behavior
    return null;
};
$html = $doc->getStructuredText("blog-post.body")->asHtml($resolver, $htmlSerializer);

    
Copy
      // In your controller
HtmlSerializer serializer = new HtmlSerializer() {
  @Override
  public String serialize(Fragment.StructuredText.Element element, String content) {
    if (element instanceof Fragment.StructuredText.Block.Image) {
      Fragment.StructuredText.Block.Image image = (Fragment.StructuredText.Block.Image)element;
      return (image.getView().asHtml(new SimpleLinkResolver() {
        public String resolve(Fragment.DocumentLink link) {
          return "/"+link.getId()+"/"+link.getSlug();
        }
      }));
    }
    return null;
  }
}

// In JSP
<h:outputText value="#{doc.getStructuredText("blog-post.quote").asHtml(resolver, serializer)}" escape="false" /> 

    
Copy
      // In your controller
var serializer = prismic.HtmlSerializer.For ((elt, body) => {
  if (elt is fragments.StructuredText.Hyperlink) {
    var link = ((fragments.StructuredText.Hyperlink)elt).Link;
    if (link is fragments.DocumentLink) {
      var doclink = ((fragments.DocumentLink)link);
      return String.Format("<a class=\"some-link\" href=\"{0}\">{1}</a>", resolver.Resolve(doclink), body);
    }
  }
}

// In Razor
@Html.Raw(Model.Doc.GetStructuredText("blog-post.body").AsHtml(Model.Resolver, Model.Serializer))
    
Copy
      @html_serializer = Prismic.html_serializer do |element, html|
  if element.is_a?(Prismic::Fragments::StructuredText::Block::Image)
    %(<img src="#{element.url}" alt="#{element.alt}" width="#{element.width}" height="#{element.height}" />)
  else
    nil
  end
end

// In the template
<%= @document['blog-post.body'].as_html_safe(link_resolver(), @html_serializer) %>