README
@cloudcreativity/ember-quill
The Quill rich text editor for Ember.
Compatibility
- Ember.js v3.16 or above
- Ember CLI v2.13 or above
- Node.js v10 or above
Installation
ember install @cloudcreativity/ember-quill
Usage
Contents
- Introduction
- Examples
<Quill>
Component<QuillEditor>
Component- Quill Service
- Quill Static Methods
- Testing
Introduction
This addon provides components for working with the Quill rich text editor in Ember.
Examples
Use the <Quill>
component to create your toolbar and editor:
<Quill as |Ql|>
<Ql.toolbar as |Tb|>
<Tb.group>
<Tb.bold />
<Tb.italic />
<Tb.underline />
</Tb.group>
<Tb.group>
<Tb.list value="ordered" />
<Tb.list value="bullet" />
</Tb.group>
</Ql.toolbar>
<Ql.editor
@delta={{this.delta}}
@focused={{true}}
@onChange={{this.setDelta}}
@placeholder="Tell us your story."
@theme="snow"
/>
<div>
Characters: {{Ql.characters}}<br>
Words: {{Ql.words}}
</div>
</Quill>
Or just use the <QuillEditor>
component by itself:
<QuillEditor
@delta={{this.delta}}
@onChange={{this.setDelta}}
@placeholder="Tell us your story."
@theme="snow"
/>
Quill Component
The <Quill>
component is a wrapper component that allows you to create the
editor's toolbar via HTML. It ensures that the editor is wired correctly
to use the HTML toolbar.
In addition, the <Quill>
component yields the length and number of words
of the editor contents, so that you can display these to the user if
desired.
Toolbar
Use the yielded toolbar
to build your
editor's toolbar,
for example:
<Quill as |Ql|>
<Ql.toolbar as |Tb|>
<Tb.bold />
<Tb.italic />
</Ql.toolbar>
</Quill>
The toolbar yields components for all the toolbar controls supported by
Quill. These are either <button>
and/or <select>
elements. The
supported controls are:
Control | Type |
---|---|
align |
<button> or <select> |
background |
<select> |
blockquote |
<button> |
bold |
<button> |
clean |
<button> |
code-block |
<button> |
code |
<button> |
color |
<select> |
direction |
<button> |
font |
<select> |
formula |
<button> |
header |
<button> or <select> |
image |
<button> |
indent |
<button> |
italic |
<button> |
link |
<button> |
list |
<button> |
script |
<button> |
size |
<select> |
strike |
<button> |
underline |
<button> |
video |
<button> |
For <button>
elements, set the value
attribute if required. For example,
the bold
button does not need a value
, but the list
button does:
<Tb.bold />
<Tb.list value="ordered" />
<Tb.list value="bullet" />
For <select>
elements, provide the list of values using the @value
argument with the {{array}}
helper:
<Tb.size @values={{array "small" false "large" "huge"}} />
Provide an empty value if you want to use the theme's default values.
For example, the Snow theme provides a list of 35 colors for the
color
and background
toolbar options. To use the defaults:
<Tb.color />
<Tb.background />
Some controls, e.g. header
, work as either <button>
or <select>
elements. For these, you must provide a @values
argument if you
want to use a <select>
. Otherwise a <button>
will be used. For example:
<!-- Header Buttons -->
<Tb.header value="1" />
<Tb.header value="2" />
<!-- Header Select -->
<Tb.header @values={{array 1 2 3 4}} />
<!-- Header Select with Theme Defaults -->
<Tb.header @values={{array}} />
The group
component allows you to group controls, i.e. add space between
sets of controls. This is done by using a <span>
with the ql-formats
class:
<Tb.group>
<Tb.bold />
<Tb.italic />
</Tb.group>
<Tb.group>
<Tb.list value="ordered" />
<Tb.list value="bullet" />
</Tb.group>
Editor
Use the yielded editor
to create the container <div>
for the Quill Editor.
This is automatically configured with the selector for your HTML toolbar:
<Quill as |Ql|>
<Ql.toolbar>
<!-- toolbar -->
</Ql.toolbar>
<Ql.editor @theme="snow" />
</Quill>
The yielded <Ql.editor>
is an instance of the <QuillEditor>
component.
This component, along with all of its options,
is described below.
Values
The <Quill>
components also yields the following values:
Value | Description |
---|---|
length |
The length of editor content, provided by Quill's getLength method. |
characters |
The length minus one. |
words |
The number of words in the editor content. |
When the Quill Editor is empty, there is always a blank line representated by
\n
. This means Quill'sgetLength
method always returns1
for an empty editor. Typically if you want to display the length to users, you would need to subtract 1 from the length. This is why we yield both thelength
and thecharacters
values.
For example, to display the number of words to the user:
<Quill as |Ql|>
<!-- Toolbar and Editor -->
Words: {{Ql.words}}
</Quill>
Quill Editor Component
The <QuillEditor>
component can be used by itself if you do not want to
define your toolbar in HTML. All the options described here can also be used
when displaying the editor within the <Quill>
component.
Configuration
The following Quill configuration options are supported when initialising Quill:
bounds
debug
formats
modules
placeholder
readOnly
scrollingContainer
theme
For example:
<QuillEditor @formats={{array "bold" "italic"}} @theme="snow" />
Quill does not provide a way of changing these values after initialisation. Therefore, changing these values after the component has been rendered is not supported.
Enabled
The <QuillEditor>
component accepts an @enabled
argument. Changing this
value allows you to toggle whether the editor is enabled or not.
For example:
<QuillEditor @enabled={{not this.formIsDisabled}} />
The
{{not}}
helper is provided by the Ember Truth Helpers addon.
Focused
The @focused
argument allows you to give the editor focus when it is
rendered. For example:
<QuillEditor @focused={{true}} />
Delta
Use the @delta
argument to provide the initial value of the editor using
a Quill Delta. This is one-way bound: to subscribe to changes to the
delta, use the onChange
action:
<QuillEditor @delta={{this.delta}} @onChange={{this.setDelta}} />
The value you provide for the
@delta
argument does not need to be a Quill Delta instance. The editor'ssetContents
method that is used to set the delta does accept the delta JSON.
Text
If you want to use plain text to set the initial value of the editor, use
the @text
argument. This is one-way bound: to subscribe to changes to
the text, use the onText
action:
<QuillEditor @text={{this.text}} @onText={{this.setText}} />
If you provide a value to the
@delta
argument, the@text
argument will be ignored.
Events
To subscribe to Quill events, use the following actions:
Quill Event | Action |
---|---|
text-change |
@onTextChange |
selection-change |
@onSelectionChange |
editor-change |
@onEditorChange |
We also provide the following custom events:
Action | Description |
---|---|
@onChange |
Provides the updated delta for the editor, provided by Quill's getContents method. |
@onText |
Provides the updated editor text, provided by Quill's getText method. |
@onLength |
Provides the length of the editor content, provided by Quill's getLength method. |
@onWords |
Provides the number of words in the editor content. |
Warning: If you are using the
<Quill>
component, the@onLength
and@onWords
actions are already wired up to provide the yieldedlength
,characters
andwords
values. If you use the@onLength
or@onWords
actions, the yielded values will NOT update.
Quill Service
If you need to interact with a Quill editor programmatically, you can do this via the Quill service.
All Quill instances are registered with the service using a name. To interact
with an instance, provide the @name
argument to the <QuillEditor>
component,
making sure that the name is unique for each editor you have rendered.
For example:
<Quill as |Ql|>
<!-- Toolbar -->
<Ql.editor @name="my-editor" />
</Quill>
<QuillEditor @name="other-editor" />
Then inject the service, for example:
import Component from '@glimmer/component';
import { inject as service } from '@ember/service';
import { action } from '@ember/object';
export default class CustomComponent extends Component {
@service('quill') quillService;
@action
resetEditor() {
this.quillService.setText('my-editor', '');
}
}
The service provides all the following Quill methods. Each takes the name of the editor instance, followed by the arguments as defined in the Quill API documentation.
deleteText
getContents
getLength
insertEmbed
insertText
setContents
setText
updateContents
format
formatLine
formatText
getFormat
removeFormat
getBounds
getSelection
blur
disable
enable
focus
hasFocus
update
If you use the
disable
orenable
methods, the@enabled
argument on the<QuillEditor>
component will get out-of-sync. We recommend using the@enabled
argument rather than the methods via the service.
As Quill editor instances are deregistered from the service when the
<QuillEditor>
component is being destroyed, any methods that return values
will return null
if the named editor does not exist on the Quill service.
If you need to call multiple methods on a Quill instance, you can use the
service's instance
method to retrieve the named editor. This will return
null
if the editor is no longer registered:
const quill = this.quillService.instance('my-editor');
if (quill) {
// ...
}
Quill Static Methods
To call static Quill methods, import Quill as follows:
import Quill from 'quill';
var Module = Quill.import('core/module');
class CustomModule extends Module {}
Quill.register('modules/custom-module', CustomModule);
Testing
All Quill event handlers are executed via the Ember runloop, to ensure that you can easily use your Quill components in tests.
Use the fillIn
test helper with the .ql-editor
selector:
test('it renders', async function (assert) {
this.set('delta', {
ops: [
{ insert: 'This is my story.\n'}
],
});
await render(hbs`
<QuillEditor
@delta={{this.delta}}
@onChange={{action (mut this.delta)}}
/>
`);
assert.dom('.ql-editor').hasText('This is my story.');
await fillIn('.ql-editor', 'This is my other story.');
assert.deepEqual(this.delta.ops, [
{ insert: 'This is my other story.\n' },
]);
});
Contributing
See the Contributing guide for details.
License
This project is licensed under the MIT License.