Configuring Rich Text Editor

As a complex widget, Rich Text Editor consists of many stand-alone Webix views with their own API.
You canredefine inner views and also you can work with the specific Rich Text Editor settings.

You can use the following settings to provide the basic configuration of the widget:

• value (string) - sets the content to be displayed in the editor on its initialization. The value is set using the HTML format, which is the default format.If you want to set the value using another format (text), use the built-insetValue() method instead

• upload (string) - the link to the URL ofthe Upload serviceused for uploading and storing images inserted into the text.This property has to be specified if you want for the image insertion functionality to work correctly. It is not defined by default

• layoutMode (string) - the mode of displaying editor layout. There are two available layout modes: "classic" and "document".

  • The "classic" mode represents the edit area that fits the entire page.
  • The "document" mode represents real document sizes (the used sizes are: A4, A5, A6, A7 - depending on the available container width)

• fullscreen (boolean) - defines whether the editor is displayed in the fullscreen mode,false by default

• menubar (boolean,object,array) - defines whether the default menubar is shown or specifies themenubar configuration,false by default

• contextMenu (boolean,array) - defines whether the default context menu is shown or specifies thecontext menu configuration,false by default

• toolbar (boolean,object,array) - defines whether the default toolbar is shown or specifies thetoolbar configuration,true by default (provides the initial set of controls)

• compact (boolean) - defines whether the editor is rendered in the compact mode

• compactWidth (number) - defines the width at which the widget is switched to the compact mode,700 by default

• datatype (string) - defines the data format of the initial value of Rich Text Editor, as well as specifies the default format that will be used for thegetValue()/setValue() calls

webix.ui({    view:"editor",    value:"<p>Hello World!</p>",    layoutMode:"document",    menubar:true,    upload:"https://docs.webix.com/richtext-backend/images"});

Related sample: Rich Text Editor: Basic Configuration

By default, Rich Text Editor is initialized with the initial set of toolbar buttons. You can redefine the configuration of the toolbar in one of the ways described below.Check the full code of Toolbar buttons and button groups configuration.

Rendering particular toolbar buttons

To use the default toolbar buttons, specify anarray that contains the names of the necessary buttons as a value of thetoolbar property. For example:

webix.ui({    type:"space",    cols:[{            view:"editor",            toolbar:["bold","italic","strike","separator","link"],},],});

Related sample: Rich Text Editor: Simplified Toolbar

Setting custom toolbar configuration

To specify a custom toolbar configuration, set thetoolbar property as anarray that can contain both strings with thedefault button names and objects with custom buttons' configurations. For example:

webix.ui({    view:"editor",    toolbar:["bold","italic","separator",{            view:"button",            width:100,            label:"Button",            click:()=>{                webix.message("Some action");},},],});

Related sample: Rich Text Editor: Custom Control in Toolbar

Setting groups of buttons

You can provide groups of toolbar buttons by specifying them as properties of thetoolbarobject in the following way:

• enabling thedefault groups of buttons
• defining which buttons of the default group should be displayed by setting a group as an array with necessary button names
• provide custom button groups by setting a custom group as an array with either default or custom buttons

For example:

