From 9d6db484134e95e1d831fadc3cb87ab946cf5d74 Mon Sep 17 00:00:00 2001
From: Cat <114286961+CatHood0@users.noreply.github.com>
Date: Mon, 22 Jul 2024 02:00:03 -0400
Subject: [PATCH] doc(attribute): added documentation about Attribute class and
 how create one (#2048)

---
 doc/attribute_introduction.md | 103 ++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 doc/attribute_introduction.md

diff --git a/doc/attribute_introduction.md b/doc/attribute_introduction.md
new file mode 100644
index 00000000..b1704e01
--- /dev/null
+++ b/doc/attribute_introduction.md
@@ -0,0 +1,103 @@
+# What is an `Attribute`
+
+An `attribute` is a property or characteristic that can be applied to text or a section of text within the editor to change its appearance or behavior. Attributes allow the user to style the text in various ways.
+
+# How do attributes work?
+
+An Attribute is applied to selected segments of text in the editor. Each attribute has an identifier and a value that determines how it should be applied to the text. For example, to apply bold to a text, an attribute with the identifier "bold" is used. When text is selected and an attribute is applied, the editor updates the visual representation of the text in real time.
+
+# Scope of an `Attribute`
+
+The attributes has an Scope that limit where start and end the `Attribute`. The Scope is called as `AttributeScope`. It has these options to be selected:
+
+```dart
+enum AttributeScope {
+  inline, // just the selected text will apply the attribute (like: bold, italic or strike)
+  block, // all the paragraph will apply the attribute (like: Header, Alignment or CodeBlock)
+  embeds, // the attr will be taked as a different part of any paragraph or line, working as a block (By now not works as an inline)
+  ignore, // the attribute can be applied, but on Retain operations will be ignored
+}
+```
+
+# How looks a `Attribute`
+
+The original `Attribute` class that you need to extend from if you want to create any custom attribute looks like:
+
+```dart
+class Attribute<T> {
+  const Attribute(
+    this.key,
+    this.scope,
+    this.value,
+  );
+
+  /// Unique key of this attribute.
+  final String key;
+  final AttributeScope scope;
+  final T value;
+}
+```
+
+The key of any `Attribute` must be **unique** to avoid any conflict with the default implementations. 
+
+#### Why `Attribute` class contains a **Generic** as a value
+
+This is the same reason why we can create `Block` styles, `Inline` styles and `Custom` styles. Having a **Generic** type value let us define any value as we want to recognize them later and apply it.
+
+### Example of an default attribute
+
+##### Inline Scope:
+```dart
+class BoldAttribute extends Attribute<bool> {
+  const BoldAttribute() : super('bold', AttributeScope.inline, true);
+}
+```
+
+##### Block Scope:
+
+```dart
+class HeaderAttribute extends Attribute<int?> {
+  const HeaderAttribute({int? level})
+      : super('header', AttributeScope.block, level);
+}
+```
+If you want to see an example of an embed implementation you can see it [here](https://github.com/singerdmx/flutter-quill/blob/master/doc/custom_embed_blocks.md)
+
+### Example of a Custom Inline `Attribute`
+
+##### The Attribute
+
+```dart
+import 'package:flutter_quill/flutter_quill.dart';
+
+const String highlightKey = 'highlight';
+const AttributeScope highlightScope = AttributeScope.inline;
+
+class HighlightAttr extends Attribute<bool?> {
+  HighlightAttr(bool? value) : super(highlightKey, highlightScope, value);
+}
+```
+
+##### Where should we add this `HighlightAttr`? 
+
+On `QuillEditor` or `QuillEditorConfigurations` **doesn't exist** a param that let us pass our `Attribute` implementations. To make this more easy, we can use just `customStyleBuilder` param from `QuillEditorConfigurations`, that let us define a function to return a `TextStyle`. With this, we can define now our `HighlightAttr`
+
+##### The editor 
+```dart
+QuillEditor.basic(
+      configurations: QuillEditorConfigurations(
+        controller: controller,
+        customStyleBuilder: (Attribute<dynamic> attribute) {
+          if (attribute.key.equals(highlightKey)) {
+            return TextStyle(color: Colors.black, backgroundColor: Colors.yellow);
+          }
+          //default paragraph style
+          return TextStyle();
+        },
+      ),
+);
+```
+
+Then, it should look as:
+
+![HighlightAttr applied on the Quill Editor](https://github.com/user-attachments/assets/89c7bda5-f0de-4832-bcaa-8e0ccbe9be18)