huypanha
/
flutter-quill
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(markdown-files): improve markdown docs files

Browse Source
pull/1924/head
Ellet 10 months ago
parent 97a08b82b7
commit e863a539bf
10 changed files with 117 additions and 108 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 53
      CONTRIBUTING.md
  2. 3
      doc/configurations/custom_buttons.md
  3. 8
      doc/configurations/font_size.md
  4. 11
      doc/configurations/localizations_setup.md
  5. 8
      doc/configurations/using_custom_app_widget.md
  6. 24
      doc/custom_embed_blocks.md
  7. 5
      doc/custom_toolbar.md
  8. 26
      doc/development_notes.md
  9. 55
      doc/todo.md
  10. 32
      doc/translation.md

53
CONTRIBUTING.md
Unescape View File

@ -2,19 +2,26 @@
First of all, we would like to thank you for your time and efforts on this project, we appreciate it
You can see tutorials online on how to contribute to any open source project, it's a simple process, and you can do it even if you are not Git expert, simply start by forking the repository, clone it, creating a new branch, make your changes and commit them, then push the branch to your fork, and you will get link to send a PR to the upstream repository
You can see tutorials online on how to contribute to any open source project, it's a simple process, and you can do it
even if you are not Git expert, simply start by forking the repository, clone it, create a new branch, make your
changes and commit them, then push the branch to your fork, and you will get link to send a PR to the upstream
repository
If you don't have anything specific in mind to improve or fix, you can take a look at the issues tab or take a look at the todos of the project, they all start with `TODO:` so you can search in your IDE or use the todos tab in the IDE
If you don't have anything specific in mind to improve or fix, you can take a look at the issues tab or take a look at
the todos of the project, they all start with `TODO:` so you can search in your IDE or use the todos tab in the IDE
You can also check the [Todo](./doc/todo.md) list or the issues if you want to
You can also check the [Todo](./doc/todo.md) list or the issues if you want to
> Make sure to not edit the `CHANGELOG.md` or the version in `pubspec.yaml` for any of the packages, this process will be automated by CI.
> Make sure to not edit the `CHANGELOG.md` or the version in `pubspec.yaml` for any of the packages, CI will automate
> this process.
## Requirements
- [Flutter SDK](https://docs.flutter.dev/get-started/install) which can be installed by following the instructions the provided link, also make sure to add it to your path so `flutter --version` and `dart --version` work
- [Intellij IDEA Community Edition](https://www.jetbrains.com/idea/download/) or [Android Studio](https://developer.android.com/studio) (with Dart and Flutter plugins) or use [VS Code](https://code.visualstudio.com/) (with Dart and flutter extensions)
- [Flutter SDK](https://docs.flutter.dev/get-started/install), which can be installed by following the instructions the
provided link, also make sure to add it to your path so `flutter --version` and `dart --version` work
- [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/)
or [Android Studio](https://developer.android.com/studio) (with Dart and Flutter plugins) or
use [VS Code](https://code.visualstudio.com/) (with Dart and flutter extensions)
## Test your changes 🧪
@ -22,8 +29,10 @@ Make sure you have the [Requirement](#requirements) installed and configured cor
To test your changes:
1. Go to the [Example project](./example/) in [main.dart](./example/lib/main.dart) and run the project either by using your IDE or `flutter run`
2. Make sure to read the [Development Notes](./doc/development_notes.md) if you made certain changes or [Translations Page](./doc/translation.md) if you made changes to the translations of the package
1. Go to the [Example project](./example/) in [main.dart](./example/lib/main.dart) and run the project either by using
your IDE or `flutter run`
2. Make sure to read the [Development Notes](./doc/development_notes.md) if you made certain changes
or [Translations Page](./doc/translation.md) if you made changes to the translations of the package
## Steps to contributing
@ -35,24 +44,29 @@ You will need a GitHub account as well as Git installed and configured with your
```
git remote add upstream git@github.com:singerdmx/flutter-quill.git
```
4. Open the project with your favorite IDE, usually, we prefer to use Jetbrains IDEs, but since [VS Code](https://code.visualstudio.com) is more used and has more support for Dart, then we suggest using it if you want to.
4. Open the project with your favorite IDE, usually, we prefer to use Jetbrains IDEs, but
since [VS Code](https://code.visualstudio.com) is more used and has more support for Dart, then we suggest using it
if you want to.
5. Create a new git branch and switch to it using `git checkout -b`
6. Make your changes
7. If you are working on changes that depend on different libraries in the same repo, then in that directory copy `pubspec_overrides.yaml.disabled` which exists in all the packages (`flutter_quill_test` and `flutter_quill_extensions` etc...)
to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be used by dart pub to override the libraries
7. If you are working on changes that depend on different libraries in the same repo, then in that directory
copy `pubspec_overrides.yaml.disabled` which exists in all the packages (`flutter_quill_test`
and `flutter_quill_extensions` etc...)
to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be used by dart pub to override the
libraries
```
cp pubspec_overrides.yaml.disabled pubspec_overrides.yaml
```
or save some time with the following script:
or save some time with the following script:
<!-- TODO: We should update this script to dart instead -->
```
./scripts/enable_local_dev.sh
```
8. Test them in the [example](./example) and add changes in there if necessary
9. Run the following script if possible
```
./scripts/before_push.sh
```
9. Run the following script if possible
```
./scripts/before_push.sh
```
10. When you are done sending your pull request, run:
```
git add .
@ -62,10 +76,11 @@ to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be us
this will push the new branch to your forked repository
11. Now you can send your pull request either by following the link that you will get in the command line or open your
forked repository. You will find an option to send the pull request, you can also
open the [Pull Requests](https://github.com/singerdmx/flutter-quill) tab and send new pull request
forked repository. You will find an option to send the pull request, you can also
open the [Pull Requests](https://github.com/singerdmx/flutter-quill) tab and send new pull request
12. Now, wait for the review, and we might ask you to make more changes, then run:
```
git add .
git commit -m "Your new commit message"

3
doc/configurations/custom_buttons.md
Unescape View File

@ -1,6 +1,7 @@
# Custom `QuillToolbar` Buttons
You may add custom buttons to the _end_ of the toolbar, via the `customButtons` option, which is a `List` of `QuillToolbarCustomButtonOptions`.
You may add custom buttons to the _end_ of the toolbar, via the `customButtons` option, which is a `List`
of `QuillToolbarCustomButtonOptions`.
To add an Icon, we should use a new `QuillToolbarCustomButtonOptions` class

8
doc/configurations/font_size.md
Unescape View File

@ -1,8 +1,12 @@
# Font Size
Within the editor toolbar, a drop-down with font-sizing capabilities is available. This can be enabled or disabled with `showFontSize`.
Within the editor toolbar, a drop-down with font-sizing capabilities is available.
This can be enabled or disabled
with `showFontSize`.
When enabled, the default font-size values can be modified via _optional_ `fontSizeValues`. `fontSizeValues` accepts a `Map<String, String>` consisting of a `String` title for the font size and a `String` value for the font size. Example:
When enabled, the default font-size values can be modified via _optional_ `fontSizeValues`.
Accepts a `Map<String, String>` consisting of a `String` title for the font size and a `String` value for the font size.
Example:
```dart
fontSizeValues: const {'Small': '8', 'Medium': '24.5', 'Large': '46'}

11
doc/configurations/localizations_setup.md
Unescape View File

@ -1,7 +1,9 @@
# Localizations Setup
in addition to the required delegates mentioned above in [Using custom app widget](./using_custom_app_widget.md)
which are:
```dart
localizationsDelegates: const [
DefaultCupertinoLocalizations.delegate,
@ -9,9 +11,11 @@ localizationsDelegates: const [
DefaultWidgetsLocalizations.delegate,
],
```
which are used by official Flutter widgets
The library also needs the
The library also needs the `FlutterQuillLocalizations.delegate`
```dart
// Required localizations delegates ...
FlutterQuillLocalizations.delegate
@ -19,7 +23,10 @@ FlutterQuillLocalizations.delegate
To offer the default localizations.
But **you don't have to** since we have wrapped the `QuillEditor` and `QuillToolbar` with `FlutterQuillLocalizationsWidget` which will check if it sets then it will go, if not, then it will be provided only for them, so it's not really required, but if you are overriding the `localizationsDelegates` you could also add the `FlutterQuillLocalizations.delegate`
But **you don't have to** since we have wrapped the `QuillEditor` and `QuillToolbar`
with `FlutterQuillLocalizationsWidget` which will check if it sets then it will go, if not, then it will be provided
only for them, so it's not really required, but if you are overriding the `localizationsDelegates` you could also add
the `FlutterQuillLocalizations.delegate`
which won't change anything
There are additional notes in the [Translation](../translation.md) section

8
doc/configurations/using_custom_app_widget.md
Unescape View File

@ -7,7 +7,7 @@ This project uses some adaptive widgets like `AdaptiveTextSelectionToolbar` whic
3. Default Widgets Localizations delegate
You don't need to include those since they are defined by default
but if you are using a Custom app or you are overriding the `localizationsDelegates` in the App widget
but if you are using a Custom app or you are overriding the `localizationsDelegates` in the App widget
then please make sure it includes those:
```dart
@ -18,7 +18,8 @@ localizationsDelegates: const [
],
```
You might need more depending on your use case, for example, if you are using custom localizations for your app, using a custom app widget like `FluentApp` from [FluentUI]
You might need more depending on your use case, for example, if you are using custom localizations for your app, using a
custom app widget like `FluentApp` from [FluentUI]
which will also need
```dart
@ -29,7 +30,8 @@ localizationsDelegates: const [
],
```
Note: In the latest versions of `FluentApp` you no longer need to add the `localizationsDelegates` but this is just an example, for more [info](https://github.com/bdlukaa/fluent_ui/pull/946)
Note: In the latest versions of `FluentApp` you no longer need to add the `localizationsDelegates` but this is just an
example, for more [info](https://github.com/bdlukaa/fluent_ui/pull/946)
There are additional notes on the [Localizations](./localizations_setup.md) page

24
doc/custom_embed_blocks.md
Unescape View File

@ -1,12 +1,16 @@
# Custom Embed Blocks
Sometimes you want to add some custom content inside your text, custom widgets inside of them. An example is adding notes to the text, or anything custom that you want to add in your text editor.
Sometimes you want to add some custom content inside your text, custom widgets inside them.
An example is adding
notes to the text, or anything custom that you want to add in your text editor.
The only thing that you need is to add a `CustomBlockEmbed` and provide a builder for it to the `embedBuilders` parameter, to transform the data inside of the Custom Block into a widget!
The only thing that you need is to add a `CustomBlockEmbed` and provide a builder for it to the `embedBuilders`
parameter, to transform the data inside the Custom Block into a widget!
Here is an example:
Starting with the `CustomBlockEmbed`, here we extend it and add the methods that are useful for the 'Note' widget, which will be the `Document`, used by the `flutter_quill` to render the rich text.
Starting with the `CustomBlockEmbed`, here we extend it and add the methods that are useful for the 'Note' widget, which
will be the `Document`, used by the `flutter_quill` to render the rich text.
```dart
class NotesBlockEmbed extends CustomBlockEmbed {
@ -21,7 +25,8 @@ class NotesBlockEmbed extends CustomBlockEmbed {
}
```
After that, we need to map this "notes" type into a widget. In that case, I used a `ListTile` with a text to show the plain text resume of the note, and the `onTap` function to edit the note.
After that, we need to map this "notes" type into a widget. In that case, I used a `ListTile` with a text to show the
plain text resume of the note, and the `onTap` function to edit the note.
Don't forget to add this method to the `QuillEditor` after that!
```dart
@ -64,7 +69,11 @@ class NotesEmbedBuilder extends EmbedBuilder {
}
```
And finally, we write the function to add/edit this note. The `showDialog` function shows the QuillEditor to edit the note after the user ends the edition, we check if the document has something, and if it has, we add or edit the `NotesBlockEmbed` inside of a `BlockEmbed.custom` (this is a little detail that will not work if you don't pass the `CustomBlockEmbed` inside of a `BlockEmbed.custom`).
And finally, we write the function to add/edit this note.
The `showDialog` function shows the QuillEditor to edit the
note after the user ends the edition, we check if the document has something, and if it has, we add or edit
the `NotesBlockEmbed` inside of a `BlockEmbed.custom` (this is a little detail that will not work if you don't pass
the `CustomBlockEmbed` inside of a `BlockEmbed.custom`).
```dart
Future<void> _addEditNote(BuildContext context, {Document? document}) async {
@ -116,11 +125,12 @@ Future<void> _addEditNote(BuildContext context, {Document? document}) async {
}
```
And voila, we have a custom widget inside of the rich text editor!
And voilà, we have a custom widget inside the rich text editor!
<p float="left">
<img width="400" alt="1" src="https://i.imgur.com/yBTPYeS.png">
</p>
> 1. For more info and a video example, see the [PR of this feature](https://github.com/singerdmx/flutter-quill/pull/877)
> 1. For more info and a video example, see
the [PR of this feature](https://github.com/singerdmx/flutter-quill/pull/877)
> 2. For more details, check out [this YouTube video](https://youtu.be/pI5p5j7cfHc)

5
doc/custom_toolbar.md
Unescape View File

@ -1,6 +1,6 @@
# Custom Toolbar
If you want to use a custom toolbar but still want the support of this library
If you want to use a custom toolbar but still want the support of this library,
You can use the `QuillBaseToolbar` which is the base for the `QuillToolbar`
Example:
@ -112,4 +112,5 @@ QuillToolbar(
)
```
if you want a more customized toolbar feel free to create your own and use the `controller` to interact with the editor. checkout the `QuillToolbar` and the buttons inside it to see an example of how that will work
if you want a more customized toolbar feel free to create your own and use the `controller` to interact with the editor.
checkout the `QuillToolbar` and the buttons inside it to see an example of how that will work

26
doc/development_notes.md
Unescape View File

@ -1,10 +1,22 @@
# Development notes
- When updating the translations or localizations in the app, please take a look at the [Translation](./translation.md) page as it has important notes in order to work, if you also add a feature that adds new localizations then you need to the instructions of it in order for the translations to take effect
- We use the same package version and `CHANGELOG.md` for all the packages, for more [details](https://github.com/singerdmx/flutter-quill/pull/1878), the process is automated. We have a script that will do the followings:
1. Generate the `CHANGELOG.md` files by `CHANGELOG_JSON.json` (source of data) and then paste them into all the packages we have (overwrite), you don't need to
manually change/update any of the mentioned files above, once a new GitHub release published, the CI will take the release notes from the release, pass the info to the
script, the release notes can be auto-generated by Github using a button, a descirptive PRs title would help but you don't have to since we can change it at anytime.
2. The script require the new version as an argument, you don't need to run the script manually, when a maintainer create a new tag and publish a new GitHub release, the publish workflow will extract the new version from the tag name, run the script (pass the extracted version as an argument), commit the changes and push them into the repository, the script will update the `version` property for all the packages so the `flutter pub publish` will use the new version for each package correctly.
- When updating the translations or localizations in the app, please take a look at the [Translation](./translation.md)
page as it has important notes to work.
If you also add a feature that adds new localizations, then you need it
to the instructions of it in order for the translations to take effect
- We use the same package version and `CHANGELOG.md` for all the packages, for
more [details](https://github.com/singerdmx/flutter-quill/pull/1878), the process is automated. We have a script that
will do the following:
1. Generate the `CHANGELOG.md` files by `CHANGELOG_JSON.json` (source of data) and then paste them into all the
packages we have (overwrite), you don't need to
manually change/update any of the mentioned files above, once a new GitHub release published, the CI will take
the release notes from the release, pass the info to the
script, the release notes can be auto-generated by GitHub using a button, a descriptive PRs title would help but
you don't have to since we can change it at anytime.
2. The script require the new version as an argument, you don't need to run the script manually, when a maintainer
create a new tag and publish a new GitHub release, the publish workflow will extract the new version from the tag
name, run the script (pass the extracted version as an argument), commit the changes and push them into the
repository, the script will update the `version` property for all the packages so the `flutter pub publish` will
use the new version for each package correctly.
the script will be used the CI and no need to run it manually
the script will be used the CI and no need to run it manually

55
doc/todo.md
Unescape View File

@ -1,55 +0,0 @@
# Todo
This is a todo list page that added recently and will be updated soon.
## Table of contents
- [Todo](#todo)
- [Table of contents](#table-of-contents)
- [Flutter Quill](#flutter-quill)
- [Features](#features)
- [Improvemenets](#improvemenets)
- [Bugs](#bugs)
- [Flutter Quill Extensions](#flutter-quill-extensions)
- [Features](#features-1)
- [Improvemenets](#improvemenets-1)
- [Bugs](#bugs-1)
## Flutter Quill
### Features
- Add support for Text magnification feature, for more [info](https://github.com/singerdmx/flutter-quill/issues/1504)
- Provide a way to expose quills undo redo stacks, for more [info](https://github.com/singerdmx/flutter-quill/issues/1381)
- Add callback to the `QuillToolbarColorButton` for custom color picking logic
### Improvemenets
- Improve the Raw Quill Editor, for more [info](https://github.com/singerdmx/flutter-quill/issues/1509)
- Provide more support to all the platforms
- Extract the shared properties between `QuillRawEditorConfigurations` and `QuillEditorConfigurations`
- The todo in the this [commit](https://github.com/singerdmx/flutter-quill/commit/79597ea6425357795c0663588ac079665241f23a) needs to be checked
- use `maybeOf` and of instead `ofNotNull` in the providers to follow flutter offical convenstion, completly rework the providers and update the build context extensions
- Add line through to the text when the check point checked is true
- Change the color of the numbers and dots in ol/ul to match the ones in the item list
- Fix the bugs of the font family and font size
- Try to update Quill Html Converter
- When pasting a HTML text from cliboard by not using the context menu builder, the new logic won't work
- When selecting all text and paste HTML text, it will not replace the current text, instead it will add a text
- Add strike-through in checkbox text when the checkpoint is checked
- No more using of dynamic
- There is a bug here, the first character is not being formatted when choosing font family or font size and type in the editor
- Fix the toolbar and the toolbar buttons, rework some of them, for example missing tooltips
### Bugs
Empty for now.
Please go to the [issues](https://github.com/singerdmx/flutter-quill/issues)
## Flutter Quill Extensions
### Features
### Improvemenets
### Bugs

32
doc/translation.md
Unescape View File

@ -1,6 +1,8 @@
# Translation
The package offers translations for the quill toolbar and editor, it will follow the locale that is defined in your `WidgetsApp` for example `MaterialApp` which usually follows the system locally unless you set your own locale with:
The package offers translations for the quill toolbar and editor, it will follow the locale that is defined in
your `WidgetsApp` for example `MaterialApp` which usually follows the system locally unless you set your own locale
with:
```dart
QuillToolbar.simple(
@ -38,16 +40,20 @@ Currently, translations are available for these 41 locales:
The translation files are located in the [l10n](../lib/src/l10n/) folder. Feel free to contribute your own translations.
You can take a look at the [untranslated.json](../lib/src/l10n/untranslated.json) file, which is a generated file that tells you which keys with which locales haven't translated so you can find the missings easily.
You can take a look at the [untranslated.json](../lib/src/l10n/untranslated.json) file, which is a generated file that
tells you which keys with which locales haven't translated so you can find the missing easily.
<details>
<summary>Add new local</summary>
1. Create a new file in [l10n](../lib/src/l10n/) folder, with the following name`quill_${localName}.arb` for example `quill_de.arb`
1. Create a new file in [l10n](../lib/src/l10n/) folder, with the following name`quill_${localName}.arb` for
example `quill_de.arb`
2. Copy the [Arb Template](../lib/src/l10n/quill_en.arb) file and paste it into your new file, replace the values with your translations
2. Copy the [Arb Template](../lib/src/l10n/quill_en.arb) file and paste it into your new file, replace the values with
your translations
3. Update [Supported Locales](#supported-locales) section in this page to update the supported translations for both the number and the list
3. Update [Supported Locales](#supported-locales) section in this page to update the supported translations for both the
number and the list
</details>
@ -58,13 +64,17 @@ You can take a look at the [untranslated.json](../lib/src/l10n/untranslated.json
2. Find the existing local, let's say you want to update the Korean translations, it will be `quill_ko.arb`
3. Use [untranslated.json](../lib/src/l10n/untranslated.json) as reference to find missings, update or add what you want to translate.
3. Use [untranslated.json](../lib/src/l10n/untranslated.json) as a reference to find missing, update or add what you
want
to translate.
</details>
<br>
We usually avoid **updating existing value of a key in the template file without updating the key or creating a new one**, this will not update the [untranslated.json](../lib/src/l10n/untranslated.json) correctly and will make it harder for contributors to find missings or incomplete.
> We usually avoid **updating the existing value of a key in the template file without updating the key or creating a new
one**.
> This will not update the [untranslated.json](../lib/src/l10n/untranslated.json) correctly and will make it harder
for contributors to find missing or incomplete.
Once you finish, run the following script:
@ -80,9 +90,11 @@ dart fix --apply ./lib/src/l10n/generated
dart format ./lib/src/l10n/generated
```
The script above will generate Dart files from the Arb files in order to test the changes and take effect, otherwise you won't notice a difference.
The script above will generate Dart files from the Arb files to test the changes and take effect, otherwise you
won't notice a difference.
> If you added or removed translations in the template file, make sure to update `_expectedTranslationKeysLength` variable in [scripts/ensure_translations_correct.dart](../scripts/ensure_translations_correct.dart) <br>
> If you added or removed translations in the template file, make sure to update `_expectedTranslationKeysLength`
> variable in [scripts/ensure_translations_correct.dart](../scripts/ensure_translations_correct.dart) <br>
> Otherwise you don't need to update it.
Then open a pull request so everyone can benefit from your translations!

Write Preview
Loading…
Cancel
Save