Download the PHP package ehyiah/ux-quill without Composer
On this page you can find all versions of the php package ehyiah/ux-quill. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download ehyiah/ux-quill
More information about ehyiah/ux-quill
Files in ehyiah/ux-quill
Package ux-quill
Short Description Symfony UX Bundle to use Quill JS wysiwyg text editor with full and easy customisation
License MIT
Informations about the package ux-quill
QuillJs Bundle for Symfony using Symfony UX
Symfony UX Bundle implementing the Quill JS Wysiwyg https://quilljs.com/
If you need an easy-to-use WYSIWYG (with no complex configuration) into a symfony project, this is what you need.
It comes with some extra features out of the box like image uploading to custom endpoint instead of base64 only.
-
Installation
- Basic Usage
-
Display Result
-
Customize quillJS with options and extra_options
- Handle images uploads
-
Handle images uploads security
-
Customize toolbar icons
-
Extend Quill stimulus controller
- EasyAdmin Integration
- EasyAdmin Usage
Installation
Step 1 Require bundle
If you are using the AssetMapper Component you're done !
step 2 next run (If you are using webpack encore, not needed with AssetMapper)
OR
It's done, you can use the QuillType to build a QuillJs WYSIWYG
You can add as many WYSIWYG fields inside same page like any normal fields.
Basic Usage
In a form, use QuillType. It works like a classic Type except it has more options : e.g:
Display result
in a twig template :
-
if you use the default class styling option you may need to encapsulate the content so the quill stylesheet can be applied like this :
- if you use the inline styling option simply :
For the most basic this is only what you have to do.
Customize Options
quill_options :
This is where you will choose what elements you want to display in your WYSIWYG. You can build an array like you would do following the QuillJs official documentation Or use a more convenient with Autocomplete using the many Fields Object in this bundle.
This example will display a h1 and h2 header options side by side
This example will display a h1 and h2 header options side by side and another Group containing a Bold and an Italic fields
You can add as many Groups as you like or just One if you don't need the WYSIWYG options to have spaces between them.
Available Fields
- Below is the list of available fields from QuillJS (https://v2.quilljs.com/docs/formats)
Field | Description | Available options (options are available as class constants in each Field Class) | Default option | QuillJS field name |
---|---|---|---|---|
BoldField | mark text as bold | - | bold | |
ColorField | Change color of the font | array of colors (default is empty array to get quillJS default value | color | |
BackGroundColorField | change background color of the selected text | array of colors (default is empty array to get quillJS default value | background | |
AlignField | Choose text alignment | false (left), center, right, justify | all | align |
DirectionField | Choose text direction | rtl (right to left, this is the only option available this widget is more like a toggle) | rtl | direction |
FontField | Choose a font | ''(sans serif) ,serif, monospace | all | font |
HeaderGroupField | Display a list of header levels | 1, 2, 3, 4, 5, 6, false (will only display normal) | all | header |
HeaderField | Add a H1 or H2 widget only | 1, 2 | 1 | header |
IndentField | Add or Remove indent | +1, -1 | +1 | indent |
ListField | Add a list | ordered, bullet, check | ordered | list |
ScriptField | sub, super | sub | script | |
SizeField | Change text size | small, false (normal), large, huge | all | size |
BlockQuoteField | Quote a text | - | blockquote | |
CleanField | Clean text styling | - | clean | |
CodeBlockField | Add a code-block | - | code-block | |
CodeField | Add some code | - | code | |
FormulaField | add a formula (with Katex) | - | formula | |
ImageField | Add an image (see quill_extra_options for uploads options) | - | image | |
ItalicField | mark text as italic | - | italic | |
LinkField | Add a link to a text | - | link | |
StrikeField | mark a text as striked | - | strike | |
UnderlineField | mark text as underlined | - | underline | |
VideoField | add an embed video | - | video |
- Below is a list of fields not available in QuillJS but taken from community:
Field | Description | Available options (options are available as class constants in each Field Class) | Default option |
---|---|---|---|
EmojiField | Add an emoji | - | |
TableField | add a table field | - |
quill_extra_options
extra_option_name | type | details |
---|---|---|
debug | string | error , warn , log , info (you can use DebugOption class constants to pick a value) |
height | string | examples: 200px , 200em , default: '200px' |
theme | string | snow , bubble , default: snow (you can use ThemeOption class constants to pick a value) |
placeholder | string | |
style | string | class , inline , choose how the style will be applied. |
upload_handler | array | (explained below (you can use UploadHandlerOption class constants to pick a value) |
use_semantic_html | bool | will use the getSemanticHTML() instead of innerHTML (can resolve some problems like https://github.com/slab/quill/issues/3957) |
custom_icons | array | customize icons by passing a SVG to replace the default quill icon (explained below |
read_only | bool | to display quill in readOnly mode |
assets | array | if you need to add custom assets (stylesheets or scripts via a CDN address) assets exemple |
assets example
OR associative array, this will allow you to override default built-in CDN assets for katex (use for FormulaField) and highlight (use for CodeBlockField)
Image upload Handling
In ImageField : QuillJS transforms images in a base64 encoded file by default to save your files. However, you can specify a custom endpoint to handle image uploading and pass in response the entire public URL to display the image.
currently handling 2 methods :
1: data sending in base64
inside a application/json
request
- in JSON mode data will look like this by calling
$request->getContent()
and in content-type headers
2: sending in a multipart/form-data
request
- in form mode you will find a in content-type headers and file will be present in $request->files named as a
Symfony\Component\HttpFoundation\File\UploadedFile
- then you can handle it like you would do with a FileType and access the file like this :
upload mode configuration :
example of a JSON configuration to send a request to the upload endpoint that returns a JSON response containing the URL to the uploaded image.
see below for a detail on these options values.
available options in upload handler:
upload_handler option name | type | default value | possible values |
---|---|---|---|
type | string | form | json , form |
upload_endpoint | string | null | the endpoint of your upload handler exemple : /upload or https://my-custom-upload-endpoint/upload |
json_response_file_path | string | null | if you specify this option, that mean your upload endpoint will return you a json response. The value must be the path inside the json (this option will be ignored if the content type of the upload endpoint response is not application/json) |
security | array | null | see below for available options |
upload endpoint security:
security options | type | used with | default values | possible values | explaination |
---|---|---|---|---|---|
type | string | null | jwt , basic , custom_header | with jwt a header will be added in the post request 'authorization' => 'Bearer MY_JWT_TOKEN' , with basic a header will be added in the post request 'authorization' => 'Basic YmFiYXI6cGFzcy1iYWJhcg==' with custom_header a header will be added in the post request 'custom_header' => 'custom_header_value==' |
||
jwt_token | string | jwt | null | pass a valid JWT token for your upload endpoint (don't specify Bearer, it will be added automatically) | |
username | string | basic | null | the username of your basic http user | |
password | string | basic | null | the password of your basic http user | |
custom_header | string | custom_header | null | the key used for your custom header | |
custom_header_value | string | custom_header | null | the value that will be passed in your custom header |
example of a JSON configuration with jwt security.
-
If your response in a classic simple
Symfony\Component\HttpFoundation\Response
, you can simply return a response like this one for exemple and do not need to specify thejson_response_file_path
option. -
If your response is a JSON response like a
Symfony\Component\HttpFoundation\JsonResponse
, thejson_response_file_path
option can be used to specify the url inside the json response. in the exemple belowjson_path_file_response
must be'file.url'
. - If your response is a JSON response like a
Symfony\Component\HttpFoundation\JsonResponse
, and thejson_response_file_path
is null.
Modules
PHP configurable modules
For these modules, you can configure them directly in your PHP form : https://quilljs.com/docs/modules
You can add/customize quill modules in this option field.
You can create your own modules classes, they need to implement the ModuleInterface
and add the name and options properties.
Some modules are automatically loaded when they are needed in fields.
Example of how to use modules:
modules | auto-imported | description | name | options type | options | default options |
---|---|---|---|---|---|---|
EmojiModule | YES | required if emoji Field is activated | emoji-toolbar | string | NONE | 'true' |
ResizeModule | YES | used in ImageField, https://www.npmjs.com/package/quill-resize-image | resize | array | [] | [] |
SyntaxModule | YES | To use with CodeBlockField field, see official description | syntax | string | NONE | 'true' |
HistoryModule | NO | The History module is responsible for handling undo and redo for Quill. see details on official site | history | array | delay , maxStack , userOnly |
['delay' => '1000', 'maxStack' => '100', 'userOnly' => 'false'] |
SmartLinksModule | NO | automatic recognition of links (can be customized within options) | smartLinks | array | linkRegex |
['linkRegex' => '/https?:\/\/[^\s]+/'] |
CounterModule | NO | Count of number and Words inside WYSIWYG (display below WYSIWYG instance by default or inside a custom html Element if you want : specify an ID in *_container with the '#') characters counter display 1 character by default because Quill is instantiated with a that count as 1 character | counter | array | words , words_label , words_container , characters , characters_label , characters_container |
['words' => true, 'words_label' => 'Number of words : ', 'words_container' => '', 'characters' => true, 'characters_label' => 'Number of characters : ', 'characters_container' => ''] |
TableModule | YES | The Table module is responsible for handling table options. see details on repository site | table-better | array | https://github.com/attoae/quill-table-better | see Ehyiah\QuillJsBundle\DTO\Modules\TableModule |
Other modules that need custom JavaScript
For other modules, you will need to extend Quill controller (see below) to use them as they required custom JavaScript as you cannot configure them in PHP.
modules | description | name | options type | options | default options |
---|---|---|---|---|---|
KeyboardModule | The Keyboard module enables custom behavior for keyboard events in particular contexts site | keyboard | array | see next documentation section | - |
ClipboardModule | The Clipboard handles copy, cut and paste between Quill and external applications site | clipboard | array | see next documentation section | - |
icons
You can customize icons used in the toolbar, pass the toolbar name and a new svg exemple :
Extend Quill stimulus controller
If you need to extend the default behavior of the built-in controller, this is possible. For example, you need to modify module registration and/or add custom JavaScript to modify quill behavior.
Some modules like Keyboard
and Clipboard
need custom JavaScript to be written.
The easiest way to do so is to create a custom stimulus controller to extend the default behavior.
You can do this easily by attaching to various events to avoid being forced to rewrite the entire controller.
Events
some events are dispatched:
event name | description | payload | usage exemple |
---|---|---|---|
options | Dispatched after editor options are created (modules, toolbar, height ...) but before the editor is initialised | QuillOptionsStatic instance |
use it to custom quill options if needed, add new modules or edit options |
connect | Dispatched after the editor is initialised with the options but before it has any content | Quill editor instance |
|
hydrate:before | Dispatched after the initial data is fetched, but before it is sent in quill editor instance | quill Delta instance |
use this if you need to edit initial data before passed to the editor instance |
hydrate:after | Dispatched after the editor has been initialised with its data | Quill editor instance |
Example of an extended controller to add Keyboard features
-
Create a new Stimulus controller inside your project
- Then in your form type
Easyadmin Integration
Integration will depend on how you handle assets in your project, AssetMapper or Webpack.
- Optional first step
If you already have an entrypoint JavaScript file that you want to re-use in admin then skip this step. And directly go to the AssetMapper or Webpack integration.
Otherwise: create a quill-admin.js inside the assets directory
- See Webpack
When using AssetMapper
create a new entry in importmap.php (the key must be quill-admin as it is the name used in the built-in QuillAdminField, but you can specify whatever you want as the actual JavaScript file in path)
and it should be done. but read below
WARNING => at the moment there seems to have an issue with easyadmin with the ->addAssetMapperEntries() function as I can not get it work as it should be.
a quick fix is to add in your crudControllers
OR
in your Dashboard controller
When using webpack
- Create in webpack.config a new entry (the entry name must be quill-admin as it is the name used in the built-in QuillAdminField, but you can specify whatever you want as the actual JavaScript file in path)
remember to recompile assets (yarn build/watch or npm equivalent).
EasyAdmin Field usage
Then you can use the QuillAdminField like this :
Or add custom options like you would do with the normal type
All versions of ux-quill with dependencies
symfony/stimulus-bundle Version ^2.9.1
twig/extra-bundle Version ^2.12|^3.0
symfony/twig-bundle Version ^6.1|^7.0
symfony/form Version ^6.1|^7.0