Skip to content

Latest commit

 

History

History
327 lines (237 loc) · 10.7 KB

00-getting-started.md

File metadata and controls

327 lines (237 loc) · 10.7 KB
Raw
layout bodyClass title description permalink menu
doc
doc
Getting started
An overview of Summernote, how to download and use, basic features, examples, and more.
/getting-started/
true

Get Summernote

Compiled CSS, JS

The fastest way to get Summernote is to download the precompiled and minified versions of our CSS and JavaScript. No documentation or original source code files are included.

Download compiled

Download source code

Get the latest Summernote LESS and Javascript source code by downloading it directly from GitHub. [Download]({{ site.repository }}/archive/master.zip)

Clone or Fork via Github

Visit us on GitHub to clone or fork the Summernote project. [project]({{ site.repository }})

Installation

Requires HTML5 doctype

Bootstrap uses certain HTML elements and CSS properties which require HTML5 doctype. Include <!DOCTYPE html> in the beginning of all your projects.

{% highlight html %}

... {% endhighlight %}

Include js/css

Summernote uses the Open Source libraries jQuery and Bootstrap, if you are using the Boostrap 3 or 4 versions of Summernote, or just jQuery if you use the Lite version of Summernote. Include the Following code in the head area of your HTML page.

{% highlight html %}

<script src="{{ site.jquery_js }}"></script> <script src="{{ site.bootstrap_js }}"></script> <script src="{{ site.summernote_js }}"></script> {% endhighlight %}

Don't forget to change the file's path if you downloaded summernote in a different folders.

You can however, and a lot of developers do these days, is include the stylesheet's within the head are of your page, and include the Javascript at the bottom of your page, but before the closing body tag.

Fontawesome dependency

After v0.8.0, You don't have to include fontawesome for displaying Summernote's icons. But You can still use fontawesome for your custom icons. For more details, please visit custom buttons section. After v0.8.18, You have the possibility to override summernote icons with your custom ones. For more details, please visit custom icons section.

Embed

Summernote can be used with or without a form.

To use without a form, we suggest using a div in the body; this element will then be used where you want the Summernote editor to be rendered within your page.

{% highlight html %}

Hello Summernote
{% endhighlight %}

To use within a form, is pretty much the same as above, but rather than a div, we recommend using a textarea element inside a form, which should include a name attribute so when the form is submitted you can use that name to process the editors data on your backend. Also, if using Summernote inside a form to set the attribute method="post" to allow larger sized editor content to parse to the backend, if you don't your data either may not parse, or will be truncated.

{% highlight html %}

<textarea id="summernote" name="editordata"></textarea> {% endhighlight %}

Run summernote

Run the script below when document is ready!

{% highlight javascript %} $(document).ready(function() { $('#summernote').summernote(); }); {% endhighlight %}

The $(document).ready function is particularly necessary if you include the Javascript at the end of the document.

Simple example

You can also test running example. Save below code as index.html and open it with your browser.

{% highlight html %}

<title>Summernote</title> <script src="{{ site.jquery_js }}"></script> <script src="{{ site.bootstrap_js }}"></script> <script src="{{ site.summernote_js }}"></script>

Hello Summernote

<script> $(document).ready(function() { $('#summernote').summernote(); }); </script> {% endhighlight %}

{% include ad-doc.html %}

For Bootstrap 4

You can also use Summernote with Bootstrap 4 using summernote-bs4.js and summernote-bs4.css.

<iframe id="bs4-frame" width="100%" height="200" frameborder="0"> {% include bs4.html %} </iframe> <script> var bs4_frame = document.querySelector('#bs4-frame'); bs4_frame.contentDocument.write(bs4_frame.innerHTML); bs4_frame.innerHTML = ''; </script>

{% highlight html %} {% include bs4.html %} {% endhighlight %}

For bootstrap 5

You can also use Summernote with Bootstrap 5 using summernote-bs5.js and summernote-bs5.css.

<iframe id="bs5-frame" width="100%" height="200" frameborder="0"> {% include bs5.html %} </iframe> <script> var bs5_frame = document.querySelector('#bs5-frame'); bs4_frame.contentDocument.write(bs4_frame.innerHTML); bs4_frame.innerHTML = ''; </script>

{% highlight html %} {% include bs5.html %} {% endhighlight %}

Without Bootstrap (lite)

You can use Summernote without Bootstrap using summernote-lite.js and summernote-lite.css.

<iframe id="lite-frame" width="100%" height="200" frameborder="0"> {% include lite.html %} </iframe> <script> var lite_frame = document.querySelector('#lite-frame'); lite_frame.contentDocument.write(lite_frame.innerHTML); lite_frame.innerHTML = ''; </script>

{% highlight html %} {% include lite.html %} {% endhighlight %}

Basic API

Initialize Summernote

{% highlight javascript %} $('#summernote').summernote(); {% endhighlight %}

Initialize Summernote with options

Height and Focus

If you set focus option, cursor will focus editable area after initialize Summernote.

{% highlight javascript %} $('#summernote').summernote({ height: 300, // set editor height minHeight: null, // set minimum height of editor maxHeight: null, // set maximum height of editor focus: true // set focus to editable area after initializing summernote }); {% endhighlight %}

If you set height, you can see resizebar below.

blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~
blah blah~

<script> $(function() { $('.height').summernote({height: 150}); }); </script>

If you don't set the height, editable area's height will change according to contents.

press enter key.

<script> $(function() { $('.noheight').summernote(); }); </script>

Destroy

Destroy Summernote.

{% highlight javascript %} $('#summernote').summernote('destroy'); {% endhighlight %}

get & set Code

Get the HTML contents of the first summernote in the set of matched elements.

{% highlight javascript %} var markupStr = $('#summernote').summernote('code'); {% endhighlight %}

If you initialize multiple editor, You can get the HTML content of the second summernote with jQuery eq.

{% highlight javascript %} var markupStr = $('.summernote').eq(1).summernote('code'); {% endhighlight %}

A string of HTML to set as the content of each matched element.

{% highlight javascript %} var markupStr = 'hello world'; $('#summernote').summernote('code', markupStr); {% endhighlight %}

for more detail api: deep dive with api

destroy and code

After v0.7.0, direct jquery methods, destroy and code were removed for avoiding conflict with other jquery libraries. You can call this methods with summernote api.

{% include ad-doc.html %}

i18n support

Language

Include libraries with lang file. eg) summernote-ko-KR.js.

{% highlight html %}

<script src="{{ site.jquery_js }}"></script> <script src="{{ site.bootstrap_js }}"></script> <script src="summernote.min.js"></script> <script src="lang/summernote-ko-KR.js"></script>

{% endhighlight %}

Run the script with locale option.

{% highlight javascript %} $(document).ready(function() { $('#summernote').summernote({ lang: 'ko-KR' // default: 'en-US' }); }); {% endhighlight %}

<script> $(document).ready(function() { $('.lang').summernote({ lang: 'ko-KR', placeholder: 'move your mouse on toolbar...' }); }); </script>

More Summernote languages: [languages]({{ site.repository }}/tree/master/lang)

Integration

3rd parties available in django, rails, angular and so on.

Django

Handy update for your django admin page.

Ruby On Rails

This gem was built to gemify the assets used in Summernote.

AngularJS

AngularJS directive to Summernote.

Apache Wicket

Summernote widget for Wicket Bootstrap.

Webpack

Example about using summernote with webpack.

Meteor

Example about using summernote with meteor.

PHP

Example for using Summernote with elFinder which uses a PHP Backend.