Docs Developer Site
Project Guillotine - Headless API for Enonic XPUsageRich text

Rich text processing

Contents

v v 5.0.0 5.0.0 The default Guillotine HTML editor type provides processing of macros and image URLs in the processedHtml field of the RichText GraphQL object type. But you might want to have custom processing of macros and images, for that you can use macrosAsJson, macros and images fields of the RichText.

Usage

Starting from v v 5.5.0 5.5.0 Guillotine by default provides links processing in the processedHtml field of the RichText GraphQL object type. All internal links to media or content will be replaced by an absolute (server) link and for each a tag a data-link-ref attribute with referenced content Id will be added. Using that reference you will be able to find link details in the links field and to do custom link processing if needed.

For instance, the processed value of a link looks like below:

<p>
    <a title="Tooltip"
        href="/admin/site/preview/hmdb/draft/hmdb/persons/lea-seydoux"
        data-link-ref="e72f48b6-a972-4133-a300-a3ab5d132800">Link 1</a>
</p>

The GraphQL query below will process links inside the field:

query {
  guillotine {
    get(key: "contentID") {
      ... on com_app_example_ContentType {
        data {
          htmlAreaField {
            links {
              ref          (1)
              uri          (2)
              media {      (3)
                content {
                 _id
                }
                intent     (4)
              }
              content {    (5)
                _id
              }
            }
          }
        }
      }
    }
  }
}
1 Reference to link in the processedHtml field
2 Link URI
3 Related media content. This field has null value for non-media content
4 Link intent. Available values download and inline
5 Related content. This field has null value for media content

Images

Starting from v v 5.0.0 5.0.0 Guillotine by default provides image processing in the processedHtml field of the RichText GraphQL object type. All internal links to resources will be replaced by an absolute (server) link and for each img tag a data-image-ref attribute with referenced content Id will be added. Using that reference you will be able to find image details in the images field and to do custom image processing if needed.

For instance, the processed value of an image looks like below:

<figure class="editor-align-justify">
    <img alt="Alt text"
         src="/site/repo/branch/appName/_/image/contentID/width-768/imageName.jpg"
         data-image-ref="4f2439ff-ecef-4470-a4b4-d8929bce6ee2" />
    <figcaption>Caption text</figcaption>
</figure>

The query below will process images inside the field:

query {
  guillotine {
    get(key: "contentID") {
      ... on com_app_example_ContentType {
        data {
          htmlAreaField {
            images {
              ref                           (1)
              image {                       (2)
                ... imageFragment
              }
              style {                       (3)
                name
                aspectRatio
                filter
              }
            }
          }
        }
      }
    }
  }
}

fragment imageFragment on Content {
  _id
  type
  ... on media_Image {
    data {
      caption
    }
  }
  ... on media_Vector {
    data {
      caption
    }
  }
}
1 Reference to an image in the processedHtml field
2 Image as Content type
3 Image style as ImageStyle type

Using the processHtml argument which has ProcessHtmlInput type for a form item of type HtmlArea or for TextComponent field you can specify imageWidths to generate relevant links for specific widths of an image. In this case srcset attribute will be added to img tags.

For instance, when using the following fragment of query:

htmlAreaField(processHtml: { imageWidths: [600, 992] }){
    processedHtml
    images {
      ref
    }
}

The result will look as follows:

<figure class="editor-align-justify">
    <img alt="Alt text"
         src="/site/repo/branch/appName/_/image/contentID/width-768/imageName.jpg"
         data-image-ref="4f2439ff-ecef-4470-a4b4-d8929bce6ee2"
         srcset="/site/repo/branch/appName/_/image/contentID/width-600/imageName.jpg 600w,
                 /site/repo/branch/appName/_/image/contentID/width-992/imageName.jpg 992w"/>
    <figcaption>Caption text</figcaption>
</figure>

Macros

Each macro will be translated to an editor-macro tag with data-macro-ref and data-macro-name attributes in the processedHtml field value. Using these references you will be able to find details of a specific macro in the macrosAsJson or macros fields and perform custom macro processing if needed.

Guillotine processes macros which have a descriptor and built-in macros called disable and embed, otherwise processing will be skipped. More details about macros here.

For instance, we have an input form item called description of HtmlArea type which contains the embed macro as shown below:

Embed Macro

The query below will fetch data for the description field:

query {
  guillotine {
    get(key: "contentID") {
      ... on com_app_example_ContentType {
        data {
          description {
            raw            // (1)
            processedHtml  // (2)
            macrosAsJson   // (3)
            macros {       // (4)
              ref
              name
              descriptor
              config {
                embed {
                  body
                }
              }
            }
          }
        }
      }
    }
  }
}
1 Non-processed value of the description field
2 Processed value of the description field
3 Array of processed macros in JSON format. The order of macros will be the same as in the raw and processedHtml fields.
4 Macro allows to specify necessary fields. That field is an alternative for macroAsJson field

Results of the query:

Response for embed macro

It is common to define a schema for your macro. This is located in the /site/macros/ directory. For instance, for a macro with name testmacro the schema must be placed at /site/macros/testmacro/testmacro.xml

<macro>
  <display-name>Current user</display-name>
  <description>Shows currently logged user</description>
  <form>
    <input name="defaulttext" type="TextLine">
      <label>Text to show if no user logged in</label>
    </input>
  </form>
</macro>

Custom Macro

Executing the query below will give your value of the defaultText input, as defined in the above schema.

query {
  guillotine {
    get(key: "contentID") {
      ... on com_app_example_ContentType {
        data {
          description {
            macros {
              ref
              name
              descriptor
              config {
                testmacro {
                  defaultText
                }
              }
            }
          }
        }
      }
    }
  }
}

Contents