Skip to content

webcomponent-tech-ref.adoc

Latest commit

 

History

History
635 lines (472 loc) · 23.6 KB

webcomponent-tech-ref.adoc

File metadata and controls

635 lines (472 loc) · 23.6 KB

Covered in this section:

Use a cloud version of the TinyMCE Web Component integration

To use a cloud version of Web Component, the integration is accessible from JSDelivr.

For example:

<script src="{webcomponent_url}"></script>

Installing the TinyMCE Web Component integration

To add the {productname} Web Component integration to a JavaScript project, on command line or command prompt, run the following:

  • NPM users:

    npm i @tinymce/tinymce-webcomponent

  • Yarn users:

    yarn add @tinymce/tinymce-webcomponent

Loading TinyMCE

The integration requires both the {productname} Web Component (tinymce-webcomponent.min.js) and {productname} (tinymce.min.js).

If {productname} is not available for {productname} Web Component, the latest version of {productname} will be automatically loaded from the {cloudname}.

To use {productname} Web Component with a self-hosted copy of {productname}, ensure that the self-hosted copy of {productname} can be loaded in the same location as the {productname} Web Component (such as the same web page).

To use {productname} from the {cloudname}, add the api-key attribute to the tinymce-editor element with an API from {accountpage}.

Configuring the editor

The editor is configured by setting attributes on the tinymce-editor custom element. All attributes may be represented as strings, however some attributes will accept boolean or number inputs. Where an array, object, or function is a valid input; examples have been provided.

Setting the initial content

To set the initial editor content, add encoded HTML to the tinymce-editor element as content, such as:

<tinymce-editor>
  &lt;p&gt;This will be the initial content of the editor.&lt;/p&gt;
</tinymce-editor>

The editor will load the text content in the tinymce-editor element as the initial HTML.

Important
 The HTML must be encoded as text to prevent injected javascript from running, which may have an unintended impact on the surrounding document.

Loading plugins

To add plugins and extend the functionality of the editor, add a string of plugin identifiers using the plugins attribute, such as:

<tinymce-editor plugins="advlist autolink link image lists charmap preview"></tinymce-editor>

For information on plugins, see: Add plugins to {productname}.

Setting the editor width

To set the width of the editor (content area and user interface), use the width attribute. For example:

Setting a pixel-based editor width

<tinymce-editor width="300"></tinymce-editor>

Setting a CSS unit based editor width

<tinymce-editor width="50%"></tinymce-editor>

Setting the editor height

To set the height of the editor (content area and user interface), use the height attribute. For example:

Setting a pixel-based editor height

<tinymce-editor height="300"></tinymce-editor>

Setting a CSS unit based height

<tinymce-editor height="15em"></tinymce-editor>

Setting the toolbar

To set the editor toolbar buttons, use the toolbar attribute. For example:

<tinymce-editor toolbar="undo redo | styles | bold italic | alignleft aligncenter alignright alignjustify | outdent indent"></tinymce-editor>

The toolbar attribute accepts a space-separated string of toolbar buttons with pipe characters (|) for grouping buttons. For a list of available toolbar buttons, see: Toolbar Buttons Available for TinyMCE.

Disabling the toolbar

To disable the toolbar, set the toolbar attribute to "false". For example:

<tinymce-editor toolbar="false"></tinymce-editor>

Setting the toolbar mode

To control the behavior of the toolbar, set the toolbar_mode attribute. For example:

<tinymce-editor toolbar_mode="floating"></tinymce-editor>

For information on the available toolbar modes, see: User interface options - toolbar_mode.

Setting the menu bar

To set the menus shown on the editor menu bar, add the menubar attribute. For example:

<tinymce-editor menubar="file edit insert view format table tools help"></tinymce-editor>

To change the menu items shown in the menus, or define custom menus, set the menu configuration option using the config attribute.

For information on:

Setting context menu

To change the context menu sections that can be shown in the editor context menu, use the contextmenu attribute. Such as:

<tinymce-editor plugins="link image table" contextmenu="link image table"></tinymce-editor>

For a list of available context menu sections, see: Available context menu sections. For information on context menus, see: User interface options - contextmenu.

Setting the quick-insert toolbar

The quick-insert toolbar is shown when a new line is added, providing buttons for inserting objects such as tables and images.

To add a quick-insert toolbar, add "quickbars" to the plugins attribute. To change the quick-insert toolbar, set the quickbars_insert_toolbar attribute, such as:

<tinymce-editor plugins="quickbars pagebreak" quickbars_insert_toolbar="quickimage quicktable quicklink | hr pagebreak"></tinymce-editor>

The quickbars_insert_toolbar attribute accepts a space-separated string of toolbar buttons with pipe characters (|) for grouping buttons. For a list of available toolbar buttons, see: Toolbar Buttons Available for TinyMCE.

To disable the quick-insert toolbar, set the quickbars_insert_toolbar attribute to "false". For example:

<tinymce-editor plugins="quickbars" quickbars_insert_toolbar="false"></tinymce-editor>

Setting the quick-selection toolbar

