Installation

# Automatic integration with HTML forms

This is the classic way of integrating the editor. It is typically used in simpler CMSes, forums, comment sections, etc.

This approach is only available in the and only if the editor was used to replace a element:

Classic editor will automatically update the value of the element once the user submits the form. You do not need any additional JavaScript code to send the editor data to the server.

In your HTTP server, you can now read the editor data from the variable of the POST request. For instance, in PHP, you can get it in this way:

Please note that the replaced element is updated automatically by CKEditor straight before the submission. If you need to access the value programatically with JavaScript (e.g. in the handler to validate the entered data), there is a chance that the element would still store the original data. In order to update the value of the replaced , use the method.

If you need to get the actual data from CKEditor at any moment using JavaScript, use the method as described in the next section.

When you print the data from the database to a element in an HTML page, you need to encode it correctly. For instance, if you use PHP then a minimal solution would look like this:

Thanks to that, the will be printed out like this:

Instead of being printed like this:

While simple content like mentioned above does not itself require to be encoded, encoding the data will prevent losing text like “<” or “<img>”.

# Why does the editor filter out my content (styles, classes, elements)? Where is config.allowedContent = true?

Unlike CKEditor 4, CKEditor 5 implements a custom data model. This means that every piece of content that is loaded into the editor needs to be converted to that model and then rendered back to the view.

Each kind of content must be handled by some feature. For instance the package handles HTML elements such as , , , etc. along with their representation in the model. The feature defines the two–way conversion between the HTML (view) and the editor model.

If you load some content unknown to any editor feature, it will be dropped. If you want all the HTML5 elements to be supported, you need to write plugins to support them. Once you do that, CKEditor 5 will not filter anything out.

# Demo

Image upload only

This demo shows the integration where the file manager’s server connector handles only:

  • Paste the image directly into the rich-text editor content and it will be automatically uploaded using the server-side connector.
  • Use the “Insert image” button in the toolbar to insert an image.

Use the toolbar button to insert an image.

Full integration

This demo shows the with the CKFinder file uploader:

  • Paste the image directly into the rich-text editor content and it will be automatically uploaded using the server-side connector.
  • Use the “Insert image or file” button in the toolbar to open the CKFinder file manager and insert an image or a link to any other file.

Use the toolbar button to open the CKFinder file manager. Use the file manager’s interface to insert an image or a link to a file.

# Collaborative editing

Another important benefit of the custom data model is that it enables the possibility of real-time collaborative editing inside CKEditor by introducing the concepts of “operations” and “operational transformations”.

With collaboration services provided by CKEditor Cloud Services it is now extremely easy to provide collaboration features inside your application.

Check the collaboration demo and read how to enable features such as comments, user presence list or showing the selection of other users in your editor.

Letters is an example of an application using the power of CKEditor 5 for collaboration.

# Where are the editor.insertHtml() and editor.insertText() methods? How to insert some content?

Because CKEditor 5 uses a custom data model, whenever you want to insert anything, you should modify the model first, which is then converted back to the view where the users input their content (called “editable”). In CKEditor 5, HTML is just one of many possible output formats. You can learn more about the ways of changing the model in the .

To insert a new link at the current position, use the following snippet:

And to insert some plain text, you can use a slightly shorter one:

You may have noticed that a link is represented as a text with an attribute in the editor model. See the API of the model writer to learn about other useful methods that can help you modify the editor model.

To insert some longer HTML code, you can parse it to the model fragment first and then it into the editor model:

# Custom link attributes (decorators)

By default, all links created in the editor have the attribute in the . If you want your links to have additional link attributes, provide an easy way to configure and manage them.

There are two types of link decorators you can use:

  • – They match links against pre–defined rules and manage their attributes based on the results.
  • – They allow users to control link attributes individually using the editor UI.

Link decorators are disabled by default and it takes a proper to enable them in your rich-text editor.

Demo

In the editor below, all external links get the and attributes (). Click a link and edit it to see that it is possible to control the attribute of specific links using the switch button in the editing balloon (). Take a look at the editor data below (updated live) to see the additional link attributes.

<p>
An <a href=»https://ckeditor.com»>external page</a> and a
<a download=»download» href=»image.png»>downloadable resource</a>.
</p>

The following code was used to run the editor. Learn more about the of the feature.

Configuration

