ts_staging
0 variant test
0 variant test
Deep dive
Customize Summernote's modules, toolbar and plugins to get your very own version
Initialization options
Customize by Initializing various options and modules.
Custom toolbar, popover
Summernote allows you to customise the toolbar.
This is a toolbar with font style only.
You can compose a toolbar with pre-shipped buttons.
- Insert
-
picture
: open image dialog -
link
: open link dialog -
video
: open video dialog -
table
: insert a table -
hr
: insert a horizontal rule
-
- Font Style
-
fontname
: set font family -
fontsize
: set font size -
fontsizeunit
: set font size unit -
color
: set foreground and background color -
forecolor
: set foreground color -
backcolor
: set background color -
bold
: toggle font weight -
italic
: toggle italic -
underline
: toggle underline -
strikethrough
: toggle strikethrough -
superscript
: toggle superscript -
subscript
: toggle subscript -
clear
: clear font style
-
- Paragraph style
-
style
: format selected block -
ol
: toggle ordered list -
ul
: toggle unordered list -
paragraph
: dropdown for paragraph align -
height
: set line height
-
- Misc
-
fullscreen
: toggle fullscreen editing mode -
codeview
: toggle wysiwyg and html editing mode -
undo
: undo -
redo
: redo -
help
: open help dialog
-
The following settings are default options for toolbar buttons.
Air-mode has its own popover, not toolbar. You can customize it with popover.air
option.
You can also setup buttons of the other popovers in the same way. The below settings are default options for popovers.
Blockquote breaking level
You can set blockquote breaking level with blockquoteBreakingLevel
option.
Each configurable breaking level means:
- 0 - No break, the new paragraph remains inside the quote.
- 1 - Break the first blockquote in the ancestors list.
- 2 - Break all blockquotes, so that the new paragraph is not quoted. (default)
Custom styles
You can set your own selection of styles with the styleTags
option.
The tags can be specified just by tag name (as with p
or pre
or h1
-h6
above). It is also possible to customize the style in more detail by providing an object looking like:
Custom fontNames
You can define fontNames items with the fontNames
option.
Summernote tests for fonts in fontNames before adding them to dropdown. This is a problem while using web fonts. It’s not easy picking a nice time to check the availability of web fonts. You can define a list of web fonts to be ignored with the fontNamesIgnoreCheck
.
Custom font size units
You can set the available font size units with the fontSizeUnits
option.
Custom line heights
You can override the default list and specify a custom one.
Custom placeholder
You can define a placeholder with the placeholder
option.
Dialogs
Dialogs can be placed in body
, not within Summernote. If you’re using Summernote within a modal dialog, please set this option as true
.
By default, dialogs are shown and hidden without a fading effect. But you can turn it on by dialogsFade
.
Disable drag and drop
You can disable drag and drop with the disableDragAndDrop
option.
Disable shortcuts
You can disable custom shortcuts with the shortcuts
option.
Disable TAB
You can disable TAB/Shift+Tab intereaction with the tabDisable
option. This will allow tabbing through fields in Forms.
XSS protection for CodeView
Summernote provides a XSS protection for CodeView. It consists of filtering tags and whitelist for iframe
.
Whitelist filter is turned on by default, but filtering tags is not. You can turn them on and off by options like below.
And, you can also add your own whitelist domains and use custom tag filters. Please check the default filter before customizing.
But you have to remember that this protection only affects on front-end side – to prevent attacks thoroughly, you have to check it on back-end side again.
Basic API
You can initialize Summernote with summernote
.
Then You can use the editor API through the summernote
method. This is an example code for inserting ‘hello world’ text.
It calls the editor module’s insertText method with ‘hello world’. The first argument is a string type which represents the module and its method. The rest are method’s arguments.
If you call the API without module name, editor.methodName
will be called.
A module named editor
supports several methods for editor’s basic behavior
codeview
You can toggle editable/codable view by API.
createRange
Creates a range object for current user selection.
disable, enable
You can disable editor by API.
If you want to enable editor again, call API with enable
.
Disable Spellchecking
You can disable Spellchecking in the Editing area with the spellCheck
option.
Disable Grammarly Browser Addon
You can disable the Grammarly Browser Addon (currently researching other Grammar Addons for their disabling options) by using the disableGrammar
option.
focus
Sets focus in current summernote
fullscreen
You can toggle Fullscreen view by API.
isFullscreen
You can programmatically determine if the Summernote is in Fullscreen mode by using isFullscreen
, which will return true
or false
.
interface
You can find programmatically which Summernote you are using. This will return one of three values: bs3
, bs4
or lite
.
isEmpty
Returns whether editor content is empty or not.
The editing area needs <p><br></p>
for focus, even if the editor content is empty. So Summernote supports this method for helping to check if editor content is empty.
reset
Clear the editor content and remove all stored history.
saveRange, restoreRange
saveRange
saves current user selection internally.
restoreRange
restores currently saved range
undo, redo
Undoes and Redoes the last command
Font style API
backColor, foreColor
Set the Background or Foreground color.
bold, italic, underline, strikethrough
Set font style.
fontName
Set font family.
fontSize
Set font size.
fontSizeUnit
Set font size unit.
removeFormat
Clean a style.
superscript, subscript
Set superscript or subscript.
Paragraph API
formatH1-H6
Change current paragraph as a <h1> ~ <h6>
.
formatPara
Change current paragraph as a <p>
.
indent and outdent
Indent or Outdent on current paragraph.
insertOrderedList
Toggle ordered list or unordered list
insertParagraph
Insert a paragraph
justify left, right and more
Set the alignment of a Paragraph.
lineHeight
Set line height.
Insertion API
createLink, unlink
Create link and unlink.
insertImage
Insert an image.
You can modify image with passing callback as second argument.
insertNode
Insert an element or textnode.
insertText
Insert text.
pasteHTML
Paste HTML string.
Range & Selection API
saveRange
refer to #saveRange
restoreRange
refer to #restorerange
getLastRange
summernote is saving a range object(WrappedRange) on current cursor.
when summernote save a range with dom event
- keydown
- keyup
- focus
- mouseup
- paste
when summernote save a range with api
editor.insertImage
-> Imageeditor.insertNode
-> Nodeeditor.insertText
-> TextNodeeditor.pasteHTML
-> last Node of contentseditor.insertHorizontalRule
-> next sibling node of hr nodeeditor.createLink
-> link node
setLastRange
You can define custom range in node of summernote editable element.
range
utility
create WrappedRange Object
range utility make a WrappedRange Class’s instance
create
create WrappedRange Object From arguments or Browser Selection
createFromNode
create WrappedRange object from node
createFromNodeBefore
create WrappedRange from node before position
createFromNodeAfter
create WrappedRange from node after position
createFromSelection
create WrappedRange object from selection
WrappedRange Object
select()
select update visible range
rng.select()
collapse(isCollapseToStart)
const newRng = rng.collapse(true); // to start rng
or
const newRng = rng.collapse(); // to end rng
splitText()
splitText on range
const textRng = rng.splitText()
deleteContents()
delete contents on range
const newRng = rng.deleteContents()
isCollapsed()
returns whether range was collapsed or not
const isCollapsed = rng.isCollapsed()
wrapBodyInlineWithPara()
wrap inline nodes which children of body with paragraph
const newRng = rng.wrapBodyInlineWithPara()
insertNode(node)
insert node at current cursor
const node = rng.insertNode(document.createElement('div'))
pasteHTML(markup)
insert html at current cursor
const nodes = rng.pasteHTML(`<div>summernote</div>`)
toString()
returns text in range
getWordRange(findAfter)
returns range for word before(or after) cursor
const newRng = rng.getWordRange(); // before cursor
// or
const newRng = rng.getWordRange(true); // after cursor
getWordsMatchRange(regex)
returns range for words before cursor that match with a Regex
// range : 'hi @Peter Pan'
const rng = range.create() // or $('.summernote').summernote('getLastRange');
const newRng = rng.getWordsMatchRange(/@[a-z ]+/i)
console.log(newRng.toString()) // '@Peter Pan'
getClientRects()
returns a list of DOMRect objects representing the area of the screen occupied by the range.
Range.getClientRects()
https://developer.mozilla.org/en-US/docs/Web/API/Range/getClientRects
Callbacks
Summernote support initialize callbacks and jquery’s custom event style callbacks.
Position of callbacks in options is changed after v0.7.0
After v0.7.0, every callbacks should be wrapped by
callbacks
object.
Callback only works with camel case string after v0.6.5
Lowercase string has been used for basic event name(ex:
oninit
,onenter
,onfocus
,onblur
,onkeyup
,onkeydown
,onpaste
). In contrast, callbacks name for advanced feature has been used with camel case string. This is inconsistent and confusing to use. So we rename all lowercase callback to camel case string.
onBeforeCommand
WIP: Need to work on an explanation
onChange
- IE9-10: DOMCharacterDataModified, DOMSubtreeModified, DOMNodeInserted
- Chrome, FF: input
onChangeCodeview
WIP: Need to work on an explanation
onDialogShown
WIP: Need to work on an explanation
onEnter
onFocus, onBlur, onBlurCodeview
onImageLinkInsert
Override insertion of image by url
onImageUpload
Override image upload handler(default: base64 dataURL on IMG
tag). You can upload image to server or AWS S3: more…
onImageUploadError
WIP: Need to work on an explanation
onInit
onKeyup, onKeydown
onMouseDown,onMouseUp
onPaste
onScroll
WIP: Need to work on an explanation
Custom button
Summernote also supports custom buttons. If you want to create your own button, you can simply define and use with options.
Define button
You can create a button object with $.summernote.ui. This buttons objects have the below properties.
- contents: contents to be displayed on the button
- tooltip: tooltip text when mouse over
- click: callback function to be called when mouse is clicked
Below codes is about simple button for inserting text ‘hello’.
You can see render()
which returns jquery object as button.
Using button with options
Let’s learn how to use the button on toolbar.
First, you can define buttons with option named buttons
which is a set of key-value. You can define custom button on toolbar options.
You can also use custom button on popover
in the same way.
Custom icons
Summernote supports the usage of your own custom icons. You can e.g. use SVG based icons instead of the default ones.
Define your own icons
If you want to override the default icons, configure summernote like this:
Module system
For supporting expandable features, summernote was assembled by module system. This module system was built inspired by spring framework.
Key terms
- Module: Module is a component.
- Context: Context is a kind of container. It has modules and editor’s states.
- Renderer: Renderer is a function for creating element.
- UI: UI is a set of renderers to build ui elements.
Module
Module is a component for implementing feature and it has lifecycle. Module also has helper methods or methods related with lifecycle.
initialize
This method will be called when editor is initialized by $(‘..’).summernote();. You can attach events and created elements on editor elements(eg, editable, …).
destroy
This method will be called when editor is destroyed by $(‘..’).summernote(‘destroy’); You should detach events and remove elements on initialize
.
shouldInitialize
This method is used for deciding whether module will be initialized or not.
Below are full codes of AutoLink module.
For more module examples: modules
Module with options
You can define custom module with options.
You can called module’s method with external API.
Plugin
Plugin is a kind of external module. You can also define your own module with plugin.
Below link is a example of external module.
Plugin was redesigned by new module system after
v0.7.0
Old plugin was hard to control editor states(eg, range, layout so on). After v0.7.0 plugin is redesigned by new module system. It is exactly same with module except surrounding module pattern.
Modules
Notification / Information Area
Summernote allows to add Notifications with Contextual Colouring to indicate the type of Notifcation, or to use the area for Informational Purposes.
The area appears at the bottom of Summernote when used in Normal Mode, and at the top of the editing area when Summernote is used in Air Mode.
To use the Notifcation area is simple and is useable by targetting the area using it’s class name .note-status-output
.
Notification elements can use any markup, but we’ve added some styling along the lines of Bootstrap’s Alerts. For e.g. to produce an Error or Danger alert you can use <div class="alert alert-danger">This is an error</div>
. You can also use alert-info
, alert-warning
, alert-success
and alert-danger
.
You can add the above message using jQuery or other Javascript method by targetting the output element, like (using jQuery):
If you want to display just Informational Text, you can also add Text without the Alert if you wish.
You can also place text to the right side by placing the Text within an element such as div
, span
or small
and including the class .pull-right
.
You can also use Contextual Colours for your text using the classes text-muted
, text-primary
, ‘text-success’, text-info
, text-warning
and text-danger
.
Materials and care
-
Share information about this garment's materials or features.
-
Include information about its feel or performance.
-
-
Provide advice on garment storage or care.
-
Consider adding an image to this column for more visual interest.
-
Give laundering instructions including water temperature and recommended drying method.
-
Consider adding an image to this column for more visual interest.
-
Introduce a set of collections that give your customers different ways to browse your products.
-
-
List your shipping policy
-
-
Share your domestic shipping prices
-
Share your international shipping prices