-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
35 changed files
with
1,709 additions
and
8,472 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,20 @@ | ||
| # Changelog | ||
| All notable changes to this project will be documented in this file. | ||
|
|
||
| ## 0.1.0 - 2021-02-18 | ||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| - initial release | ||
| ## [Unreleased] | ||
| - Refactoring | ||
| - Tests | ||
|
|
||
| ## [0.2.0] - 2021-03-14 | ||
| ### Added | ||
| - Code field support. | ||
| - Json field support. | ||
|
|
||
| ## [0.1.0] - 2021-02-18 | ||
| ### Added | ||
| - Nova Translatable field for text and text area | ||
| - Single line support. | ||
| - Sluggable support. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,149 +1,138 @@ | ||
| # Making Nova fields translatable | ||
| # Laravel Nova Translatable | ||
|
|
||
| This package contains a `Translatable` class you can use to make any Nova field type translatable and groupable into Panel by locale. | ||
| This [Laravel Nova](https://nova.laravel.com/) field allows you to manage translated fields with [astrotomic/laravel-translatable](https://github.com/Astrotomic/laravel-translatable). | ||
|
|
||
| Imagine you have this `fields` method in a `Post` Nova resource: | ||
| ## Requirements | ||
|
|
||
| ```php | ||
| public function fields(Request $request) | ||
| { | ||
| return [ | ||
| ID::make()->sortable(), | ||
|
|
||
| Panel::make('it', []), | ||
| Panel::make('en', []), | ||
|
|
||
| Translatable::make([ | ||
| Text::make('title'), | ||
| NovaTinyMCE::make('text'), | ||
| ])->groupsFieldsIntoPanels(), | ||
| ]; | ||
| } | ||
| ```json | ||
| laravel/nova: ^2.9 || ^3.0 | ||
| astrotomic/laravel-translatable: ^11.0 | ||
| waynestate/nova-ckeditor4-field: ^0.6.0 | ||
| ``` | ||
|
|
||
| That `Post` Nova resource will be rendered like this. | ||
| ## Features | ||
|
|
||
|  | ||
| * Supports almost all Nova fields | ||
| * Supports default validation automatically | ||
| * Simple to implement with minimal code changes (after astrotomic/laravel-translatable support) | ||
| * Locale tabs to switch between different locale values of the same field | ||
|
|
||
| ## Requirements | ||
|
|
||
| This Nova field requires Nova 3 specifically and MySQL 5.7.8 or higher. | ||
| ## Supported fields | ||
| * Code | ||
| * Counted text (with max char and warning treshold) | ||
| * CKEditor | ||
| * Json | ||
| * Sluggable | ||
| * Text (also single line) | ||
| * Textarea | ||
| * Trix | ||
|
|
||
| ## Installation | ||
|
|
||
| First you must install [spatie/laravel-translatable](https://github.com/spatie/laravel-translatable) into your Laravel app. In a nutshell, this package will store translations for your model in a json column in your table. On top of that, it provides many handy functions to store and retrieve translations. Be sure to read [the entire readme of laravel-translatable](https://github.com/spatie/laravel-translatable/blob/master/README.md) before using this Nova package. | ||
| Firstly, set up [astrotomic/laravel-translatable](https://github.com/astrotomic/laravel-translatable). | ||
|
|
||
| Next, you can install this Nova package into a Laravel app that uses [Nova](https://nova.laravel.com) via composer: | ||
| Install the package in a Laravel Nova project via Composer: | ||
|
|
||
| ```bash | ||
| composer require rslanzi/nova-translatable | ||
| # Install nova-translatable | ||
| composer install rslanzi/nova-translatable | ||
|
|
||
| # Publish configuration (optional, but useful for setting default locales) | ||
| php artisan vendor:publish --tag="nova-translatable-config" | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| In order to use the package you must first let `Translatable` know which locales your app is using using the `Translatable::defaultLocales()` method. You can put this code in `AppServiceProvider` or a dedicated service provider of your own. | ||
|
|
||
| ### Text Field | ||
| Single line text field | ||
| ```php | ||
| // in any service provider | ||
|
|
||
| \Rslanzi\NovaTranslatable\Translatable::defaultLocales(['en', 'it']); | ||
| NovaTranslatable::make('Title') | ||
| ->singleLine() | ||
| ``` | ||
|
|
||
| Next, you must prepare your model [as explained](https://github.com/spatie/laravel-translatable#making-a-model-translatable) in the readme of laravel-translatable. In short: you must add `json` columns to your model's table for each field you want to translate. Your model must use the `Spatie\Translatable\HasTranslations` on your model. Finally, you must also add a `$translatable` property on your model that holds an array with the translatable attribute names. | ||
|
|
||
| Now that your model is configured for translations, you can use `Translatable` in the related Nova resource. Any fields you want to display in a multilingual way can be passed as an array to `Translatable. | ||
|
|
||
| ### Textarea Field: | ||
| Multi line text field | ||
| ```php | ||
| public function fields(Request $request) | ||
| { | ||
| return [ | ||
| ID::make()->sortable(), | ||
|
|
||
| Translatable::make([ | ||
| Text::make('title'), | ||
| Trix::make('text'), | ||
| ]), | ||
| ]; | ||
| } | ||
| NovaTranslatable::make('Text') | ||
| ->hideFromIndex() | ||
| ``` | ||
|
|
||
| ### Customizing the locales per translatable | ||
|
|
||
| If you have a Nova resource where you want different locales than the ones configured globally, you can call the `locales` method on `Translatable`. | ||
|
|
||
| ### Counted Text Field: | ||
| Text field with chars counter | ||
| ```php | ||
| Translatable::make([ | ||
| Text::make('title'), | ||
| Trix::make('text'), | ||
| ])->locales(['de', 'es']), | ||
| NovaTranslatable::make('Title') | ||
| ->singleLine() | ||
| ->counted() | ||
| ``` | ||
|
|
||
| These fields will now use the `de` and `es` locales. | ||
|
|
||
| ### Customizing the name of a translatable | ||
|
|
||
| By default translatable fields get ` ($locale)` appended to their name. You can customize this behaviour globally by providing a closure to `displayLocalizedNameByDefaultUsing` on `Translatable`. This callback will be used to render the localized field names. | ||
|
|
||
| #### Counted with max chars threshold. | ||
| Exceeded the threshold, the counter turns red. | ||
| ```php | ||
| Translatable::displayLocalizedNameByDefaultUsing(function(Field $field, string $locale) { | ||
| return ucfirst($field->name) . " [{$locale}]"; | ||
| }) | ||
| NovaTranslatable::make('Title') | ||
| ->singleLine() | ||
| ->counted() | ||
| ->maxChars(60) | ||
| ->warningAt(50), | ||
| ``` | ||
|
|
||
| With this in place all names of translatable fields will get ` [$locale]` appended. | ||
|
|
||
| You can also customize the localized field name per resource by passing a closure the `displayLocalizedNameUsing` function. | ||
|
|
||
| #### Counted with max chars and warning thresholds. | ||
| Exceeded the warning threshold, the counter turns orange, exceeded the max chars threshold, the counter turns red. | ||
| ```php | ||
| Translatable::make([ | ||
| Text::make('title'), | ||
| Trix::make('text'), | ||
| ])->displayLocalizedNameUsing(function(Field $field, string $locale) { | ||
| return ucfirst($field->name) . " --- {$locale}]"; | ||
| }), | ||
| NovaTranslatable::make('Title') | ||
| ->singleLine() | ||
| ->counted() | ||
| ->maxChars(60) | ||
| ->warningAt(50), | ||
| ``` | ||
|
|
||
| With this in place, the localized field names will be suffixed with ` --- $locale`. | ||
|
|
||
| Of course you can still customize the name of a field as usual. | ||
|
|
||
| ### CKEditor Field | ||
| CKEditor WYSIWYG editor. Usefull to manage HTML fields. | ||
| ```php | ||
| Translatable::make([ | ||
| Text::make('My title', 'title'), | ||
| Trix::make('text'), | ||
| ])->displayLocalizedNameUsing(function(Field $field, string $locale) { | ||
| return ucfirst($field->name) . " [{$locale}]"; | ||
| }), | ||
| NovaTranslatable::make('Text') | ||
| ->ckeditor() | ||
| ``` | ||
|
|
||
| Using the code about above the name for the `title` field will be "My title ['en']". | ||
|
|
||
| ## On customizing the UI | ||
|
|
||
| You might wonder why we didn't render the translatable fields in tabs, panels or with magical unicorns displayed next to them. The truth is that everybody wants translations to be displayed a bit different. That's why we opted to keep them very simple for now. | ||
|
|
||
| If Nova gains the ability to better structure a long form natively, we'd probably start leveraging that in a new major version of the package. | ||
|
|
||
| ### Testing | ||
| ### Trix Field | ||
| Trix field | ||
| ```php | ||
| NovaTranslatable::make('Text') | ||
| ->trix() | ||
| ``` | ||
|
|
||
| ```bash | ||
| composer test | ||
| ### Sluggable Field | ||
| Automatically populate a slug field based on another field. Title in this case. | ||
| ```php | ||
| NovaTranslatable::make('Title') | ||
| ->sluggable('Slug'), | ||
| NovaTranslatable::make('Slug') | ||
| ->singleLine() | ||
| ``` | ||
|
|
||
| ### Changelog | ||
| ### Code Field | ||
| Code field. Use a syntax highlighted text area. | ||
| ```php | ||
| NovaTranslatable::make('Text') | ||
| ->code() | ||
| ``` | ||
| #### Code Field with custom language | ||
| Code field. Use a syntax highlighted text area. | ||
| ```php | ||
| NovaTranslatable::make('Text') | ||
| ->code() | ||
| ->language('php') | ||
| ``` | ||
| **The Code field's currently supported languages are:** | ||
| dockerfile, javascript, markdown, nginx, php, ruby, sass, shell, vue, xml, yaml | ||
|
|
||
| Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. | ||
| ### Json Field | ||
| ```php | ||
| NovaTranslatable::make('Text') | ||
| ->json() | ||
| ``` | ||
|
|
||
| ## Contributing | ||
| Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. | ||
|
|
||
| Please see [CONTRIBUTING](CONTRIBUTING.md) for details. | ||
|
|
||
|
|
||
| ## Credits | ||
|
|
||
| - [Freek Van der Herten](https://github.com/freekmurze) | ||
| - [Riccardo Slanzi](https://github.com/rslanzi) | ||
| Please make sure to update tests as appropriate. | ||
|
|
||
| ## License | ||
|
|
||
| The MIT License (MIT). Please see [License File](LICENSE.md) for more information. | ||
| This project is open-sourced software licensed under the [MIT license](LICENSE.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.