Decorators are configured through definitions provided in the configuration option.

Each decorator definition must have its own unique name. In case of , that name also represents the decorator in the .

Link decorators work independently of one another and no conflict resolution mechanism exists. For example, configuring the attribute using both an automatic and a manual decorator at the same time could end up with quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.

Adding and attributes to external links

A very common use case for (automatic) link decorators is adding and attributes to all external links in the document. A dedicated configuration has been created for that purpose. When this option is set to , all links starting with , or are “decorated” with and attributes.

Internally, this configuration corresponds to an with the following definition:

If you want to leave the decision whether a link should open in a new tab to the users, do not use the configuration but define a new with the following definition instead:

Adding default link protocol to external links

A default link protocol can be useful when the user forgets to type the full URL address to an external source or website. Sometimes copying the text, like for example , and converting it to a link may cause some issues. As a result, the created link will direct you to because of the missing protocol. This makes the link relative to the site where it appears.

After you enable the configuration option, the link feature will be able to handle this issue for you. By default it does not fix the passed link value, but when you set to, for example, , the plugin will add the given protocol to every link that may need it (like , , etc. where is missing).

See a basic configuration example:

With the option enabled, you are still able to link things locally using or . The protocol will not be added to these links.

Adding attributes to links based on pre–defined rules (automatic decorators)

Automatic link decorators match all links in the editor content against a function which decides whether the link should receive some set of attributes, considering the URL () of the link. These decorators work silently and are being applied during the only.

For instance, to create an automatic decorator that adds the attribute to all links ending with the extension, you should add the following definition to :

If you want the and attributes to be added to all external links in your content, we prepared a exactly for that purpose so you do not have to define the automatic decorator by yourself.

Adding attributes to links using the UI (manual decorators)

Manual link decorators are represented in the link editing balloon as switch buttons that the users can use to control the presence of attributes of a particular link (check out the to learn more). Each manual decorator definition contains a human–readable label displayed next to the switch button in the link editing balloon. Make sure it is compact and precise for the convenience of the users.

To configure a “Downloadable” switch button in the link editing balloon that adds the attribute to the link when turned on, add the following definition to :

# Next Steps

Go ahead and play a bit more with the sample; try to change your configuration as suggested to customize it. And when you are ready to dive a bit deeper into CKEditor 4, you can try the following:

  1. Check the Setting Configuration article to see how to adjust the editor to your needs.
  2. Get familiar with Advanced Content Filter. This is a useful tool that adjusts the content inserted into CKEditor 4 to the features that are enabled and filters out disallowed content.
  3. Modify your toolbar to only include the features that you need. You can find the useful visual toolbar configurator directly in your editor sample.
  4. Learn about CKEditor 4 features in the Features Overview section.
  5. Visit the CKEditor 4 Examples to see the huge collection of working editor samples showcasing its features, with source code readily available to see and download.
  6. Browse the Add-ons Repository for some additional plugins or skins.
  7. Use online builder to create your custom CKEditor 4 build.
  8. Browse the Developer’s Guide for some further ideas on what to do with CKEditor 4 and join the CKEditor community at Stack Overflow to discuss all CKEditor things with fellow developers!

# Plugin Loading

It is now time to tell CKEditor 4 to load our plugin. To do so we have to add its name to the CKEDITOR.config.extraPlugins configuration option:

Please note that since CKEditor 4.1 all editor plugins that create content should be integrated with Advanced Content Filter (ACF). In this case the plugin only inserts content that is usually allowed in default editor installations (the element), but if you want to customize it and insert elements that are not allowed by the configuration, you need to either set in order to disable content filtering or integrate your plugin with ACF. For more information, please refer to the official Advanced Content Filter integration guide.

Now load a CKEditor 4 sample page. You should be able to see the new plugin button in the toolbar. For example:

Frequently asked questions

Under which open source licenses are CKEditor 4 and CKEditor 5 available?

CKEditor 4 is distributed under three copyleft Open Source license options: GPL, LGPL and MPL.

CKEditor 5 is distributed under a GPL 2+ copyleft license. For more details visit ckeditor.com/legal. Note, that if you are running an OSI approved project that is not compatible with GPL 2+ copyleft, find out more about our Free for Open Source offer: ckeditor.com/wysiwyg-editor-open-source/.

What are the benefits of being commercially licensed for CKEditor?

