Yii 2 implementation of Quill, modern WYSIWYG editor.
You can find Quill at https://quilljs.com/
Run console command
composer require bizley/quill:^3.3
Or add the package to your composer.json
:
{
"require": {
"bizley/quill": "^3.3"
}
}
and run composer update
.
This package might depend on some NPM packages. Make sure you can fetch them by configuring your
composer.json
properly (i.e. by using https://asset-packagist.org/ - see instructions there).
Use it as an active field extension
<?= $form->field($model, $attribute)->widget(\bizley\quill\Quill::class, []) ?>
Or as a standalone widget
<?= \bizley\quill\Quill::widget(['name' => 'editor', 'value' => '']) ?>
theme string default 'snow'
'snow'
(Quill::THEME_SNOW
) for Quill's snow theme,
'bubble'
(Quill::THEME_BUBBLE
) for Quill's bubble theme,
false
or null
to remove theme (you might need to provide your own toolbar in case of no theme).
See Quill's documentation for themes.
toolbarOptions boolean|string|array default true
true
for theme's default toolbar,
'FULL'
(Quill::TOOLBAR_FULL
) for full Quill's toolbar,
'BASIC'
(Quill::TOOLBAR_BASIC
) for few basic toolbar options,
array for toolbar configuration (see below).
Quill's toolbar from version 1.0 can be easily configured with custom set of buttons.
See Toolbar module documentation for details.
You can pass PHP array to 'toolbarOptions'
parameter to configure this module (it will be JSON-encoded).
For example, to get:
new Quill('#editor', {
modules: {
toolbar: [['bold', 'italic', 'underline'], [{'color': []}]]
}
});
add the following code in widget configuration:
[
'toolbarOptions' => [['bold', 'italic', 'underline'], [['color' => []]]],
],
Quill editor is rendered in div
container (this can be changed by setting 'tag'
parameter) and edited content is
copied to hidden input field so it can be used in forms. You can modify container's HTML attributes by setting
'options'
parameter and hidden field HTML attributes by setting 'hiddenOptions'
parameter.
When allowResize
option is set to false
(default) editor's height is 150px (this can be changed by setting
'options'
parameter). Setting allowResize
to true
resets the minimum height and allows it to be expanded freely.
Editor's box extends as new text lines are added.
By default, Quill is provided through the CDN (https://cdn.quilljs.com). You can change the Quill's version set with the
current yii2-quill's release by changing 'quillVersion'
parameter but some options may not work correctly in this case.
Starting from version 3.0.0 you can use local assets for Quill provided through NPM packet manager - to do
so run
composer require npm-asset/quill:^1.3
Or add the package to your composer.json
:
{
"require": {
"npm-asset/quill": "^1.3"
}
}
You also need to set ['localAssets' => true]
in Quill's configuration.
You can use parameter 'js'
to append additional JS code.
For example, to disable user input Quill's API provides this JS:
quill.enable(false);
To get the same through widget's configuration add the following code:
[
'js' => '{quill}.enable(false);',
],
{quill}
placeholder will be automatically replaced with the editor's object variable name.
For more details about Quill's API visit https://quilljs.com/docs/api/
Quill can render math formulas using the KaTeX library.
To add this option configure widget with Formula module:
[
'modules' => [
'formula' => true, // Include formula module
],
'toolbarOptions' => [['formula']], // Include button in toolbar
]
By default, KaTeX is provided through the CDN (https://cdn.jsdelivr.net). You can change the version of KaTeX by setting
the 'katexVersion'
parameter. Starting from version 3.0.0 you can use local assets for KaTeX provided through NPM
packet manager - to do so run
composer require npm-asset/katex:^0.15
Or add the package to your composer.json
:
{
"require": {
"npm-asset/katex": "^0.15"
}
}
You also need to set ['localAssets' => true]
in Quill's configuration.
Quill can automatically detect and apply syntax highlighting using the highlight.js library. To add this option configure widget with Syntax Highlighter module:
[
'modules' => [
'syntax' => true, // Include syntax module
],
'toolbarOptions' => [['code-block']] // Include button in toolbar
]
By default, highlight.js is provided through the CDN (https://cdn.jsdelivr.net). You can change the version of
highlight.js by setting the 'highlightVersion'
parameter. Starting from version 3.0.0 you can use local assets for
highlight.js provided through NPM packet manager - to do so run
composer require npm-asset/highlight.js:^11.4
Or add the package to your composer.json
:
{
"require": {
"npm-asset/highlight.js": "^11.4"
}
}
You also need to set ['localAssets' => true]
in Quill's configuration.
You can change the default highlight.js stylesheet (for both CDN and local version) by setting the 'highlightStyle'
parameter. See the list of possible styles.
You can add Smart Break (support for shift + enter) by using the quill-smart-break plugin:
[
'modules' => [
'smart-breaker' => true,
],
]
Starting from version 3.1.0 quill-smart-break is provided through NPM packet manager by local asset. For
previous versions you would have to add it through custom JS (see js
property).
Run
composer require npm-asset/quill-smart-break:^0.2
Or add the package to your composer.json
:
{
"require": {
"npm-asset/quill-smart-break": "^0.2"
}
}
You also need to set ['localAssets' => true]
in Quill's configuration.