Skip to content

Commit e7fa389

Browse files
dacharyckrollins-mdb
dacharyc
and
krollins-mdb
authored
(DOCSP-39523): Consolidate Call a Function page (#3322)
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-39523 *Staged Page* - [Call an Atlas Function](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39523/sdk/atlas/call-function/) *Page Source* Add links to every SDK's pages where you got the SDK-specific information: - [C++: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/cpp/app-services/call-a-function/) - [Flutter: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/flutter/app-services/call-function/) - [Java: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/java/app-services/call-a-function/) - [Kotlin: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/app-services/call-function/) - [.NET: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/app-services/call-a-function/) - [Node.js: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/app-services/connect-to-app-services-backend/) - [Swift: Call a Function](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/app-services/call-a-function/) ### PR Author Checklist Before requesting a review for your PR, please check these items: - [x] Open the PR against the `feature-consolidated-sdk-docs` branch instead of `master` - [x] Tag the consolidated page for: - genre - meta.keywords - meta.description #### Naming - [x] Update Realm naming and the language around persistence layer/local/device per [this document](https://docs.google.com/document/d/126OczVxBWAwZ4P5ZsSM29WI3REvONEr1ald-mAwPtyQ/edit?usp=sharing) - [x] Include `.rst` files comply with [the naming guidelines](https://docs.google.com/document/d/1h8cr66zoEVeXytVfvDxlCSsUS5IZwvUQvfSCEXNMpek/edit#heading=h.ulh8b5f2hu9) #### Links and Refs - [x] Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections - [x] Remove or update any SDK-specific refs to use the new consolidated SDK ref targets - [x] [Update any Kotlin API links](https://jira.mongodb.org/browse/DOCSP-32519) to use the new Kotlin SDK roles #### Content - [x] Shared code boxes have snippets or placeholders for all 9 languages - [x] API description sections have API details or a generic placeholder for all 9 languages - [x] Check related pages for relevant content to include - [x] Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic ### Reviewer Checklist As a reviewer, please check these items: - [x] Shared code example boxes contain language-specific snippets or placeholders for every language - [ ] API reference details contain working API reference links or generic content - [x] Realm naming/language has been updated - [x] All relevant content from individual SDK pages is present on the consolidated page --------- Co-authored-by: Kyle Rollins <115574589+krollins-mdb@users.noreply.github.com>
1 parent c63b55c commit e7fa389

12 files changed

+268
-9
lines changed

‎source/includes/api-details/cpp/atlas/call-atlas-function-call-function-description.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
To call an Atlas Function, use the
2+
:cpp-sdk:`call_function() <structrealm_1_1user.html#a82ab02822dd96e8d44201b996dd6ed0c>`
3+
member function on the ``user`` object. Pass in the name of the
4+
function as a string for the first parameter. This function takes two arguments,
5+
which we provide as a string array of arguments.
6+
7+
The callback can provide an optional string result, or an optional error.
8+
In this example, we check that the result has a value.

‎source/includes/api-details/csharp/atlas/call-atlas-function-call-function-description.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
To call an Atlas Function, use the
2+
:dotnet-sdk:`Functions.CallAsync() <reference/Realms.Sync.User.FunctionsClient.html#Realms_Sync_User_FunctionsClient_CallAsync_System_String_System_Object___>`
3+
method on the ``User`` object, passing in the name of the function as the first
4+
parameter and the arguments as the remaining parameters:
5+
6+
.. literalinclude:: /examples/generated/dotnet/FunctionExamples.snippet.callfunc.cs
7+
:language: csharp
8+
9+
.. note::
10+
11+
The ``CallAsync()`` method returns a single ``BsonValue`` object, which you can
12+
deserialize after calling the function or by using the generic
13+
overload. Both of these approaches to deserialization are shown in the
14+
code above.
15+
16+
A ``BsonValue`` object can hold a single primitive value (as shown in the
17+
example above), or hold a complete BSON document. If
18+
you have a class that maps to the returned object, you can deserialize
19+
to that class by using the generic overload. For example, the following code
20+
calls a function that returns an object from a collection of "RealmTasks".
21+
Since we know the shape of the returned object, we we can deserialize the
22+
``BsonValue`` to a class that we have created, and then we have
23+
access to the properties and methods on that object:

‎source/includes/api-details/dart/atlas/call-atlas-function-call-function-description.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
To call a Function, call :flutter-sdk:`User.functions.call() <realm/FunctionsClient/call.html>`.
2+
Pass the Function name as the first argument and all arguments for the Function
3+
in a List as the second argument.
4+
5+
To include objects as arguments to the Function,
6+
convert them to JSON first. You can do this using the `jsonEncode()
7+
<https://api.flutter.dev/flutter/dart-convert/jsonEncode.html>`__
8+
function included in the built-in ``dart:convert`` library.
9+
10+
The Function returns a ``dynamic`` value containing :manual:`MongoDB Extended JSON (EJSON)
11+
</reference/mongodb-extended-json/>` deserialized to a native Dart object.

‎source/includes/api-details/java/atlas/call-atlas-function-call-function-description.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
To execute a function from the SDK, use the
2+
:java-sdk:`getFunctions() <io/realm/mongodb/App.html#getFunctions(io.realm.mongodb.User)>`
3+
method of the your :java-sdk:`App <io/realm/mongodb/App.html>`
4+
to retrieve a :java-sdk:`Functions manager <io/realm/mongodb/functions/Functions.html>`.
5+
6+
Pass the name and parameters of the function you would like to call to
7+
:java-sdk:`callFunction() <io/realm/mongodb/functions/Functions.html#callFunction(java.lang.String,java.util.List,java.lang.Class)>`
8+
or :java-sdk:`callFunctionAsync() <io/realm/mongodb/functions/Functions.html#callFunctionAsync(java.lang.String,java.util.List,java.lang.Class,io.realm.mongodb.App.Callback)>`:

‎source/includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
To call a function, you can either pass its name and arguments to
2+
``User.callFunction()`` or call the function as if it was a method on the
3+
:js-sdk:`User.functions <classes/User.html#functions>` property.

‎source/includes/api-details/kotlin/atlas/call-atlas-function-call-function-description.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
To call an Atlas Function, pass its name and all arguments to
2+
:kotlin-sync-sdk:`Functions.call() <io.realm.kotlin.mongodb.ext/call.html>`.
3+
4+
You can serialize Function arguments and return values using an EJSON encoder.
5+
For more information, including examples, refer to :ref:`sdks-ejson-encoding-for-atlas`.
6+
7+
To call this Atlas Function from the SDK:

‎source/includes/api-details/objectivec/atlas/call-atlas-function-call-function-description.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
To execute a function in Objective-C, call the :objc-sdk:`callFunctionNamed:arguments:completionBlock:
2+
<Classes/RLMUser.html#/c:objc(cs)RLMUser(im)callFunctionNamed:arguments:completionBlock:>`.
3+
method on the :objc-sdk:`RLMUser <Classes/RLMUser.html>` object.
4+
5+
Provide the Function name, arguments, and completion block to execute when the
6+
Function call is complete.

‎source/includes/api-details/swift/atlas/call-atlas-function-call-function-description.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
To execute a function in Swift, use the :swift-sdk:`functions
2+
<Structs/Functions.html>` object on the currently logged-in user.
3+
4+
The ``functions`` object has dynamic members corresponding to functions.
5+
In this case, ``functions.concatenate()`` refers to the ``concatenate``
6+
function. Pass a ``BSONArray`` of arguments.
7+
8+
Async/Await
9+
```````````
10+
11+
.. literalinclude:: /examples/generated/code/start/Functions.snippet.async-call-a-function.swift
12+
:language: swift
13+
14+
Completion Handler
15+
``````````````````
16+
17+
The trailing closure is the completion handler to call when the function call
18+
is complete. This handler is executed on a non-main global ``DispatchQueue``.

‎source/includes/important-sanitize-client-data-in-functions.rst

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎source/includes/sdk-examples/atlas/call-atlas-function-call-function.rst

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: cpp-sdk
5+
content: |
6+
7+
.. literalinclude:: /examples/generated/cpp/call-function.snippet.call-a-function.cpp
8+
:language: cpp
9+
10+
- id: csharp
11+
content: |
12+
13+
.. literalinclude:: /examples/generated/dotnet/FunctionExamples.snippet.callfuncWithPOCO.cs
14+
:language: csharp
15+
16+
- id: dart
17+
content: |
18+
19+
.. literalinclude:: /examples/generated/flutter/functions_test.snippet.call-function.dart
20+
:language: dart
21+
22+
- id: java
23+
content: |
24+
25+
.. literalinclude:: /examples/generated/java/sync/FunctionTest.snippet.call-a-function.java
26+
:language: java
27+
:emphasize-lines: 10-17
28+
29+
- id: java-kotlin
30+
content: |
31+
32+
.. literalinclude:: /examples/generated/java/sync/FunctionTest.snippet.call-a-function.kt
33+
:language: kotlin
34+
:emphasize-lines: 8,9,10,11,12,13,14,15,16,17
35+
36+
- id: javascript
37+
content: |
38+
39+
.. io-code-block::
40+
41+
.. input:: /examples/generated/node/call-a-function.snippet.call-a-function-by-name.js
42+
:language: javascript
43+
44+
.. output::
45+
:language: console
46+
47+
Using the "functions.sum()" method: the sum of 2 + 3 = 5
48+
Using the "callFunction()" method: the sum of 2 + 3 = 5
49+
50+
- id: kotlin
51+
content: |
52+
53+
.. literalinclude:: /examples/generated/kotlin/FunctionsTest.snippet.call-function.kt
54+
:language: kotlin
55+
56+
- id: objectivec
57+
content: |
58+
59+
.. literalinclude:: /examples/generated/code/start/Functions.snippet.call-a-function.m
60+
:language: objectivec
61+
62+
- id: swift
63+
content: |
64+
65+
.. literalinclude:: /examples/generated/code/start/Functions.snippet.call-a-function.swift
66+
:language: swift
67+
68+
- id: typescript
69+
content: |
70+
71+
.. io-code-block::
72+
73+
.. input:: /examples/generated/node/call-a-function.snippet.call-a-function-by-name.js
74+
:language: javascript
75+
76+
.. output::
77+
:language: console
78+
79+
Using the "functions.sum()" method: the sum of 2 + 3 = 5
80+
Using the "callFunction()" method: the sum of 2 + 3 = 5

‎source/sdk/atlas/call-function.txt

Lines changed: 99 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,107 @@
11
.. _sdks-call-function:
22

3-
===============
4-
Call a Function
5-
===============
3+
======================
4+
Call an Atlas Function
5+
======================
6+
7+
.. meta::
8+
:description: Call serverless Atlas Functions from a client application with Atlas Device SDK.
9+
:keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example
10+
11+
.. facet::
12+
:name: genre
13+
:values: reference
14+
15+
.. facet::
16+
:name: programming_language
17+
:values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift
618

719
.. contents:: On this page
820
:local:
921
:backlinks: none
10-
:depth: 2
22+
:depth: 1
1123
:class: singlecol
1224

13-
Placeholder page for the call a Function content.
25+
.. tabs-selector:: drivers
26+
27+
You can call an **Atlas Function** from a client application using Atlas
28+
Device SDK. Functions are serverless JavaScript functions that let you define
29+
and execute server-side logic. These server-side Functions can run in the
30+
context of the authenticated user, and thus honor the rules, roles, and
31+
permissions that you have assigned to your data in Atlas.
32+
33+
For more information on configuring and writing Atlas Functions, refer to
34+
:ref:`Atlas Functions <functions>` in the App Services documentation.
35+
36+
Before You Begin
37+
----------------
38+
39+
#. In an App Services App, :ref:`define an Atlas Function <define-a-function>`.
40+
#. In your client project, :ref:`initialize the App client <sdks-connect-to-atlas>`.
41+
#. Then, :ref:`authenticate a user <sdks-authenticate-users>`. You access
42+
Functions through the user object.
43+
44+
The example on this page demonstrates calling an :ref:`Atlas Function <functions>`
45+
that takes two arguments, performs some work, and returns the result.
46+
47+
Call a Function
48+
---------------
49+
50+
.. important::
51+
52+
Make sure to sanitize client data to protect against code injection when using
53+
Functions.
54+
55+
.. tabs-drivers::
56+
57+
.. tab::
58+
:tabid: cpp-sdk
59+
60+
.. include:: /includes/api-details/cpp/atlas/call-atlas-function-call-function-description.rst
61+
62+
.. tab::
63+
:tabid: csharp
64+
65+
.. include:: /includes/api-details/csharp/atlas/call-atlas-function-call-function-description.rst
66+
67+
.. tab::
68+
:tabid: dart
69+
70+
.. include:: /includes/api-details/dart/atlas/call-atlas-function-call-function-description.rst
71+
72+
.. tab::
73+
:tabid: java
74+
75+
.. include:: /includes/api-details/java/atlas/call-atlas-function-call-function-description.rst
76+
77+
.. tab::
78+
:tabid: java-kotlin
79+
80+
.. include:: /includes/api-details/java/atlas/call-atlas-function-call-function-description.rst
81+
82+
.. tab::
83+
:tabid: javascript
84+
85+
.. include:: /includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst
86+
87+
.. tab::
88+
:tabid: kotlin
89+
90+
.. include:: /includes/api-details/kotlin/atlas/call-atlas-function-call-function-description.rst
91+
92+
.. tab::
93+
:tabid: objectivec
94+
95+
.. include:: /includes/api-details/objectivec/atlas/call-atlas-function-call-function-description.rst
96+
97+
.. tab::
98+
:tabid: swift
99+
100+
.. include:: /includes/api-details/swift/atlas/call-atlas-function-call-function-description.rst
101+
102+
.. tab::
103+
:tabid: typescript
104+
105+
.. include:: /includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst
106+
107+
.. include:: /includes/sdk-examples/atlas/call-atlas-function-call-function.rst

‎source/sdk/serialization.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,8 @@ Serialization
1111
:class: singlecol
1212

1313
Placeholder page for information about serialization in the SDKs.
14+
15+
.. _sdks-ejson-encoding-for-atlas:
16+
17+
EJSON Encoding
18+
--------------

0 commit comments

Comments
 (0)