webix.ui({    view:"editor",    toolbar:{// the default "history" group of buttons is enabled        history:true,// certain buttons are specified for the "align" group        align:["align-left","align-center","align-right"],// a custom group is set as a mix of a default and a custom buttons"custom-group":["clear",{                view:"button",                width:100,                value:"Button",                click:()=> webix.message("action"),}]}});

By default, the menubar is disabled in the Rich Text Editor widget.You can enable the default menubar or redefine the configuration of the menubar in one of the ways provided below.Check the full code of Menu items and button groups configuration.

Setting the default menubar

To use the default set of menu options, specify themenubar property and set its value totrue.

webix.ui({    view:"editor",    value:"<p>Hello World!</p>",    menubar:true,             upload:"https://docs.webix.com/richtext-backend/images"});

Related sample: Rich Text Editor: Menubar

Setting custom menubar configuration

You can set a custom menubar configuration by specifying themenubar property either as anarray or as anobject with both the default and custom options. Note:

• to set a default menu option (with the default sub-options), it is enough to specify its id
• to handle clicks on custom menu options, use theonMenuItemClick event

Specifying the menubar as an array

This way allows specifying the menubar with both the default and custom options and/or sub-options.

The menu options can be set as strings (for existing options) or objects. When set as objects, they may contain the following properties:

• theid of a default or custom menu option
• thevalue of the option
• thedata array with the sub-options that should be rendered for the specified menu option. Sub-options use the same object structure as regular menubar options, allowing for nesting as needed.

For example:

webix.ui({    view:"editor",    value:"<p>Some text</p>",    menubar:[// sets the default "File" menu option"file",// sets the default "Format" menu option{                                                                   id:"format"},// sets the default "Edit" menu option with certain default sub-options{                                                                   id:"edit",             data:[{ id:"undo"},{ id:"redo"}]},// sets the default "View" menu option with a default and a custom sub-options{                                                                   id:"view",                                                     data:[{ id:"mode"},{ id:"view-option", value:"View option"}]},// sets a custom menu option with two sub-options{                                                                   id:"option",            value:"Some option",            data:[{ id:"option-1", value:"Option 1"},{ id:"option-2", value:"Option 2"}]}],              on:{        onMenuItemClick(id){            webix.message(id);}},                                                  upload:"https://docs.webix.com/richtext-backend/images"});

Specifying the menubar as an object

This approach also allows specifying default and custom options and/or sub-options in the menubar, butin a bit different way. Each menu option is set as akey:value pair, where:

• key - the id of a default or custom option
• value - either aboolean value to enable the default menu option with default sub-options,
  or anobject with the option's settings that may contain:
  • value - the value of the option
  • data - an array with the sub-options that should be rendered for the specified menu option. Sub-options use the same object structure as regular menubar options, allowing for nesting as needed

webix.ui({    view:"editor",    value:"<p>Some text</p>",    menubar:{// sets the default "File" menu option        file:true,// sets the default "Edit" menu option with certain default sub-options        edit:{            data:[{ id:"undo"},{ id:"redo"}]},// sets the default "View" menu option with a default and a custom sub-options        view:{                                                     data:[{ id:"mode"},{ id:"view-option", value:"View option"}]},// sets a custom menu option with two sub-options        option:{            value:"Some option",            data:[{ id:"option-1", value:"Option 1"},{ id:"option-2", value:"Option 2"},],},},    on:{        onMenuItemClick(id){            webix.message(id);}},    upload:"https://docs.webix.com/richtext-backend/images"});

Related sample: Rich Text Editor: Custom Options in Menubar

By default, the context menu is disabled in the Rich Text Editor widget.You can enable the default context menu or redefine its configuration.Check the full code of Context Menu configuration.

Setting the default context menu

To add the default context menu into the Rich Text Editor, set the value of thecontextMenu property totrue.

webix.ui({    view:"editor",    value:"<p>Some text</p>",    contextMenu:true,    upload:"https://docs.webix.com/editor-backend/images"});

Thedefault context menu includes the following groups of actions: "clipboard", "format", and "insert".

Setting custom configuration for context menu

You can set a custom context menu configuration to render both the default, customized and custom options by using thecontextMenu property as anarray. Note:

• to set a default context menu option, it is enough to specify its id
• to handle clicks on custom context menu options, use theonContextMenuItemClick event

The options can be set asstrings (ids of existing options) orobjects. When set as objects, they may contain the following properties:

• id - required, the id of a default or custom menu option
• value - the value of the option, optional for default options, required for custom options
• icon - optional, the icon of the option, will be added to a default option by its id
• hotkey - optional, the hotkey of the option, will be added to a default option by its id
• data - optional, an array with sub-options that can be used to add sub-menus

For example:

webix.ui({  view:"editor",  value:"<p>Some text</p>",  contextMenu:[// default options from Context Menu"bold","italic",{ $template:"Separator"},// options that exist in Editor's menu; labels are modified{      id:"docx",      value:"Export to DOCX",       icon:"rti-document"},{         id:"print",       value:"Print",       icon:"rti-print"},// a custom option that can be handled in onContextMenuItemClick{      id:"print-selection",       value:"Print selection",      icon:"rti-print"},],  on:{    onContextMenuItemClick(id){      webix.message(id);}},                                                  upload:"https://docs.webix.com/richtext-backend/images"});

ThelayoutMode,fullscreen,menubar,toolbar andcontextMenu properties are also accessible asreactive via the widget state. They store global app state and let developers track its changes. Any change of a reactive property is immediately reflected in the widget.

Apart from these properties there are several others:

• activeStyles (object) - stores the styles under the current cursor's position. The default value is{}

• selectedImage (null,object) - the object of the selected image,null by default. Contains the following fields:

  • id (number,string) - the id of the selected image
  • node (object) - the object of the selected image

• editImage (null,object) - stores the image options while the editor is open. The default value isnull. The image editing object can contain the following options:

  • id - the id of the image
  • width - the width of the image
  • height - the height of the image
  • src - the image source path
  • alt - an alternate text for the image, if it isn't displayed

• paintMode (object) - the object with the current state of the paint mode. Contains the following fields:

  • enabled (boolean) - enables/disables the paint mode
  • continuous (boolean) - defines whether the continuous paint mode is enabled
    The possible values of thepaintMode property are:
    • { enabled: true, continuous: false } - the ordinary paint mode is on
    • { enabled: false, continuous: true } - the continuous mode is on, the paint mode is off
    • { enabled: true, continuous: true } - the continuous paint mode is on
    • { enabled: false, continuous: false } - the paint mode is off

You can get the current state of the widget with the help of thegetState() method:

webix.ui({    view:"editor",     id:"editor",    value:"<p>Some text</p>"}); const state= $$("editor").getState(); /*    {        activeStyles: {bold: true, tag: "p"},        editImage: null,        fullscreen: false,        layoutMode: "classic",        menubar: false,         paintMode: {             enabled: true,             continuous: true         },        toolbar: true,        selectedImage: null    }*/

You can use the$observe handler to listen to changes and provide custom handlers for them:

const state= $$("editor").getState();state.$observe("layoutMode", v=> webix.message(`Layout mode: ${v}`));state.layoutMode="document";

Related sample: Rich Text Editor: State Observer

In the sample above, the currentstate is accessed viaJetAppinstance which is available in theonInit event handler.