Skip to content

Commit

Permalink
update QuillJs to version 2.0, add new fields, update readme && clean…
Browse files Browse the repository at this point in the history 
… code
  • Loading branch information
@Ehyiah
Ehyiah committed Apr 19, 2024
1 parent a7cea4d commit 8ec67d1
Show file tree
Hide file tree
Showing 68 changed files with 1,973 additions and 426 deletions.
8 changes: 8 additions & 0 deletions src/QuillJs/.github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Please do not submit any Pull Requests here. They will be closed.
---

Please submit your PR here instead:
https://github.com/symfony/ux

This repository is what we call a "subtree split": a read-only subset of that main repository.
We're looking forward to your PR there!
33 changes: 33 additions & 0 deletions src/QuillJs/.github/workflows/check-subtree-split.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Check subtree split
on:
pull_request_target:
jobs:
close-pull-request:
runs-on: ubuntu-latest
steps:
- name: Close pull request
uses: actions/github-script@v6
with:
script: |
if (context.repo.owner === "symfony") {
github.rest.issues.createComment({
owner: "symfony",
repo: context.repo.repo,
issue_number: context.issue.number,
body: `
Thanks for your Pull Request! We love contributions.
However, you should instead open your PR on the main repository:
https://github.com/symfony/ux
This repository is what we call a "subtree split": a read-only subset of that main repository.
We're looking forward to your PR there!
`
});
github.rest.pulls.update({
owner: "symfony",
repo: context.repo.repo,
pull_number: context.issue.number,
state: "closed"
});
}
12 changes: 5 additions & 7 deletions src/QuillJs/LICENSE
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
MIT License

Copyright (c) 2023 Matthieu Gostiaux
Copyright (c) 2024-present Fabien Potencier

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
Expand All @@ -17,5 +15,5 @@ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
280 changes: 271 additions & 9 deletions src/QuillJs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,275 @@
# Symfony UX QuillJs
# QuillJs Bundle for Symfony using Symfony UX

