Quill


(Bizley) #1

Yii 2 implementation of Quill, modern WYSIWYG editor.

[size="5"]Quill[/size]

You can find Quill at http://quilljs.com

  • Documentation

  • Examples

  • GitHub

[size="5"]yii2-quill[/size]

[size="4"]Installation[/size]

Easiest way to install this extension is through the Composer.

Add in your composer.json:


"bizley/quill": "*"

or run console command:


php composer.phar require bizley/quill "*"

[size="4"]Usage[/size]

Use it as an active field extension


<?= $form->field($model, $attribute)->widget(bizley\quill\Quill::className(), []) ?>

or as a standalone widget


<?= bizley\quill\Quill::widget(['name' => 'editor']) ?>

[size="4"]Parameters[/size]

  • theme string default ‘bootstrap’

    false or null for Quill’s default theme with quill.base.css,

    ‘snow’ for Quill’s snow theme with quill.snow.css,

    ‘bootstrap’ for snow theme with editor wrapped in Bootstrap’s panel

    You can set theme in configs array instead but this is the only way to set ‘bootstrap’ theme.

    See Quill’s documentation for themes.

  • toolbar string or array default ‘full’

    In case of string:

    false or null to switch toolbar off,

    ‘full’ for full Quill’s toolbar as seen here,

    ‘basic’ for few basic toolbar options,

    anything else for single button (see below).

    In case of array:

    string element for single button (see below),

    array element for buttons grouped together - every element of this array should be string (a single button).

  • configs array default []

    Array of Quill’s configuration. This is the equivalent of Quill’s configs variable

[size="4"]Toolbar[/size]

Quill allows you to add your own HTML toolbar for the editor. This is very flexible solution but in most cases you just need to get few standard buttons without worrying about the HTML tags and where and how to properly place them.

With yii2-quill it is quite simple - there are predefined buttons you can use:

  • ‘|’ separator,

  • ‘b’ bold,

  • ‘i’ italic,

  • ‘u’ underline,

  • ‘s’ strikethrough,

  • ‘font’ font family,

  • ‘size’ font size,

  • ‘textColor’ font colour,

  • ‘backColor’ background colour,

  • ‘ol’ ordered list,

  • ‘ul’ bullet list,

  • ‘alignment’ text alignment,

  • ‘link’ link,

  • ‘image’ image

With toolbar parameter set to ‘full’ all these buttons are added. ‘basic’ gives you only ‘b’, ‘i’, ‘u’, ‘s’, ‘ol’, ‘ul’, ‘alignment’, ‘link’.

In case you want totally different set of buttons you can set them like:


'toolbar' => ['b', 'i', 'u', '|', 'font', '|', 'alignment'],

If you want to group some buttons together use nested arrays:


'toolbar' => [['b', 'i', 'u'], ['font', 'alignment']],

And don’t worry about adding modules in configs for ‘link’ and ‘image’ options - this is done automatically.

You may wonder what to do in case of adding some button that is not listed here - simply just put the HTML code of the button inside the toolbar array. And there is still this option to create separate toolbar from the scratch - you can add toolbar module with its container’s ID in the configs array as seen here.

[size="5"]GitHub repo[/size]

https://github.com/bizley-code/yii2-quill


(Bizley) #2

[size="6"]Quill v1.0 is finally here (no more beta) and so yii2-quill gets v2.0[/size]

[size="5"]Installation[/size]

Easiest way to install this extension is through the Composer.

Add in your composer.json:


"bizley/quill": "^2.0"

or run console command:


php composer.phar require "bizley/quill ^2.0"

If you want to install Quill beta version add:


"bizley/quill": "^1.0"