The quick-selection toolbar is shown when text is selected, providing formatting buttons such as: bold, italic, and link.

To add a quick-selection toolbar, add "quickbars" to the plugins attribute. To change the quick-selection toolbar, set the quickbars_selection_toolbar attribute, such as:

<tinymce-editor plugins="quickbars" quickbars_selection_toolbar="bold italic | blocks | quicklink blockquote"></tinymce-editor>

The quickbars_selection_toolbar attribute accepts a space-separated string of toolbar buttons with pipe characters (|) for grouping buttons. For a list of available toolbar buttons, see: Toolbar Buttons Available for TinyMCE.

To disable the quick-selection toolbar, set the quickbars_selection_toolbar attribute to "false". For example:

<tinymce-editor plugins="quickbars" quickbars_selection_toolbar="false"></tinymce-editor>

Setting content stylesheets

To set the CSS for the content area of the editor, use the content_css attribute.

For example, to use one of the {productname} CSS configurations:

<tinymce-editor content_css="writer"></tinymce-editor>

To use a custom CSS file, provide a relative or abolute path to the css file, such as:

<tinymce-editor content_css="path/to/mycontent.css"></tinymce-editor>

{companyname} recommends using:

  • The content_style option to apply a small set of CSS styles.

  • The content_css option for applying large or complex CSS configurations.

For information on the content_css option, see: Content appearance options - content_css.

Setting content styling

To apply a small set of CSS styles to the editor, use the content_style attribute. For example:

<tinymce-editor content_style="div { margin: 10px; border: 5px solid red; padding: 3px; }"></tinymce-editor>

{companyname} recommends using:

  • The content_style option to apply a small set of CSS styles.

  • The content_css option for applying large or complex CSS configurations.

For information on the content_style option, see: Content appearance options - content_style.

Settings for when PowerPaste plugin enabled

Note
 These settings only apply if the PowerPaste plugin (powerpaste) is enabled.

PowerPaste’s word import method

To control how content pasted from Microsoft Word is filtered, use the powerpaste_word_import attribute. For example:

<tinymce-editor powerpaste_word_import="merge"></tinymce-editor>

For information on the powerpaste_word_import option, including supported values, see: The PowerPaste plugin - powerpaste_word_import.

PowerPaste’s html import method

To control how content pasted from sources other than Microsoft Word is filtered, use the powerpaste_html_import attribute. For example:

<tinymce-editor powerpaste_html_import="prompt"></tinymce-editor>

For information on the powerpaste_html_import option, including supported values, see: The PowerPaste plugin - powerpaste_html_import.

PowerPaste to allow local images

To prevent Base64 encoded images with a data URI from being pasted into the editor, set powerpaste_allow_local_images to "false". For example:

<tinymce-editor powerpaste_allow_local_images="false"></tinymce-editor>

For information on the powerpaste_allow_local_images option, including supported values, see: The PowerPaste plugin - powerpaste_allow_local_images.

Showing resize handles

The resize attribute gives you the ability to disable the resize handle or set it to resize the editor both horizontal and vertically. By default the editor will resize vertically (resize="true").

To remove the resize handle and disable resizing of the editor, set the resize attribute to "false". Such as:

<tinymce-editor resize="false"></tinymce-editor>

To allow the user to resize the editor both horizontally and vertically, set the resize attribute to "both". For example:

<tinymce-editor resize="both"></tinymce-editor>

For information on the resize option, see: User interface options - resize.

Setting the editor setup function

To execute a javascript callback before the editor instance is rendered, use the setup attribute. For example:

<script>
  function setupEditor(editor) {
    editor.on('click', function () {
      console.log('Editor was clicked');
    });
  }
</script>
<tinymce-editor setup="setupEditor"></tinymce-editor>

For information on the setup option, see: Integration and setup options - setup.

Setting the editor skin

To apply a custom skin to the editor, use the skin attribute. For example:

<tinymce-editor skin="borderless"></tinymce-editor>

For information on:

Setting the images upload URL

To specify the location of a server-side upload handler, use the images_upload_url attribute. For example:

<tinymce-editor images_upload_url="postAcceptor.php"></tinymce-editor>

The upload handler should return the location of the uploaded file in the following format:

{ "location": "folder/sub-folder/new-location.png" }

For information on using the images_upload_url, see: Image uploads - images_upload_url.

Setting the images upload handler

To specify custom image upload handler callback function, use the images_upload_handler attribute.

<script>
link:example$misc/images-upload-handler-function.js[role=include]
</script>
<tinymce-editor images_upload_handler="example_image_upload_handler"></tinymce-editor>

For information on using the images_upload_handler option, see: Image uploads - images_upload_handler.

Setting the images upload base path

To specify the basepath to prepend to URLs returned from the configured images_upload_url script, use the images_upload_base_path attribute. For example:

<tinymce-editor images_upload_url="postAcceptor.php" images_upload_base_path="/some/basepath"></tinymce-editor>

For information on using the images_upload_base_path option, see: Image uploads - images_upload_base_path.

Setting the images upload to have credentials

