Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/cloudcreativity/ember-quill

The Quill rich-text editor for Ember.
https://github.com/cloudcreativity/ember-quill
Last synced: 18 days ago
JSON representation
The Quill rich-text editor for Ember.
Host: GitHub
URL: https://github.com/cloudcreativity/ember-quill
Owner: cloudcreativity
License: mit
Created: 2020-12-08T17:56:19.000Z (about 4 years ago)
Default Branch: develop
Last Pushed: 2021-03-30T16:55:26.000Z (over 3 years ago)
Last Synced: 2024-11-12T10:48:43.028Z (about 1 month ago)
Language: JavaScript
Size: 466 KB
Stars: 4
Watchers: 3
Forks: 4
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project

README

        # @cloudcreativity/ember-quill

The [Quill](https://quilljs.com/) 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](#introduction)

- [Examples](#examples)

- [`` Component](#quill-component)

- [`` Component](#quill-editor-component)

- [Quill Service](#quill-service)

- [Quill Static Methods](#quill-static-methods)

- [Testing](#testing)

### Introduction

This addon provides components for working with the [Quill](https://quilljs.com)

rich text editor in Ember.

### Examples

Use the `` component to create your toolbar and editor:

```hbs

  

    

      

      

      

    

    

      

      

    

  

  

  


    Characters: {{Ql.characters}}


    Words: {{Ql.words}}

  


```

Or just use the `` component by itself:

```hbs

```

### Quill Component

The `` 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 `` 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](https://quilljs.com/docs/modules/toolbar/),

for example:

```hbs

  

    

    

  

```

The toolbar yields components for all the toolbar controls supported by

Quill. These are either `` and/or `` elements. The

supported controls are:

| Control | Type |

| --- | --- |

| `align` | `` or `` |

| `background` | `` |

| `blockquote` | `` |

| `bold` | `` |

| `clean` | `` |

| `code-block` | `` |

| `code` | `` |

| `color` | `` |

| `direction` | `` |

| `font` | `` |

| `formula` | `` |

| `header` | `` or `` |

| `image` | `` |

| `indent` | `` |

| `italic` | `` |

| `link` | `` |

| `list` | `` |

| `script` | `` |

| `size` | `` |

| `strike` | `` |

| `underline` | `` |

| `video` | `` |

For `` elements, set the `value` attribute if required. For example,

the `bold` button does not need a `value`, but the `list` button does:

```hbs

```

For `` elements, provide the list of values using the `@value`

argument with the `{{array}}` helper:

```hbs

```

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:

```hbs

```

Some controls, e.g. `header`, work as either `` or ``

elements. For these, you **must** provide a `@values` argument if you

want to use a ``. Otherwise a `` will be used. For example:

```hbs

```

The `group` component allows you to group controls, i.e. add space between

sets of controls. This is done by using a `` with the `ql-formats`

class:

```hbs

  

  

  

  

```

#### Editor

Use the yielded `editor` to create the container `
` for the Quill Editor.

This is automatically configured with the selector for your HTML toolbar:

```hbs

  

    

  

  

```

The yielded `` is an instance of the `` component.

This component, along with all of its options,

[is described below.](#quill-editor-component)

#### Values

The `` 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's `getLength` method always returns `1` 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 the `length` and

> the `characters` values.

For example, to display the number of words to the user:

```hbs

  

  Words: {{Ql.words}}

```

### Quill Editor Component

The `` 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 `` component.

#### Configuration

The following [Quill configuration](https://quilljs.com/docs/configuration/)

options are supported when initialising Quill:

- `bounds`

- `debug`

- `formats`

- `modules`

- `placeholder`

- `readOnly`

- `scrollingContainer`

- `theme`

For example:

```hbs

```

> 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 `` component accepts an `@enabled` argument. Changing this

value allows you to toggle whether the editor is enabled or not.

For example:

```hbs

```

> The `{{not}}` helper is provided by the

[Ember Truth Helpers addon.](https://github.com/jmurphyau/ember-truth-helpers)

#### Focused

The `@focused` argument allows you to give the editor focus when it is

rendered. For example:

```hbs

```

#### 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:

```hbs

```

> The value you provide for the `@delta` argument does not need to be a

Quill Delta instance. The editor's `setContents` 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:

```hbs

```

> If you provide a value to the `@delta` argument, the `@text` argument

will be ignored.

#### Events

To subscribe to [Quill events](https://quilljs.com/docs/api/#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 `` component, the `@onLength` and

`@onWords` actions are already wired up to provide the yielded `length`,

`characters` and `words` 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 `` component,

making sure that the name is unique for each editor you have rendered.

For example:

```hbs

  

  

```

Then inject the service, for example:

```js

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.](https://quilljs.com/docs/api/)

- `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` or `enable` methods, the `@enabled` argument

on the `` 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

`` 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:

```js

const quill = this.quillService.instance('my-editor');

if (quill) {

  // ...

}

```

### Quill Static Methods

To call static Quill methods, import Quill as follows:

```js

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:

```js

test('it renders', async function (assert) {

  this.set('delta', {

    ops: [

      { insert: 'This is my story.\n'}

    ],

  });

  await render(hbs`

    

  `);

  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](CONTRIBUTING.md) guide for details.

## License

This project is licensed under the [MIT License](LICENSE.md).