[size="5"]Basic parameters[/size]

  • theme string default [font=“Courier New”]‘snow’[/font]

    [font=“Courier New”]‘snow’[/font] ([font=“Courier New”]Quill::THEME_SNOW[/font]) for Quill’s snow theme,

    [font=“Courier New”]‘bubble’[/font] ([font=“Courier New”]Quill::THEME_BUBBLE[/font]) for Quill’s bubble theme,

    [font="Courier New"]false[/font] or [font="Courier New"]null[/font] to remove theme.

    See Quill’s documentation for themes.

  • toolbarOptions boolean|string|array default [font="Courier New"]true[/font]

    [font=“Courier New”]true[/font] for theme’s default toolbar,

    [font=“Courier New”]‘FULL’[/font] ([font=“Courier New”]Quill::TOOLBAR_FULL[/font]) for full Quill’s toolbar,

    [font=“Courier New”]‘BASIC’[/font] ([font=“Courier New”]Quill::TOOLBAR_BASIC[/font]) for few basic toolbar options,

    [font="Courier New"]array[/font] for toolbar configuration (see below).

[size="5"]Toolbar[/size]

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 [font=“Courier New”]‘toolbarOptions’[/font] 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' => []]]],

],



Toolbar configuration for previous yii2-quill version (^1.0 with Quill beta) is deprecated.

[size="5"]Additional information[/size]

[size=“4”]Container and form’s input[/size]

Quill editor is rendered in [font=“Courier New”]div[/font] container (this can be changed by setting [font=“Courier New”]‘tag’[/font] parameter)

and edited content is copied to hidden input field so it can be used in forms.

[size=“4”]Editor box’s height[/size]

Default editor height is 150px (this can be changed by setting [font=“Courier New”]‘options’[/font] parameter) and

its box extends as new text lines are added.

[size="4"]Quill source[/size]

Quill’s JS code is provided by CDN. You can change the Quill’s version set with the current yii2-quill’s

release by changing [font=“Courier New”]‘quillVersion’[/font] parameter but some options may not work correctly in this case.

[size="4"]Additional JavaScript code[/size]

You can use parameter [font=“Courier New”]‘js’[/font] 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);',

],



[font=“Courier New”]{quill}[/font] 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/

[size="4"]Formula module[/size]

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

]



You can change the version of KaTeX by setting the [font=“Courier New”]‘katexVersion’[/font] parameter.

[size="4"]Syntax Highlighter module[/size]

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

]



You can change the version of highlight.js by setting the [font=“Courier New”]‘highlightVersion’[/font] parameter.

You can change the default highlight.js stylesheet by setting the [font=“Courier New”]‘highlightStyle’[/font] parameter.

See the list of possible styles (all files ending with [font="Courier New"].min.css[/font]).


(Medina) #3

That´s exaclty the editor we were searching for. We will implement it on further versions of Menapro instead tinymce. But we´d like to know if there is the posibility to show a dialog before inserting a picture (alt attribute).


(Bizley) #4

Quill is very flexible so it’s definitely possible. You have to create your image handler and add it to the editor.

As an example of custom image handler this is what I’m using inside Podium (forum module extension) now:




<?= $form->field($model, $attribute)->widget(\bizley\quill\Quill::className(), [

    'toolbarOptions' => [

        // buttons here ...

    ],

    'js' => "{quill}.getModule('toolbar').addHandler('image', imageHandler);

function imageHandler() {

    var range = this.quill.getSelection();

    var value = prompt('URL:');

    this.quill.insertEmbed(range.index, 'image', value, Quill.sources.USER);

}"

]) ?>



With this handler images are added as URL addresses instead of base64-encoded data.


(Medina) #5

Ok. Thanks. We´ll give it a try.


(smohadjer) #6

Does anyone know how I can add custom attributes such as form=“formId” to the hidden input field that quill generates and uses to submit the content of editor? I used the following code, but the form attribute ended up on a div container rather than on the hidden input field!

			$form->field($model, 'press_release', [
			'options' => ['form' => 'starterWizard__form']
			])
			->label('Add press release:')
			->widget(\bizley\quill\Quill::class, [
				'toolbarOptions' => 'FULL'
			]);

(Bizley) #7

Made possible in yii2-quill 2.5.0 :wink: