Summernote - Documentation

Getting Started

Installation

Summernote can be integrated into your project through various methods:

1. Using the CDN: The easiest way to get started is by including Summernote via a CDN link in your HTML file. Add the following lines within the <head> section of your HTML:

<link href="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.js"></script>

Replace 0.8.18 with the desired version number if needed. Note that summernote-lite.min.js and summernote-lite.min.css are for the lite version. For the full version use summernote.min.js and summernote.min.css

2. Using npm (Node Package Manager): If you are using npm, install Summernote using the following command:

npm install summernote --save

Then include the CSS and JS files in your project. The exact location will depend on your project structure. Refer to your build process documentation for specifics.

3. Using yarn (Yarn Package Manager): Similar to npm:

yarn add summernote

Again, include the CSS and JS files appropriately within your project.

Basic Usage

After including Summernote (using either CDN or npm/yarn), you need to initialize it on a <textarea> element. This is done by calling the summernote() method on your textarea element using jQuery. Ensure you have jQuery included in your project as Summernote relies on it.

$(document).ready(function() {
  $('#summernote').summernote();
});

Replace #summernote with the ID of your <textarea> element. For example:

<textarea id="summernote"></textarea>

This will transform your textarea into a WYSIWYG editor.

First Example

Let’s create a simple HTML file demonstrating basic Summernote integration:

<!DOCTYPE html>
<html>
<head>
<title>Summernote Example</title>
<link href="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.css" rel="stylesheet">
</head>
<body>
<textarea id="summernote"></textarea>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.js"></script>
<script>
$(document).ready(function() {
  $('#summernote').summernote();
});
</script>
</body>
</html>

This code includes Summernote via CDN, initializes it on a textarea with the ID “summernote”, and provides a basic example. Remember to replace the CDN links with local paths if you’ve installed Summernote using npm or yarn.

Configuration Options

Summernote offers many configuration options to customize its behavior and appearance. These options are passed as a JavaScript object to the summernote() method. Here are a few examples:

$(document).ready(function() {
  $('#summernote').summernote({
    airMode: true, // Enables Air Mode (fullscreen editing)
    height: 300, // Sets the editor height in pixels
    callbacks: {
      onInit: function(e) {
        console.log('Summernote initialized!');
      },
      onImageUpload: function(files, editor, welEditable) {
        // Custom image upload handling
      }
    },
    toolbar: [
      ['style', ['style']],
      ['font', ['bold', 'italic', 'underline', 'clear']],
      ['para', ['ul', 'ol', 'paragraph']],
      ['insert', ['link', 'picture', 'video']],
      ['view', ['fullscreen', 'codeview']]
    ]
  });
});

The full list of configuration options can be found in the Summernote documentation. Refer to the official documentation for detailed explanations and usage examples for each option. This allows for extensive customization to fit your application’s needs.

Core Features

Editor Initialization

Summernote’s core functionality revolves around initializing the editor on a <textarea> element. This is achieved using jQuery’s .summernote() method, passing an optional configuration object as an argument. The simplest initialization looks like this:

$(document).ready(function() {
  $('#summernote').summernote();
});

This replaces the <textarea> with the Summernote editor. The ID #summernote should match the ID of your <textarea> element. You can customize the editor’s behavior and appearance extensively through the configuration object (see the Configuration Options section for details). Remember that jQuery is a required dependency for Summernote.

Toolbar Customization

The Summernote toolbar is highly customizable. You can add, remove, or rearrange buttons to fit your specific requirements. This is done through the toolbar configuration option. The toolbar option accepts a nested array, where each inner array represents a group of buttons.

$(document).ready(function() {
  $('#summernote').summernote({
    toolbar: [
      ['style', ['style']], // Style group
      ['font', ['bold', 'italic', 'underline', 'clear']], // Font group
      ['para', ['ul', 'ol', 'paragraph']], // Paragraph group
      ['insert', ['link', 'picture', 'video']], // Insert group
      ['view', ['fullscreen', 'codeview']] // View group
    ]
  });
});

Each button within a group is represented by a string that corresponds to a Summernote command. You can consult the Summernote documentation for a complete list of available commands. Removing a group is as simple as omitting it from the array. Experiment with different configurations to create your ideal toolbar.

Air Mode

Air Mode provides a distraction-free, fullscreen editing experience. It’s enabled by setting the airMode configuration option to true:

$(document).ready(function() {
  $('#summernote').summernote({
    airMode: true
  });
});