To receive credentials (such as cookies, authorization headers, or TLS client certificates) for cross-domain image uploads, set the images_upload_credentials attribute to "true".

<tinymce-editor images_upload_url="postAcceptor.php" images_upload_credentials="true"></tinymce-editor>

For information on using the images_upload_credentials option, see: Image uploads - images_upload_credentials.

Setting the images upload to reuse filenames

To force the editor to use the same filename for a given image, regardless of the number of times it is uploaded within a given instance, set the images_reuse_filename attribute to "true".

<tinymce-editor images_upload_url="postAcceptor.php" images_reuse_filename="true"></tinymce-editor>

For information on using the images_reuse_filename option, see: Image uploads - images_reuse_filename.

Setting the icon pack

To apply a bundled set of custom or premium icons to the editor, use the icons attribute. For example:

<tinymce-editor icons="material"></tinymce-editor>

Use this attribute if the icon pack is bundled with {productname} (including custom icon packs). If the icon pack is hosted on a web site, use the icons_url attribute.

For information on:

Setting the icon pack URL

To apply a hosted set of custom or premium icons to the editor, use the icons_url attribute. For example:

<tinymce-editor icons_url="https://www.example.com/icons/material/icons.js"></tinymce-editor>

Use this attribute if the icon pack is hosted on a web site. If the icon pack is bundled with {productname} (including custom icon packs), use the icons attribute.

For information on:

Setting additional configuration options

To configure any {productname} option that does not have a corresponding attribute, use the config attribute. For example:

<script>
  window.myConfig = {
    height: 500,
    spellchecker_dialog: true,
    spellchecker_ignore_list: ['Ephox', 'Moxiecode']
  };
</script>
<tinymce-editor
  config="myConfig"
  width="50%"
  toolbar="undo redo | bold italic | forecolor backcolor | alignleft aligncenter alignright alignjustify | bullist numlist | link | spellchecker"
  plugins="lists link searchreplace table tinymcespellchecker wordcount"
></tinymce-editor>

Configuration options that have an attribute can also be passed to the config attribute.

Event binding

There are two methods to bind events for the TinyMCE Web Component.

  • The setup attribute, as described in Setting the editor setup function. For example:

    <script>
  function setupEditor(editor) {
    editor.on('click', function () {
      console.log('Editor was clicked');
    });
  }
</script>
<tinymce-editor setup="setupEditor"/>

  • The on- attributes, such as the on-NodeChange attribute. For example:

    <script>
  function changeHandler(evt) {
    console.log('The ' + evt['type'] + ' event was fired.');
  }
</script>
<tinymce-editor on-Change="changeHandler"/>

    If these attributes are later removed, the event will be automatically unbound. For the full list of supported on- attributes, see: Supported browser events and Supported TinyMCE events.

Supported browser events

Bind the following browser events using the corresponding {productname} Web Component attribute.

Browser event Attribute

BeforePaste

on-BeforePaste

Blur

on-Blur

Click

on-Click

ContextMenu

on-ContextMenu

Copy

on-Copy

Cut

on-Cut

Dblclick

on-Dblclick

Drag

on-Drag

DragDrop

on-DragDrop

DragEnd

on-DragEnd

DragGesture

on-DragGesture

DragOver

on-DragOver

Drop

on-Drop

Focus

on-Focus

FocusIn

on-FocusIn

FocusOut

on-FocusOut

KeyDown

on-KeyDown

KeyPress

on-KeyPress

KeyUp

on-KeyUp

MouseDown

on-MouseDown

MouseEnter

on-MouseEnter

MouseLeave

on-MouseLeave

MouseMove

on-MouseMove

MouseOut

on-MouseOut

MouseOver

on-MouseOver

MouseUp

on-MouseUp

Paste

on-Paste

SelectionChange

on-SelectionChange

Supported TinyMCE events

Bind the following {productname} events using the corresponding {productname} Web Component attribute.

{productname} event Attribute

Activate

on-Activate

AddUndo

on-AddUndo

BeforeAddUndo

on-BeforeAddUndo

BeforeExecCommand

on-BeforeExecCommand

BeforeGetContent

on-BeforeGetContent

BeforeRenderUI

on-BeforeRenderUI

BeforeSetContent

on-BeforeSetContent

Change

on-Change

ClearUndos

on-ClearUndos

Deactivate

on-Deactivate

Dirty

on-Dirty

ExecCommand

on-ExecCommand

GetContent

on-GetContent

Hide

on-Hide

Init

on-Init

LoadContent

on-LoadContent

NodeChange

on-NodeChange

PostProcess

on-PostProcess

PostRender

on-PostRender

PreProcess

on-PreProcess

ProgressState

on-ProgressState

Redo

on-Redo

Remove

on-Remove

Reset

on-Reset

SaveContent

on-SaveContent

SetAttrib

on-SetAttrib

ObjectResizeStart

on-ObjectResizeStart

ObjectResized

on-ObjectResized

ObjectSelected

on-ObjectSelected

SetContent

on-SetContent

Show

on-Show

Submit

on-Submit

Undo

on-Undo

VisualAid

on-VisualAid