From 1a6e662e1a119b1a09ec7596a83d17e6e6d7ee2e Mon Sep 17 00:00:00 2001 From: Ellet <73608287+freshtechtips@users.noreply.github.com> Date: Wed, 25 Oct 2023 20:25:22 +0300 Subject: [PATCH] Mirgration Guide and update README.md (#1473) --- CHANGELOG.md | 5 + README.md | 53 ++- doc/migration.md | 435 ++++++++++++++++++ .../models/config/editor/element_options.dart | 6 +- lib/src/widgets/text_block.dart | 2 +- pubspec.yaml | 2 +- 6 files changed, 487 insertions(+), 16 deletions(-) create mode 100644 doc/migration.md diff --git a/CHANGELOG.md b/CHANGELOG.md index bd2cf973..6544edd0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ +## [8.0.0] +- If you have mirgrated recently, don't get scared from this update, it just add a documentation, mirgration guide and mark the version as more stable release, since we did break a lot of breaking changes (at least that what most developers says) we should have change the major version but when we were in the development of this new version, our time was very tight and now we are fixing the version number +- It also rename one single property from `code` to `codeBlock` in the `elements` of the new `QuillEditor` Configurations class +- Updating the README to be more readable + ## [7.10.2] - Removing line numbers from code block by default, you still can enable this thanks to the new configurations in the `QuillEditor` you will find a `elementOptions` property, in it you will find the code which mean code block options. just pass true to `enableLineNumbers` diff --git a/README.md b/README.md index debda61c..10fa98ae 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Flutter Quill +

@@ -28,6 +30,34 @@ This library is a WYSIWYG editor built for the modern Android, iOS, web and desk Pub: [FlutterQuill] +## Table of contents +- [Flutter Quill](#flutter-quill) + - [Table of contents](#table-of-contents) + - [Demo](#demo) + - [Installation](#installation) + - [Usage](#usage) + - [Mirgration](#mirgration) + - [Input / Output](#input--output) + - [Configurations](#configurations) + - [Using Custom App Widget](#using-custom-app-widget) + - [Font Size](#font-size) + - [Font Family](#font-family) + - [Custom Buttons](#custom-buttons) + - [Embed Blocks](#embed-blocks) + - [Using the embed blocks from `flutter_quill_extensions`](#using-the-embed-blocks-from-flutter_quill_extensions) + - [Custom Size Image for Mobile](#custom-size-image-for-mobile) + - [Custom Size Image for other platforms (excluding web)](#custom-size-image-for-other-platforms-excluding-web) + - [Custom Embed Blocks](#custom-embed-blocks) + - [Custom Toolbar](#custom-toolbar) + - [Translation](#translation) + - [](#) + - [Contributing to translations](#contributing-to-translations) + - [Conversion to HTML](#conversion-to-html) + - [Testing](#testing) + - [License](#license) + - [Contributors](#contributors) + - [Sponsors](#sponsors) + ## Demo

@@ -103,6 +133,9 @@ And depending on your use case, you might want to dispose the `_controller` in d Check out [Sample Page] for more advanced usage. +## Mirgration +We have recently add [mirgration guide](/doc/migration.md) for mirgration from different versions + ## Input / Output This library uses [Quill] as an internal data format. @@ -128,21 +161,18 @@ _controller = QuillController( ); ``` -## Web +## Configurations + +The `QuillToolbar` class lets you customize which formatting options are available. +[Sample Page] provides sample code for advanced usage and configuration. -For web development, use `flutter config --enable-web` for flutter or use [ReactQuill] for React. +For **web development**, use `flutter config --enable-web` for flutter or use [ReactQuill] for React. It is required to provide `EmbedBuilder`, e.g. [defaultEmbedBuildersWeb](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/universal_ui/universal_ui.dart#L99). Also it is required to provide `webImagePickImpl`, e.g. [Sample Page](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/pages/home_page.dart#L317). -## Desktop - -It is required to provide `filePickImpl` for toolbar image button, e.g. [Sample Page](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/pages/home_page.dart#L297). - -## Configuration +For **desktop platforms** It is required to provide `filePickImpl` for toolbar image button, e.g. [Sample Page](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/pages/home_page.dart#L297). -The `QuillToolbar` class lets you customize which formatting options are available. -[Sample Page] provides sample code for advanced usage and configuration. ### Using Custom App Widget @@ -279,7 +309,8 @@ Expanded( ) ``` -> [!WARNING] + + ### Custom Size Image for Mobile diff --git a/doc/migration.md b/doc/migration.md new file mode 100644 index 00000000..dc8232af --- /dev/null +++ b/doc/migration.md @@ -0,0 +1,435 @@ +# Mirgration guide + +Here you can find the mirgration guide between different versions, you can contribute to this page to make it better for everyone!! + + +- [Mirgration guide](#mirgration-guide) + - [from 7.0.0 to 8.0.0](#from-700-to-800) + +## from 7.0.0 to 8.0.0 + +We have refactored a lot of the base code to allow you to customize everything you want, and it allow us to add new configurations very easily using inherited widgets without passing configurations all over the constructors everywhere which will be very hard to test, fix bugs, and maintain + +1. Passing the controller + +The controller code (should be the same) +```dart +QuillController _controller = QuillController.basic(); +``` + +**Old code**: +```dart + +Column( + children: [ + QuillToolbar.basic(controller: _controller), + Expanded( + child: QuillEditor.basic( + controller: _controller, + readOnly: false, // true for view only mode + ), + ) + ], +) + +``` + +**New code**: + +```dart +QuillProvider( + configurations: QuillConfigurations( + controller: _controller, + sharedConfigurations: const QuillSharedConfigurations(), + ), + child: Column( + children: [ + const QuillToolbar(), + Expanded( + child: QuillEditor.basic( + configurations: const QuillEditorConfigurations( + readOnly: false, // true for view only mode + ), + ), + ) + ], + ), +) +``` + +The `QuillProvider` is inherited widget which allow you pass configurations once and use them in the children of it. here we are passing the `_controller` once in the configurations of `QuillProvider` and the `QuillToolbar` and `QuillEditor` will get the `QuillConfigurations` internally, if it doesn't exists you will get an exception. + +we also added the `sharedConfigurations` which allow you to configure shared things like the `Local` so you don't have to define them twice, we have removed those from the `QuillToolbar` and `QuillEditor` + +2. The QuillToolbar buttons, we have renamed almost all the buttons, examples: + - `QuillHistory` to `QuillToolbarHistoryButton` + - `IndentButton` to `QuillToolbarIndentButton` + +and they usually have two parameters, `controller` and `options`, example of the type for the buttons + - `QuillToolbarHistoryButton` have `QuillToolbarHistoryButtonOptions` + - `QuillToolbarIndentButton` have `QuillToolbarIndentButtonOptions` + - `QuillToolbarClearFormatButton` have `QuillToolbarClearFormatButtonOptions` + +All the options have parent `QuillToolbarBaseButtonOptions` which have commons things like + +```dart + /// By default it will use a Icon data from Icons which comes from material + /// library for each button, to change this, please pass a different value + /// If there is no Icon in this button then pass null in the child class + final IconData? iconData; + + /// To change the the icon size pass a different value, by default will be + /// [kDefaultIconSize] + /// this will be used for all the buttons but you can override this + final double globalIconSize; + + /// To do extra logic after pressing the button + final VoidCallback? afterButtonPressed; + + /// By default it will use the default tooltip which already localized + final String? tooltip; + + /// Use custom theme + final QuillIconTheme? iconTheme; + + /// If you want to dispaly a differnet widget based using a builder + final QuillToolbarButtonOptionsChildBuilder childBuilder; + + /// By default it will be from the one in [QuillProvider] + /// To override it you must pass not null controller + /// if you wish to use the controller in the [childBuilder], please use the + /// one from the extraOptions since it will be not null and will be the one + /// which will be used from the quill toolbar + final QuillController? controller; +``` + +The `QuillToolbarBaseButtonOptions is`: +/// The [T] is the options for the button, usually should refresnce itself +/// it's used in [childBuilder] so the developer can custmize this when using it +/// The [I] is extra options for the button, usually for it's state +```dart +@immutable +class QuillToolbarBaseButtonOptions extends Equatable +``` + +Example for the clear format button: + +```dart +class QuillToolbarClearFormatButtonExtraOptions + extends QuillToolbarBaseButtonExtraOptions { + const QuillToolbarClearFormatButtonExtraOptions({ + required super.controller, + required super.context, + required super.onPressed, + }); +} + +class QuillToolbarClearFormatButtonOptions + extends QuillToolbarBaseButtonOptions { + const QuillToolbarClearFormatButtonOptions({ + super.iconData, + super.afterButtonPressed, + super.childBuilder, + super.controller, + super.iconTheme, + super.tooltip, + this.iconSize, + }); + + final double? iconSize; +} + +``` + +The base for extra options: +```dart +@immutable +class QuillToolbarBaseButtonExtraOptions extends Equatable { + const QuillToolbarBaseButtonExtraOptions({ + required this.controller, + required this.context, + required this.onPressed, + }); + + /// if you need the not null controller for some usage in the [childBuilder] + /// then please use this instead of the one in the [options] + final QuillController controller; + + /// if the child builder you must use this when the widget tapped or pressed + /// in order to do what it expected to do + final VoidCallback? onPressed; + + final BuildContext context; + @override + List get props => [ + controller, + ]; +} +``` + +which usually share common things, it also add extra property which was not exsisting, which is `childBuilder` which allow to render custom widget based on the state of the button and the options of it + +```dart +QuillToolbar( + configurations: QuillToolbarConfigurations( + buttonOptions: QuillToolbarButtonOptions( + clearFormat: QuillToolbarClearFormatButtonOptions( + childBuilder: (options, extraOptions) { + return IconButton.filled( + onPressed: extraOptions.onPressed, + icon: const Icon( + CupertinoIcons.clear // or options.iconData + ), + ); + }, + ), + ), + ), +), +``` + +the `extraOptions` usually contains the state variables and the evenets that you need to trigger like the `onPressed`, it also has the end context and the controller that will be used +while the `options` has the custom controller for each button and it's nullable because there could be no custom controller so we will just use the global one + +3. The `QuillToolbar` and `QuillToolbar.basic()` factory constructor + +since the basic factory constructor has more options than the original `QuillToolbar` which doesn't make much sense, at least to some developers, we have refactored the `QuillToolbar.basic()` to a different widget called the `QuillToolbar` and the `QuillToolbar` has been renamed to `QuillBaseToolbar` which is the base for `QuillToolbar` or any custom toolbar, sure you can create custom toolbar from scratch by just using the `controller` but if you want more support from the library use the `QuillBaseToolbar` + +the children widgets of the new `QuillToolbar` and `QuillEditor` access to thier configurations by another two inherited widgets +since `QuillToolbar` and `QuillEditor` take the configuration class and provide them internally using `QuillToolbarProvider` and `QuillEditorProvider` +however the `QuillBaseToolbar` has a little bit different configurations so it has a different provider called `QuillBaseToolbarProvider` and it also already provided by default + +But there is one **note**: +> If you are using the toolbar buttons like `QuillToolbarHistoryButton`, `QuillToolbarToggleStyleButton` in the somewhere like the the custom toolbar (using `QuillBaseToolbar` or any custom widget) then you must provide them with `QuillToolbarProvider` inherited widget, you don't have to do this if you are using the `QuillToolbar` since it will be done for you +> + +Example of custom toolbar: + +```dart +QuillProvider( + configurations: QuillConfigurations( + controller: _controller, + sharedConfigurations: const QuillSharedConfigurations(), + ), + child: Column( + children: [ + QuillToolbarProvider( + toolbarConfigurations: const QuillToolbarConfigurations(), + child: QuillBaseToolbar( + configurations: QuillBaseToolbarConfigurations( + toolbarSize: 15 * 2, + multiRowsDisplay: false, + childrenBuilder: (context) { + final controller = context.requireQuillController; // new extension which is a little bit shorter to access the quill provider then the controller + + // there are many options, feel free to explore them all!! + return [ + QuillToolbarHistoryButton( + controller: controller, + options: const QuillToolbarHistoryButtonOptions( + isUndo: true), + ), + QuillToolbarHistoryButton( + controller: controller, + options: const QuillToolbarHistoryButtonOptions( + isUndo: false), + ), + QuillToolbarToggleStyleButton( + attribute: Attribute.bold, + controller: controller, + options: const QuillToolbarToggleStyleButtonOptions( + iconData: Icons.format_bold, + iconSize: 20, + ), + ), + QuillToolbarToggleStyleButton( + attribute: Attribute.italic, + controller: controller, + options: const QuillToolbarToggleStyleButtonOptions( + iconData: Icons.format_italic, + iconSize: 20, + ), + ), + QuillToolbarToggleStyleButton( + attribute: Attribute.underline, + controller: controller, + options: const QuillToolbarToggleStyleButtonOptions( + iconData: Icons.format_underline, + iconSize: 20, + ), + ), + QuillToolbarClearFormatButton( + controller: controller, + options: const QuillToolbarClearFormatButtonOptions( + iconData: Icons.format_clear, + iconSize: 20, + ), + ), + VerticalDivider( + indent: 12, + endIndent: 12, + color: Colors.grey.shade400, + ), + QuillToolbarSelectHeaderStyleButtons( + controller: controller, + options: + const QuillToolbarSelectHeaderStyleButtonsOptions( + iconSize: 20, + ), + ), + QuillToolbarToggleStyleButton( + attribute: Attribute.ol, + controller: controller, + options: const QuillToolbarToggleStyleButtonOptions( + iconData: Icons.format_list_numbered, + iconSize: 20, + ), + ), + QuillToolbarToggleStyleButton( + attribute: Attribute.ul, + controller: controller, + options: const QuillToolbarToggleStyleButtonOptions( + iconData: Icons.format_list_bulleted, + iconSize: 20, + ), + ), + QuillToolbarToggleStyleButton( + attribute: Attribute.blockQuote, + controller: controller, + options: const QuillToolbarToggleStyleButtonOptions( + iconData: Icons.format_quote, + iconSize: 20, + ), + ), + VerticalDivider( + indent: 12, + endIndent: 12, + color: Colors.grey.shade400, + ), + QuillToolbarIndentButton( + controller: controller, + isIncrease: true, + options: const QuillToolbarIndentButtonOptions( + iconData: Icons.format_indent_increase, + iconSize: 20, + )), + QuillToolbarIndentButton( + controller: controller, + isIncrease: false, + options: const QuillToolbarIndentButtonOptions( + iconData: Icons.format_indent_decrease, + iconSize: 20, + ), + ), + ]; + }, + ), + ), + ), + Expanded( + child: QuillEditor.basic( + configurations: const QuillEditorConfigurations( + readOnly: false, + placeholder: 'Write your notes', + padding: EdgeInsets.all(16), + ), + ), + ) + ], + ), +) +``` + +4. The `QuillEditor` and `QuillEditor.basic()` + +since the `QuillEditor.basic()` is a lighter version than the original `QuillEditor` since it has less required configurations so we didn't change much, other than configuration class, but we most inform you if you are plan on sending pull request or you are a maintainer and when you add new property or change anything in `QuillEditorConfigurations` please regenerate the `copyWith` otherwise the `QuilEditor.basic()` will not apply some configurations + +we have disabled the line numbers in the code block by default, you can enable them again using the followings: + +```dart +QuillEditor.basic( + configurations: const QuillEditorConfigurations( + elementOptions: QuillEditorElementOptions( + codeBlock: QuillEditorCodeBlockElementOptions( + enableLineNumbers: true, + ), + ), + ), +) +``` + +5. `QuillCustomButton`: + +We have renamed the property `icon` to `iconData` for indicate it a icon data and not icon widget +```dart + QuillCustomButton( + iconData: Icons.ac_unit, + onTap: () { + debugPrint('snowflake'); + } + ), +``` + +6. Using custom local for both `QuillEditor` and `QuillToolbar` + +We have added sharedConfigurations property for shared things +```dart + QuillProvider( + configurations: QuillConfigurations( + controller: _controller, + sharedConfigurations: const QuillSharedConfigurations( + locale: Locale('fr'), + ), + ), + child: Column( + children: [ + const QuillToolbar( + configurations: QuillToolbarConfigurations(), + ), + Expanded( + child: QuillEditor.basic( + configurations: const QuillEditorConfigurations(), + ), + ) + ], + ), +) +``` + +7. Custom Size Image for other platforms (excluding web) + +We have added new properties `width`, `height`, `margin`, `alignment` for all platforms other than mobile and web for the images for example + +```dart +{ + "insert": { + "image": "https://user-images.githubusercontent.com/122956/72955931-ccc07900-3d52-11ea-89b1-d468a6e2aa2b.png" + }, + "attributes":{ + "style":"width: 50; height: 50; margin: 10; alignment: topLeft" + } +} +``` + +8. Other Improvemenets + +You don't need anything to get this done, we have used const more when possible, removed unused evenets, flutter best practices, convert to stateless widgets when possible, use better ways to listen for changes example: + + instead of + +```dart +MediaQuery.of(context).size; +``` + +we will use +```dart +MediaQuery.sizeOf(context); +``` +We also minimized the amount of rebuilds using more efficent logic and there is more. + +9. More options + +We have add more options in the extension package, for all the buttons, configurations, animations, enable and disable things + +If you have facing any issues or questions feel free to ask us on Github issues \ No newline at end of file diff --git a/lib/src/models/config/editor/element_options.dart b/lib/src/models/config/editor/element_options.dart index a88433c4..a2c20171 100644 --- a/lib/src/models/config/editor/element_options.dart +++ b/lib/src/models/config/editor/element_options.dart @@ -8,12 +8,12 @@ export 'elements/code_block.dart'; @immutable class QuillEditorElementOptions extends Equatable { const QuillEditorElementOptions({ - this.code = const QuillEditorCodeBlockElementOptions(), + this.codeBlock = const QuillEditorCodeBlockElementOptions(), }); - final QuillEditorCodeBlockElementOptions code; + final QuillEditorCodeBlockElementOptions codeBlock; @override List get props => [ - code, + codeBlock, ]; } diff --git a/lib/src/widgets/text_block.dart b/lib/src/widgets/text_block.dart index e2671ce5..d10596fe 100644 --- a/lib/src/widgets/text_block.dart +++ b/lib/src/widgets/text_block.dart @@ -232,7 +232,7 @@ class EditableTextBlock extends StatelessWidget { ); } if (attrs.containsKey(Attribute.codeBlock.key) && - context.requireQuillEditorElementOptions.code.enableLineNumbers) { + context.requireQuillEditorElementOptions.codeBlock.enableLineNumbers) { return QuillNumberPoint( index: index, indentLevelCounts: indentLevelCounts, diff --git a/pubspec.yaml b/pubspec.yaml index 9e064a1a..f7885b20 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: flutter_quill description: A rich text editor built for the modern Android, iOS, web and desktop platforms. It is the WYSIWYG editor and a Quill component for Flutter. -version: 7.10.2 +version: 8.0.0 homepage: https://1o24bbs.com/c/bulletjournal/108 repository: https://github.com/singerdmx/flutter-quill topics: