Created DataExtension API Builders (markdown)

DataExtension-API-Builders.md

@@ -0,0 +1,91 @@
+![Plan Header](https://puu.sh/AXSg7/5f2f78c06c.jpg)
+# DataExtension API - Builders
+
+DataExtension Builder APIs require `DATA_EXTENSION_BUILDER_API` capability.
+
+----
+
+# 🧰 `@DataBuilderProvider` annotation
+
+**Speciality:** Dynamic definition of providers at runtime.
+
+Usage:
+```java
+@DataBuilderProvider
+public ExtensionDataBuilder lotsOfData(UUID playerUUID) {
+    ExtensionDataBuilder builder = newExtensionDataBuilder();
+    ...
+    return builder;
+}
+```
+
+## Adding values
+
+You can add all the same kinds of values as with the annotation API.
+In the most simple form:
+```java
+ExtensionDataBuilder builder = newExtensionDataBuilder();
+return builder.addValue(Long.class, 
+    builder.valueBuilder("Steps taken")
+           .buildNumber(53298L)
+);
+```
+
+Here are the types and build methods that are available:
+```java
+builder.addValue(Boolean.class, builder.valueBuilder("Example").buildBoolean(false));
+
+Boolean.class,  ...buildBoolean(false));
+Boolean.class,  ...buildBoolean(() -> false));
+Boolean.class,  ...buildBooleanProvidingCondition(false, "conditionName"));       // for use with @Conditional on other provider annotations
+Boolean.class,  ...buildBooleanProvidingCondition(() -> false, "conditionName")); // for use with @Conditional on other provider annotations
+Long.class,     ...buildNumber(1234L));
+Long.class,     ...buildNumber(() -> 1234L));
+Double.class,   ...buildDouble(500.52));
+Double.class,   ...buildDouble(() ->500.52));
+Double.class,   ...buildPercentage(0.52));
+Double.class,   ...buildPercentage(() -> 0.52));
+String.class,   ...buildString("Example"));
+String.class,   ...buildString(() -> "Example"));
+String[].class, ...buildGroup(new String[]{"Admin", "Moderator"}));
+String[].class, ...buildGroup(() -> new String[]{"Admin", "Moderator"}));
+Table.class,    ...buildTable(Table.builder()...build(), Color.BLUE);
+Table.class,    ...buildTable(() -> Table.builder()...build(), Color.BLUE);
+```
+The lambda methods can be used for method references, conditional values (eg returning null sometimes) and for throwing `NotReadyException` for a specific value.
+
+In addition to this value builder has a lot of other methods:
+```
+builder.valueBuilder("Example")                                        // 50 char limit
+    .description("Describes what Example is about")                    // 150 char limit
+    .icon("gavel", Family.SOLID, Color.RED)                            // https://fontawesome.com/icons
+    .icon(Icon.called("gavel").of(Family.SOLID).of(Color.RED).build()) // https://fontawesome.com/icons
+    .showInPlayerTable()
+    .showOnTab("tabName")                                              // remember @TabInfo annotation
+    .formatAsDateWithYear()    // for numbers
+    .formatAsDateWithSeconds() // for numbers
+    .formatAsTimeAmount()      // for numbers
+    .format(FormatType.NONE)   // for numbers
+    .showAsPlayerPageLink()    // for strings
+```
+
+## Adding tables
+
+In addition to the ValueBuilder methods, you can use `ExtensionDataBuilder#addTable` methods for adding tables dynamically.
+
+```java
+ExtensionDataBuilder builder = newExtensionDataBuilder()
+    .addTable("table name", Table.builder()...build(), Color.BLUE)
+    .addTable("table name", Table.builder()...build(), Color.BLUE, "tabName");
+```
+
+## Stuff to avoid
+
+⚠️ Don't define `@Conditional` with `@DataBuilderProvider` - it is not supported
+
+```java
+@DataBuilderProvider
+@Conditional("conditionName") // Throws IllegalArgumentException when registering the extension
+public ExtensionDataBuilder lotsOfData(UUID playerUUID) {
+}
+```