Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
mohamedsabil83 committed Jul 31, 2023
1 parent 67d46bf commit 4205423
Show file tree
Hide file tree
Showing 4 changed files with 191 additions and 161 deletions.
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
build
composer.lock
coverage
docs
phpunit.xml
phpstan.neon
testbench.yaml
Expand Down
170 changes: 10 additions & 160 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,170 +9,20 @@

Filament Forms TinyEditor is a package for [Laravel Filament](https://github.com/laravel-filament/filament) that wraps [TinyMce Editor](https://www.tiny.cloud) into a usable component. It's works with [Filament Forms](https://filamentadmin.com/docs/2.x/forms/installation) standalone too.

Light mode | Dark mode
:-----------------------------------:|:-----------------------------------:
![Light example](./art/editor.png) | ![Dark example](./art/editor-dark.png)
| Light mode | Dark mode |
|:----------------------------------:|:--------------------------------------:|
| ![Light example](./art/editor.png) | ![Dark example](./art/editor-dark.png) |

## Installation
## Compatibility

You can install the package via composer:
| Filament Version | Package Version |
|:----------------:|:---------------:|
| 3.x | 2.x |
| 2.x | 1.x |

```bash
composer require mohamedsabil83/filament-forms-tinyeditor
```
## Documentation

Next, publish the asset by run the following:

```bash
php artisan vendor:publish --tag="filament-forms-tinyeditor-assets"
```

## Upgrade

**Sometimes,** you may need to re-publish and override the assets after upgrading:

```bash
php artisan vendor:publish --tag="filament-forms-tinyeditor-assets" --force
```

## Usage

```php
use Mohamedsabil83\FilamentFormsTinyeditor\Components\TinyEditor;

TinyEditor::make('content')
```

## Customiziation

There is some customization that can be applied to the editor.

### **Simple editor**

To use a predefined simple editor, you may use the `simple()` method:

```php
TinyEditor::make('content')->simple()
```

### **Toolbar**

You can add many editors with differnt toolbars for each of them. First, publish the configuration files:

```bash
php artisan vendor:publish --tag="filament-forms-tinyeditor-config"
```

Each profile looks like the following: (You can add as many you want):

```php
'simple' => [
'plugins' => 'directionality emoticons link wordcount',
'toolbar' => 'removeformat | bold italic | rtl ltr | link emoticons',
],
```

Then, use each of the profile when adding editor:

```php
TinyEditor::make('content')->profile('your-profile-name')
```

For more information about available plugins and toolbar buttons, visit the related page on the [TinyMCE](https://www.tiny.cloud/docs/advanced/available-toolbar-buttons) site.

### **Custom TinyMCE Config**

By default, tinymce initialized with necessary configs, but if you want to add your config for example `image_advtab: true` ([image_advtab@TinyMce Docs](https://www.tiny.cloud/docs/plugins/opensource/image/#exampleusingimage_advtab)) you can use custom_configs key inside laravel configuration file

You need to convert tinymce json to php array.

Eg. `image_advtab: true` to `'image_advtab' => true`.

Eg.
```js
image_class_list: [
{title: 'None', value: ''},
{title: 'Fluid', value: 'img-fluid'},
]
```
to
```php
'image_class_list' => [
[
'title' => 'None',
'value' => '',
],
[
'title' => 'Fluid',
'value' => 'img-fluid',
]
]
```

There is no restriction of configs, you can add everything in here it will be converted and added to tinymce.init() function

```php
// config/filament-forms-tinyeditor.php

'simple' => [
'plugins' => 'directionality emoticons link wordcount',
'toolbar' => 'removeformat | bold italic | rtl ltr | link emoticons',
'custom_configs' => [
'image_advtab' => true
]
],
```

Will be converted and added to javascript directly.
```js
tinymce.init({
//... all other things
"image_advtab": true
})
```
### **Image Upload**
You can customize how the image plugin handles uploads using the methods associated with the `HasFileAttachments` trait. This measns you can specify the storage disk driver, directory and image visibility easily using methods directly on the field component.
```php
TinyEditor::make('content')->fileAttachmentsDisk('local')->fileAttachmentsVisibility('public')->fileAttachmentsDirectory('uploads');
```

### **Editor Height**

By default, the editor will automatically resizes to match the content inside it. If you need to control the height of the editor you can use `->minHeight(int)` method to set the **minimum height** and `->maxHeight(int)` method to set the **maximum height**.

```php
TinyEditor::make('content')->minHeight(300)
```

```php
TinyEditor::make('content')->maxHeight(300)
```

### **Show menubar**

To show the menubar of the editor, use the `->showMenuBar()` method:

```php
TinyEditor::make('content')->showMenuBar()
```

### **Sticky menubar**

To sticky the menubar of the editor, use the `->toolbarSticky()` method:

```php
TinyEditor::make('content')->toolbarSticky()
```

### **Localization**

By default, toolbar button labels shown same as current laravel locale. To force editor to use a specific language, you can use tge `->language()` method:

```php
TinyEditor::make('content')->language('ar')
```

You can found [here](https://github.com/mohamedsabil83/filament-forms-tinyeditor/tree/main/resources/dist/tinymce/langs) a list of all available languages.
See the documentation for detailed [installation](docs/installation.md) instructions and [usage](docs/usage-and-customization.md) details.

## Changelog

Expand Down
39 changes: 39 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
title: Installation
---

## Installation

You can install the package via composer:

```bash
composer require mohamedsabil83/filament-forms-tinyeditor
```

After installing the package, you don't have to do anything if you have **Filament** installed. If not, and you want to use it with **Forms standalone**, run the following command:

```bash
php artisan filament:assets
```

Optionally, you can publish the config file for [Customization](./usage-and-customization.md#customization):

```bash
php artisan vendor:publish --tag="filament-forms-tinyeditor-config"
```

## Upgrade

Like installation, you don't have to do anything more after upgrade unless you work using **Forms standalone**. In that case, you need to run the following command:

```bash
php artisan filament:assets
```

## Upgrade from 1.x to 2.x

Version 2.x of the package has been updated to use the CDN version of TinyMCE instead of the local one, resulting in only one file being published. To ensure a smooth upgrade to 2.x, please delete the old local files by removing the directory **public/vendor/filament-forms-tinyeditor** and then execute the following command after upgrading to version 2.x:

```bash
php artisan filament:assets
```
142 changes: 142 additions & 0 deletions docs/usage-and-customization.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
---
title: Usage & Customization
---

## Usage

```php
use Mohamedsabil83\FilamentFormsTinyeditor\Components\TinyEditor;

TinyEditor::make('content')
```

## Customization

There is some customization that can be applied to the editor.

### **Simple editor**

To use a predefined simple editor, you may use the `simple()` method:

```php
TinyEditor::make('content')->simple()
```

### **Toolbar**

You can add many editors with differnt toolbars for each of them. First, publish the configuration files:

```bash
php artisan vendor:publish --tag="filament-forms-tinyeditor-config"
```

Each profile looks like the following: (You can add as many you want):

```php
'simple' => [
'plugins' => 'directionality emoticons link wordcount',
'toolbar' => 'removeformat | bold italic | rtl ltr | link emoticons',
],
```

Then, use each of the profile when adding editor:

```php
TinyEditor::make('content')->profile('your-profile-name')
```

For more information about available plugins and toolbar buttons, visit the related page on the [TinyMCE](https://www.tiny.cloud/docs/advanced/available-toolbar-buttons) site.

### **Custom TinyMCE Config**

By default, tinymce initialized with necessary configs, but if you want to add your config for example `image_advtab: true` ([image_advtab@TinyMce Docs](https://www.tiny.cloud/docs/plugins/opensource/image/#exampleusingimage_advtab)) you can use custom_configs key inside laravel configuration file

You need to convert tinymce json to php array.

Eg. `image_advtab: true` to `'image_advtab' => true`.

Eg.
```js
image_class_list: [
{title: 'None', value: ''},
{title: 'Fluid', value: 'img-fluid'},
]
```
to
```php
'image_class_list' => [
[
'title' => 'None',
'value' => '',
],
[
'title' => 'Fluid',
'value' => 'img-fluid',
]
]
```

There is no restriction of configs, you can add everything in here it will be converted and added to tinymce.init() function

```php
// config/filament-forms-tinyeditor.php

'simple' => [
'plugins' => 'directionality emoticons link wordcount',
'toolbar' => 'removeformat | bold italic | rtl ltr | link emoticons',
'custom_configs' => [
'image_advtab' => true
]
],
```

Will be converted and added to javascript directly.
```js
tinymce.init({
//... all other things
"image_advtab": true
})
```
### **Image Upload**
You can customize how the image plugin handles uploads using the methods associated with the `HasFileAttachments` trait. This measns you can specify the storage disk driver, directory and image visibility easily using methods directly on the field component.
```php
TinyEditor::make('content')->fileAttachmentsDisk('local')->fileAttachmentsVisibility('public')->fileAttachmentsDirectory('uploads');
```

### **Editor Height**

By default, the editor will automatically resizes to match the content inside it. If you need to control the height of the editor you can use `->minHeight(int)` method to set the **minimum height** and `->maxHeight(int)` method to set the **maximum height**.

```php
TinyEditor::make('content')->minHeight(300)
```

```php
TinyEditor::make('content')->maxHeight(300)
```

### **Show menubar**

To show the menubar of the editor, use the `->showMenuBar()` method:

```php
TinyEditor::make('content')->showMenuBar()
```

### **Sticky menubar**

To sticky the menubar of the editor, use the `->toolbarSticky()` method:

```php
TinyEditor::make('content')->toolbarSticky()
```

### **Localization**

By default, toolbar button labels shown same as current laravel locale. To force editor to use a specific language, you can use tge `->language()` method:

```php
TinyEditor::make('content')->language('ar')
```

You can found [here](https://www.jsdelivr.com/package/npm/tinymce-i18n?tab=files&path=langs5) a list of all available languages.

0 comments on commit 4205423

Please sign in to comment.