Quill allows granular access to its contents.
-Retrieves the string contents of the editor.
-Methods
-getText()getText(start)getText(start, end)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
start |
- Number | -Start index of text retrieval. Defaults to 0. | -
end |
- Number | -End index of text retrieval. Defaults to end of the - document. | -
Returns
-Examples
-
-var text = editor.getText(0, 10);
-
- Retrieves the length of the editor contents.
-Methods
-getLength()Returns
-Examples
-
-var length = editor.getLength();
-
- Retrieves contents of the editor, with formatting data, represented by - a Delta object.
-Methods
-getContents()getContents(start)getContents(start, end)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
start |
- Number | -Start index of retrieval. Defaults to 0. | -
end |
- Number | -End index of retrieval. Defaults to the rest of the - document. | -
Returns
-Examples
-
-var delta = editor.getContents();
-
- Retrieves the HTML contents of the editor.
-Methods
-getHTML()Returns
-Examples
-
-var html = editor.getHTML();
-
- Inserts text into the editor. See formats for a list of available formats.
-Methods
-insertText(index, text)insertText(index, text, name,
- value)insertText(index, text,
- formats)insertText(index, text,
- source)insertText(index, text, name,
- value, source)insertText(index, text, formats,
- source)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
index |
- Number | -Index where text should be inserted. | -
text |
- String | -Text to be inserted. | -
name |
- String | -Name of format to apply to inserted text. | -
value |
- String | -Value of format to apply to inserted text. | -
formats |
- Object | -Key/value pairs of formats to apply to inserted text. | -
source |
- String | -
- Source to be
- emitted. Defaults to api.
- |
-
Examples
-
-editor.insertText(0, 'Hello', 'bold', true);
-
-editor.insertText(5, 'Quill', {
- 'italic': true,
- 'fore-color': '#ffff00'
-});
-
- Deletes text from the editor.
-Methods
-deleteText(start, end)deleteText(start, end,
- source)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
start |
- Number | -Start index of deletion. | -
end |
- Number | -End index of deletion. | -
source |
- String | -
- Source to be
- emitted. Defaults to api.
- |
-
Examples
-
-editor.deleteText(0, 10);
-
- Formats text in the editor. For line level formats, such as text
- alignment, target the newline character or use the formatLine helper. See formats for a list of available formats.
Methods
-formatText(start, end)formatText(start, end, name,
- value)formatText(start, end,
- formats)formatText(start, end,
- source)formatText(start, end, name, value,
- source)formatText(start, end, formats,
- source)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
start |
- Number | -Start index of formatting range. | -
end |
- Number | -End index of formatting range. | -
name |
- String | -Name of format to apply to text. | -
value |
- String | -Value of format to apply to text. A falsy value will remove the - format. | -
source |
- String | -
- Source to be
- emitted. Defaults to api.
- |
-
Examples
-
-editor.setText('Hello\nWorld!\n');
-
-editor.formatText(0, 5, 'bold', true); // bolds 'hello'
-
-editor.formatText(0, 5, { // unbolds 'hello' and set its color to blue
- 'bold': false,
- 'color': 'rgb(0, 0, 255)'
-});
-
-editor.formatText(5, 6, 'align', 'right'); // right aligns the 'hello' line
-
- Formats all lines in given range. See formats for a list of available formats. Has no - effect when called with inline formats.
-Methods
-formatLine(start, end)formatLine(start, end, name,
- value)formatLine(start, end,
- formats)formatLine(start, end,
- source)formatLine(start, end, name, value,
- source)formatLine(start, end, formats,
- source)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
start |
- Number | -Start index of formatting range. | -
end |
- Number | -End index of formatting range. | -
name |
- String | -Name of format to apply to text. | -
value |
- String | -Value of format to apply to text. A falsy value will remove the - format. | -
source |
- String | -
- Source to be
- emitted. Defaults to api.
- |
-
Examples
-
-editor.setText('Hello\nWorld!\n');
-
-editor.formatLine(1, 3, 'align', 'right'); // right aligns the first line
-editor.formatLine(4, 8, 'align', 'center'); // center aligns both lines
-
- Insert embedded content into the editor. Currently only images are - supported.
-Methods
-insertEmbed(index, type,
- url)insertEmbed(index, type, url,
- source)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
index |
- Number | -Index where content should be inserted. | -
type |
- String | -Type of content. Currently accepts only image. |
-
url |
- String | -URL where content is located. | -
source |
- String | -
- Source to be
- emitted. Defaults to api.
- |
-
Examples
-
-editor.insertEmbed(10, 'image', 'https://quilljs.com/images/cloud.png');
-
- Applies Delta to editor contents.
-Methods
-updateContents(delta)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
delta |
- - Delta - | -Delta that will be applied. | -
Examples
-
-// Assuming editor currently contains [{ insert: 'Hello World!' }]
-editor.updateContents({
- ops: [
- { retain: 6 }, // Keep 'Hello '
- { delete: 5 }, // 'World' is deleted
- { insert: 'Quill' }, // Insert 'Quill'
- { retain: 1, attributes: { bold: true } } // Apply bold to exclamation mark
- ]
-});
-// Editor should now be [{ insert: 'Hello Quill' }, { insert: '!', attributes: { bold: true} }]
-
- Overwrites editor with given contents.
-Methods
-setContents(delta)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
delta |
- - Delta - | -Delta editor should be set to. | -
Examples
-
-editor.setContents([
- { insert: 'Hello ' },
- { insert: 'World!', attributes: { bold: true } },
- { insert: '\n' }
-]);
-
- Sets contents of editor with given HTML. Note the editor will
- normalize the input to the subset it recognizes. For example strong tags will be converted to b tags.
Methods
-setHTML(html)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
html |
- String | -HTML to set editor contents to. | -
Examples
-
-editor.setHTML('<div>Hello</div>');
-
- Sets contents of editor with given text. Note Quill documents end with - a newline so one will be added for you if omitted.
-Methods
-setText(text)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
text |
- String | -Text to set editor contents to. | -
Examples
-
-editor.setText('Hello\n');
-
- Retrieves the user’s selection range.
-Methods
-getSelection()Returns
-start and end representing user’s selection rangeExamples
-
-var range = editor.getSelection();
-if (range) {
- if (range.start == range.end) {
- console.log('User cursor is at index', range.start);
- } else {
- var text = editor.getText(range.start, range.end);
- console.log('User has highlighted: ', text);
- }
-} else {
- console.log('User cursor is not in editor');
-}
-
- Sets user selection to given range. Will also focus the editor. If
- null, will blur the editor.
Methods
-setSelection(start,
- end)setSelection(start, end,
- source)setSelection(range)setSelection(range,
- source)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
start |
- Number | -Start index of selection range. | -
end |
- Number | -End index of selection range. | -
range |
- Object | -Object with start and end - keys indicating the corresponding indexes where the selection - exists. | -
source |
- String | -
- Source to be
- emitted. Defaults to api.
- |
-
Examples
-
-editor.setSelection(0, 5);
-
- Sets the format at the current cursor position. Thus subsequent typing - will result in those characters being set to the given format value. For - example, setting bold and then typing ‘a’ will result in a bolded - ‘a’.
-Has no effect if current selection does not exist or is not a - cursor.
-Methods
-prepareFormat(format,
- value)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
format |
- String | -- Name of format to set. See formats for a list of available - formats. - | -
value |
- String | -Value of format to apply to set. A falsy value will unset the - format. | -
Examples
-
-editor.prepareFormat('bold', true);
-
- Focuses the editor.
-Methods
-focus()Examples
-
-editor.focus();
-
- Retrieves the pixel position (relative to the editor container) and - height of a cursor at a given index. The actual cursor need not be at - that index. Useful for calculating where to place tooltips.
-Methods
-getBounds(index)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
index |
- Number | -Index position to measure cursor bounds. | -
Returns
-height, left, and top.Examples
-
-editor.setText('Hello\nWorld\n');
-editor.getBounds(7); // Returns { height: 15, left: 27, top: 31 }
-
- Registers a module, making it available to be added to an editor. See - Modules for more details.
-Methods
-registerModule(name,
- function)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
name |
- String | -Name of module to register. | -
options |
- Function | -Options to be passed into module constructor. | -
Examples
-
-Quill.registerModule('custom-module', function(quill, options) {
- console.log(options);
-});
-
- Add module to editor. The module should have been previously - registered with registerModule. See - Modules for more details.
-Methods
-addModule(name,
- options)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
name |
- String | -Name of module to add. | -
options |
- Object | -Options to be passed into module constructor. | -
Returns
-Examples
-
-var toolbar = editor.addModule('toolbar', {
- container: '#toolbar-container'
-});
-
- Retrieves a module that has been added to the editor.
-Methods
-getModule(name)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
name |
- String | -Name of module to retrieve. | -
Returns
-Examples
-
-var toolbar = editor.getModule('toolbar');
-
- Calls a given callback when given module is added. If the module is - already added, the callback is called immediately.
-Methods
-onModuleLoad(name,
- callback)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
name |
- String | -Name of module. | -
callback |
- Function | -Function to call. | -
Examples
-
-editor.onModuleLoad('toolbar', function(toolbar) {
- console.log('Toolbar has been added');
-});
-
- Add a custom defined format to editor.
-Methods
-addFormat(name, config)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
name |
- String | -Name of format to add. Will overwrite if name already - exists. | -
config |
- Object | -- Format configurations. See formats for more details. - | -
Examples
-
-editor.addFormat('strike', { tag: 'S', prepare: 'strikeThrough' });
-
- Add a div container inside the Quill container, sibling to the editor
- itself. By convention, Quill modules should have a class name prefixed
- with ql-.
Methods
-addContainer(cssClass,
- before)Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
cssClass |
- String | -CSS class to add to created container. | -
before |
- Boolean | -If true, will insert
- before the editor container, otherwise it will be appended
- after. |
-
Returns
-Examples
-
-var container = editor.addContainer('ql-custom');
-
- Quill allows several ways to customize it to suit your needs. This - section is dedicated to tweaking existing functionality. See the Modules section for adding new functionality - and the Themes section for styling.
-Quill requires an container where the editor will be appended. You can - either pass in a CSS selector or a DOM object.
-
-var editor = new Quill('.editor'); // The first result of the selector will be used
-
-
-var container = document.getElementById('editor');
-var editor = new Quill(container);
-
-
-var container = $('.editor').get(0);
-var editor = new Quill(container);
-
- To configure Quill, pass in an options object:
-
-var configs = {
- readOnly: true,
- theme: 'snow'
-};
-var editor = new Quill('#editor', configs);
-
- The following keys are recognized:
-Default: 100
Number of milliseconds between checking for local changes in the - editor. Note that certain actions or API calls may prompt immediate - checking.
-Default: false
Whether to instantiate the editor to read-only mode.
-Default: {}
Object containing CSS rules to add to the Quill editor. Passing in
- false (not merely a falsy
- value) will prevent Quill from inserting any default styles. In this
- latter case it is assumed either the base stylesheet (quill.base.css) or a theme stylesheet is
- included manually.
Example
-
-var editor = new Quill('#editor', {
- styles: {
- '.ql-editor': {
- 'font-family': "'Arial', san-serif"
- },
- '.ql-editor a': {
- 'text-decoration': 'none'
- }
- }
-});
-
- Quill uses the rich - text format to represent the editor’s contents, as well as changes to - those contents. In most cases directly dealing with Deltas can be - avoided. But it is available to provide a powerful interface to - Quill.
-A Delta representing the editor’s contents looks something like - this:
-
-{
- ops:[
- { insert: 'Gandalf', attributes: { bold: true } },
- { insert: ' the ' },
- { insert: 'Grey', attributes: { color: '#ccc' } }
- ]
-)
-
- A change looks something like this:
-
-{
- ops: [
- { retain: 12 },
- { delete: 4 },
- { insert: 'White', attributes: { color: '#fff' } }
- ]
-}
-
- Note there’s really no difference between the two; the contents - representation is simply the change from an empty document.
-Operations describe a singular change. They can be an insert, delete or retain. Note operations do not take an index. They always - describe the change at the current index. Use retains to “keep” or “skip” - certain parts of the document.
-Insert operations have an insert key defined. A String value represents
- inserting text. A Number value represents inserting an embed, with the
- value corresponding to an embed type (such as an image or video).
Quill recognizes the following embed types:
-
-{
- image: 1
-}
-
- In both cases of text and embeds, an optional attributes key can be defined with an Object
- to describe additonal formatting information. A format on the newline
- character describes the format for the line. Formats can be changed by
- the retain operation.
-// Insert a bolded "Text"
-{ insert: "Text", attributes: { bold: true } }
-
-// Insert a link
-{ insert: "Google", attributes: { link: 'https://www.google.com' } }
-
-// Insert an image
-{
- insert: 1,
- attributes: {
- image: 'https://octodex.github.com/images/labtocat.png'
- }
-}
-
-// Aligned text example
-{
- ops:[
- { insert: 'Right align' },
- { insert: '\n', attributes: { align: 'right' } },
- { insert: 'Center align' },
- { insert: '\n', attributes: { align: 'center' } }
- ]
-)
-
- Delete operations have a Number delete key defined representing the number of
- characters to delete. All embeds have a length of 1.
-// Delete the next 10 characters
-{ delete: 10 }
-
- Retain operations have a Number retain key defined representing the number of
- characters to keep (other libraries might use the name keep or skip). An
- optional attributes key can be
- defined with an Object to describe formatting changes to the character
- range. A value of null in the attributes Object represents removal of that
- key.
Note: It is not necessary to retain the last characters of a - document as this is implied.
-
-// Keep the next 5 characters
-{ retain: 5 }
-
-// Keep and bold the next 5 characters
-{ retain: 5, attributes: { bold: true } }
-
-// Keep and unbold the next 5 characters
-// More specifically, remove the bold key in the attributes Object
-// in the next 5 characters
-{ retain: 5, attributes: { bold: null } }
-
- Quill inherits from EventEmitter and allows - you access to listen to the following events:
-Emitted when the contents of Quill have changed. Details of the
- change, along with the source of the change are provided. The source will
- be "user" if it originates from
- the users. For example:
Changes may occur through an API but as long as they originate from
- the user, the provided source will still be "user". For example, when a user clicks on the
- toolbar, technically the toolbar module calls a Quill API to effect the
- change. But source is still "user"
- since the origin of the change was the user’s click.
Callback Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
delta |
- - Delta - | -Represention of change. | -
source |
- String | -Source of change. Will be either "user" or "api". |
-
Examples
-
-editor.on('text-change', function(delta, source) {
- if (source == 'api') {
- console.log("An API call triggered this change.");
- } else if (source == 'user') {
- console.log("A user action triggered this change.");
- }
-});
-
- Emitted when a user or API causes the selection to change, with a - range representing the selection boundaries. A null range indicates - selection loss (usually caused by loss of focus from the editor).
-You can also use this event as a focus change event by just checking - if the emitted range is null or not.
-Callback Parameters
-| Parameter | -Type | -Description | -
|---|---|---|
range |
- Object | -Object with start and end - keys indicating the corresponding indexes where the selection - exists. | -
source |
- String | -Source of change. Will be either "user" or "api". |
-
Examples
-
-editor.on('selection-change', function(range) {
- if (range) {
- if (range.start == range.end) {
- console.log('User cursor is on', range.start);
- } else {
- var text = editor.getText(range.start, range.end);
- console.log('User has highlighted', text);
- }
- } else {
- console.log('Cursor not in the editor');
- }
-});
-
- The two examples below demonstrate what is possible with Quill. Check out how they interact with each other!
-A basic editor with just a few formats to get started.
-
-var basicEditor = new Quill('#basic-editor');
-basicEditor.addModule('toolbar', {
- container: '#basic-toolbar'
-});
-
- Uses all the features of Quill, including Modules and Themes.
-
-// Initialize editor with custom theme and modules
-var fullEditor = new Quill('#full-editor', {
- modules: {
- 'authorship': { authorId: 'galadriel', enabled: true },
- 'multi-cursor': true,
- 'toolbar': { container: '#full-toolbar' },
- 'link-tooltip': true
- },
- theme: 'snow'
-});
-
-// Add basic editor's author
-var authorship = fullEditor.getModule('authorship');
-authorship.addAuthor('gandalf', 'rgba(255,153,51,0.4)');
-
-// Add a cursor to represent basic editor's cursor
-var cursorManager = fullEditor.getModule('multi-cursor');
-cursorManager.setCursor('gandalf', fullEditor.getLength()-1, 'Gandalf', 'rgba(255,153,51,0.9)');
-
-// Sync basic editor's cursor location
-basicEditor.on('selection-change', function(range) {
- if (range) {
- cursorManager.moveCursor('gandalf', range.end);
- }
-});
-
-// Update basic editor's content with ours
-fullEditor.on('text-change', function(delta, source) {
- if (source === 'user') {
- basicEditor.updateContents(delta);
- }
-});
-
-// basicEditor needs authorship module to accept changes from fullEditor's authorship module
-basicEditor.addModule('authorship', {
- authorId: 'gandalf',
- color: 'rgba(255,153,51,0.4)'
-});
-
-// Update our content with basic editor's
-basicEditor.on('text-change', function(delta, source) {
- if (source === 'user') {
- fullEditor.updateContents(delta);
- }
-});
-
- Quill currently supports a number of formats. Enabling a format:
-Note that enabling a format is distinct from adding a control in the - toolbar. By default all - supported formats are enabled.
-bolditalicstrikeunderlinefontsizecolorbackgroundimagelinkbulletlistalignTo customize the supported formats, pass in a whitelist array of - formats you wish to support.
-
-var editor = new Quill('#editor', {
- formats: ['bold', 'italic', 'color']
-});
-
- The Authorship module highlights the background of text to show who - wrote what.
-Enabling this module will also add a new format author to the list of recognized formats. The value of the author format is the id of the author. Changes
- made to the Quill editor will also attach the local author metadata.
| Parameter | -Type | -Description | -
|---|---|---|
authorId |
- String | -ID of current author. | -
button |
- String | -CSS selector for button that toggles authorship colors - on/off. | -
color |
- String | -Color to correspond with current author. Can be any valid CSS - color. | -
addAuthor(id, color)| Parameter | -Type | -Description | -
|---|---|---|
id |
- String | -ID of author to add. | -
color |
- String | -Color to correspond with author id. Can be any valid CSS - color. | -
-var editor = new Quill('#editor');
-
-var module = editor.addModule('authorship', {
- authorId: 'id-1234',
- button: '#author-button',
- color: 'rgb(255, 0, 255)'
-});
-
-module.addAuthor('id-5678', 'rgb(255, 255, 0)'); // Set external authors
-
-editor.on('text-update', function(delta) {
- // If the user types an 'a' into the editor, normally we would get:
- // delta.ops = [{ 'a' }]
- // But with the author module enabled we would now get:
- // delta.ops = [{ value: 'a', attributes: { author: 'id-1234' } }]
-});
-
- Modules allow Quill’s behavior and functionality to customized. To - enable a module, simply add it to the editor at initialization:
-
-var editor = new Quill('#editor', {
- modules: { toolbar: options }
-});
-
- Or you can add it later:
-
-editor.addModule('toolbar', options);
-
- A few common and officially supported modules are listed here:
-You can also build your own module. Simply register it with Quill.registerModule and the module will be passed - the corresponding Quill editor and options. Check out the Building a Custom Module guide for - a walkthrough.
-
-Quill.registerModule('armorer', function(quill, options) {
- switch(options.hero) {
- case 'aragorn':
- console.log('anduril');
- break;
- case 'bilbo':
- case 'frodo':
- console.log('sting');
- break;
- case 'eomer':
- console.log('guthwine');
- break;
- case 'gandalf':
- console.log('glamdring');
- break;
- default:
- console.log('stick');
- }
-});
-
-var quill = new Quill('#editor');
-quill.addModule('armorer', {
- hero: 'sam'
-});
-
- The Multiple Cursors modules enables the display of multiple external - cursors inside the Quill editor.
-| Parameter | -Type | -Description | -
|---|---|---|
template |
- String | -HTML template to use for cursor element. | -
timeout |
- Number | -Milliseconds of inaction before cursor flag is hidden. | -
setCursor(id, index, text,
- color)| Parameter | -Type | -Description | -
|---|---|---|
id |
- String | -ID of cursor. | -
index |
- Number | -Position to place the cursor. | -
text |
- String | -Text to place above cursor. | -
color |
- String | -Color of cursor. Can be any valid CSS color. | -
-var editor = new Quill('#editor');
-var module = editor.addModule('multi-cursor', {
- timeout: 10000
-});
-
-module.setCursor('id-1234', 10, 'Frodo', 'rgb(255, 0, 255)');
-
- The Toolbar module allow users to easily format Quill’s contents.
-Simply create a container and the module to the Quill editor.
-
-<!-- Create toolbar container -->
-<div id="toolbar">
- <!-- Add font size dropdown -->
- <select class="ql-size">
- <option value="10px">Small</option>
- <option value="13px" selected>Normal</option>
- <option value="18px">Large</option>
- <option value="32px">Huge</option>
- </select>
- <!-- Add a bold button -->
- <button class="ql-bold"></button>
-</div>
-<div id="editor"></div>
-
-<!-- Initialize editor and toolbar -->
-<script>
- var editor = new Quill('#editor');
- editor.addModule('toolbar', {
- container: '#toolbar' // Selector for toolbar container
- });
-</script>
-
- The ql-toolbar class will be
- added to the toolbar container.
A click handler will be added to any DOM element with the following - classes:
-ql-boldql-italicql-strikeql-underlineql-linkA change (DOM change event)
- handler will be added to any DOM element with the following classes:
ql-backgroundql-colorql-fontql-sizeThe toolbar will also listen to cursor movements and will add an
- ql-active class to elements in the
- toolbar that corresponds to the format of the text the cursor is on.
The following classes are also recognized by the toolbar but largely - used by Themes for styling:
-ql-format-buttonql-format-groupql-format-separatorThe best way to get started is a simple example. Quill is initialized - with a DOM element to contain the editor. The contents of that element - will become the initial contents of Quill.
-
-<!-- Create the toolbar container -->
-<div id="toolbar">
- <button class="ql-bold">Bold</button>
- <button class="ql-italic">Italic</button>
-</div>
-
-<!-- Create the editor container -->
-<div id="editor">
- <div>Hello World!</div>
- <div>Some initial <b>bold</b> text</div>
- <div><br></div>
-</div>
-
-<!-- Include the Quill library -->
-<script src="//cdn.quilljs.com/0.20.1/quill.js"></script>
-
-<!-- Initialize Quill editor -->
-<script>
- var quill = new Quill('#editor');
- quill.addModule('toolbar', { container: '#toolbar' });
-</script>
-
- Quill also supports a powerful API for - fine grain access and manipulation of the editor contents.
-
-<script>
- quill.on('text-change', function(delta, source) {
- console.log('Editor contents have changed', delta);
- });
-
- quill.insertText(11, ' Bilbo');
- console.log(quill.getText()); // Should output "Hello World Bilbo!\nSome initial bold text";
-</script>
-
- That’s all you need to do to set up a simple Quill editor! But the - power of Quill is its flexibility and extensibility. Check out the - Examples to see this in action. Or start - interacting with Quill with its flexible API.
-Themes allow you to easily make your Quill editor look good with - minimal effort.
-To use a custom theme, simply add its stylesheet in the <head>:
-<link rel="stylesheet" href="//cdn.quilljs.com/0.20.1/quill.snow.css" />
-
- and specify its usage at initialization:
-
-var editor = new Quill('#editor', {
- theme: 'snow'
-});
-
- There is currently only one predefined theme snow for Quill.
In the future we will provide more options and even allow you to - create your own. We will provide documentation and guidance here once - they are finalized.
-
Quill is open source. It is hosted and maintained on GitHub.
- Download Quill -Hello World!
'; -``` - - -## Configuration - -### matchers - -An array of matchers can be passed into Clipboard's configuration options. These will be appended after Quill's own default matchers. - -```javascript -var quill = new Quill('#editor', { - modules: { - clipboard: { - matchers: [ - ['B', customMatcherA], - [Node.TEXT_NODE, customMatcherB] - ] - } - } -}); -``` diff --git a/docs/1.0/docs/modules/history.md b/docs/1.0/docs/modules/history.md deleted file mode 100644 index 72114ae025..0000000000 --- a/docs/1.0/docs/modules/history.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -layout: v1.0-docs -title: History Module -permalink: /1.0/docs/modules/history/ ---- - -The History module is responsible for handling undo and redo for Quill. It can be configured with the following options: - -## Configuration - -#### delay - -- Default: `1000` - -Changes occuring within the `delay` number of milliseconds is merged into a single change. - -For example, with delay set to `0`, nearly every character is recorded as one change and so undo would undo one character at a time. With delay set to `1000`, undo would undo all changes that occured within the last 1000 milliseconds. - - -#### maxStack - -- Default: `100` - -Maximum size of the history's undo/redo stack. Merged changes with the `delay` option counts as a singular change. - - -#### userOnly - -- Default: `false` - -By default all changes, whether originating from user input or programmatically through the API, are treated the same and change be undone or redone by the history module. If `userOnly` is set to `true`, only user changes will be undone or redone. - - -### Example - -```javascript -var quill = new Quill('#editor', { - modules: { - history: { - delay: 2000, - maxStack: 500, - userOnly: true - } - }, - theme: 'snow' -}); -``` - -## API - -#### clear - -Clears the history stack. - -**Methods** - -```js -clear() -``` - -**Examples** - -```js -quill.history.clear(); -``` - - -#### cutoff experimental {#cutoff-experimental} - -Normally changes made in short succession (configured by `delay`) are merged as a single change, so that triggering an undo will undo multiple changes. Using `cutoff()` will reset the merger window so that a changes before and after `cutoff()` is called will not be merged. - -**Methods** - -```js -cutoff() -``` - -**Examples** - -```js -quill.history.cutoff(); -``` - - -#### undo - -Undo last change. - -**Methods** - -```js -undo() -``` - -**Examples** - -```js -quill.history.undo(); -``` - - -#### redo - -If last change was an undo, redo this undo. Otherwise does nothing. - -**Methods** - -```js -redo() -``` - -**Examples** - -```js -quill.history.redo(); -``` diff --git a/docs/1.0/docs/modules/keyboard.md b/docs/1.0/docs/modules/keyboard.md deleted file mode 100644 index 51b155140a..0000000000 --- a/docs/1.0/docs/modules/keyboard.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -layout: v1.0-docs -title: Keyboard Module -permalink: /1.0/docs/modules/keyboard/ ---- - -The Keyboard module enables custom behavior for keyboard events in particular contexts. Quill uses this to bind formatting hotkeys and prevent undesirable browser side effects. - - -### Key Bindings - -Keyboard handlers are bound to a particular key and key modifiers. The `key` is the JavaScript event key code, but string shorthands are allowed for alphanumeric keys and some common keys. - -Key modifiers include: `metaKey`, `ctrlKey`, `shiftKey` and `altKey`. In addition, `shortKey` is a platform specific modifier equivalent to `metaKey` on a Mac and `ctrlKey` on Linux and Windows. - -Handlers will be called with `this` bound to the keyboard instance and be passed the current selection range. - -```js -quill.keyboard.addBinding({ - key: 'B', - shortKey: true -}, function(range, context) { - this.quill.formatText(range, 'bold', true); -}); - -// addBinding may also be called with one parameter, -// in the same form as in initialization -quill.keyboard.addBinding({ - key: 'B', - shortKey: true, - handler: function(range, context) { - - } -}); -``` - -If a modifier key is `false`, it is assumed to mean that modifier is not active. You may also pass `null` to mean any value for the modifier. - -```js -// Only b with no modifier will trigger -quill.keyboard.addBinding({ key: 'B' }, handler); - -// Only shift+b will trigger -quill.keyboard.addBinding({ key: 'B', shiftKey: true }, handler); - -// Either b or shift+b will trigger -quill.keyboard.addBinding({ key: 'B', shiftKey: null }, handler); - -``` - -Multiple handlers may be bound to the same key and modifier combination. Handlers will be called synchronously, in the order they were bound. By default, a handler stops propagating to the next handler, unless it explicitly returns `true`. - - -```js -quill.keyboard.addBinding({ key: 'tab' }, function(range) { - // I will normally prevent handlers of the tab key - // Return true to let later handlers be called - return true; -}); -``` - -Note: Since Quill's default handlers are added at initialization, the only way to prevent them is to add yours in the [configuration](#configuration). - - -### Context - -Contexts enable further specification for handlers to be called only in particular scenarios. Regardless if context is specified, a context object is provided as a second parameter for all handlers. - -```js -// If the user hits backspace at the beginning of list or blockquote, -// remove the format instead delete any text -quill.keyboard.addBinding({ key: Keyboard.keys.BACKSPACE }, { - collapsed: true, - format: ['blockquote', 'list'], - offset: 0 -}, function(range, context) { - if (context.format.list) { - this.quill.format('list', false); - } else { - this.quill.format('blockquote', false); - } -}); -``` - -#### collapsed - -If `true`, handler is called only if the user's selection is collapsed, i.e. in cursor form. If `false`, the users's selection must be non-zero length, such as when the user has highlighted text. - - -#### empty - -If `true`, called only if user's selection is on an empty line, `false` for a non-empty line. Note setting empty to be true implies collapsed is also true and offset is 0—otherwise the user's selection would not be on an empty line. - -```js -// If the user hits enter on an empty list, remove the list instead -quill.keyboard.addBinding({ key: Keyboard.keys.ENTER }, { - empty: true, // implies collapsed: true and offset: 0 - format: ['list'] -}, function(range, context) { - this.quill.format('list', false); -}); -``` - - -#### format - -When an Array, handler will be called if *any* of the specified formats are active. When an Object, *all* specified formats conditions must be met. In either case, the context parameter will be an Object of all current active formats, the same returned by `quill.getFormat()`. - -```js -var context = { - format: { - list: true, // must be on a list, but can be any value - script: 'super', // must be exactly 'super', 'sub' will not suffice - link: false // cannot be in any link - } -}; -``` - - -#### offset - -Handler will be only called when the user's selection starts `offset` characters from the beginning of the line. Note this is before printable keys have been applied. This is useful in combination with other context specifications. - - -#### prefix - -Regex that must match the text immediately preceding the user's selection's start position. The text will not match cross format boundaries. The supplied `context.prefix` value will be the entire immediately preceding text, not just the regex match. - -```js -// When the user types space... -quill.keyboard.addBinding({ key: ' ' }, { - collapsed: true, - format: { list: false }, // ...on an line that's not already a list - prefix: /^-$/, // ...following a '-' character - offset: 1, // ...at the 1st position of the line, - // otherwise handler would trigger if the user - // typed hyphen+space mid sentence -}, function(range, context) { - // the space character is consumed by this handler - // so we only need to delete the hyphen - this.quill.deleteText(range.index - 1, 1); - // apply bullet formatting to the line - this.quill.formatLine(range.index, 1, 'list', 'bullet'); - // restore selection - this.quill.setSelection(range.index - 1); - - // console.log(context.prefix) would print '-' -}); -``` - -#### suffix - -The same as [`prefix`](#prefix) except matching text immediately following the user's selection's end position. - - -### Configuration - -By default, Quill comes with several useful key bindings, for example indenting lists with tabs. You can add your own upon initization. - -Some bindings are essential to preventing dangerous browser defaults, such as the enter and backspace keys. You cannot remove these bindings to revert to native browser behaviors. However since bindings specified in the configuration will run before Quill's defaults, you can handle special cases and propagate to Quill's otherwise. - -Adding a binding with `quill.keyboard.addBinding` will not run before Quill's because the defaults bindings will have been added by that point. - -Each binding config must contain `key` and `handler` options, and may optionally include any of the `context` options. - -```javascript -var bindings = { - // This will overwrite the default binding also named 'tab' - tab: { - key: 9, - handler: function() { - // Handle tab - } - }, - - // There is no default binding named 'custom' - // so this will be added without overwriting anything - custom: { - key: 'B', - shiftKey: true, - handler: function(range, context) { - // Handle shift+b - } - }, - - list: { - key: 'backspace', - format: ['list'], - handler: function(range, context) { - if (context.offset === 0) { - // When backspace on the first character of a list, - // remove the list instead - this.quill.format('list', false, Quill.sources.USER); - } else { - // Otherwise propogate to Quill's default - return true; - } - } - } -}; - -var quill = new Quill('#editor', { - modules: { - keyboard: { - bindings: bindings - } - } -}); -``` - - -### Peformance - -Like DOM events, Quill key bindings are blocking calls on every match, so it is a bad idea to have a very expensive handler for a very common key binding. Apply the same performance best practices as you would when attaching to common blocking DOM events, like `scroll` or `mousemove`. diff --git a/docs/1.0/docs/quickstart.md b/docs/1.0/docs/quickstart.md deleted file mode 100644 index f1f560b3be..0000000000 --- a/docs/1.0/docs/quickstart.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: v1.0-docs -title: Quickstart -permalink: /1.0/docs/quickstart/ -redirect_from: - - /1.0/docs/ ---- - -The best way to get started is try a simple example. Quill is initialized with a DOM element to contain the editor. The contents of that element will become the initial contents of Quill. - -```html - - - - -Hello World!
-Some initial bold text
-Pippin looked out from the shelter of Gandalf"s cloak. He wondered if he was awake or still sleeping, still in the swift-moving dream in which he had been wrapped so long since the great ride began. The dark world was rushing by and the wind sang loudly in his ears. He could see nothing but the wheeling stars, and away to his right vast shadows against the sky where the mountains of the South marched past. Sleepily he tried to reckon the times and stages of their journey, but his memory was drowsy and uncertain.
-There had been the first ride at terrible speed without a halt, and then in the dawn he had seen a pale gleam of gold, and they had come to the silent town and the great empty house on the hill. And hardly had they reached its shelter when the winged shadow had passed over once again, and men wilted with fear. But Gandalf had spoken soft words to him, and he had slept in a corner, tired but uneasy, dimly aware of comings and goings and of men talking and Gandalf giving orders. And then again riding, riding in the night. This was the second, no, the third night since he had looked in the Stone. And with that hideous memory he woke fully, and shivered, and the noise of the wind became filled with menacing voices.
-A light kindled in the sky, a blaze of yellow fire behind dark barriers Pippin cowered back, afraid for a moment, wondering into what dreadful country Gandalf was bearing him. He rubbed his eyes, and then he saw that it was the moon rising above the eastern shadows, now almost at the full. So the night was not yet old and for hours the dark journey would go on. He stirred and spoke.
-"Where are we, Gandalf?" he asked.
-"In the realm of Gondor," the wizard answered. "The land of Anórien is still passing by."
-There was a silence again for a while. Then, "What is that?" cried Pippin suddenly, clutching at Gandalf"s cloak. "Look! Fire, red fire! Are there dragons in this land? Look, there is another!"
-For answer Gandalf cried aloud to his horse. "On, Shadowfax! We must hasten. Time is short. See! The beacons of Gondor are alight, calling for aid. War is kindled. See, there is the fire on Amon Dîn, and flame on Eilenach; and there they go speeding west: Nardol, Erelas, Min-Rimmon, Calenhad, and the Halifirien on the borders of Rohan."
-But Shadowfax paused in his stride, slowing to a walk, and then he lifted up his head and neighed. And out of the darkness the answering neigh of other horses came; and presently the thudding of hoofs was heard, and three riders swept up and passed like flying ghosts in the moon and vanished into the West. Then Shadowfax gathered himself together and sprang away, and the night flowed over him like a roaring wind. -
-Pippin became drowsy again and paid little attention to Gandalf telling him of the customs of Gondor, and how the Lord of the City had beacons built on the tops of outlying hills along both borders of the great range, and maintained posts at these points where fresh horses were always in readiness to bear his errand-riders to Rohan in the North, or to Belfalas in the South. "It is long since the beacons of the North were lit," he said; "and in the ancient days of Gondor they were not needed, for they had the Seven Stones." Pippin stirred uneasily.
-"Sleep again, and do not be afraid!" said Gandalf. "For you are not going like Frodo to Mordor, but to Minas Tirith, and there you will be as safe as you can be anywhere in these days. If Gondor falls, or the Ring is taken, then the Shire will be no refuge."
-"You do not comfort me," said Pippin, but nonetheless sleep crept over him. The last thing that he remembered before he fell into deep dream was a glimpse of high white peaks, glimmering like floating isles above the clouds as they caught the light of the westering moon. He wondered where Frodo was, and if he was already in Mordor, or if he was dead; and he did not know that Frodo from far away looked on that same moon as it set beyond Gondor ere the coming of the day.
-Quill is a free, open source WYSIWYG editor built for the modern web. With its modular architecture and expressive API, it is completely customizable to fit any need.
-// <link href="https://cdn.quilljs.com/1.2.6/quill.snow.css" rel="stylesheet">
-// <script src="https://cdn.quilljs.com/1.2.6/quill.min.js"></script>
-
-var quill = new Quill('#editor', {
- modules: {
- toolbar: '#toolbar'
- },
- theme: 'snow'
-});
-
-// Open your browser's developer console to try out the API!
-
- Built with
--
https://en.wikipedia.org/wiki/One_Ring
-Three Rings for the Elven-kings under the sky,
-Seven for the Dwarf-lords in halls of stone,
-Nine for Mortal Men, doomed to die,
-One for the Dark Lord on his dark throne.
-In the Land of Mordor where the Shadows lie.
-One Ring to rule them all, One Ring to find them,
-One Ring to bring them all and in the darkness bind them.
-In the Land of Mordor where the Shadows lie.
\ No newline at end of file diff --git a/docs/_includes/meta.html b/docs/_includes/meta.html deleted file mode 100644 index 7033cb7d86..0000000000 --- a/docs/_includes/meta.html +++ /dev/null @@ -1,26 +0,0 @@ - - - - -{% if page.description %} - -{% else %} - -{% endif %} - - -{% if page.path != "index.html" %} - -{% else %} - -{% endif %} - - - - - - - - - -{% feed_meta %} \ No newline at end of file diff --git a/docs/_includes/open-source.html b/docs/_includes/open-source.html deleted file mode 100644 index a68749b504..0000000000 --- a/docs/_includes/open-source.html +++ /dev/null @@ -1,12 +0,0 @@ -
-// Implement and register module
-Quill.registerModule('counter', function(quill, options) {
- var container = document.querySelector('#counter');
- quill.on('text-change', function() {
- var text = quill.getText();
- // There are a couple issues with counting
- // this way but we'll fix this later
- container.innerHTML = text.split(/\s+/).length;
- });
-});
-
-// We can now initialize Quill with something like this:
-var quill = new Quill('#editor', {
- modules: {
- counter: true
- }
-});
-
-Quill.registerModule('counter', function(quill, options) {
- var container = document.querySelector(options.container);
- quill.on('text-change', function() {
- var text = quill.getText();
- if (options.unit === 'word') {
- container.innerHTML = text.split(/\s+/).length + ' words';
- } else {
- container.innerHTML = text.length + ' characters';
- }
- });
-});
-
-var quill = new Quill('#editor', {
- modules: {
- counter: {
- container: '#counter',
- unit: 'word'
- }
- }
-});
-
-var Counter = function(quill, options) {
- this.quill = quill;
- this.options = options;
- var container = document.querySelector(options.container);
- var _this = this;
- quill.on('text-change', function() {
- var length = _this.calculate();
- container.innerHTML = length + ' ' + options.unit + 's';
- });
-};
-
-Counter.prototype.calculate = function() {
- var text = this.quill.getText();
- if (this.options.unit === 'word') {
- return text.split(/\s+/).length;
- } else {
- return text.length;
- }
-};
-
-Quill.registerModule('counter', Counter);
-
-var quill = new Quill('#editor');
-var counter = quill.addModule('counter', {
- container: '#counter',
- unit: 'word'
-});
-
-// We can now access calculate() directly
-console.log(counter.calculate(), 'words');
-
-var Counter = function(quill, options) {
- this.quill = quill;
- this.options = options;
- this.container = document.querySelector(options.container);
- quill.on('text-change', this.update.bind(this));
- this.update(); // Account for initial contents
-};
-
-Counter.prototype.calculate = function() {
- var text = this.quill.getText();
- if (this.options.unit === 'word') {
- text = text.trim();
- // Splitting empty text returns a non-empty array
- return text.length > 0 ? text.split(/\s+/).length : 0;
- } else {
- return text.length;
- }
-};
-
-Counter.prototype.update = function() {
- var length = this.calculate();
- var label = this.options.unit;
- if (length !== 1) {
- label += 's';
- }
- this.container.innerHTML = length + ' ' + label;
-}
-
-Quill.registerModule('counter', Counter);
-
-var quill = new Quill('#editor');
-var counter = quill.addModule('counter', {
- container: '#counter',
- unit: 'word'
-});
-The 2.0 branch of Quill has officially been opened and development commenced. One design principle Quill embraces is to first make it possible, then make it easy. This allows the technical challenges to be proved out and provides clarity around use cases so that the right audience is designed for. Quill 1.0 pushed the boundaries on the former, and now 2.0 will focus on the latter.
-- Let’s take a look at how we got here and where Quill is going! -
- Read more -