Symfony UX QuillJs integrates [QuillJs](https://quilljs.com/) into Symfony applications.
Symfony UX Bundle implementing the Quill JS Wysiwyg https://quilljs.com/

**This repository is a READ-ONLY sub-tree split**. See
https://github.com/symfony/ux to create issues or submit pull requests.
If you need a easy to use WYSIWYG (with no complex configuration) into a symfony project this is what you need.

## Resources
* [Installation](#installation)

- [Documentation](https://symfony.com/bundles/ux-quill/current/index.html)
- [Report issues](https://github.com/symfony/ux/issues) and
[send Pull Requests](https://github.com/symfony/ux/pulls)
in the [main Symfony UX repository](https://github.com/symfony/ux)

* [Basic Usage](#basic-usage)
* [Display Result](#display-result)


* [Customize quillJS with options and extra_options](#customize-options)
* [Handle images uploads](#image-upload-handling)


* [EasyAdmin Integration](#easyadmin-integration)
* [EasyAdmin Usage](#usage)

## Installation
### Step 1 Require bundle
```sh
composer require symfony/ux-quill
```
If you are using the AssetMapper Component you're done !

### step 2 next run (If you are using webpack encore, not needed with AssetMapper)
``` sh
yarn install --force
yarn watch
```
OR
``` sh
npm install --force
npm run watch
```
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:
```php
use Symfony\UX\QuillJs\Form\QuillType;

public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
// ...
->add('myField', QuillType::class)
;
}
```

# Display result
in a twig template simply :
```
<div>{{ myField|raw }}</div>
```
you can of course sanitize HTML if you need to for security reason, but don't forget to configure it
to your needs as many html balise and style elements will be removed by default.
Same goes in your Form configuration
```
'sanitize_html' => false,
'sanitizer' => 'my_awesome_sanitizer_config
```


For the most basic this is only what you have to do.
# Customize Options
```php
use Symfony\UX\QuillJs\Form\QuillType;

public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
// ...
->add('myField', QuillType::class, [
'quill_extra_options' => [
'height' => '780px',
'theme' => 'snow',
'placeholder' => 'Hello Quill WYSIWYG',
],
'quill_options' => [
// this is where you customize the WYSIWYG by creating one or many Groups
// you can also build your groups using a classic array but many classes are covering every Quill available Fields (see below for detailed list)
QuillGroup::build(
new BoldInlineField(),
new ItalicInlineField(),
// and many more
),
QuillGroup::build(
new HeaderField(HeaderField::HEADER_OPTION_1),
new HeaderField(HeaderField::HEADER_OPTION_2),
// and many more
),
// Or add all available fields at once
QuillGroup::buildWithAllFields()
]
])
;
}
```


## 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.
```
QuillGroup::build(
new HeaderField(HeaderField::HEADER_OPTION_1),
new HeaderField(HeaderField::HEADER_OPTION_2),
)
```
This example will display a h1 and h2 header options side by side
```
QuillGroup::build(
new HeaderField(HeaderField::HEADER_OPTION_1),
new HeaderField(HeaderField::HEADER_OPTION_2),
)
QuillGroup::build(
new BoldInlineField(),
new ItalicInlineField(),
)
```
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.

### 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](https://katex.org/)) | - | | formula |
| ImageField | Add an image (see [quill_extra_options](#image-upload-handling) 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 | - | |



## quill_extra_options:

- **debug**: type:string, values: 'error', 'warn', 'log', 'info' (you can use DebugOption class to build it)
- **height**: type string, examples: 200px, 200em, default: '200px'
- **theme**: type: string, values: 'snow', 'bubble', default: 'snow' (you can use ThemeOption class to build it)
- **placeholder**: type: string
- **upload_handler**: type: array (explained below)

### Image upload Handling
in ***ImageInlineField*** : QuillJS transform images in 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 :
- data sending in base64 inside a json
- OR
- in a multipart/form-data
```
'quill_extra_options' => [
///
'upload_handler' => [
'type' => 'json',
// or 'type' => 'form',
'path' => '/my-custom-endpoint/upload',
]
],
```
- your endpoint must return the complete URL of the file example :
```
https://upload.wikimedia.org/wikipedia/commons/thumb/6/6a/JavaScript-logo.png/480px-JavaScript-logo.png
```
- in json mode data will look like this by calling $request->getContent() and ```application/json``` in content-type headers
```
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAlgAAAJYCAQAAAAUb1BXAAAABGdBTUEAALGPC/xhBQAAACyygyyioiBqFCUIKC64x..."
```
- in form mode you will find a ```multipart/form-data``` in content-type headers and file will be present in $request->files named ```file```
- then you can handle it like you would do with a FileType



# Easyadmin Integration
- First create a quill-admin.js inside assets directory
```
// start the Stimulus application
import './bootstrap';
```
## 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)
```
'quill-admin' => [
'path' => './assets/quill-admin.js',
'entrypoint' => true,
],
```
and i 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
```
public function configureAssets(Assets $assets): Assets
{
$assets->addAssetMapperEntry('quill-admin');
return parent::configureAssets($assets); // TODO: Change the autogenerated stub
}
```

OR

in your dashboard
```
public function configureAssets(): Assets
{
$assets = Assets::new();
$assets->addAssetMapperEntry('quill-admin');
return $assets;
}
```

## When using webpack
- Next 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)
```
.addEntry('quill-admin', './assets/quill-admin.js')
```
don't forget to recompile assets (yarn build/watch or npm equivalent).

## EasyAdmin
Then you can use the QuillAdminField like this :
```
QuillAdminField::new('quill')
```

Or add custom options like you would do with the normal type
```
QuillAdminField::new('quill')
->setFormTypeOptions([
'quill_options' =>
QuillGroup::build(
new BoldInlineField(),
new ItalicInlineField(),
new HeaderField(HeaderField::HEADER_OPTION_1),
new HeaderField(HeaderField::HEADER_OPTION_2),
)
])
```
33 changes: 33 additions & 0 deletions src/QuillJs/assets/dist/blots/image.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
import Quill from 'quill';
const InlineBlot = Quill.import('blots/block');
class LoadingImage extends InlineBlot {
static create(src) {
const node = super.create(src);
if (src === true) return node;
const image = document.createElement('img');
image.setAttribute('src', src);
node.appendChild(image);
return node;
}
deleteAt(index, length) {
super.deleteAt(index, length);
this.cache = {};
}
static value(domNode) {
const {
src,
custom
} = domNode.dataset;
return {
src,
custom
};
}
}
LoadingImage.blotName = 'imageBlot';
LoadingImage.className = 'image-uploading';
LoadingImage.tagName = 'span';
Quill.register({
'formats/imageBlot': LoadingImage
});
export default LoadingImage;
Loading

0 comments on commit 8ec67d1

Please sign in to comment.