Compared to Open Source which comes with a multitude of obligations, the obvious advantage is a legal one: commercial licenses do not require you to share your source code with the public in any way. Also, commercial licenses come with another equally important advantage: support. Our support team can make sure that you understand and integrate the editor correctly, and will be there to help in case you run into a wall.

What is an Active User?

Active User is a person or bot that used our software at least once in a given billing period. For example, if you purchased a pool of 25 Active Users and in the middle of the billing period (be it annual or monthly) and 2 of your users are no longer active, you may allocate these 2 slots to 2 new users of your application.

What happens if I exceed my active user allowance?

If you exceed your active user allowance, simply contact us at sales@cksource.com to talk about upgrading your allowance or customizing your plan.

What is a product or internal application family?

A product (OEM or SaaS) or internal application family cannot be treated as one even under one suite of software solutions. Each product or internal application within your family supports your users in a different area of the business and shall be licensed separately. If you wish to embed the editor in a product or internal application family solution, please contact us.

What is a Developer?

A Developer is an employee or individual contractor designated by you to perform development activities (coding, configuring, code testing) with our products or to receive ongoing technical support.

What is the number of support requests per month?

The number of support requests per month is the total monthly allowance of support requests for the product bundle you purchased. The product bundle means any additional products you purchased with CKEditor (e.g. CKEditor and CKFinder, Accessibility Checker or CKEditor and Easy Image, etc.).

If you purchased CKEditor as a stand-alone product, the number of support requests per month refers only to the editor support.

What is the minimum length of subscription-based software licenses?

The minimum length of subscription-based license agreements for our software products (CKEditor, CKFinder, Accessibility Checker, Letters, CKEditor 5 Comments Plugin, CKEditor 5 Track Changes Plugin and CKEditor Cloud Services On-Premises) is 12 months regardless of which billing you choose (monthly or annual).

If you decide to terminate your subscription of CKEditor, CKFinder, Accessibility Checker, Letters, CKEditor 5 Comments Plugin, CKEditor 5 Track Changes Plugin and CKEditor Cloud Services On-Premises, you are obliged to immediately remove our software completely from your or your clients’ servers. That means that upon your cancellation you’re not allowed to distribute or commercialize our software as part of your Product or provide access to it via your Internal Application.

What is the minimum length of CKEditor Cloud Services subscriptions?

The minimum length of CKEditor Cloud Services subscription is one month. If you are interested in a much longer contract (such as 2 or 3 years), we are open to negotiate the price.

# Configuration options compatibility table

The following table presents configuration options available in CKEditor 4 and their equivalent in CKEditor 5.

Note: The number of options was reduced on purpose. We understood that configuring CKEditor 4 was a bit too troublesome due to the number of configuration options available (over 240). Sometimes they were definitely too low-level, also many times they were so infrequently used that it did not justify the increased level of the application complexity. This is why when designing CKEditor 5 from scratch, we decided to come with a simplified editor, with well-thought default behavior, based on the results of the Editor Recommendations project.

If you are missing any particular features or settings, feel free to . Search the issues section in the repository first as the feature you are after may have already been reported — you can support it by upvoting . Please be as precise as possible, explaining the exact use case, the context where the editor is used, and the expected behavior.

# Configuring the font size feature

It is possible to configure which font size options are supported by the WYSIWYG editor. Use the configuration option to do so.

Use the special keyword to use the default font size defined in the web page styles. It removes any custom font size.

The font size feature supports two ways of defining the configuration: using predefined (named) presets or simple numeric values.

Using the predefined presets

The font size feature defines 4 named presets:

Each size is represented in the view as a element with the class. For example, the preset looks as follows in the editor data:

The CSS definition for the classes (presets) must be included in the web page styles where the edited content is rendered.

Here is an example of the font size CSS classes:

An example of the editor that supports only two font sizes:

This is a mixed text with different font sizes:
small and
big

Using numerical values

The font size feature also supports numerical values.

In this case, each size is represented in the view as a element with the style set in . For example, will be represented in the editor data as:

Here is an example of the WYSIWYG editor that supports numerical font sizes. Note that is controlled by the default styles of the web page:

9px

11px

13px

Normal

17px

19px

21px

Accepting all font sizes

By default, all values that are not specified in the are stripped. You can enable support for all font sizes by using the option.

This option can be used only in combination with .