In Air Mode, the toolbar is minimized, and the editor takes up the entire screen. This is ideal for users who prefer a clean writing environment. Switching back to the standard editor view can be done through the toolbar.

Content Manipulation

Summernote provides methods for manipulating the editor’s content programmatically. You can access the content using the following methods:

Example of setting content:

$('#summernote').summernote('setContents', '<h1>Hello, World!</h1>');

Example of getting content:

var content = $('#summernote').summernote('code');
console.log(content);

Event Handling

Summernote offers several events that you can listen for to respond to user actions or editor changes. These events are bound using jQuery’s .on() method:

$('#summernote').on('summernote.change', function(we, contents, $editable) {
  console.log('Content changed:', contents);
});

This example logs a message to the console whenever the editor’s content changes. Other notable events include:

Refer to the Summernote documentation for a comprehensive list of available events and their details. Event handling provides powerful capabilities to integrate Summernote seamlessly into your applications and customize its functionality further.

Advanced Features

Plugins

Summernote’s functionality can be extended significantly through the use of plugins. Plugins provide additional features and capabilities that are not included in the core library. While Summernote doesn’t have a built-in plugin manager, you can integrate external plugins by including their JavaScript and CSS files in your project and then initializing them alongside Summernote.

Many community-contributed plugins are available online. You’ll need to carefully review the plugin’s documentation for specific instructions on how to integrate it into your project. This typically involves including the plugin’s files and then calling the plugin’s initialization function, often passing a configuration object.

For example, a hypothetical plugin might be initialized like this:

$(document).ready(function() {
  $('#summernote').summernote({
    // ... other Summernote options ...
  }).myCustomPlugin({option1: 'value1', option2: 'value2'}); // Assuming 'myCustomPlugin' is the plugin's initialization function
});

Remember to always check the license of any external plugins before integrating them into your project.

Extending Summernote

For more substantial modifications or custom features not easily achievable with plugins, you can directly extend Summernote’s functionality. This involves modifying the Summernote codebase itself or creating custom functions that interact with the Summernote API. This approach requires a deeper understanding of Summernote’s internal workings and JavaScript development. Be cautious when modifying the core codebase, as updates to Summernote may overwrite your changes. It is generally recommended to create separate functions and utilize Summernote’s API as much as possible for extending functionality.

Customizing the UI

Summernote’s UI can be customized to match your application’s design. This can involve modifying the CSS styles of the editor or creating entirely new UI elements using JavaScript. Modifying the CSS is usually the simplest method, allowing you to change colors, fonts, sizes, and spacing. More complex UI changes might require writing custom JavaScript code to manipulate the DOM elements of the Summernote editor. It’s important to remember that directly manipulating the internal structure of the editor is generally discouraged, due to potential conflicts with future Summernote updates. Using CSS to override existing styles is the safer and recommended approach.

Integration with Frameworks

Summernote can be integrated with various JavaScript frameworks like React, Angular, and Vue.js. The integration process typically involves using the framework’s component model to wrap the Summernote editor. For example, in React you might create a custom component that renders the <textarea> and initializes Summernote within its lifecycle methods. This approach requires familiarity with the specific framework’s patterns and best practices. Consult the documentation of your chosen framework for more details on how to integrate Summernote.

Accessibility

Building accessible web applications is crucial. Summernote strives to provide accessibility features, but further considerations are often needed depending on your specific use-case. Ensure proper ARIA attributes are used, and the editor’s content remains semantically correct. Provide alternative text for images. Consider keyboard navigation and screen reader compatibility. Thorough testing with assistive technologies is essential to ensure the editor is accessible to users with disabilities. Using semantic HTML within the editor is crucial for screen readers to interpret the content correctly. Regularly review and update your accessibility implementation to adhere to current best practices and standards (e.g., WCAG).

API Reference

Summernote Object

The core of Summernote’s API is the Summernote object itself, which is created when you initialize the editor on a <textarea> element using $(selector).summernote(). This object provides access to various methods and properties for manipulating the editor. You access methods and properties of the Summernote object using the jQuery chaining syntax. For example, $('#summernote').summernote('code') calls the code() method of the Summernote object associated with the element with the ID “summernote”.

Methods

Summernote provides numerous methods to interact with the editor programmatically. Some key methods include:

A comprehensive list of available methods, along with detailed descriptions and examples, can be found in the official Summernote documentation. Consult the documentation for the most up-to-date information on all available methods and their parameters.

Events

Summernote triggers various events during its operation. These events allow developers to respond to specific actions or changes within the editor. Events are bound using jQuery’s .on() method, targeting the summernote namespace. For example:

$('#summernote').on('summernote.change', function(we, contents, $editable) {
  console.log('Content changed:', contents);
});

This code snippet listens for the summernote.change event and logs the new content to the console whenever the editor content is modified. Other important events include summernote.init, summernote.focus, summernote.blur, summernote.paste, summernote.keyup, and summernote.keydown. Refer to the Summernote documentation for a complete list of available events.

Callbacks

Callbacks provide a way to execute custom functions at specific points during the editor’s lifecycle. Callbacks are defined within the configuration object passed to the summernote() method. Common callbacks include:

Example:

$('#summernote').summernote({
  callbacks: {
    onInit: function() {
      console.log('Summernote initialized!');
    },
    onImageUpload: function(files) {
      // Handle image upload
    }
  }
});

Consult the Summernote documentation for a complete list of available callbacks and their parameters. Callbacks offer a powerful mechanism to extend and customize Summernote’s functionality to meet your application’s specific requirements.

Troubleshooting

Common Issues

This section addresses some frequently encountered issues when using Summernote:

Debugging Tips

When troubleshooting Summernote, these tips can be helpful:

Error Messages

Summernote may produce error messages in your browser’s console. These messages should provide clues about the nature of the problem. Pay close attention to error messages and search online for solutions related to the specific error. The error message might indicate problems with:

Community Support

If you’re unable to resolve an issue using the above methods, consider seeking help from the Summernote community. Online forums, issue trackers, or the Summernote’s official website may provide answers to your questions or assistance from other developers. When seeking help, be sure to provide the following information:

Clear and concise information will significantly help others in the community assist you more effectively.

Examples

Simple Example

This example demonstrates the most basic Summernote integration:

<!DOCTYPE html>
<html>
<head>
<title>Summernote Simple Example</title>
<link href="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.css" rel="stylesheet">
</head>
<body>
<textarea id="summernote"></textarea>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.js"></script>
<script>
  $(document).ready(function() {
    $('#summernote').summernote();
  });
</script>
</body>
</html>

This code includes Summernote via CDN, initializes it on a <textarea> with the ID “summernote”, and uses the default configuration. Remember to replace the CDN links with local paths if you’ve installed Summernote using npm or yarn. This provides a fully functional WYSIWYG editor with the default toolbar.

Advanced Example

This example showcases more advanced features, including custom toolbar, Air Mode, and a callback function:

<!DOCTYPE html>
<html>
<head>
<title>Summernote Advanced Example</title>
<link href="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.css" rel="stylesheet">
</head>
<body>
<textarea id="summernote"></textarea>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/summernote@0.8.18/dist/summernote-lite.min.js"></script>
<script>
$(document).ready(function() {
  $('#summernote').summernote({
    airMode: true,
    toolbar: [
      ['style', ['style']],
      ['font', ['bold', 'italic', 'underline']],
      ['para', ['ul', 'ol', 'paragraph']],
      ['insert', ['link', 'picture']]
    ],
    callbacks: {
      onChange: function(contents, $editable) {
        console.log('Content changed: ', contents);
      }
    }
  });
});
</script>
</body>
</html>

This example uses Air Mode, customizes the toolbar to include only specific buttons, and adds a callback function that logs the content changes to the console. This illustrates how to customize Summernote’s functionality and appearance to fit specific application requirements. Remember to adjust paths to your local files if you’re not using the CDN.

Integration with other libraries

Integrating Summernote with other libraries depends heavily on the specific library. There isn’t a universal approach. However, the general principle involves initializing Summernote after the other library has been set up and ensuring that there are no conflicts between their JavaScript or CSS.

For example, integrating with a date picker library:

  1. Include Libraries: Include both Summernote and the date picker library’s CSS and JS files in your project.

  2. Initialize Libraries: Initialize the date picker library before initializing Summernote. This ensures the date picker is ready before Summernote attempts to interact with it.

  3. Custom Callback (if needed): If the date picker needs specific integration within Summernote (for example, adding a button to insert a date), create a custom callback function within Summernote’s configuration to handle this interaction. This callback might involve adding a button to the toolbar and handling the associated event to insert the selected date into the editor.

  4. Handle potential conflicts: Carefully review the documentation of both libraries for potential CSS or JavaScript conflicts. Resolve these conflicts by overriding CSS classes or adjusting the order of inclusion in your HTML.

Remember that the exact implementation will depend significantly on the specific libraries involved. Always refer to the individual libraries’ documentation for detailed integration instructions.