Skip to content

Commit c92d7f9

Browse files
dacharycdacharyc
authored
(DOCSP-39533): Consolidate Add Sync to an App page (#3351)
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-39533 *Staged Page* - [Add Sync to an App](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39533/sdk/sync/add-sync-to-app/) Note for reviewer: some of the API descriptions are intentionally missing because there isn't necessarily anything else relevant to add. *Page Source* Add links to every SDK's pages where you got the SDK-specific information: - [Flutter: Add Sync to an App](https://www.mongodb.com/docs/atlas/device-sdks/sdk/flutter/sync/add-sync-to-app/) - [Kotlin: Add Sync to an App](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/sync/add-sync-to-app/) - [.NET: Add Sync to an App](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/sync/add-sync-to-app/) - [Swift: Add Sync to an App](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/sync/add-sync-to-app/) ### 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 - [ ] 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: - [ ] Shared code example boxes contain language-specific snippets or placeholders for every language - [ ] API reference details contain working API reference links or generic content - [ ] Realm naming/language has been updated - [ ] All relevant content from individual SDK pages is present on the consolidated page
1 parent ad32aa9 commit c92d7f9

23 files changed

+681
-1
lines changed

‎source/includes/api-details/csharp/sync/add-sync-to-app-define-sync-configuration-description.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Device Sync requires a :dotnet-sdk:`FlexibleSyncConfiguration
2+
<reference/Realms.Sync.FlexibleSyncConfiguration.html>`
3+
object to open a synced database. Note that
4+
this is different than the :dotnet-sdk:`RealmConfiguration
5+
<reference/Realms.RealmConfiguration.html>` object that specifies some of the
6+
base database options.
7+
8+
The ``FlexibleSyncConfiguration`` object requires an authenticated **User**.
9+
10+
You can optionally provide an **Initial Subscription**. This is the
11+
subscription query that specifies the data to sync when the synced database is
12+
opened. You can update your subscriptions after you open the database.
13+
14+
If you do not provide an initial subscription as part of the Sync
15+
configuration, you must manually add subscriptions before you can read from or
16+
write to the database.
17+
18+
Refer to :ref:`sdks-manage-sync-subscriptions` for more information.
19+
20+
For additional database configuration parameters, refer to
21+
:ref:`sdks-configure-and-open-synced-database`.
22+
23+
For our example app, we define a configuration with an initial subscription
24+
that queries all ``MyTask`` objects.

‎source/includes/api-details/csharp/sync/add-sync-to-app-example-data-model-description.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
The examples on this page refer to an example Todo app with an already-defined
2+
``Item`` model that has:
3+
4+
- An ObjectId ``_id`` property
5+
- A string ``Name`` property
6+
- An ``ItemStatus`` enum property
7+
- A string ``Assignee`` property

‎source/includes/api-details/csharp/sync/add-sync-to-app-use-synced-database-description.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
The following code demonstrates two ways to create a new ``Task`` object and
2+
add it to the database.

‎source/includes/api-details/dart/sync/add-sync-to-app-define-sync-configuration-description.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Device Sync requires a :flutter-sdk:`FlexibleSyncConfiguration
2+
<realm/FlexibleSyncConfiguration-class.html>`
3+
object to open a synced database. Note that
4+
this is different than the :flutter-sdk:`Configuration
5+
<realm/Configuration-class.html>` object that specifies some of the
6+
base database options.
7+
8+
The ``FlexibleSyncConfiguration`` object requires an authenticated **User**.
9+
10+
For additional database configuration parameters, refer to
11+
:ref:`sdks-configure-and-open-synced-database`.
12+
13+
For our example app, we define a configuration to manage objects conforming to
14+
``Car.schema``.

‎source/includes/api-details/dart/sync/add-sync-to-app-example-data-model-description.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The examples on this page refer to an example app with an already-defined
2+
data model that includes a ``Car`` object containing an ``ObjectId`` and a
3+
string car ``model``.

‎source/includes/api-details/dart/sync/add-sync-to-app-open-synced-database-description.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
After you open the database, you must add subscriptions before you can read from or
2+
write to the database.
3+
4+
Refer to :ref:`sdks-manage-sync-subscriptions` for more information.

‎source/includes/api-details/dart/sync/add-sync-to-app-use-synced-database-description.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
The following code creates a new ``Car`` object and writes it to the database:

‎source/includes/api-details/kotlin/sync/add-sync-to-app-define-sync-configuration-description.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Device Sync requires a :kotlin-sync-sdk:`SyncConfiguration
2+
<io.realm.kotlin.mongodb.sync/-sync-configuration/index.html>`
3+
object to open a synced database. Note that
4+
this is different than the ``RealmConfiguration`` object that specifies some
5+
of the base database options.
6+
7+
The ``SyncConfiguration`` object requires the following:
8+
9+
- **User**: the authenticated user object.
10+
- **Schema**: all object types that you want to include in this database.
11+
- **Initial Subscription**: the subscription query
12+
that specifies the data to sync when the synced database is
13+
initially opened. You can update your subscriptions
14+
after the database is opened. Refer to
15+
:ref:`sdks-manage-sync-subscriptions` for more information.
16+
17+
For additional configuration parameters, refer to
18+
:ref:`sdks-configure-and-open-synced-database`.
19+
20+
For our example app, we define a configuration with:
21+
22+
- a schema that includes our ``List`` and ``Item`` objects
23+
- an initial subscription that queries all ``List`` objects
24+
that the user owns and all incomplete ``Item`` objects

‎source/includes/api-details/kotlin/sync/add-sync-to-app-example-data-model-description.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The examples on this page refer to an example Todo app with an already-defined
2+
data model that includes a ``List`` object containing a list of ``Item``
3+
objects.

‎source/includes/api-details/kotlin/sync/add-sync-to-app-open-synced-database-description.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
For our example app, we pass our ``config`` object to
2+
``realm.open()`` to open a synced database, then wait for
3+
our subscriptions to sync with the backend.
4+
5+
Because we have Development Mode enabled, Device Sync
6+
automatically adds the following as queryable fields based on
7+
our initial subscription:
8+
9+
- ``_id`` (always included)
10+
- ``ownerId``
11+
- ``complete``

‎source/includes/api-details/kotlin/sync/add-sync-to-app-prerequisites-description.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Atlas Device SDK for Kotlin has a separate distribution to add App Services
2+
and Device Sync functionality to an app. If you haven't already added it,
3+
update your dependencies to include the Sync distribution of the Kotlin library.
4+
For more details, refer to :ref:`sdks-install`.

‎source/includes/api-details/kotlin/sync/add-sync-to-app-use-synced-database-description.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
For our example app, we write a new ``List`` and ``Item`` object,
2+
then copy them to the synced database.
3+
4+
The objects successfully write to the device, then sync to Atlas because:
5+
6+
- Both objects are within the parameters of the subscription query
7+
(the ``List`` is owned by the user and the ``Item`` is incomplete).
8+
- The current user has permission to write data to the backend (the role allows
9+
authorized users to read and write all data).

‎source/includes/api-details/swift/sync/add-sync-to-app-define-sync-configuration-description.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Device Sync requires a :swift-sdk:`FlexibleSyncConfiguration
2+
<Extensions/User.html#/s:So7RLMUserC10RealmSwiftE25flexibleSyncConfiguration15clientResetMode31cancelAsyncOpenOnNonFatalErrors20initialSubscriptions05rerunmL0AC0B0V0F0VAC06ClienthI0O_SbyAC0E15SubscriptionSetVcSbtF>`
3+
object to open a synced database. Note that
4+
this is different than the :swift-sdk:`Configuration
5+
<Structs/Realm/Configuration.html>` object that specifies some of the base
6+
database options.
7+
8+
The ``FlexibleSyncConfiguration`` can take an ``initialSubscriptions`` block
9+
paired with a ``rerunOnOpen`` bool. The initial subscriptions are the
10+
subscription queries that specify what data to sync when the synced database
11+
is first opened. If your app needs it, you can pair this with ``reRunOnOpen``
12+
to recalculate dynamic queries every time the app opens, such as syncing
13+
documents within a date range.
14+
15+
You can update your subscriptions after the database is opened. Refer to
16+
:ref:`sdks-manage-sync-subscriptions` for more information.
17+
18+
For additional configuration parameters, refer to
19+
:ref:`sdks-configure-and-open-synced-database`.
20+
21+
For our example app, we define a configuration with:
22+
23+
- an initial subscription that queries ``Todo`` objects
24+
for documents where the ``ownerId`` matches the ``user.id`` of the logged-in user
25+
- a schema that includes our ``Todo`` object type

‎source/includes/api-details/swift/sync/add-sync-to-app-example-data-model-description.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
In this example, our model includes an ``ownerId`` field that maps to the
2+
``user.id`` of the logged-in user.

‎source/includes/api-details/swift/sync/add-sync-to-app-use-synced-database-description.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
The following code creates a new ``Task`` object and writes it to the database.

‎source/includes/sdk-examples/sync/add-sync-to-app-authenticate-user.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: csharp
5+
content: |
6+
7+
.. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_anon.cs
8+
:language: csharp
9+
10+
- id: dart
11+
content: |
12+
13+
.. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.log-in.dart
14+
:language: dart
15+
16+
- id: kotlin
17+
content: |
18+
19+
.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.authenticate-user.kt
20+
:language: kotlin
21+
22+
- id: swift
23+
content: |
24+
25+
.. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.authenticate-user.swift
26+
:language: swift

‎source/includes/sdk-examples/sync/add-sync-to-app-connect-to-atlas.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: csharp
5+
content: |
6+
7+
.. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.initialize-realm.cs
8+
:language: csharp
9+
10+
- id: dart
11+
content: |
12+
13+
.. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.connect-to-app.dart
14+
:language: dart
15+
16+
- id: kotlin
17+
content: |
18+
19+
.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.connect-to-backend.kt
20+
:language: kotlin
21+
22+
- id: swift
23+
content: |
24+
25+
.. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.connect-to-backend.swift
26+
:language: swift

‎source/includes/sdk-examples/sync/add-sync-to-app-define-sync-configuration.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: csharp
5+
content: |
6+
7+
.. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.bootstrap-a-subscription.cs
8+
:language: csharp
9+
10+
- id: dart
11+
content: |
12+
13+
.. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.opened-synced-realm.dart
14+
:language: dart
15+
16+
- id: kotlin
17+
content: |
18+
19+
.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.define-synced-realm.kt
20+
:language: kotlin
21+
22+
- id: swift
23+
content: |
24+
25+
.. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.open-synced-realm.swift
26+
:language: swift

‎source/includes/sdk-examples/sync/add-sync-to-app-example-data-model.rst

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: csharp
5+
content: |
6+
7+
.. literalinclude:: /examples/MissingPlaceholders/example.cs
8+
:language: csharp
9+
:copyable: false
10+
11+
- id: dart
12+
content: |
13+
14+
.. literalinclude:: /examples/MissingPlaceholders/example.dart
15+
:language: dart
16+
:copyable: false
17+
18+
- id: kotlin
19+
content: |
20+
21+
.. literalinclude:: /examples/generated/kotlin/SchemaSync.snippet.sync-to-do-model.kt
22+
:language: kotlin
23+
24+
- id: swift
25+
content: |
26+
27+
.. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.model.swift
28+
:language: swift

‎source/includes/sdk-examples/sync/add-sync-to-app-open-synced-database.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: csharp
5+
content: |
6+
7+
.. literalinclude:: /examples/MissingPlaceholders/example.cs
8+
:language: csharp
9+
:copyable: false
10+
11+
- id: dart
12+
content: |
13+
14+
.. literalinclude:: /examples/MissingPlaceholders/example.dart
15+
:language: dart
16+
:copyable: false
17+
18+
- id: kotlin
19+
content: |
20+
21+
.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-synced-realm.kt
22+
:language: kotlin
23+
24+
- id: swift
25+
content: |
26+
27+
.. literalinclude:: /examples/MissingPlaceholders/example.swift
28+
:language: swift
29+
:copyable: false

‎source/includes/sdk-examples/sync/add-sync-to-app-use-synced-database.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. tabs-drivers::
2+
3+
tabs:
4+
- id: csharp
5+
content: |
6+
7+
.. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.create.cs
8+
:language: csharp
9+
10+
- id: dart
11+
content: |
12+
13+
.. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.write.dart
14+
:language: dart
15+
16+
- id: kotlin
17+
content: |
18+
19+
.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.write-to-synced-realm.kt
20+
:language: kotlin
21+
22+
- id: swift
23+
content: |
24+
25+
.. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.create-todo.swift
26+
:language: swift

‎source/sdk/crud/threading.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,4 @@ Frozen Objects
3838
Update a Frozen Object
3939
~~~~~~~~~~~~~~~~~~~~~~
4040

41+
.. _sdks-threading-three-rules:

0 commit comments

Comments
 (0)