feat(docs): Add operator plugin docs.

lowdefy · Mar 9, 2023 · 9fd356a · 9fd356a
1 parent 792eee0
commit 9fd356a
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 0 deletions.
diff --git a/packages/docs/menus.yaml b/packages/docs/menus.yaml
@@ -187,6 +187,11 @@
           pageId: plugins-actions
           properties:
             title: Actions
+        - id: plugins-operators
+          type: MenuLink
+          pageId: plugins-operators
+          properties:
+            title: Operators
 
     - id: users_group
       type: MenuGroup

diff --git a/packages/docs/pages.yaml b/packages/docs/pages.yaml
@@ -32,6 +32,7 @@
 - _ref: plugins/plugins-introduction.yaml
 - _ref: plugins/plugins-dev.yaml
 - _ref: plugins/plugins-actions.yaml
+- _ref: plugins/plugins-operators.yaml
 
 - _ref: users/users-introduction.yaml
 - _ref: users/login-and-logout.yaml

diff --git a/packages/docs/plugins/plugins-actions.yaml b/packages/docs/plugins/plugins-actions.yaml
@@ -86,3 +86,10 @@ _ref:
 
             export default Confetti;
             ```
+      - _ref:
+          path: templates/navigation_buttons.yaml
+          vars:
+            previous_page_title: Developing Plugins
+            previous_page_id: plugins-dev
+            next_page_title: Operators
+            next_page_id: plugins-operators
diff --git a/packages/docs/plugins/plugins-operators.yaml b/packages/docs/plugins/plugins-operators.yaml
@@ -0,0 +1,84 @@
+_ref:
+  path: templates/general.yaml.njk
+  vars:
+    pageId: plugins-operators
+    pageTitle: Operator Plugins
+    section: Plugins
+    filePath: plugins/plugins-operators.yaml
+    content:
+      - id: md1
+        type: MarkdownWithCode
+        properties:
+          content: |
+            Operators are synchronous functions that are used in Lowdefy to express logic. If you need to use asynchronous code, or promises, write an [action](/plugins-actions) instead.  Operator names should start with a single underscore, as this is used by the Lowdefy engine to identify and evaluate operators. By convention, operator functions are written in _snake_case_.
+
+            Operators are used in both the web client and server runtimes. Some operators make sense in both environments, but other operators only work in one or the other. The `types.js` file declares the server and client operators exported by an app in the `operators.client` and `operators.server` fields. The operator named exports are exported under the `./operators/client` and `./operators/server` package entry points for client and server operators respectively. The same function can be exported for both the client and the server runtimes, or two different implementations can be exported in each file.
+
+            Client parameters:
+            - `actions: object`: The actions data object.
+            - `args: array`: If the operator is used inside a `_function` operator, `args` is an array of arguments passed to the function.
+            - `arrayIndices: array`. ??
+            - `basePath: string`: The configured app URL basePath.
+            - `event: object`: The event data object.
+            - `eventLog: array`:
+            - `globals: object`: Commonly used Javascript global objects. These are passed to the operator for easier testing.
+              - `document: object`: The browser [`window.document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/Document) global variable.
+              - `window: object`: The browser [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) global variable.
+            - `home: object`:
+              - `configured: boolean`: True if the user configured a home pageId.
+              - `pageId: string`: The pageId of the home page. Either the user configured home pageId, or the pageId of the first page visible to the user in the default menu.
+            - `input: object`: The input data object.
+            - `lowdefyGlobal: `: The Lowdefy global data object.
+            - `menus: array`: The app menus.
+            - `methodName: string`: The name of the method if the operator is called a with a method (as `_operator.methodName`).
+            - `operators: object`: An object with all the operator functions used on the server.
+            - `pageId: string`: The pageId of the page the operator is evaluated on.
+            - `params: any`: The `params` defined by the user in the Lowdefy configuration. Operators are evaluated before the params are passed to the operator. No validation is performed on this object.
+            - `requests: object`: The requests data object.
+            - `runtime: string`: The runtime is set to the constant `"browser"`.
+            - `state: object`: The state data object.
+            - `user: object`: The user data object.
+
+
+            Server parameters:
+            - `args: array`: If the operator is used inside a `_function` operator, `args` is an array of arguments passed to the function.
+            - `arrayIndices: array`. An empty array. Provided for consistency with client operators.
+            - `methodName: string`: The name of the method if the operator is called a with a method (as `_operator.methodName`).
+            - `operators: object`: An object with all the operator functions used on the server.
+            - `params: any`: The `params` defined by the user in the Lowdefy configuration. Operators are evaluated before the params are passed to the operator. No validation is performed on this object.
+            - `payload: object`: The payload object passed to a request.
+            - `runtime: string`: The runtime is set to the constant `"node"`.
+            - `secrets: object`: The secrets data object.
+            - `user: object`: The user data object.
+
+            ### Pure Functions
+
+            Operators in Lowdefy are usually pure functions - given a specific input they always give the same output. If a operator is used in blocks, they must be pure functions because operators are evaluated every time a page is re-rendered. Operators in block properties are evaluated recursively until the evaluated result matches the previous evaluated result.
+
+            #### Examples
+
+            ###### An operator that multiplies a number by 11:
+            ```js
+            function _times_eleven({ params }) {
+              return params.number * 11;
+            }
+
+            export default _times_eleven;
+            ```
+
+            ###### The _eq operator:
+            ```js
+            import { type } from '@lowdefy/helpers';
+
+            function _eq({ params }) {
+              if (!type.isArray(params)) {
+                throw new Error('Operator Error: _eq takes an array type as input.');
+              }
+              if (params.length !== 2) {
+                throw new Error('Operator Error: _eq takes an array of length 2 as input');
+              }
+              return params[0] === params[1];
+            }
+
+            export default _eq;
+            ```
diff --git a/packages/docs/templates/general.yaml.njk b/packages/docs/templates/general.yaml.njk
@@ -54,6 +54,10 @@ events:
       type: Request
       messages:
         error: false
+      skip:
+        _build.eq:
+          - _build.env: NEXT_PUBLIC_VERCEL_ENV
+          - null
       params: post_telemetry