From 606346aeaba441608b8163036f8d395095b61794 Mon Sep 17 00:00:00 2001 From: SamTolmay Date: Wed, 27 Jan 2021 11:51:43 +0200 Subject: [PATCH] feat(docs): Add operator docs. --- packages/docs/lowdefy.yaml | 24 ++++++ packages/docs/operators/_if.yaml | 86 +++++---------------- packages/docs/operators/_list_contexts.yaml | 34 ++++++++ packages/docs/operators/_nunjucks.yaml | 57 ++++++++++++++ packages/docs/operators/_operator.yaml | 45 +++++++++++ packages/docs/operators/_random.yaml | 8 +- packages/docs/operators/_regex.yaml | 70 +++++++++++++++++ packages/docs/operators/_request.yaml | 36 +++++++++ packages/docs/operators/_type.yaml | 79 +++++++++++++++++++ packages/docs/operators/_uuid.yaml | 2 +- packages/docs/templates/operators.yaml.njk | 12 --- 11 files changed, 371 insertions(+), 82 deletions(-) create mode 100644 packages/docs/operators/_list_contexts.yaml create mode 100644 packages/docs/operators/_nunjucks.yaml create mode 100644 packages/docs/operators/_operator.yaml create mode 100644 packages/docs/operators/_regex.yaml create mode 100644 packages/docs/operators/_request.yaml create mode 100644 packages/docs/operators/_type.yaml diff --git a/packages/docs/lowdefy.yaml b/packages/docs/lowdefy.yaml index 0d49e7d1d..36e036c23 100644 --- a/packages/docs/lowdefy.yaml +++ b/packages/docs/lowdefy.yaml @@ -242,6 +242,9 @@ menus: - id: _if_none type: MenuLink pageId: _if_none + - id: _list_contexts + type: MenuLink + pageId: _list_contexts - id: _log type: MenuLink pageId: _log @@ -254,6 +257,12 @@ menus: - id: _not type: MenuLink pageId: _not + - id: _nunjucks + type: MenuLink + pageId: _nunjucks + - id: _operator + type: MenuLink + pageId: _operator - id: _or type: MenuLink pageId: _or @@ -263,12 +272,21 @@ menus: - id: _random type: MenuLink pageId: _random + - id: _regex + type: MenuLink + pageId: _regex + - id: _request + type: MenuLink + pageId: _request - id: _subtract type: MenuLink pageId: _subtract - id: _sum type: MenuLink pageId: _sum + - id: _type + type: MenuLink + pageId: _type - id: _uuid type: MenuLink pageId: _uuid @@ -325,15 +343,21 @@ pages: - _ref: operators/_gte.yaml - _ref: operators/_if.yaml - _ref: operators/_if_none.yaml + - _ref: operators/_list_contexts.yaml - _ref: operators/_lt.yaml - _ref: operators/_lte.yaml - _ref: operators/_log.yaml - _ref: operators/_not.yaml + - _ref: operators/_nunjucks.yaml + - _ref: operators/_operator.yaml - _ref: operators/_or.yaml - _ref: operators/_product.yaml - _ref: operators/_random.yaml + - _ref: operators/_regex.yaml + - _ref: operators/_request.yaml - _ref: operators/_subtract.yaml - _ref: operators/_sum.yaml + - _ref: operators/_type.yaml - _ref: operators/_uuid.yaml - _ref: 404.yaml diff --git a/packages/docs/operators/_if.yaml b/packages/docs/operators/_if.yaml index 6ae815339..b0c072ff7 100644 --- a/packages/docs/operators/_if.yaml +++ b/packages/docs/operators/_if.yaml @@ -15,72 +15,28 @@ _ref: path: templates/operators.yaml.njk vars: - pageId: _and - pageTitle: _and - argument_types: array - return_types: boolean + pageId: _if + pageTitle: _if + types: | + ``` + (arguments: {test: boolean, then: any, else: any}): any + ``` description: | - The `_and` operator performs a logical `and` over an array of inputs, using javascript 'truthy' and 'falsy' rules. - - It returns true if all the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). Else it returns false. + The `_if` operator returns the `then` argument if it's `test` argument is `true`, and it's `else` argument if it is `false`. Generally other operators are used to evaluate the `test` argument. arguments: | - #### array - An array of values over which to perform a logical and. + #### object + - `test: boolean`: The boolean result of a test. + - `then: any`: The value to return if the test is `true`. + - `else: any`: The value to return if the test is `false`. examples: | - #### Two `true` values: + #### Return a value based on a user input: + ```yaml + _if: + test: + _eq: + - _state: text_input + - The password + then: The user entered the password + else: Access denied ``` - _and: - - true - - true - ``` - Returns: `true` - - #### Array of `true` and `false` values: - ``` - _and: - - true - - true - - true - - false - ``` - Returns: `false` - - #### Check if two boolean inputs are true: - ``` - _and: - - _state: confirm_accept_terms - - _state: confirm_accept_privacy_policy - ``` - Returns: `true` if both inputs are `true` - - #### Truthy values: - ``` - _and: - - "Hello" - - 42 - - [] - - key: value - ``` - Returns: `true` - - #### Falsy values: - ``` - _and: - - true - - null - ``` - Returns: `false` - - ``` - _and: - - true - - 0 - ``` - Returns: `false` - - ``` - _and: - - true - - "" - ``` - Returns: `false` + Returns: `"The user entered the password"` if the text input's value is `"The password"`, else `"Access denied"` diff --git a/packages/docs/operators/_list_contexts.yaml b/packages/docs/operators/_list_contexts.yaml new file mode 100644 index 000000000..9bca15833 --- /dev/null +++ b/packages/docs/operators/_list_contexts.yaml @@ -0,0 +1,34 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _list_contexts + pageTitle: _list_contexts + types: | + ``` + (value: any): string[] + ``` + description: | + The `_list_contexts` operator returns an array with the ids of all the `contexts` in the app. + arguments: | + #### any + The `_list_contexts` operator returns the array regardless of arguments. + examples: | + #### List all context ids: + ```yaml + _list_contexts: true + ``` + Returns: An array of all `context` ids. diff --git a/packages/docs/operators/_nunjucks.yaml b/packages/docs/operators/_nunjucks.yaml new file mode 100644 index 000000000..f0f6c076c --- /dev/null +++ b/packages/docs/operators/_nunjucks.yaml @@ -0,0 +1,57 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _nunjucks + pageTitle: _nunjucks + types: | + ``` + (template: string): string + (arguments: {template: string, on: object}): string + ``` + description: | + The `_nunjucks` hydrates a [Nunjucks](https://mozilla.github.io/nunjucks/) template. + + If called with a string argument, the template variables are the values in `state`. Otherwise template variables can be specified using the `on` argument. + arguments: | + #### string + The template to hydrate. The template variables used are the values in state + + #### object + - `template: string`: The template to hydrate. + - `on: object`: The template variables to use when hydrating the template. + examples: | + #### Populate a template from values in `state`: + ```yaml + _nunjucks: Hello {{ name }} + ``` + Returns: `"Hello Steven"` if the value of name in state is `"Steven"`. + + #### Populate a markdown template with different values: + ```yaml + _nunjucks: + template: | + ### {{ title }} + + {% for item in item_list %} + - {{ item.name }}: {{ item.description }} + {% endfor %} + on: + title: + _state: title + items: + _request: get_items + ``` diff --git a/packages/docs/operators/_operator.yaml b/packages/docs/operators/_operator.yaml new file mode 100644 index 000000000..b021de589 --- /dev/null +++ b/packages/docs/operators/_operator.yaml @@ -0,0 +1,45 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _operator + pageTitle: _operator + types: | + ``` + (arguments: {operator: string, params: any): any + ``` + description: | + The `_operator` operator evaluates an operator with the given params. This is useful if the operator needs to be chosen dynamically. The `_operator` cannot evaluate itself. + arguments: | + #### object + - `operator: string`: The name of the operator to evaluate. + - `params: any`: The params to give to the operator. + examples: | + #### Get a value from `urlQuery` if specified, else use the value in `state`: + ```yaml + _operator: + operator: + _if: + test: + _eq: + - _state: location_selector + - url_query + then: _url_query + else: _state + params: + key: field_to_get + ``` + Returns: Value from `urlQuery` if `location_selector == url_query`, else the value from `state`. diff --git a/packages/docs/operators/_random.yaml b/packages/docs/operators/_random.yaml index f291d047c..8b227fc26 100644 --- a/packages/docs/operators/_random.yaml +++ b/packages/docs/operators/_random.yaml @@ -29,10 +29,10 @@ _ref: The type to generate. One of `string`, `integer`, or `float`. #### object - - `type: string` - The type to generate. One of `string`, `integer`, or `float`. - - `length: string` - The length of the string to generate if type is `string`. Default is `8`. - - `max: number` - The maximum possible number if type is one of `integer` or `float`. Default is `100` if `integer` or `1` if `float`. - - `min: number` - The minimum possible number if type is one of `integer` or `float`. Default is `0`. + - `type: string`: __Required__ - The type to generate. One of `string`, `integer`, or `float`. + - `length: string`: The length of the string to generate if type is `string`. Default is `8`. + - `max: number`: The maximum possible number if type is one of `integer` or `float`. Default is `100` if `integer` or `1` if `float`. + - `min: number`: The minimum possible number if type is one of `integer` or `float`. Default is `0`. examples: | #### Random string: ```yaml diff --git a/packages/docs/operators/_regex.yaml b/packages/docs/operators/_regex.yaml new file mode 100644 index 000000000..b38e8f927 --- /dev/null +++ b/packages/docs/operators/_regex.yaml @@ -0,0 +1,70 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _regex + pageTitle: _regex + types: | + ``` + (pattern: string): boolean + (arguments: {pattern: string, on?: string, key?: string, flags?: string}): boolean + ``` + description: | + The `_regex` operator performs a regex test on a string, and returns `true` if there is a match. + + The regex operator has shorthand argument definitions that can be used on web client. + arguments: | + #### string + The regular expression pattern to test. The string shorthand can only be used in an input block, and the tested value will be the block's value. + + #### object + - `pattern: string`: __Required__ - The regular expression pattern to test. + - `on: string`: The string to test the value on. One of `on` or `key` must be specified unless the operator is used in an input block. + - `key: string`: The key of a value in `state` to test. One of `on` or `key` must be specified unless the operator is used in an input block. + - `flags: string`: The regex flags to use. The default value is `"gm"`. + examples: | + #### Check if a username is valid (Alphanumeric string that may include _ and – having a length of 3 to 16 characters): + ```yaml + _regex: + pattern: ^[a-z0-9_-]{3,16}$ + on: + _state: username_input + ``` + Returns: `true` if matched else `false`. + + #### Using the key of the value in `state`: + ```yaml + _regex: + pattern: ^[a-z0-9_-]{3,16}$ + key: username_input + ``` + Returns: `true` if matched else `false`. + + #### Using the value of the block in which the operator is evaluated: + ```yaml + _regex: ^[a-z0-9_-]{3,16}$ + ``` + Returns: `true` if matched else `false`. + + #### Case insensitive match: + ```yaml + _regex: + pattern: ^[a-z0-9_-]{3,16}$ + on: + _state: username_input + flags: 'gmi' + ``` + Returns: `true` if matched else `false`. diff --git a/packages/docs/operators/_request.yaml b/packages/docs/operators/_request.yaml new file mode 100644 index 000000000..5667ee856 --- /dev/null +++ b/packages/docs/operators/_request.yaml @@ -0,0 +1,36 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _request + pageTitle: _request + types: | + ``` + (requestId: string): any + ``` + description: | + The `_request` operator returns the response value of a request. If the request has not yet been call, or is still executing, the returned value is `null`. + + It only returns true if all the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). Else it returns false. + arguments: | + #### string + The id of the request. + examples: | + #### Using a request response: + ```yaml + _request: my_request + ``` + Returns: The response returned by the request. diff --git a/packages/docs/operators/_type.yaml b/packages/docs/operators/_type.yaml new file mode 100644 index 000000000..21cef89e6 --- /dev/null +++ b/packages/docs/operators/_type.yaml @@ -0,0 +1,79 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _type + pageTitle: _type + types: | + ``` + (type: enum): boolean + (arguments: {type: string, on?: any, key?: string}): boolean + ``` + description: | + The `_type` operator performs a type test on an object, and returns true if the object is of the specified type. + + The regex operator has shorthand argument definitions that can be used on web client. + arguments: | + #### string + The type to test. The string shorthand can only be used in an input block, and the tested value will be the block's value. + + #### object + - `type: enum`: __Required__ - The type to test. Can be one of: + - `string` + - `array` + - `date` + - `object` + - `boolean` + - `number` + - `integer` + - `null` + - `undefined` + - `none` (`null` or `undefined`) + - `primitive` (`undefined`, `null`, `string`, `number`, `boolean`, or `date`) + - `on: any`: The value to test. One of `on` or `key` must be specified unless the operator is used in an input block. + - `key: string`: The key of a value in `state` to test. One of `on` or `key` must be specified unless the operator is used in an input block. + examples: | + #### Check if a value is a number: + ```yaml + _type: + type: number + on: + _state: input + ``` + Returns: `true` if a number. + + #### Using the key of the value in `state`: + ```yaml + _type: + type: number + key: input + ``` + Returns: `true` if a number. + + #### Using the value of the block in which the operator is evaluated: + ```yaml + _type: number + ``` + Returns: `true` if a number + + #### Test if an id in the `urlQuery` is undefined or null: + ```yaml + _type: + type: none + on: + _url_query: id + ``` + Returns: `true` if the id is none, diff --git a/packages/docs/operators/_uuid.yaml b/packages/docs/operators/_uuid.yaml index 36628134c..75210cc73 100644 --- a/packages/docs/operators/_uuid.yaml +++ b/packages/docs/operators/_uuid.yaml @@ -29,7 +29,7 @@ _ref: ``` arguments: | #### any - The `_uuid` operator generates a UUID regardless of input. + The `_uuid` operator generates a UUID regardless of arguments. examples: | #### Generate a uuid: ```yaml diff --git a/packages/docs/templates/operators.yaml.njk b/packages/docs/templates/operators.yaml.njk index 785550362..f102a09bc 100644 --- a/packages/docs/templates/operators.yaml.njk +++ b/packages/docs/templates/operators.yaml.njk @@ -31,9 +31,6 @@ _ref: _var: types - id: description type: MarkdownWithHtml - style: - '.markdown-body': - fontSize: 14px properties: content: _var: description @@ -46,24 +43,15 @@ _ref: content: '### Arguments' - id: arguments type: MarkdownWithHtml - style: - '.markdown-body': - fontSize: 14px properties: content: _var: arguments - id: examples_title type: Markdown - style: - '.markdown-body': - fontSize: 14px properties: content: '### Examples' - id: examples type: MarkdownWithHtml - style: - '.markdown-body': - fontSize: 14px properties: content: _var: examples \ No newline at end of file