From 31f378a65a6b7c5adbefa5961c051899a4b82b58 Mon Sep 17 00:00:00 2001 From: maxquinones Date: Mon, 19 Oct 2026 07:56:13 -0700 Subject: [PATCH] feat: add documentation for core and custom reactors, update sidebar positions --- .../CoreVSCustomReactors.md | 107 ++++++++++++++++++ .../Custom Reactors.md | 6 +- .../Python Reactors.md | 2 +- .../Add Custom Reactors to Apps/Run Pixels.md | 2 +- .../SQL CRUD Operations.md | 2 +- .../CoreVSCustomReactors.md | 107 ++++++++++++++++++ .../Custom Reactors.md | 6 +- .../Python Reactors.md | 2 +- .../Add Custom Reactors to Apps/Run Pixels.md | 2 +- .../SQL CRUD Operations.md | 2 +- 10 files changed, 226 insertions(+), 12 deletions(-) create mode 100644 docusaurus/docs/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md create mode 100644 docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md diff --git a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md new file mode 100644 index 0000000..8896871 --- /dev/null +++ b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md @@ -0,0 +1,107 @@ +--- +sidebar_label: "Core Reactors vs Custom Reactors" +sidebar_position: 3 +slug: "java/core-vs-custom-reactors" +description: "Understand the differences between platform-provided core reactors and app-specific custom reactors." +--- + +import AppName from "@site/src/components/CustomFields"; + +# Difference between Core Reactors vs Custom Reactors + +Reactors are Java classes that implement business logic for a [Pixel](../../Building%20Apps/Add%20Custom%20Reactors%20to%20Apps/Pixels.md) command. provides a large set of platform reactors, and you can also create reactors for logic that is specific to your application. + +## Core reactors + +Core reactors are built into and maintained as part of the platform. They provide the standard commands used for common operations such as working with databases, querying data, managing insights, and interacting with platform services. + +Core reactors: + +- Are available to apps without adding Java source code to the app. +- Follow the platform's established input, output, security, and error-handling behavior. +- Are updated and distributed through releases. +- Can be discovered through `Help()` in the Pixel terminal and inspected with the command's `--help` option. +- Are the preferred choice when an existing command already meets your requirements. + +For an introduction to Pixel commands and their syntax, see [Pixels](../../Building%20Apps/Add%20Custom%20Reactors%20to%20Apps/Pixels.md). + +See [list of core reactors](../../../developer/Reactors) + +## Custom reactors + +Custom reactors are Java classes that you add to an app when the platform reactors do not provide the required behavior. They let you implement application-specific logic or use Java libraries that are not part of the standard reactor set. + +Custom reactors: + +- Are owned and maintained by the app development team. +- Live in the app's Java folder and are compiled for that app. +- Can define their own inputs, validation, business logic, and return values. +- Can reuse classes by declaring the required Maven dependencies. +- Must be tested and recompiled whenever their source code changes. + +See [Create Your Own Pixel](Custom%20Reactors.md) for the process of creating a custom reactor. + +## Comparison + +| Area | Core reactor | Custom reactor | +| --- | --- | --- | +| Ownership | Maintained by | Maintained by the app team | +| Availability | Included with the platform | Added to a specific app | +| Setup | No Java source or compilation required | Requires Java source, dependencies, and compilation | +| Behavior | Standardized across the platform version | Defined by the custom implementation | +| Updates | Delivered with platform releases | Updated when the app team changes and recompiles the code | +| Reuse | Available to apps that use the platform | Available wherever the custom reactor is deployed | +| Best for | Common platform operations | Application-specific or integration-specific logic | + +## Which should you use? + +Use a core reactor when: + +- The required operation is already available in the platform. +- You want standard platform behavior and support. +- You want to avoid maintaining additional Java code. + +Use a custom reactor when: + +- No core reactor provides the required operation. +- The operation contains business rules unique to your app. +- You need to integrate with a library, service, or system that is not supported by a core reactor. +- You need to combine several operations behind one app-specific Pixel command. + +Before creating a custom reactor, search the available commands with `Help()` and review the relevant command's `--help` output. Extending an existing core reactor or composing existing Pixel commands may be simpler than maintaining new Java code. + +## Important considerations + +Custom reactors have more flexibility, but they also introduce an application maintenance responsibility. Keep dependencies explicit, validate inputs, handle errors consistently, and test the reactor with representative Pixel calls. After changing the source code, recompile the custom reactors so the updated implementation is deployed to the app. + +## Best Practices + +### Document the custom reactor + +Implement/Override these methods + +```java + +@Override + protected String getDescriptionForKey(String key) { + if(key.equals(ReactorKeysEnum.VALUE.getKey())) { + return "The value to echo back"; + } + return super.getDescriptionForKey(key); + } + + @Override + public String getReactorDescription() { + return "This reactor returns back the input the user enters"; + } +``` + + Check for required keys + +```java + public AdminSqlQueryReactor() { + this.keysToGet = new String[] { ReactorKeysEnum.QUERY_KEY.getKey(), ReactorKeysEnum.DATABASE.getKey(), + ReactorKeysEnum.LIMIT.getKey(), "commit" }; + this.keyRequired = new int[] { 1, 1, 0, 0, 0 }; + } +``` \ No newline at end of file diff --git a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md index 1cc2239..40f371c 100644 --- a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md +++ b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md @@ -1,13 +1,13 @@ --- -sidebar_label: 'Create Custom Pixel' -sidebar_position: 3 +sidebar_label: 'Create Custom Pixel Reactor' +sidebar_position: 4 slug: "java/custom-reactor" description: "How to create custom pixels (reactors)" --- import AppName from "@site/src/components/CustomFields"; -# Create Your Own Pixel +# Create Your Own Pixel/Reactor ### Overview A reactor is a business logic unit of **[Pixel](../../Building%20Apps/Add%20Custom%20Reactors%20to%20Apps/Pixels.md)** which performs the desired operation for the user. At its core, a reactor is just a Java class file. Custom reactors are located inside a java folder within an App folder diff --git a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Python Reactors.md b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Python Reactors.md index 214ebea..b80ff18 100644 --- a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Python Reactors.md +++ b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Python Reactors.md @@ -1,6 +1,6 @@ --- sidebar_label: 'Python Reactors' -sidebar_position: 6 +sidebar_position: 7 slug: "custom-reactor/python-inline" description: "A guide to using python in reactors" --- diff --git a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Run Pixels.md b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Run Pixels.md index a0d6d3d..0fe23a3 100644 --- a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Run Pixels.md +++ b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/Run Pixels.md @@ -1,6 +1,6 @@ --- sidebar_label: 'Run Pixels' -sidebar_position: 4 +sidebar_position: 5 slug: "java/run-pixel" description: "How to run pixels" --- diff --git a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md index 63a0f1b..85913ef 100644 --- a/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md +++ b/docusaurus/docs/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md @@ -1,6 +1,6 @@ --- sidebar_label: 'SQL CRUD Operations' -sidebar_position: 5 +sidebar_position: 6 slug: "custom-reactor/crud-ops" description: "How to create SQL CRUD operations in a reactor" --- diff --git a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md new file mode 100644 index 0000000..8896871 --- /dev/null +++ b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/CoreVSCustomReactors.md @@ -0,0 +1,107 @@ +--- +sidebar_label: "Core Reactors vs Custom Reactors" +sidebar_position: 3 +slug: "java/core-vs-custom-reactors" +description: "Understand the differences between platform-provided core reactors and app-specific custom reactors." +--- + +import AppName from "@site/src/components/CustomFields"; + +# Difference between Core Reactors vs Custom Reactors + +Reactors are Java classes that implement business logic for a [Pixel](../../Building%20Apps/Add%20Custom%20Reactors%20to%20Apps/Pixels.md) command. provides a large set of platform reactors, and you can also create reactors for logic that is specific to your application. + +## Core reactors + +Core reactors are built into and maintained as part of the platform. They provide the standard commands used for common operations such as working with databases, querying data, managing insights, and interacting with platform services. + +Core reactors: + +- Are available to apps without adding Java source code to the app. +- Follow the platform's established input, output, security, and error-handling behavior. +- Are updated and distributed through releases. +- Can be discovered through `Help()` in the Pixel terminal and inspected with the command's `--help` option. +- Are the preferred choice when an existing command already meets your requirements. + +For an introduction to Pixel commands and their syntax, see [Pixels](../../Building%20Apps/Add%20Custom%20Reactors%20to%20Apps/Pixels.md). + +See [list of core reactors](../../../developer/Reactors) + +## Custom reactors + +Custom reactors are Java classes that you add to an app when the platform reactors do not provide the required behavior. They let you implement application-specific logic or use Java libraries that are not part of the standard reactor set. + +Custom reactors: + +- Are owned and maintained by the app development team. +- Live in the app's Java folder and are compiled for that app. +- Can define their own inputs, validation, business logic, and return values. +- Can reuse classes by declaring the required Maven dependencies. +- Must be tested and recompiled whenever their source code changes. + +See [Create Your Own Pixel](Custom%20Reactors.md) for the process of creating a custom reactor. + +## Comparison + +| Area | Core reactor | Custom reactor | +| --- | --- | --- | +| Ownership | Maintained by | Maintained by the app team | +| Availability | Included with the platform | Added to a specific app | +| Setup | No Java source or compilation required | Requires Java source, dependencies, and compilation | +| Behavior | Standardized across the platform version | Defined by the custom implementation | +| Updates | Delivered with platform releases | Updated when the app team changes and recompiles the code | +| Reuse | Available to apps that use the platform | Available wherever the custom reactor is deployed | +| Best for | Common platform operations | Application-specific or integration-specific logic | + +## Which should you use? + +Use a core reactor when: + +- The required operation is already available in the platform. +- You want standard platform behavior and support. +- You want to avoid maintaining additional Java code. + +Use a custom reactor when: + +- No core reactor provides the required operation. +- The operation contains business rules unique to your app. +- You need to integrate with a library, service, or system that is not supported by a core reactor. +- You need to combine several operations behind one app-specific Pixel command. + +Before creating a custom reactor, search the available commands with `Help()` and review the relevant command's `--help` output. Extending an existing core reactor or composing existing Pixel commands may be simpler than maintaining new Java code. + +## Important considerations + +Custom reactors have more flexibility, but they also introduce an application maintenance responsibility. Keep dependencies explicit, validate inputs, handle errors consistently, and test the reactor with representative Pixel calls. After changing the source code, recompile the custom reactors so the updated implementation is deployed to the app. + +## Best Practices + +### Document the custom reactor + +Implement/Override these methods + +```java + +@Override + protected String getDescriptionForKey(String key) { + if(key.equals(ReactorKeysEnum.VALUE.getKey())) { + return "The value to echo back"; + } + return super.getDescriptionForKey(key); + } + + @Override + public String getReactorDescription() { + return "This reactor returns back the input the user enters"; + } +``` + + Check for required keys + +```java + public AdminSqlQueryReactor() { + this.keysToGet = new String[] { ReactorKeysEnum.QUERY_KEY.getKey(), ReactorKeysEnum.DATABASE.getKey(), + ReactorKeysEnum.LIMIT.getKey(), "commit" }; + this.keyRequired = new int[] { 1, 1, 0, 0, 0 }; + } +``` \ No newline at end of file diff --git a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md index 1cc2239..40f371c 100644 --- a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md +++ b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Custom Reactors.md @@ -1,13 +1,13 @@ --- -sidebar_label: 'Create Custom Pixel' -sidebar_position: 3 +sidebar_label: 'Create Custom Pixel Reactor' +sidebar_position: 4 slug: "java/custom-reactor" description: "How to create custom pixels (reactors)" --- import AppName from "@site/src/components/CustomFields"; -# Create Your Own Pixel +# Create Your Own Pixel/Reactor ### Overview A reactor is a business logic unit of **[Pixel](../../Building%20Apps/Add%20Custom%20Reactors%20to%20Apps/Pixels.md)** which performs the desired operation for the user. At its core, a reactor is just a Java class file. Custom reactors are located inside a java folder within an App folder diff --git a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Python Reactors.md b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Python Reactors.md index 214ebea..b80ff18 100644 --- a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Python Reactors.md +++ b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Python Reactors.md @@ -1,6 +1,6 @@ --- sidebar_label: 'Python Reactors' -sidebar_position: 6 +sidebar_position: 7 slug: "custom-reactor/python-inline" description: "A guide to using python in reactors" --- diff --git a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Run Pixels.md b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Run Pixels.md index a355ea7..eb15fc5 100644 --- a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Run Pixels.md +++ b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/Run Pixels.md @@ -1,6 +1,6 @@ --- sidebar_label: 'Run Pixels' -sidebar_position: 4 +sidebar_position: 5 slug: "java/run-pixel" description: "How to run pixels" --- diff --git a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md index 48acf86..dead1b7 100644 --- a/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md +++ b/docusaurus/versioned_docs/version-5.0.0/Building Apps/Add Custom Reactors to Apps/SQL CRUD Operations.md @@ -1,6 +1,6 @@ --- sidebar_label: 'SQL CRUD Operations' -sidebar_position: 5 +sidebar_position: 6 slug: "custom-reactor/crud-ops" description: "How to create SQL CRUD operations in a reactor" ---