# Demystifying AppFlowy Editor's Codebase
by Mayur, as part of the AppFlowy Mentorship Program
## Introduction
The AppFlowy Editor package is one of the core components of AppFlowy. It is a popular package in the Flutter Community, offering highly customizable rich text editing experience.
This article is aimed at people looking to use the AppFlowy Editor in their own projects and at people who want to contribute to this package. It describes the project folder structuring and strategies for adding new features.
## Components of the Editor
Let’s explore what actually happens behind the scenes when a user creates a document with the AppFlowy Editor and discuss how that relates to its underlying components.
### The Selection Menu
When you start the Editor, you are asked to press the `/` (slash) key on your keyboard to get the Selection Menu.
The Selection Menu allows you to insert editor plugins or components.
the selection menu
Below is the code for the SelectionMenuWidget:
```dart
//appflowy-editor\lib\src\editor\selection_menu\selection_menu_widget.dart
class SelectionMenuWidget extends StatefulWidget {
const SelectionMenuWidget({
//constructor ...
}) : super(key: key);
final List items;
final int itemCountFilter;
final int maxItemInRow;
final SelectionMenuService menuService;
final EditorState editorState;
final VoidCallback onSelectionUpdate;
final VoidCallback onExit;
final SelectionMenuStyle selectionMenuStyle;
final bool deleteSlashByDefault;
//variable declarations
}
class _SelectionMenuWidgetState extends State {
...
}
```
The EditorState (the property `editorState` ) is an entity that encapsulates the state of the entire Editor and includes the services of the editor (discussed below).
The SelectionMenuService (the property `selectionMenuService`) is responsible for implementing the UI for the SelectionMenu. It achieves this by adding `OverlayEntry` on top of the Editor widget. This is a pattern you will encounter again when you explore the `Toolbar` and `FindAndReplace` plugins.
### Selection Menu Items
The `items` property of the SelectionMenuWidget is assigned a list of `SelectionMenuItems`.
Selection Menu Items consist of the following options which you see on the Selection Menu, such as:
* Text
* H1
* Image
* Quote
* Checkbox
This is what a typical `SelectionMenuItem` instance looks like:
```dart
// appflowy-editor\lib\src\editor\selection_menu\selection_menu_service.dart
SelectionMenuItem(
name: AppFlowyEditorLocalizations.current.bulletedList,
icon: (editorState, isSelected, style) => SelectionMenuIconWidget(
name: 'bulleted_list',
isSelected: isSelected,
style: style,
),
keywords: ['bulleted list', 'list', 'unordered list'],
handler: (editorState, _, __) {
insertBulletedListAfterSelection(editorState);
},
),
```
As you can see we have parameters for:
* name
* icon
* keywords
* handler
The *keywords* are used to filter results from the menu, and are matched against what you type after pressing `/` (slash).
The *handler* serves as a callback for when the user clicks on the SelectionMenuItem. This handler can be used to insert a node, transform the current node, and much more.
Once this node is inserted into the Document, the Editor searches for that node's respective BlockComponentBuilder to render it on the Editor.
### Nodes
Node is a class that is actually stored in the Document Tree.
Let us take a look at the definition of Node class:
```dart
// appflowy-editor\lib\src\core\document\node.dart
final class Node extends ChangeNotifier with LinkedListEntry {
Node({
required this.type,
String? id,
this.parent,
Attributes attributes = const {},
Iterable children = const [],
}) : _children = LinkedList()
..addAll(
children.map(
(e) => e..unlink(),
),
), // unlink the given children to avoid the error of "node has already a parent"
_attributes = attributes,
id = id ?? nanoid(10) {
for (final child in this.children) {
child.parent = this;
}
}
/// Parses an [Map] into a [Node]
factory Node.fromJson(Map json){...}
// other useful definitions and methods.
}
```
It has a `type` that defines the type of the node such as the heading, todo\_list, etc.
This type is used to determine which Block Component to render on the Flutter App, this determining logic is done by `BlockComponentRendererService`, which we will talk about later.
It has `attributes` that control its appearance and state. For example, todo\_list has an attribute called "checked" which determines whether it is completed or incomplete.
The `children` parameter defines the children of the node, these are stored in a LinkedList which combined with the Document Tree allows the Editor to support Node Hierarchy.
To learn more about Node and its properties, read this [article](https://blog-appflowy.ghost.io/how-we-built-a-highly-customizable-rich-text-editor-for-flutter/).
### Block Components
Each Node type has a corresponding BlockComponentBuilder which functions as a widget builder. It accepts a Node as an input and produces a Widget as an output, allowing you to get a [Flutter widget](https://api.flutter.dev/flutter/widgets/Widget-class.html) for a Node.
Take a look at the implementation of `BlockComponentBuilder` class at this location:
```
appflowy-editor\lib\src\editor\editor_component\service\renderer\block_component_service.dart
```
An example that implements the `BlockComponentBuilder` to show the bulleted\_list in the editor can be found here:
```
appflowy-editor\lib\src\editor\block_component\bulleted_list_block_component\bulleted_list_block_component.dart
```
### Putting it All Together
So let's outline what actually happens behind the scenes when we press a slash on the Editor and select an option, such as a Heading.
1. First, when we press `\` (slash), the `SelectionMenu` appears with a bunch of `SelectionMenuItems`.
2. When we click the Heading item, a Node of the corresponding type ('heading') gets inserted in the **Editor Document Tree** using the `EditorState`.
3. The `AppFlowyEditor` then looks at its newly added node and searches for its corresponding `BlockComponentBuilder` using the type of the Node. So it will search for a BlockComponentBuilder for type 'heading'. Once found, it executes the builder to show a Flutter representation of the Heading Node.
## Folder Organization
Now that we have a basic understanding of how things are happening inside the Editor and how its components work, let's explore the Folder organization to get an understanding of what is located where and discuss some other important modules that are part of the AppFlowyEditor.
Here is the organization of folders that make the AppFlowyEditor package:
`AppFlowy-Editor`\
`├── example`\
`├── lib`\
`├── ├── l10n`\
`├── ├── src`\
`├── ├── ├── core`\
`├── ├── ├── editor`\
`├── ├── ├── extensions`\
`├── ├── ├── history`\
`├── ├── ├── infra`\
`├── ├── ├── l10n`\
`├── ├── ├── plugins`\
`├── ├── ├── render`\
`├── ├── ├── service`\
`├── ├── └── editor_state.dart`\
`├── └── appflowy_editor.dart`\
`├── test`\
`└──pubspec.yaml`
We are mainly concerned about the `lib/src` folder, which is the main source code for our package.
Below is an overview of notable folders inside `src` and understand what they contain.
### src\core
This is the library that contains the core modules such as node, path, attributes, position, selection, transaction, document, and more. To learn more about what these actually are, read this [article](https://blog-appflowy.ghost.io/how-we-built-a-highly-customizable-rich-text-editor-for-flutter/).
### src\editor
This folder consists of all the significant modules and components such as various BlockComponents, the EditorComponent itself, various plugins like the SelectionMenu, Toolbar, FindAndReplace, and some utilities.
When you expand this folder you will see the following subdirectories.\
\
`src/editor`\
`├── block_component`\
`├── command`\
`├── editor_component`\
`├── find_replace_menu`\
`├── selection_menu`\
`├── toolbar`\
`└── editor.dart`
#### block\_component
The block\_component consists of a collection of block\_components such as headings, bulleted\_lists, image\_block\_components, etc. We have already mentioned some of them.
#### editor\_component
The EditorComponent is the root node of the document tree. Its job is to hold all other components, display these components, and allow scrolling, typing, and listening to Shortcut Events. It is a class implementing the `BlockComponentBuilder` with a Node type of 'page'.
The `editor_component\service` contains the scroll service, keyboard service, selection service, shortcuts, IME service, and the definitions of `BlockComponentBuilder` itself within this directory:
```
editor_component\service\renderer
```
Each one of these services is worth an article explaining, but I urge the reader to explore more about them at their convenience.
Other modules inside editor\_components include:
* find\_replace\_menu
* toolbar
* selection\_menu
All of them are helpful features that serve some purpose of enhancing the use of AppFlowyEditor for managing data in the Document.
As the name suggests, the **find\_replace\_menu** finds and replaces character matches, and the **toolbar** is used to style different nodes on the editor.
