From 5d24c9b0f466c1885088e0077a8c0fb69cf193be Mon Sep 17 00:00:00 2001 From: "Lucas.Xu" Date: Wed, 17 Aug 2022 20:50:56 +0800 Subject: [PATCH 1/5] Update README.md --- frontend/app_flowy/packages/appflowy_editor/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/app_flowy/packages/appflowy_editor/README.md b/frontend/app_flowy/packages/appflowy_editor/README.md index 4f078f1fa9f5f..a8c59a1a5fa4f 100644 --- a/frontend/app_flowy/packages/appflowy_editor/README.md +++ b/frontend/app_flowy/packages/appflowy_editor/README.md @@ -87,4 +87,4 @@ Please refer to [customizing a shortcut event](documentation/customizing.md#cust Please refer to the API documentation (link). ## Contributing -Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Please look at [CONTRIBUTING.md](documentation/contributing.md) for details. +Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Please look at [CONTRIBUTING.md](https://appflowy.gitbook.io/docs/essential-documentation/contribute-to-appflowy/contributing-to-appflowy) for details. From 912d0919b5cca34b5a6623fd973f6d3dc67d8607 Mon Sep 17 00:00:00 2001 From: "Lucas.Xu" Date: Wed, 17 Aug 2022 20:54:22 +0800 Subject: [PATCH 2/5] Update testing.md --- .../app_flowy/packages/appflowy_editor/documentation/testing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md b/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md index badd6f0924e11..dd98fa9a9e778 100644 --- a/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md +++ b/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md @@ -43,7 +43,6 @@ print(length); **Get the node of the specified path** ```dart -// 获取上述文档结构中的第一个文本节点 final firstTextNode = editor.nodeAtPath([0]) as TextNode; ``` From 049da503ff93aa57914b7c6900196c85efea5024 Mon Sep 17 00:00:00 2001 From: Annie Date: Wed, 17 Aug 2022 21:25:24 +0800 Subject: [PATCH 3/5] Update customizing.md --- .../documentation/customizing.md | 41 +++++++++++-------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/frontend/app_flowy/packages/appflowy_editor/documentation/customizing.md b/frontend/app_flowy/packages/appflowy_editor/documentation/customizing.md index eac3bcad7d627..85fa195c96628 100644 --- a/frontend/app_flowy/packages/appflowy_editor/documentation/customizing.md +++ b/frontend/app_flowy/packages/appflowy_editor/documentation/customizing.md @@ -1,11 +1,12 @@ -# How to customizing ... +# How to customize ... -## Customizing a shortcut event -we will use a simple example to describe how to quickly extend shortcut event. +## Customize a shortcut event + +We will use a simple example to illustrate how to quickly add a shortcut event. For example, typing `_xxx_` will be converted into _xxx_. -To start with, we build the simplest example, just a blank document. +Let's start with a blank document. ```dart @override @@ -22,11 +23,11 @@ Widget build(BuildContext context) { } ``` -Nothing will happen after typing `_xxx_`. +At this point, nothing magic will happen after typing `_xxx_`. ![Before](./images/customizing_a_shortcut_event_before.gif) -Next, we will create a function to handler underscore input. +Next, we will create a function to handle an underscore input. ```dart import 'package:appflowy_editor/appflowy_editor.dart'; @@ -42,7 +43,7 @@ FlowyKeyEventHandler underscoreToItalicHandler = (editorState, event) { }; ``` -Then, we need to determine if the currently selected node is `TextNode` and is a single-select case, because for the multi-select case, underscore input should be considered as replacement. +Then, we need to determine if the currently selected node is `TextNode` and the selection is collapsed. ```dart // ... @@ -50,7 +51,7 @@ FlowyKeyEventHandler underscoreToItalicHandler = (editorState, event) { // ... // Obtaining the selection and selected nodes of the current document through `selectionService`. - // And determine whether it is a single selection and whether the selected node is a text node. + // And determine whether the selection is collapsed and whether the selected node is a text node. final selectionService = editorState.service.selectionService; final selection = selectionService.currentSelection.value; final textNodes = selectionService.currentSelectedNodes.whereType(); @@ -59,7 +60,11 @@ FlowyKeyEventHandler underscoreToItalicHandler = (editorState, event) { } ``` -Now, we start working on underscore logic by looking for the position of the previous underscore and returning if not found. If found, the text wrapped in the two underscores will be converted info italic. +Now, we start dealing with underscore. + +Look for the position of the previous underscore and +1. return, if not found. +2. if found, the text wrapped in between two underscores will be displayed in italic. ```dart // ... @@ -94,7 +99,7 @@ FlowyKeyEventHandler underscoreToItalicHandler = (editorState, event) { }; ``` -So far, the 'underscore handler' function has completed and only needs to be injected info AppFlowyEditor. +So far, the 'underscore handler' function is done and the only task left is to inject it into the AppFlowyEditor. ```dart @override @@ -117,12 +122,12 @@ Widget build(BuildContext context) { [Complete code example]() -## Customizing a component -we will use a simple example to describe how to quickly extend custom component. +## Customize a component +We will use a simple example to showcase how to quickly add a custom component. -For example, we want to render an image from network. +For example, we want to render an image from the network. -To start with, we build the simplest example, just a blank document. +To start with, let's create an empty document by running commands as follows: ```dart @override @@ -139,7 +144,7 @@ Widget build(BuildContext context) { } ``` -Next, we choose a unique string for the type of the custom node and use `network_image` in this case. And we add `network_image_src` to the `attributes` to describe the link of the image. +Next, we choose a unique string for your custom node's type. We use `network_image` in this case. And we add `network_image_src` to the `attributes` to describe the link of the image. > For the definition of the [Node](), please refer to this [link](). @@ -152,7 +157,9 @@ Next, we choose a unique string for the type of the custom node and use `network } ``` -Then, we create a class that inherits [NodeWidgetBuilder](). As shown in the autoprompt, we need to implement two functions, one that returns a widget and the other that verifies the correctness of the [Node](). +Then, we create a class that inherits [NodeWidgetBuilder](). As shown in the autoprompt, we need to implement two functions: +1. one returns a widget +2. the other verifies the correctness of the [Node](). ```dart @@ -276,4 +283,4 @@ return AppFlowyEditor( ![](./images/customizing_a_component.gif) -[Complete code example]() \ No newline at end of file +[Here you can check out the complete code file of this example]() From 020aed275f626900cf7dcab19226b00b63fd84cd Mon Sep 17 00:00:00 2001 From: Annie Date: Wed, 17 Aug 2022 21:36:21 +0800 Subject: [PATCH 4/5] Update testing.md --- .../appflowy_editor/documentation/testing.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md b/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md index dd98fa9a9e778..25d918c4b5f94 100644 --- a/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md +++ b/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md @@ -1,10 +1,10 @@ # Testing -> The directory structure of test files is consistent with the code files, makes it easy for us to judge the test status of the new added files and to retrieve the test code path of the corresponding file. +> The directory structure of test files is consistent with the code files, making it easy for us to map a file with the corresponding test and check if the test is updated ## Testing Functions -**Construct document for testing** +**Construct a document for testing** ```dart const text = 'Welcome to Appflowy 😁'; // Get the instance of editor. @@ -35,13 +35,13 @@ editor.insertTextNode( await editor.startTesting(); ``` -**Get the number of nodes in document** +**Get the number of nodes in the document** ```dart final length = editor.documentLength; print(length); ``` -**Get the node of the specified path** +**Get the node of a defined path** ```dart final firstTextNode = editor.nodeAtPath([0]) as TextNode; ``` @@ -59,7 +59,7 @@ final selection = editor.documentSelection; print(selection); ``` -**Simulate shortcut event input** +**Simulate shortcut event inputs** ```dart // Command + A. await editor.pressLogicKey(LogicalKeyboardKey.keyA, isMetaPressed: true); @@ -71,7 +71,7 @@ await editor.pressLogicKey( ); ``` -**Simulate text input** +**Simulate a text input** ```dart // Insert 'Hello World' at the beginning of the first node. editor.insertText(firstTextNode, 'Hello World', 0); @@ -88,9 +88,9 @@ print(attributes); ``` ## Example -For example, we are going to test the file `select_all_handler.dart` +For example, we are going to test `select_all_handler.dart` + -**Full code example** ```dart import 'package:appflowy_editor/appflowy_editor.dart'; import 'package:flutter/services.dart'; @@ -125,4 +125,4 @@ void main() async { } ``` -For the rest of the information on testing, such as simulated clicks, please refer to [An introduction to widget testing](https://docs.flutter.dev/cookbook/testing/widget/introduction) +For more information about testing, such as simulating a click, please refer to [An introduction to widget testing](https://docs.flutter.dev/cookbook/testing/widget/introduction) From ca4165a5cd859d0e3a098fd45eb6e0dde6b41e86 Mon Sep 17 00:00:00 2001 From: Annie Date: Wed, 17 Aug 2022 21:39:30 +0800 Subject: [PATCH 5/5] Update README.md --- frontend/app_flowy/packages/appflowy_editor/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/app_flowy/packages/appflowy_editor/README.md b/frontend/app_flowy/packages/appflowy_editor/README.md index a8c59a1a5fa4f..2f6d40f2fd3df 100644 --- a/frontend/app_flowy/packages/appflowy_editor/README.md +++ b/frontend/app_flowy/packages/appflowy_editor/README.md @@ -22,7 +22,7 @@ and the Flutter guide for ## Key Features -* Allow you to build rich, intuitive editors like those in Notion +* Allow you to build rich, intuitive editors * Customize to your needs by customizing components, shortcut events, and many more coming soon including menu options and themes * [Test-covered](https://github.com/LucasXu0/AppFlowy/blob/documentation/appflowy_editor/frontend/app_flowy/packages/appflowy_editor/documentation/testing.md) and maintained by AppFlowy's core team along with a community of more than 1,000 builders