CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

MergeFieldsConfig (merge-fields)

@ckeditor/ckeditor5-merge-fields/src/mergefieldsconfig

interface

The configuration of the merge fields feature.

The properties defined in this config are set in the config.mergeFields namespace.

ClassicEditor
	.create( editorElement, {
		mergeFields: {
			// Merge fields configuration.
		}
	} )
	.then( ... )
	.catch( ... );

See all editor options.

Filtering

Properties

  • dataSets : Array<DataSetDefinition> | undefined

    The data sets that can be displayed in place of the merge fields in the editor.

    Defaults to []

  • definitions : Array<GroupDefinition | MergeFieldDefinition> | undefined

    The definitions of the merge fields that can be used in the editor. It's allowed to define them in any combination of groups and individual merge fields. The order of the definitions is respected when displaying the merge fields in the UI dropdown except that merge fields that are not assigned to any group are displayed at the very bottom of the list.

  • initialPreviewMode : string | undefined

    A name of the preview mode that should be active when the editor is initialized. Possible values are:

    • '$labels' - displays the labels of the merge fields,
    • '$defaultValues' - displays the default values,
    • one of the configured data sets identifiers.

    If not set, it will default to the one of the available preview modes, with the priority as in the list above.

  • prefix : string | undefined

    A prefix used to identify merge fields in the editor data.

    The list of allowed characters includes: '"`!#%:;=@{}~$()*+/?[\]^|.

    Defaults to '{{'

  • previewHtmlValues : boolean | undefined

    A flag indicating whether the feature preview mode should interpret merge fields data set values and default values as HTML strings and render them as HTML.

    When set to true, the merge field value will be interpreted and rendered as HTML. For example, '<img src="image.jpg" />' merge field value will be previewed as the image located at given src.

    When set to false, the merge field value will be interpreted as a regular text. For example, '<img src="image.jpg" />' will be displayed exactly as defined, meaning that text <img src="image.jpg" /> will be displayed instead of an image.

    By default, it is set to false.

    Read more about the security of previewing merge fields HTML values in the Merge fields feature documentation.

    Defaults to false

  • previewModes : Array<string> | undefined

    Determines the available preview modes in the dropdown and menu bar. Possible values are:

    • '$labels' - adds the option to display the labels of the merge fields.
    • '$defaultValues' - adds the option to display the default values.
    • '$dataSets' - adds the options to display each of the configured data sets.

    At least one mode must be enabled. If more than one preview mode is configured, you can add previewMergeFields button to the toolbar to switch between them, and the menu bar button will be added automatically to the View category.

    Defaults to [ '$labels', '$defaultValues', '$dataSets' ]

  • sanitizeHtml : ( string ) => MergeFieldsSanitizeOutput | undefined

    Callback used to sanitize the HTML used in merge fields values when they are previewed inside the editor.

    We strongly recommend overwriting the default function to avoid XSS vulnerabilities.

    Read more about the security aspect of this feature in Merge fields feature documentation.

    The function receives the input HTML (as a string), and should return an object that matches the MergeFieldsSanitizeOutput interface.

    ClassicEditor
  .create( editorElement, {
    mergeFields: {
      previewHtmlValues: true,
      sanitizeHtml( inputHtml ) {
        // Strip unsafe elements and attributes, e.g.:
        // the `<script>` elements and `on*` attributes.
        const outputHtml = sanitize( inputHtml );

        return {
          html: outputHtml,
          // true or false depending on whether the sanitizer stripped anything.
          hasChanged: ...
        };
      },
    }
  } )
  .then( ... )
  .catch( ... );

    Note: The function is used only when the feature is configured to render previews.

  • suffix : string | undefined

    A suffix used to identify merge fields in the editor data.

    The list of allowed characters includes: '"`!#%:;=@{}~$()*+/?[\]^|.

    Defaults to '}}'