The editor is a powerful and versatile component of KendoReact, making it easy to add and format text and other HTML content. Learn how to use and customize it in your React apps.
The Editor component in KendoReact is a full-featured, highly customizable WYSIWYG rich text editor that can be integrated wherever you need to provide HTML editing (CMS, forums, ticketing systems, mail clients, chat clients, etc). It enables users to input free-form text, apply a large spectrum of formatting options, and insert HTML content such as images, tables, and hyperlinks.
The Editor offers a large set of built-in tools. You can also add custom tools, change the rendering of all the editor's elements (custom rendering) and extend the built-in functionality by adding plugins. The Editor, like all other components in the KendoReact UI library, is built in TypeScript.
In this blog post, I will show you how to use the Editor, and we will go through:
- Getting Started with the KendoReact Editor
- How to Customize the React Text Editor's Built-In Tools
- How to Implement Custom Tools into the KendoReact Editor
- Why Sanitize Pasted Content?
Getting Started with the KendoReact Editor
First, you need to import the Editor
component and EditorTools
module from the package, @progress/kendo-react-editor. Then, get the needed tools from EditorTools
and pass them into the tools
prop of the Editor. Setting initial content happens through the defaultContent
prop. Getting content from the Editor
or setting new content happens using the helper getHtml()
and setHtml()
functions exported by the EditorUtils
module.
Up to this point, you don't need to know how the Editor manages its content or how the tools work. If your project requires customization or needs the Editor's functionality to be extended though, keep reading as we dive into the different ways you can customize or extend the functionality of the Editor.
How to Customize the React Text Editor's Built-In Tools
There are two ways for customizing this editor's built-in tools:
- Using the Editor's utility functions for generating tools
- Wrapping the tool into a higher-order component (HOC) function, through which to add the new props you need
Using the Editor's Utility Functions for Generating Tools
All the Editor's tools are React components and are generated by a corresponding HOC function. Each tool also has a settings object which is being passed to its generation function as a parameter. The Editor package exports both the functions and the settings needed for tool generation. For example, the Bold tool has been created in the following way:
import { EditorToolsSettings, EditorTools } from '@progress/kendo-react-editor';
const BoldTool = EditorTools.createInlineFormatTool(EditorToolsSettings.bold);
Passing a modified version of EditorToolsSettings.bold
to EditorTools.createInlineFormatTool()
will create a custom tool. Here's how the default settings of the Bold tool look:
const boldSettings = {
mark: 'strong', // toggle the 'STRONG' tag
altMarks: ['b'], // recognize the 'B' tag also as Bold
// recognize an inline node with font-weight style and a
// value matching the regular expression
altStyle: { name: 'font-weight', value: /^(bold(er)?|[5-9]\d{2,})$/ },
// props which will be passed to the Button component of the tool
props: {
icon: 'bold',
type: 'button'
}
};
// The messages keys used by the tool for localization. See
// also https://www.telerik.com/kendo-react-ui/components/editor/globalization/#toc-messages
{
messages: {
title: 'editor.bold'
},
// the name of the command that the tool executes
commandName: 'Bold'
};
This approach allows you to easily modify the appearance and behavior of the tools without having to learn in-depth how the whole component is built. Follow this link for a full list of settings and functions for Editor tool generation.
Wrapping the Tool into a HOC
The HOC will extend the props of the desired tool and return the custom tool. Then add the HOC function into your tools collection. Simple as that:
const CustomBold = (props) => {
return (
<Bold
{...props}
title="Custom Bold"
/>
);
};
<Editor
tools={[
[CustomBold, /* ... */]
]}
<!-- ... -->
/>
Currently, the props of all tools extend the KendoReact Button and DropDownList props. In our case, the props that are available for our custom tool are listed in the ButtonProps interface. In other words, when it comes to customizing the tools, you can also configure everything that the KendoReact Button or DropDownList allows.
How to Implement Custom Tools into the KendoReact Editor
The above approach for customizing built-in tools can also be used for generating new tools. For example, if we take the Bold tool settings and change the mark
to 'code'
, props.icon
to 'code-snippet'
, and remove altMarks
and altStyle
fields, we can generate an entirely different tool that will toggle the <code>
element.
const codeSnippetSettings = {
mark: 'code', // toggle the 'code' tag
props: {
icon: 'code-snippet',
type: 'button'
},
messages: {},
commandName: 'Code'
};
const CodeTool = EditorTools.createInlineFormatTool(codeSnippetSettings);
The Editor's package also exports all the functionality that is used from the built-in tools, which includes functions for formatting, inserting content and others. This allows you to create your own tools for which the foundations have been already laid out (i.e. how to insert HTML content or apply formatting).
Here is an example of our custom code tool and a few more tools for formatting and inserting content:
Why Sanitize Pasted Content?
Pasted HTML content could look quite ugly, especially if copied from MS Word. Lists are presented as styled paragraphs, and content could contain invalid HTML styles, comments and XML strings.
In our experience, people are not always happy with the built-in paste functionality. They often have project-specific requirements, which need to be handled externally. For this reason, we have decided to move the format-stripping functionality outside of the Editor, so everyone can play with the code and edit it as needed.
Theming
As with all KendoReact UI components for React, the Editor can also be styled in all three out-of-the-box themes: Bootstrap theme, Material, and our own Default theme. If you are working within your own design system/theme, you can easily customize the Editor's styling using CSS or create your own theme using the KendoReact ThemeBuilder.
Under the Hood
For the Editor, we have decided to use an external engine instead of implementing our own from scratch. Since HTML editing has been here for a while, currently there are a lot of available engines to work with, and there is no value added in starting an Editor from scratch. After evaluating the available options, we decided that the ProseMirror toolkit is the right choice for our use case. It is very powerful and written in pure JavaScript.
The Editor in KendoReact is a versatile WYSIWYG rich text editor whose functionality can be customized or extended to meet any project requirements. Built specifically for React, it is as fast and lightweight as the framework itself and can save you a lot of development time.
Top comments (0)