# Base image support

The feature adds support for plain images with just the attribute set. This translates to the following HTML:

This feature follows the markup proposed by the Editor Recommendations project.

You can see the demo of a WYSIWYG editor with the base image feature enabled below:

This is CKEditor 5.

The base image feature, unlike in CKEditor 4, does not support any user interface for inserting or managing images. Its sole purpose is to lay ground for other plugins (mentioned above) to build the target user experience. This pattern (composition of atomic features) is common for CKEditor 5 and allows the developers to build their own customized experience by implementing specific subfeatures differently.

# Creating an Editor Command

It is customary for CKEditor 4 plugins to define an editor command that performs an action associated with them. The command should be defined inside the function in order to be created upon the initialization of a CKEditor 4 instance.

In this case we are going to use the method to define the command that will insert the current date and time into CKEditor 4:

The method defines a function that
will be fired when the command is executed.

The most important part of the plugin functionality is to insert the HTML code into the document. To do this,
we will use the method. This method
can be used to insert arbitrary HTML code into the document, so with a bit of tweaking
you can customize the timestamp plugin code to add other HTML elements into the
CKEditor 4 editing area.

# Localization

CKEditor 5 supports multiple UI languages, and so does the official Vue.js component. Follow the instructions below to translate CKEditor 5 in your Vue.js application.

Ready-to-use builds

When using one of the , you need to import the translations first.

  • When using a :
  • When using :

Then, configure the language of the editor in the component:

For more information, please refer to the Setting the UI language guide.

CKEditor 5 built from source

Using the editor requires you to modify the webpack configuration. Pass the (also ) to the constructor of to localize your editor:

After building the application, CKEditor 5 will run with the UI translated to the specified language.

For more information, please refer to the “Setting UI language” guide.

Plugins:¶

django-ckeditor includes the following ckeditor plugins, but not all are enabled by default:

a11yhelp, about, adobeair, ajax, autoembed, autogrow, autolink, bbcode, clipboard, codesnippet,
codesnippetgeshi, colordialog, devtools, dialog, div, divarea, docprops, embed, embedbase,
embedsemantic, filetools, find, flash, forms, iframe, iframedialog, image, image2, language,
lineutils, link, liststyle, magicline, mathjax, menubutton, notification, notificationaggregator,
pagebreak, pastefromword, placeholder, preview, scayt, sharedspace, showblocks, smiley,
sourcedialog, specialchar, stylesheetparser, table, tableresize, tabletools, templates, uicolor,
uploadimage, uploadwidget, widget, wsc, xml

Installation¶

  1. Install or add django-ckeditor to your python path.

    pip install django-ckeditor
    
  2. Add to your setting.

  3. Run the management command: . This will copy static CKEditor required media resources into the directory given by the setting. See Django’s documentation on managing static files for more info.

  4. CKEditor needs to know where its assets are located because it loads them
    lazily only when needed. The location is determined by looking at a script
    tag which includes a URL ending in . This does not work all
    the time, for example when using , any asset
    packaging pipeline or whatnot. django-ckeditor is quite good at
    automatically detecting the correct place even then, but sometimes you have
    to hardcode somewhere. It is recommended to override
    the template with your own if you really need to do
    this, i.e.:

    {% extends "admin/base_site.html" %}
    
    {% block extrahead %}
    <script>window.CKEDITOR_BASEPATH = '/static/ckeditor/ckeditor/';</script>
    {{ block.super }}
    {% endblock %}
    

    Of course you should adapt this snippet to your needs when using
    CKEditor outside the admin app.

# Using CKEditor from source

Integrating the rich text editor from source allows you to use the full power of CKEditor 5 Framework.

This guide assumes that you are using Vue CLI 3+ as your boilerplate and your application has been created using the command.

Learn more about building CKEditor from source in the Advanced setup guide.

Configuring

To build CKEditor with your application, certain changes must be made to the default project configuration.

First, install the necessary dependencies:

Edit the file and use the following configuration. If the file is not present, create it in the root of the application (i.e. next to ):

By default, the Vue CLI uses for all SVG files. The copies the file to the output directory and resolves imports into URLs. The CKEditor’s UI components use SVG so the theme icons must be loaded using . If your project uses different approach then CKEditor’s UI library you must create different webpack loader rules for your project SVG files and CKEditor’s ones.

