Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@nadar
nadar authored Feb 13, 2024
1 parent 6881d5b commit 2f784e0
Showing 1 changed file with 33 additions and 31 deletions.
64 changes: 33 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Quill Delta to HTML Parser

A PHP library to parse [Quill WYSIWYG](https://quilljs.com/) editor [deltas](https://github.com/quilljs/delta) into HTML - flexible and extendible for custom elements. Every element is parsed by the same mechanism, this makes it easy to extend and understand. It will also sanitize the output value, so its more secure especially when using user generated text.
A PHP library to parse [Quill WYSIWYG](https://quilljs.com/) editor [deltas](https://github.com/quilljs/delta) into HTML - flexible and extendable for custom elements. Every element is parsed by the same mechanism, making it easy to extend and understand. It also sanitizes the output value, making it more secure, especially when using user-generated text.

![Tests](https://github.com/nadar/quill-delta-parser/workflows/Tests/badge.svg)
[![Maintainability](https://api.codeclimate.com/v1/badges/fdf80e7b61e4505bc421/maintainability)](https://codeclimate.com/github/nadar/quill-delta-parser/maintainability)
Expand All @@ -13,7 +13,7 @@ What is Quill? Quill is a free, open source WYSIWYG editor built for the modern

## Installation

The package is only available through composer:
The package is available only through Composer:

```sh
composer require nadar/quill-delta-parser
Expand All @@ -22,17 +22,17 @@ composer require nadar/quill-delta-parser
## Usage

```php
// ensure to load the autoload file from composer somewhere in your application
// Ensure to load the autoload file from Composer somewhere in your application.
require __DIR__ . '/vendor/autoload.php';

// create the lexer object with your given quill json delta code (either PHP array or JSON string)
// Create the lexer object with your given Quill JSON delta code (either PHP array or JSON string).
$lexer = new \nadar\quill\Lexer($json);

// echoing the html for the given json ops.
// Echo the HTML for the given JSON ops.
echo $lexer->render();
```

Where `$json` is the ops json array from quill, for example:
Where `$json` is the ops JSON array from Quill, for example:

```json
{
Expand All @@ -47,7 +47,7 @@ Where `$json` is the ops json array from quill, for example:
"insert": "\n"
},
{
"insert": "\nThis is the php quill "
"insert": "\nThis is the PHP Quill "
},
{
"attributes": {
Expand All @@ -67,17 +67,17 @@ This would render the following HTML:
```html
<h1>Hello</h1>
<p><br></p>
<p>This is the php quill <strong>parser</strong>!</p>
<p>This is the PHP Quill <strong>parser</strong>!</p>
```

## Extend the Parser

In order to extend the Parser by adding your own listeners (this can be the case if you are using quill plugins which generates custom delta code), you have to decide whether it's an:
To extend the Parser by adding your own listeners (this can be the case if you are using Quill plugins which generate custom delta code), you have to decide whether it's an:

+ inline element: Replaces content with new parsed content, this is mostly the case when working with quill extensions.
+ block element: Block elements which encloses the whole input with a tag, for example heading.
+ Inline element: Replaces content with new parsed content, mostly the case when working with Quill extensions.
+ Block element: Encloses the whole input with a tag, for example, a heading.

An example for a mention plugin which generates the following delta `{"insert":{"mention":{"id":"1","value":"Basil","denotationChar":"@"}}}` an inline plugin could look like this:
An example for a mention plugin that generates the following delta `{"insert":{"mention":{"id":"1","value":"Basil","denotationChar":"@"}}}`; an inline plugin could look like this:

```php
class Mention extends InlineListener
Expand All @@ -87,12 +87,12 @@ class Mention extends InlineListener
*/
public function process(Line $line)
{
// check if input is json, decodes to an array and checks if the key "mention"
// exists, if yes return the value for this key.
// Check if input is JSON, decodes to an array, and checks if the key "mention"
// exists. If yes, return the value for this key.
$mention = $line->insertJsonKey('mention');
if ($mention) {
// apply the inline behavior, updates the content and append to next "block" element.
// the value in this example would be "<strong>Basil</strong>".
// Apply the inline behavior, updates the content and append to the next "block" element.
// The value in this example would be "<strong>Basil</strong>".
$this->updateInput($line, '<strong>'.$mention['value'].'</strong>');
}
}
Expand All @@ -103,58 +103,60 @@ Now register the listener:

```php
$lexer = new Lexer($json);
$lexer->registerListener(new Mention);
$lexer->registerListener(new Mention());
echo $lexer->render();
```

## Override built-in Listeners
## Override Built-in Listeners

Certain listeners (image, video, color) produce a HTML output which maybe not suit your use case, so you have the option to override the properties of those plugins and re-register the Listener, here an example with the image tag:
Certain listeners (image, video, color) produce an HTML output which may not suit your use case, so you have the option to override the properties of those plugins and re-register the Listener. Here's an example with the image tag:

```php
$image = new Image();


$image->wrapper = '<img src="{src}" class="my-image" />';

// override the default listener behavior for image color:
// Override the default listener behavior for image color:
$lexer = new Lexer($json);
$lexer->registerListener($image);
echo $lexer->render();
```

If the class name has changed by our own image class, you can use `overwriteListener` to achieve the same result, but with your total custom class. The reason is that the listeners are registered by its class names.
If you want to replace a class with your own image class, use `overwriteListener` to achieve the same result, but with your totally custom class. The reason is that listeners are registered by their class names.

```php
$mySuperClass = new class() extends Image {
// here is the custom class code ...
}
// Here is the custom class code ...
};

$lexer->overwriteListener(new Image, $mySuperClass);
$lexer->overwriteListener(new Image(), $mySuperClass);
```

Or, of course when you have a seperate file for your class
Or, of course, when you have a separate file for your class:

```php
class MySuperDuperImageClass extends Image
{
// here is the custom class code ...
// Here is the custom class code ...
}

$lexer->overwriteListener(new Image, new MySuperDuperImageClass);
$lexer->overwriteListener(new Image(), new MySuperDuperImageClass());
```

## Debuging
## Debugging

Sometimes the handling of delta and how the data is parsed is very hard to debug and understand. Therefore you can use the debugger class which will print a table with informations about how the data is parsed.
Sometimes, understanding how delta is handled and parsed can be challenging to debug. Therefore, you can use the debugger class, which will print a table with information about how the data is parsed.

```php
$lexer = new Lexer($json);
$lexer->render(); // make sure to run the render before call debugPrint();
$lexer->render(); // Make sure to run the render before calling debugPrint().

$debug = new Debug($lexer);
echo $debug->debugPrint();
```

There is also a built in docker compose file which provides access to the output.php file. The output.php helps to directly write content with the quill editor while displaying what is rendered including all debug informations. In order to run this docker webserver execute the following command in the root directory of your git repository clone:
There is also a built-in Docker Compose file which provides access to the `output.php` file. The `output.php` helps to directly write content with the Quill editor while displaying what is rendered, including all debug information. To run this Docker webserver, execute the following command in the root directory of your Git repository clone:

```sh
docker-compose up
Expand Down

0 comments on commit 2f784e0

Please sign in to comment.