lowdefy/packages/docs/operators/_url_query.yaml

# 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
  transformer: templates/operatorsMethodTransformer.js
  vars:
    pageId: _url_query
    pageTitle: _url_query
    types: |
      ```
      (key: string): any
      (all: boolean): any
      (arguments: {
        all?: boolean,
        key?: string,
        default?: any,
        contextId?: string
      }): any
      ```      
    description: |
      The `_url_query` operator gets a value from the [`urlQuery`](/context-and-state) object. The `urlQuery` is a data object that is set as the [`https://en.wikipedia.org/wiki/Query_string`] of the app URL. It can be set when linking to a new page using the [`Link`](/link) action, and can be used to set data like a `id` when switching to a new page. Unlike `input`, the `urlQuery` is visible to the user, and can be modified by the user.

      > __DO NOT__ set any private or personal information to `urlQuery`; all data set to `urlQuery` are accessible publicly. Setting a `id` that can be guessed, like an incremental `id`, can lead to security issues, since users can easily guess and access data for other `ids`.

      If the page is reloaded, the `urlQuery` is not lost. By using `urlQuery`, you can make links containing data that can be shared by users. By default, `_url_query` accesses the `url_query` object from the [`context`](/context-and-state) the operator is used in, but a different context can be specified.

      `urlQuery` objects are serialized to JSON, allowing nested objects or arrays to be specified.      

    arguments: |
      ###### string
      If the `_url_query` operator is called with a string argument, the value of the key in the `urlQuery` object is returned. If the value is not found, `null` is returned. Dot notation and [block list indexes](/lists) are supported.

      ###### boolean
      If the `_url_query` operator is called with boolean argument `true`, the entire `urlQuery` object is returned.

      ###### object
        - `all: boolean`: If `all` is set to `true`, the entire `urlQuery` object is returned. One of `all` or `key` are required.
        - `key: string`: The value of the key in the `urlQuery` object is returned. If the value is not found, `null`, or the specified default value is returned. Dot notation and [block list indexes](/lists) are supported. One of `all` or `key` are required.
        - `default: any`: A value to return if the `key` is not found in `urlQuery`. By default, `null` is returned if a value is not found.
        - `contextId: string`: The id of a `context`. Setting this will get the value from the `urlQuery` of the specified context. A list of `contexts` that exist are returned by the [`_list_contexts`](/_list_contexts) operator. Cannot be used in `connections` or `requests`.      
    examples: |
      ###### Get the value of `my_key` from `urlQuery`:
      ```yaml
      _url_query: my_key
      ```
      ```yaml
      _url_query:
        key: my_key
      ```
      Returns: The value of `my_key` in `urlQuery`.

      ###### Get the entire `urlQuery` object:
      ```yaml
      _url_query: true
      ```
      ```yaml
      _url_query:
        all: true
      ```
      Returns: The entire `urlQuery` object.

      ###### Dot notation:
      Assuming urlQuery:
      ```yaml
      my_object:
        subfield: 'Value'
      ```
      then:
      ```yaml
      _url_query: my_object.subfield
      ```
      ```yaml
      _url_query:
        key: my_object.subfield
      ```
      Returns: `"Value"`.

      ###### Return a default value if the value is not found:
      ```yaml
      _url_query:
        key: might_not_exist
        default: Default value
      ```
      Returns: The value of `might_not_exist`, or `"Default value"`.

      ###### Block list indices:
      Assuming `urlQuery`:
      ```yaml
      my_array:
        - value: 0
        - value: 1
        - value: 2
      ```
      then:
      ```yaml
      _url_query: my_array.$.value
      ```
      Returns: `0` when used from the first block (0th index) in a list.

      ###### Get a value from another `context`:
      ```yaml
      _url_query:
        key: my_key
        contextId: 'pageId:contextId:{}'
      ```
      Returns: The value of `my_key` in `urlQuery` in context `contextId` on page `pageId`.