Using the editor from source

Having configured , you can choose the building blocks of your editor. Install the packages necessary for your integration:

You can use more packages, depending on which features are needed in your application.

Instead of calling , you can always .

Now all you need to do is specify the list of rich text editor options (including plugins) in the data property:

Events

  • Fired when the property changed value.

    Parameters

    An object containing information about the fired event.

    Name of the changed property ().

    New value of the property with given key or , if operation should remove property.

    Old value of the property with given key or , if property was not set before.

  • Fired when the property changed value.

    Parameters

    An object containing information about the fired event.

    Name of the changed property ().

    New value of the property with given key or , if operation should remove property.

    Old value of the property with given key or , if property was not set before.

  • mixed

    Fired when a property changed value.

    Parameters

    An object containing information about the fired event.

    The property name.

    The new property value.

    The previous property value.

  • Fired when this editor instance is destroyed. The editor at this point is not usable and this event should be used to
    perform the clean-up in any plugin.

    See also the property.

    Parameters

    An object containing information about the fired event.

  • Fired when the and all additional
    editor components are ready.

    Note: This event is most useful for plugin developers. When integrating the editor with your website or
    application, you do not have to listen to because when the promise returned by the static
    event is resolved, the editor is already ready.
    In fact, since the first moment when the editor instance is available to you is inside ‘s callback,
    you cannot even add a listener to the event.

    See also the property.

    Parameters

    An object containing information about the fired event.

  • mixed

    Fired when a property value is going to be set but is not set yet (before the event is fired).

    You can control the final value of the property by using
    the .

    Note: The event is fired even when the new value is the same as the old value.

    Parameters

    An object containing information about the fired event.

    The property name.

    The new property value.

    The previous property value.

# Common API

The plugin registers the following components:

  • The dropdown.

  • The command.

    The number of options and their names correspond to the configuration option.

    You can change the font family of the current selection by executing the command with a desired value:

    The must correspond to the first font name in the configuration string. For the following default configuration:

    the command will accept the corresponding strings as values:

    Note that passing an empty value will remove the attribute from the selection ():

The plugin registers the following components:

  • The dropdown.

  • The command.

    The number of options and their names correspond to the configuration option.

    You can change the font size of the current selection by executing the command with a desired value:

    Passing an empty value will remove any set:

The plugin registers the following components:

  • The dropdown.

  • The command.

    You can change the font color of the current selection by executing the command with a desired value:

    Passing an empty value will remove the font color from the selection:

The plugin registers the following components:

  • The dropdown.

  • The command.

    You can change the font background color of the current selection by executing the command with a desired value:

    Passing an empty value will remove the font background color from the selection:

We recommend using the official for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

Events

  • inherited

    Fired when the property changed value.

    Parameters

    An object containing information about the fired event.

    Name of the changed property ().

    New value of the property with given key or , if operation should remove property.

    Old value of the property with given key or , if property was not set before.

  • inherited

    Fired when the property changed value.

    Parameters

    An object containing information about the fired event.

    Name of the changed property ().

    New value of the property with given key or , if operation should remove property.

    Old value of the property with given key or , if property was not set before.

  • mixed

    Fired when a property changed value.

    Parameters

    An object containing information about the fired event.

    The property name.

    The new property value.

    The previous property value.

  • inherited

    Fired when this editor instance is destroyed. The editor at this point is not usable and this event should be used to
    perform the clean-up in any plugin.

    See also the property.

    Parameters

    An object containing information about the fired event.

  • inherited

    Fired when the and all additional
    editor components are ready.

    Note: This event is most useful for plugin developers. When integrating the editor with your website or
    application, you do not have to listen to because when the promise returned by the static
    event is resolved, the editor is already ready.
    In fact, since the first moment when the editor instance is available to you is inside ‘s callback,
    you cannot even add a listener to the event.

    See also the property.

    Parameters

    An object containing information about the fired event.

  • mixed

    Fired when a property value is going to be set but is not set yet (before the event is fired).

    You can control the final value of the property by using
    the .

    Note: The event is fired even when the new value is the same as the old value.

    Parameters

    An object containing information about the fired event.

    The property name.

    The new property value.

    The previous property value.

Оцените статью
Рейтинг автора
5
Материал подготовил
Андрей Измаилов
Наш эксперт
Написано статей
116
Добавить комментарий