From 5012a876dbfc1a39c742fed5c52b34aa952f718c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 12:48:39 -0400 Subject: [PATCH 01/18] Draft consolidated Quick Start page --- source/frameworks/flutter.txt | 10 +- source/frameworks/flutter/quick-start.txt | 8 + source/frameworks/swiftui.txt | 11 +- source/frameworks/swiftui/quick-start.txt | 421 ++++++++++++++++ ...quick-start-close-database-description.rst | 2 + ...t-define-your-object-model-description.rst | 7 + .../quick-start-import-realm-description.rst | 2 + .../quick-start-open-database-description.rst | 4 + ...start-open-synced-database-description.rst | 5 + .../quick-start-write-to-synced-db.rst | 3 + ...quick-start-close-database-description.rst | 12 + ...t-define-your-object-model-description.rst | 7 + .../quick-start-import-realm-description.rst | 1 + .../quick-start-open-database-description.rst | 6 + ...start-open-synced-database-description.rst | 5 + ...quick-start-close-database-description.rst | 1 + ...art-define-your-object-model-procedure.rst | 39 ++ .../quick-start-import-realm-description.rst | 8 + .../quick-start-open-database-description.rst | 7 + ...start-open-synced-database-description.rst | 17 + ...quick-start-close-database-description.rst | 4 + ...t-define-your-object-model-description.rst | 2 + .../quick-start-import-realm-description.rst | 34 ++ .../quick-start-open-database-description.rst | 4 + ...start-open-synced-database-description.rst | 3 + ...start-close-database-js-ts-description.rst | 2 + ...ne-your-object-model-js-ts-description.rst | 12 + ...k-start-import-realm-js-ts-description.rst | 2 + ...-start-open-database-js-ts-description.rst | 3 + ...open-synced-database-js-ts-description.rst | 14 + ...quick-start-close-database-description.rst | 4 + ...t-define-your-object-model-description.rst | 3 + .../quick-start-import-realm-description.rst | 8 + .../quick-start-open-database-description.rst | 12 + ...start-open-synced-database-description.rst | 26 + ...quick-start-close-database-description.rst | 5 + ...t-define-your-object-model-description.rst | 2 + .../quick-start-import-realm-description.rst | 7 + .../quick-start-open-database-description.rst | 7 + ...start-open-synced-database-description.rst | 7 + .../includes/dotnet-implement-interface.rst | 6 +- .../quick-start-authenticate-user.rst | 59 +++ .../quick-start-close-database.rst | 59 +++ .../quick-start-create-objects.rst | 59 +++ .../quick-start-define-your-object-model.rst | 67 +++ .../quick-start-delete-objects.rst | 59 +++ .../quick-start-filter-objects.rst | 59 +++ .../quick-start/quick-start-import-realm.rst | 60 +++ .../quick-start-initialize-app.rst | 59 +++ .../quick-start/quick-start-open-database.rst | 57 +++ .../quick-start-open-synced-database.rst | 59 +++ .../quick-start-react-to-changes.rst | 60 +++ .../quick-start/quick-start-read-objects.rst | 59 +++ .../quick-start-update-object-properties.rst | 59 +++ .../quick-start-write-to-synced-db.rst | 56 +++ source/includes/sync-memory-performance.rst | 6 +- source/sdk/crud/query-engines.txt | 2 - source/sdk/crud/read.txt | 22 + source/sdk/crud/threading.txt | 5 + source/sdk/model-data/object-models.txt | 14 +- source/sdk/quick-start.txt | 472 +++++++++++++++++- 61 files changed, 2069 insertions(+), 26 deletions(-) create mode 100644 source/frameworks/flutter/quick-start.txt create mode 100644 source/frameworks/swiftui/quick-start.txt create mode 100644 source/includes/api-details/cpp/quick-start/quick-start-close-database-description.rst create mode 100644 source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst create mode 100644 source/includes/api-details/cpp/quick-start/quick-start-import-realm-description.rst create mode 100644 source/includes/api-details/cpp/quick-start/quick-start-open-database-description.rst create mode 100644 source/includes/api-details/cpp/quick-start/quick-start-open-synced-database-description.rst create mode 100644 source/includes/api-details/cpp/quick-start/quick-start-write-to-synced-db.rst create mode 100644 source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst create mode 100644 source/includes/api-details/csharp/quick-start/quick-start-define-your-object-model-description.rst create mode 100644 source/includes/api-details/csharp/quick-start/quick-start-import-realm-description.rst create mode 100644 source/includes/api-details/csharp/quick-start/quick-start-open-database-description.rst create mode 100644 source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst create mode 100644 source/includes/api-details/dart/quick-start/quick-start-close-database-description.rst create mode 100644 source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst create mode 100644 source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst create mode 100644 source/includes/api-details/dart/quick-start/quick-start-open-database-description.rst create mode 100644 source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst create mode 100644 source/includes/api-details/java/quick-start/quick-start-close-database-description.rst create mode 100644 source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst create mode 100644 source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst create mode 100644 source/includes/api-details/java/quick-start/quick-start-open-database-description.rst create mode 100644 source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst create mode 100644 source/includes/api-details/javascript/quick-start/quick-start-close-database-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/quick-start/quick-start-define-your-object-model-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/quick-start/quick-start-import-realm-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/quick-start/quick-start-open-database-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/quick-start/quick-start-open-synced-database-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/quick-start/quick-start-close-database-description.rst create mode 100644 source/includes/api-details/kotlin/quick-start/quick-start-define-your-object-model-description.rst create mode 100644 source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst create mode 100644 source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst create mode 100644 source/includes/api-details/kotlin/quick-start/quick-start-open-synced-database-description.rst create mode 100644 source/includes/api-details/swift/quick-start/quick-start-close-database-description.rst create mode 100644 source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst create mode 100644 source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst create mode 100644 source/includes/api-details/swift/quick-start/quick-start-open-database-description.rst create mode 100644 source/includes/api-details/swift/quick-start/quick-start-open-synced-database-description.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-close-database.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-create-objects.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-import-realm.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-open-database.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-read-objects.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst create mode 100644 source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst diff --git a/source/frameworks/flutter.txt b/source/frameworks/flutter.txt index e3937c6699..fe10d1acbc 100644 --- a/source/frameworks/flutter.txt +++ b/source/frameworks/flutter.txt @@ -4,11 +4,7 @@ Build with Flutter ================== -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol +.. toctree:: + :titlesonly: -Placeholder page for information about building with Flutter. (This may -be a directory depending on how much content we have/need.) + Quick Start diff --git a/source/frameworks/flutter/quick-start.txt b/source/frameworks/flutter/quick-start.txt new file mode 100644 index 0000000000..646599638f --- /dev/null +++ b/source/frameworks/flutter/quick-start.txt @@ -0,0 +1,8 @@ +.. _frameworks-flutter-quick-start: + +======================== +Quick Start with Flutter +======================== + +Placeholder page for a Flutter quick start. + diff --git a/source/frameworks/swiftui.txt b/source/frameworks/swiftui.txt index 869adedb3f..4fe996a62f 100644 --- a/source/frameworks/swiftui.txt +++ b/source/frameworks/swiftui.txt @@ -4,12 +4,7 @@ Build with SwiftUI ================== -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol +.. toctree:: + :titlesonly: -Placeholder page for information about building with SwiftUI. - -This will be a directory with SwiftUI content. + Quick Start diff --git a/source/frameworks/swiftui/quick-start.txt b/source/frameworks/swiftui/quick-start.txt new file mode 100644 index 0000000000..f1b669b048 --- /dev/null +++ b/source/frameworks/swiftui/quick-start.txt @@ -0,0 +1,421 @@ +.. _ios-swiftui-combine-quick-start: +.. _ios-swiftui-quick-start: + +================== +SwiftUI QuickStart +================== + +.. meta:: + :description: Learn how to use Atlas Device SDK with SwiftUI property wrappers. + :keywords: code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: swift + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Prerequisites +------------- + +- :ref:`Install the Swift SDK. `. +- Meet the minimum Xcode and iOS targets required by the Swift SDK version. +- Create a new Xcode project using the SwiftUI "App" template. + +Overview +-------- + +.. seealso:: Use SwiftUI with Atlas Device SDK + + This page provides a small working app to get you up and running with + SwiftUI and Atlas Device SDK quickly. If you'd like to learn from a working + example app, instead, check out the the SwiftUI :ref:`template app + ` or the :ref:`swift-swiftui-tutorial`. + +This page contains all of the code for a working SwiftUI and Atlas Device SDK +app. The app starts on the ``ItemsView``, where you can edit a list of items: + +- Press the ``Add`` button on the bottom right of the screen to add + randomly-generated items. +- Press the ``Edit`` button on the top right to modify the list order, + which the app persists in the realm. +- You can also swipe to delete items. + +When you have items in the list, you can press one of the items to +navigate to the ``ItemDetailsView``. This is where you can modify the +item name or mark it as a favorite: + +- Press the text field in the center of the screen and type a new name. + When you press Return, the item name should update across the app. +- You can also toggle its favorite status by pressing the heart toggle in the + top right. + +.. tip:: + + This guide optionally integrates with :ref:`Device Sync `. See + :ref:`swiftui-integrate-with-sync` below. + +Get Started +~~~~~~~~~~~ + +We assume you have created an Xcode project with the SwiftUI "App" +template. Open the main Swift file and delete all of the code inside, +including any ``@main`` ``App`` classes that Xcode generated for you. At +the top of the file, import the Realm and SwiftUI frameworks: + +.. literalinclude:: /examples/generated/swiftui/local/SwiftUIFlexSyncExampleApp.snippet.imports.swift + :language: swift + +.. tip:: + + Just want to dive right in with the complete code? Jump to + :ref:`swiftui-complete-code` below. + +.. _swiftui_quickstart-define-models: + +Define Models +~~~~~~~~~~~~~ + +A common SDK data modeling use case is to have "things" and +"containers of things". This app defines two related SDK object models: item +and itemGroup. + +An item has two user-facing properties: + +- A randomly generated-name, which the user can edit. +- An ``isFavorite`` boolean property, which shows whether the user "favorited" + the item. + +An itemGroup contains items. You can extend the itemGroup to have a name and an +association with a specific user, but that's out of scope of this guide. + +Paste the following code into your main Swift file to define the models: + +Because Sync does not automatically include linked objects, we must add +``ownerId`` to both objects. You can omit ``ownerId`` if you only want to use +a non-synced database. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.flexible-sync-models.swift + :language: swift + +Views and Observed Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The entrypoint of the app is the ``ContentView`` class that derives from +``SwiftUI.App``. For now, this always displays the +``LocalOnlyContentView``. Later, this will show the ``SyncContentView`` +when Device Sync is enabled. + +.. literalinclude:: /examples/generated/swiftui/local/SwiftUIFlexSyncExampleApp.snippet.content-view.swift + :language: swift + +.. tip:: + + You can use a database other than the default database by passing + an environment object from higher in the View hierarchy: + + .. code-block:: swift + + LocalOnlyContentView() + .environment(\.realmConfiguration, Realm.Configuration( /* ... */ )) + +The LocalOnlyContentView has an :swift-sdk:`@ObservedResults +` itemGroups. This implicitly uses the default +database to load all itemGroups when the view appears. + +This app only expects there to ever be one itemGroup. If there is an itemGroup +in the database, the LocalOnlyContentView renders an ``ItemsView`` for +that itemGroup. + +If there is no itemGroup already in the database, then the +LocalOnlyContentView displays a ProgressView while it adds one. Because +the view observes the itemGroups thanks to the ``@ObservedResults`` property +wrapper, the view immediately refreshes upon adding that first itemGroup and +displays the ItemsView. + +.. literalinclude:: /examples/generated/swiftui/local/SwiftUIFlexSyncExampleApp.snippet.local-only-content-view.swift + :language: swift + +.. tip:: + + Starting in SDK version 10.12.0, you can use an optional key path parameter + with ``@ObservedResults`` to filter change notifications to only those + occurring on the provided key path or key paths. For example: + + .. code-block:: + + @ObservedResults(MyObject.self, keyPaths: ["myList.property"]) + +The ItemsView receives the itemGroup from the parent view and stores it in +an :swift-sdk:`@ObservedRealmObject ` +property. This allows the ItemsView to "know" when the object has +changed regardless of where that change happened. + +The ItemsView iterates over the itemGroup's items and passes each item to an +``ItemRow`` for rendering as a list. + +To define what happens when a user deletes or moves a row, we pass the +``remove`` and ``move`` methods of the SDK +:swift-sdk:`List ` as the handlers of the respective +remove and move events of the SwiftUI List. Thanks to the +``@ObservedRealmObject`` property wrapper, we can use these methods +without explicitly opening a write transaction. The property wrapper +automatically opens a write transaction as needed. + +.. literalinclude:: /examples/generated/swiftui/local/SwiftUIFlexSyncExampleApp.snippet.items-view.swift + :language: swift + +Finally, the ``ItemRow`` and ``ItemDetailsView`` classes use the +``@ObservedRealmObject`` property wrapper with the item passed in from +above. These classes demonstrate a few more examples of how to use the +property wrapper to display and update properties. + +.. literalinclude:: /examples/generated/swiftui/local/SwiftUIFlexSyncExampleApp.snippet.item-row-and-details.swift + :language: swift + +.. tip:: + + ``@ObservedRealmObject`` is a frozen object. If you want to :ref:`modify + the properties ` of an ``@ObservedRealmObject`` + directly in a write transaction, you must ``.thaw()`` it first. + +At this point, you have everything you need to work with Atlas Device SDK and +SwiftUI on a device. Test it out and see if everything is working as expected. +Read on to learn how to integrate this app with Device Sync. + +.. _swiftui-integrate-with-sync: + +Integrate Atlas Device Sync +--------------------------- + +Now that we have a working app, we can optionally integrate with Device Sync. +Sync allows you to you see the changes you make across devices. Before you can +add sync to this app, make sure to: + +- :ref:`Create an App Services App `. +- :ref:`Enable anonymous authentication `. +- :ref:`Enable Device Sync `. + + 1. Specify a cluster and database. + #. Turn on Development Mode. + #. Use ``ownerId`` as the queryable field. + #. Enable Sync. + +- :ref:`Define the rules ` that determine which + permissions users have when using Device Sync. For this example, we assign + a default role, which applies to any collection that does not have a + collection-specific role. In this example, a user can read and write data + where the ``user.id`` of the logged-in user matches the ``ownerId`` of the + object: + + .. literalinclude:: /includes/swiftui-tutorial-default-role.json + :language: json + +Now, deploy your application updates. + +.. tip:: + + The Sync version of this app changes the app flow a bit. The first + screen becomes the ``LoginView``. When you press the :guilabel:`Log + in` button, the app navigates to the ItemsView, where you see the + synced list of items in a single itemGroup. + +At the top of the source file, initialize an SDK :swift-sdk:`App +` with :ref:`your App ID `: + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.mongodb-realm.swift + :language: swift + +.. tip:: + + You can change the app reference to ``nil`` to switch back to + non-Device Sync mode. + +Let's update the main ContentView to show the ``SyncContentView`` if the +app reference is not ``nil``: + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.content-view.swift + :language: swift + +We define the SyncContentView below. + +The SyncContentView observes the SDK app instance. The app instance is +the interface to the App Services backend, which provides the user +authentication required for Sync. By observing the app instance, the +SyncContentView can react when a user logs in or out. + +This view has two possible states: + +- If the SDK app does not have a currently logged-in user, show the ``LoginView``. +- If the app does have a logged-in user, show the ``OpenSyncedRealmView``. + +In this view, after confirming we have a user, we create a +:swift-sdk:`flexibleSyncConfiguration() +` +that includes the ``initialSubscriptions`` parameter. We can use this +parameter to :ref:`subscribe to queryable fields +`. These initial subscriptions +search for data that matches the queries, and syncs that data to the +realm. If no data matches the queries, the realm opens with an initial +empty state. + +Your client application can only write objects that match the +subscription query to a realm opened with a ``flexibleSyncConfiguration``. +Trying to write objects that don't match the query causes the app to +perform a compensating write to undo the illegal write operation. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.flex-sync-content-view.swift + :language: swift + +In our subscriptions, we're querying for ``ItemGroup`` and ``Item`` objects +where the ``ownerId`` matches the logged-in user's ``user.id``. +Together with the permissions we used when we enabled Device Sync +above, this means that the user can only read and write their own +data. + +Device Sync does not automatically provide access to linked objects. +Because of this, we must add subscriptions for both the ``ItemGroup`` and +``Item`` objects - we can't just query for one or the other and get +the related objects. + +From here, we pass the flexibleSyncConfiguration to the +OpenSyncedRealmView as a ``realmConfiguration`` using an environment +object. This is the view responsible for opening a database and working +with the data. The SDK uses this configuration to search for data +that should sync to the database. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.realm-config-environment-object.swift + :language: swift + +Once logged in, we open the database asynchronously with the +:swift-sdk:`AsyncOpen ` property wrapper. + +Because we've injected a ``flexibleSyncConfiguration()`` into the +view as an environment value, the property wrapper uses this +configuration to initiate Sync and download any matching data before +opening the database. If we had not provided a configuration, the property +wrapper would create a default ``flexibleSyncConfiguration()`` for us, +and we could :ref:`subscribe to queries ` +in ``.onAppear``. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.flex-sync-property-wrapper.swift + :language: swift + +The OpenSyncedRealmView switches on the :swift-sdk:`AsyncOpenState +enum `, which lets us show different views +based on the state. In our example, we show a ``ProgressView`` while we're +connecting to the App and the database is syncing. We then open the +database, passing the ``itemGroup`` to the ``ItemsView``, or show an +``ErrorView`` if we can't open the database. + +.. tip:: + + When opening a synced database, use the :swift-sdk:`AsyncOpen + ` property wrapper to always download synced changes + before opening the database, or the :swift-sdk:`AutoOpen + ` property wrapper to open a database while syncing + in the background. ``AsyncOpen`` requires the user to be online, + while ``AutoOpen`` opens a database even if the user is offline. + +This view has a few different states: + +- While connecting or waiting for login, show a ``ProgressView``. +- While downloading changes to the database, show a ``ProgressView`` with a + progress indicator. +- When the database opens, check for an itemGroup object. If one does not exist + yet, create one. Then, show the ItemsView for the itemGroup in the database. + Provide a ``LogoutButton`` that the ItemsView can display on the top left + of the navigation bar. +- If there is an error loading the database, show an error view containing + the error. + +When you run the app and see the main UI, there are no items in the view. +That's because we're using anonymous login, so this is the first time this +specific user logs in. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.open-realm-view-flex-sync.swift + :language: swift + +In our subscriptions, we're querying for ``ItemGroup`` and ``Item`` objects +where the ``ownerId`` matches the logged-in user's ``user.id``. +Together with the permissions we used when we created the Sync app above, this +means that the user can only read and write their own data. + +Sync does not automatically provide access to linked objects. +Because of this, we must add subscriptions for both the ``ItemGroup`` and +``Item`` objects - we can't just query for one or the other and get +the related objects. + +With this in mind, we must also update the view here where we are +creating a ``ItemGroup`` object. We must set the ``ownerId`` as the ``user.id`` +of the logged-in user. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.add-ownerid-to-group.swift + :language: swift + +And we must also update the ``ItemsView`` to add ``ownerId`` when we +create ``Item`` objects: + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.add-ownerid-to-create-button-code.swift + :language: swift + +Authenticate Users with Atlas App Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The LoginView maintains some state in order to display an activity +indicator or error. It uses a reference to the app instance passed +in from above to log in when the :guilabel:`Log in anonymously` button +is clicked. + +.. tip:: + + In the LoginView, you can implement :ref:`email/password + authentication ` or :ref:`another + authentication provider `. For simplicity, + this example uses Anonymous authentication. + +Once login is complete, the LoginView itself doesn't need to do anything +more. Because the parent view is observing the app, it notices +when the user authentication state has changed and shows +something other than the LoginView. + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.login-view.swift + :language: swift + +The LogoutButton works just like the LoginView, but logs out instead of +logging in: + +.. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.logout-button.swift + :language: swift + +Once logged in, the app follows the same flow as the non-Sync version. + +.. _swiftui-complete-code: + +Complete Code +------------- + +If you would like to copy and paste or examine the complete code with or +without Device Sync, see below. + +.. tabs:: + + .. tab:: Without Sync + :tabid: local + + .. literalinclude:: /examples/generated/swiftui/local/SwiftUIFlexSyncExampleApp.snippet.complete-swiftui-flex-sync-quickstart.swift + :language: swift + + .. tab:: With Flexible Sync + :tabid: flex-sync + + .. literalinclude:: /examples/generated/swiftui/flex-sync/SwiftUIFlexSyncExampleApp.snippet.complete-swiftui-flex-sync-quickstart.swift + :language: swift diff --git a/source/includes/api-details/cpp/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/cpp/quick-start/quick-start-close-database-description.rst new file mode 100644 index 0000000000..a301a9efdd --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-close-database-description.rst @@ -0,0 +1,2 @@ +To close a database and release all underlying resources, call ``db::close()``. +Closing the database invalidates any remaining objects. diff --git a/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst new file mode 100644 index 0000000000..709e48a443 --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,7 @@ +In this quick start, you can remove ``ownerId`` unless you want to add the +optional Device Sync. + +.. important:: Define SDK Models within the realm namespace + + The C++ SDK requires you to define the object models that you want to store + in the database within the ``realm`` namespace. diff --git a/source/includes/api-details/cpp/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/cpp/quick-start/quick-start-import-realm-description.rst new file mode 100644 index 0000000000..b1df5087ff --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,2 @@ +Make the C++ SDK available in your code by including the +``cpprealm/sdk.hpp`` header in the translation unit where you want to use it: diff --git a/source/includes/api-details/cpp/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/cpp/quick-start/quick-start-open-database-description.rst new file mode 100644 index 0000000000..8034837014 --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,4 @@ +When you open a database, you must specify a :cpp-sdk:`db_config +`. You can +optionally open a database at a specific path, or provide a ``sync_config`` +to open a synced database. diff --git a/source/includes/api-details/cpp/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/cpp/quick-start/quick-start-open-synced-database-description.rst new file mode 100644 index 0000000000..3208130bac --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-open-synced-database-description.rst @@ -0,0 +1,5 @@ +Once you have enabled Device Sync and authenticated a user, you can create +a :cpp-sdk:`sync_configuration +` object and +open the database. You can then add a Sync subscription that determines what +data the database can read and write. diff --git a/source/includes/api-details/cpp/quick-start/quick-start-write-to-synced-db.rst b/source/includes/api-details/cpp/quick-start/quick-start-write-to-synced-db.rst new file mode 100644 index 0000000000..56c87e4850 --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-write-to-synced-db.rst @@ -0,0 +1,3 @@ +In this example, we store the ``user.identifier()`` of the logged-in user in +the ``ownerId`` property of the ``Todo`` item. We then use this property +in subscription queries and the Device Sync permissions. diff --git a/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst new file mode 100644 index 0000000000..3c199a444b --- /dev/null +++ b/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst @@ -0,0 +1,12 @@ +The database instance implements ``IDisposable`` to ensure native resources are +freed up. You should dispose of a database object immediately after use, +especially on background threads. The simplest way to do this is by declaring +the database object with a ``using`` statement, or wrapping the code that +interacts with a database in a ``using (...)`` statement: + +.. literalinclude:: /examples/generated/dotnet/OpenARealmExamples.snippet.scope.cs + :language: csharp + +If you require a database object to be shared outside of a single method, +to manage its state by calling the +:dotnet-sdk:`Dispose() ` method: diff --git a/source/includes/api-details/csharp/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-define-your-object-model-description.rst new file mode 100644 index 0000000000..c5922bdcd8 --- /dev/null +++ b/source/includes/api-details/csharp/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,7 @@ +.. include:: /includes/dotnet-implement-interface.rst + +The following code shows how to define an object model for an ``Item`` object. +In this example, we have marked the ``Id`` field as the Primary Key and marked +the ``Status`` property as optional. We've also chosen to use the ``MapTo`` +attribute; properties will be stored in lower case on the server, but can use +.NET-friendly casing on our property names when using Device Sync. diff --git a/source/includes/api-details/csharp/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-import-realm-description.rst new file mode 100644 index 0000000000..3bff9b4832 --- /dev/null +++ b/source/includes/api-details/csharp/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1 @@ +Add the following line to the top of your source files to use the SDK: diff --git a/source/includes/api-details/csharp/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-open-database-description.rst new file mode 100644 index 0000000000..0ffd36bc4b --- /dev/null +++ b/source/includes/api-details/csharp/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,6 @@ +Open a database with either the +:dotnet-sdk:`Realm.GetInstance() ` or +:dotnet-sdk:`Realm.GetInstanceAsync() ` +method. Which method you use depends entirely on if and how you are using `asynchronous +patterns `_ in your app. +The following code shows how to use ``GetInstance()``: diff --git a/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst new file mode 100644 index 0000000000..c84b6d147d --- /dev/null +++ b/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst @@ -0,0 +1,5 @@ +Once you have enabled Device Sync and authenticated a user, you can +open a synced database. Use a``FlexibleSyncConfiguration`` object to define +the specifics of how your application synchronizes data with App Services. +Then, add a Sync subscription that determines what data the user can read and +write. diff --git a/source/includes/api-details/dart/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/dart/quick-start/quick-start-close-database-description.rst new file mode 100644 index 0000000000..7f5b1e7c49 --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-close-database-description.rst @@ -0,0 +1 @@ +Once you've finished working with a database, close it to prevent memory leaks. diff --git a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst new file mode 100644 index 0000000000..3330e40f85 --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst @@ -0,0 +1,39 @@ +Your application's **data model** defines the structure of data stored within +the database. You can define your application's data model via Dart +classes in your application code with an SDK object schema. +You then have to generate the :flutter-sdk:`RealmObjectBase ` +class that's used within your application. + +For more information, refer to :ref:`Define an Object Schema +`. + +.. procedure:: + + .. step:: Create a Model Class + + Add an SDK model class. Give your class a private name + (starting with ``_``), such as a file ``car.dart`` with a class + ``_Car``. + + .. step:: Generate an SDK Object Class + + Generate a RealmObject class ``Car`` from the data model class ``_Car``: + + .. code-block:: + + dart run realm_dart generate + + Running this creates a ``Car`` class in a ``car.realm.dart`` file + located in the directory where you defined the model class. This ``Car`` + class is public and part of the same library as the ``_Car`` data model + class. The generated ``Car`` class is what's used throughout your + application. + + .. step:: Watch for Changes to the Model (Optional) + + You can watch your data model class to generate a new ``Car`` class + whenever there's a change to ``_Car``: + + .. code-block:: + + dart run realm_dart generate --watch diff --git a/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst new file mode 100644 index 0000000000..42f74ae257 --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,8 @@ +Import the package into any files where you use it. + +.. tip:: Standalone Dart or Flutter Project? + + This quick start contains information for using the SDK with a standalone + Dart project. The package that you import, and the way you create object + models, differ if you are using the SDK in a Flutter project. For a quick + start using Flutter, refer to :ref:`frameworks-flutter-quick-start`. diff --git a/source/includes/api-details/dart/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/dart/quick-start/quick-start-open-database-description.rst new file mode 100644 index 0000000000..cbffb4975e --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,7 @@ +Use the :flutter-sdk:`Configuration ` class +to define the specifics of the database instance, including schema and whether +the database is non-synced or synced. + +Pass your configuration to the +:flutter-sdk:`database constructor ` to generate an +instance of that database: diff --git a/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst new file mode 100644 index 0000000000..bc0693257a --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst @@ -0,0 +1,17 @@ +Once you have enabled Device Sync and authenticated a user, +create a :flutter-sdk:`Configuration.flexibleSync() ` +object. Then, pass the configuration to :flutter-sdk:`Realm() ` +to open an instance of the database. The synced database **must** have a +different :flutter-sdk:`Configuration.path ` +from other opened non-synced databases. + +.. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.open-sync-realm.dart + :language: dart + +Now create a subscription to synchronize data with Atlas using Device Sync. +Add the subscription within the :flutter-sdk:`SubscriptionSet.update() ` +callback function. + +The update block callback function, includes a :flutter-sdk:`MutableSubscriptionSet() +` object as an argument. +Use ``MutableSubscriptionSet.add()`` to add a new subscription. diff --git a/source/includes/api-details/java/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/java/quick-start/quick-start-close-database-description.rst new file mode 100644 index 0000000000..05acd377d6 --- /dev/null +++ b/source/includes/api-details/java/quick-start/quick-start-close-database-description.rst @@ -0,0 +1,4 @@ +It is important to remember to call the :java-sdk:`close() +` method when done with a +database instance to free resources. Neglecting to close realms can lead to an +``OutOfMemoryError``. diff --git a/source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst new file mode 100644 index 0000000000..53f44f339b --- /dev/null +++ b/source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,2 @@ +To define your application's data model, add the following class +definitions to your application code: diff --git a/source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst new file mode 100644 index 0000000000..4f0e358fa2 --- /dev/null +++ b/source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,34 @@ +Before you can use the SDK in your app, you must +initialize the Realm library. Your application should +initialize the SDK just once each time the application runs. + +To initialize the Realm library, provide an Android +``context`` to the ``Realm.init()`` static function. You can provide +an Activity, Fragment, or Application ``context`` for initialization with no +difference in behavior. You can initialize the library +in the ``onCreate()`` method of an `application subclass +`__ to +ensure that you only initialize the SDK once each time the +application runs. + +.. tip:: Register Your Application Subclass in the Android Manifest + + If you create your own ``Application`` subclass, you must add it to your + application's ``AndroidManifest.xml`` to execute your custom + application logic. Set the ``android.name`` property of your manifest's + application definition to ensure that Android instantiates your ``Application`` + subclass before any other class when a user launches your application. + + .. code-block:: xml + :emphasize-lines: 6 + :copyable: false + + + + + + diff --git a/source/includes/api-details/java/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/java/quick-start/quick-start-open-database-description.rst new file mode 100644 index 0000000000..e9beceea91 --- /dev/null +++ b/source/includes/api-details/java/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,4 @@ +Use ``RealmConfiguration`` to control the specifics of the database you +would like to open, including the name or location of the database, +whether to allow synchronous reads or writes to a database on the UI +thread, and more. diff --git a/source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst new file mode 100644 index 0000000000..9aa8fecdbe --- /dev/null +++ b/source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst @@ -0,0 +1,3 @@ +Use ``SyncConfiguration`` to define the specifics of how your application +synchronizes data with App Services, including timeouts, synchronous +reads and writes on the UI thread, and more. diff --git a/source/includes/api-details/javascript/quick-start/quick-start-close-database-js-ts-description.rst b/source/includes/api-details/javascript/quick-start/quick-start-close-database-js-ts-description.rst new file mode 100644 index 0000000000..18be7432f5 --- /dev/null +++ b/source/includes/api-details/javascript/quick-start/quick-start-close-database-js-ts-description.rst @@ -0,0 +1,2 @@ +Call the :js-sdk:`realm.close() ` method when done +with a database instance to avoid memory leaks. diff --git a/source/includes/api-details/javascript/quick-start/quick-start-define-your-object-model-js-ts-description.rst b/source/includes/api-details/javascript/quick-start/quick-start-define-your-object-model-js-ts-description.rst new file mode 100644 index 0000000000..023ea614ee --- /dev/null +++ b/source/includes/api-details/javascript/quick-start/quick-start-define-your-object-model-js-ts-description.rst @@ -0,0 +1,12 @@ +To define an SDK object type, create a schema object that specifies the type's +``name`` and ``properties``. The type name must be unique among object types in +the database. + +The following code shows how to define an object model for a ``Task`` object. +In this example: + +- The ``primaryKey`` is the ``_id`` of type ``int``. Another common type used + for primary keys is ``ObjectId``. +- The ``name`` field is required. +- The ``status`` and ``owner_id`` fields are optional, denoted by the question + mark immediately after the data type. diff --git a/source/includes/api-details/javascript/quick-start/quick-start-import-realm-js-ts-description.rst b/source/includes/api-details/javascript/quick-start/quick-start-import-realm-js-ts-description.rst new file mode 100644 index 0000000000..c00d1a27e0 --- /dev/null +++ b/source/includes/api-details/javascript/quick-start/quick-start-import-realm-js-ts-description.rst @@ -0,0 +1,2 @@ +At the top of your source files where you want to use the SDK, add +the following line: diff --git a/source/includes/api-details/javascript/quick-start/quick-start-open-database-js-ts-description.rst b/source/includes/api-details/javascript/quick-start/quick-start-open-database-js-ts-description.rst new file mode 100644 index 0000000000..35f1522e71 --- /dev/null +++ b/source/includes/api-details/javascript/quick-start/quick-start-open-database-js-ts-description.rst @@ -0,0 +1,3 @@ +To open a database, pass a :js-sdk:`Realm.BaseConfiguration +` object to :js-sdk:`Realm.open() +`. diff --git a/source/includes/api-details/javascript/quick-start/quick-start-open-synced-database-js-ts-description.rst b/source/includes/api-details/javascript/quick-start/quick-start-open-synced-database-js-ts-description.rst new file mode 100644 index 0000000000..202e5bfb06 --- /dev/null +++ b/source/includes/api-details/javascript/quick-start/quick-start-open-synced-database-js-ts-description.rst @@ -0,0 +1,14 @@ +After you have initialized your App, authenticated a user, and +defined your object model, you can create a :js-sdk:`SyncConfiguration +`. + +To open a synced database, call :js-sdk:`Realm.open() `. +Pass in a :js-sdk:`BaseConfiguration ` +object, which must include the ``sync`` property defining a +:js-sdk:`SyncConfiguration ` object. +In the ``SyncConfiguration``, you must include include a ``user`` and set +``flexible: true``. + +Additionally, you need at least one subscription before you can read from or +write to the database. Use ``Configuration.sync.initialSubscriptions`` to +define the initial subscription set when the database file is first opened. diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-close-database-description.rst new file mode 100644 index 0000000000..0a21062cf8 --- /dev/null +++ b/source/includes/api-details/kotlin/quick-start/quick-start-close-database-description.rst @@ -0,0 +1,4 @@ +To close a database and release all underlying resources, call +:kotlin-sdk:`realm.close() `. The +``close()`` method blocks until all write transactions on the database +have completed. diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-define-your-object-model-description.rst new file mode 100644 index 0000000000..9718fc9a31 --- /dev/null +++ b/source/includes/api-details/kotlin/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,3 @@ +To define your application's data model, add a class definition to your +application code. The example below illustrates the creation of an ``Item`` +model that represents Todo items in a Todo list app. diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst new file mode 100644 index 0000000000..7608985818 --- /dev/null +++ b/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,8 @@ +.. note:: Using this Quick Start with KMP + + If you're running this project in a fresh Kotlin Multiplatform (KMP) template project, you can + copy and paste the following snippets into the :file:`Greeting.greeting()` method in the + :file:`commonMain` module. + +At the top of your source files where you want to use the SDK, add +the appropriate imports. For this quick start, we use these imports: diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst new file mode 100644 index 0000000000..36ddeb1573 --- /dev/null +++ b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,12 @@ +Use +:kotlin-sdk:`RealmConfiguration.create() +` +to open a database using default parameters. Pass your configuration to the +:kotlin-sdk:`factory constructor ` +to generate an instance of that database. + +For more information on how to control the specifics of the +:kotlin-sdk:`RealmConfiguration +` +you would like to open (e.g. name, location, schema version), refer to +:ref:`sdks-sdks-configure-and-open-database`. diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-open-synced-database-description.rst new file mode 100644 index 0000000000..c187e82ba6 --- /dev/null +++ b/source/includes/api-details/kotlin/quick-start/quick-start-open-synced-database-description.rst @@ -0,0 +1,26 @@ +Once you have initialized your Atlas App Services App, authenticated a user, and +defined your object model, you can create a :kotlin-sync-sdk:`SyncConfiguration +`. + +If you have opened a non-synced database following the **Open a Database** +section on this page, replace the :kotlin-sdk:`RealmConfiguration +` with +the ``SyncConfiguration`` described below. + +Pass the authenticated user and the ``Item`` class to the +:kotlin-sync-sdk:`SyncConfiguration.Builder +` +function to create ``SyncConfiguration``. + +.. important:: Initial Subscriptions + + You need at least one subscription before you can read from or write to the + database. Use :kotlin-sync-sdk:`initialSubscriptions + ` + to define the initial subscription set when you first open the database file. + Pass the query you wish to subscribe to and a name for the subscription to + the :kotlin-sync-sdk:`add() + ` function. + +The example below specifies a subscription named "User's Items" with +all ``Item`` objects. diff --git a/source/includes/api-details/swift/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/swift/quick-start/quick-start-close-database-description.rst new file mode 100644 index 0000000000..1a308b0fd6 --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-close-database-description.rst @@ -0,0 +1,5 @@ +Unlike the other SDKs, there is no need to manually close a database in Swift +or Objective-C. When a database goes out of scope and is removed from memory +due to `ARC +`__, +the database is automatically closed. diff --git a/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst new file mode 100644 index 0000000000..3403e894d7 --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,2 @@ +In this quick start, you can remove ``ownerId`` unless you want to add the +optional Device Sync. diff --git a/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst new file mode 100644 index 0000000000..ca02e49c45 --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,7 @@ +.. seealso:: + + If your app uses SwiftUI, check out the :ref:`SwiftUI Quick Start + `. + +Near the top of any Swift file that uses the SDK, add the following import +statement: diff --git a/source/includes/api-details/swift/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/swift/quick-start/quick-start-open-database-description.rst new file mode 100644 index 0000000000..4d159e67b1 --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,7 @@ +In a non-synced database, the simplest option to open the database +is to use the default database with no configuration parameter, as shown in +the example below. + +You can also specify a :swift-sdk:`Realm.Configuration ` +parameter to open a database at a specific file URL, in-memory, or with a +subset of classes. diff --git a/source/includes/api-details/swift/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/swift/quick-start/quick-start-open-synced-database-description.rst new file mode 100644 index 0000000000..6908fc9525 --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-open-synced-database-description.rst @@ -0,0 +1,7 @@ +Once you have enabled Device Sync and authenticated a user, you can create +a :swift-sdk:`Configuration ` object and +open the database. You can then add a the Sync subscription that determines +what data the database can read and write. + +Once you have a database with a subscription, this example passes the database +and the user to another function where you can use the database. diff --git a/source/includes/dotnet-implement-interface.rst b/source/includes/dotnet-implement-interface.rst index 1b59486362..a7cba41021 100644 --- a/source/includes/dotnet-implement-interface.rst +++ b/source/includes/dotnet-implement-interface.rst @@ -1,6 +1,6 @@ .. important:: Inheritance - All Realm objects inherit from the + All SDK objects inherit from the :dotnet-sdk:`IRealmObject `, :dotnet-sdk:`IEmbeddedObject `, or :dotnet-sdk:`IAsymmetricObject ` @@ -10,9 +10,9 @@ :dotnet-sdk:`RealmObject `, :dotnet-sdk:`EmbeddedObject `, or :dotnet-sdk:`AsymmetricObject ` - base classes. This approach to Realm model definition is still supported, but + base classes. This approach to SDK model definition is still supported, but does not include new features such as the :ref:`nullability annotations - `. In a future SDK release, the + `. In a future SDK release, the base classes will become deprecated. You should use the interfaces for any new classes that you write and should consider migrating your existing classes. \ No newline at end of file diff --git a/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst b/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst new file mode 100644 index 0000000000..424ffbaeac --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.authenticate-user.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.anon-login.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.log-in.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.authenticate-a-user.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.authenticate-a-user.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-authenticate.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.authenticate-user.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.anonymous-login.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-close-database.rst b/source/includes/sdk-examples/quick-start/quick-start-close-database.rst new file mode 100644 index 0000000000..ae029c863e --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-close-database.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/close-realm.snippet.close-realm.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/OpenARealmExamples.snippet.dispose.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/open_realm_test.snippet.close-realm.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/OpenARealmTest.snippet.close-a-realm-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/OpenARealmTest.snippet.close-a-realm-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-close-realm.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.close-a-realm.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst new file mode 100644 index 0000000000..687e5c24e8 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.create-todo.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.create.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.create-realm-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.create-object-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.create-object-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-create.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.create-todo.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.create-modify-delete.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst b/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst new file mode 100644 index 0000000000..373524de0a --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst @@ -0,0 +1,67 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.model.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Task.snippet.item-model.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/car.snippet.define-model-dart.dart + :language: dart + :caption: car.dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/DefinitelyNotJavaTask.snippet.define-object-model-local.java + :language: java + :caption: Task.java + :copyable: false + + .. literalinclude:: /examples/generated/java/local/TaskStatus.snippet.define-object-model-local.java + :language: java + :caption: TaskStatus.java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.define-object-model-local.kt + :language: kotlin + :caption: Task.kt + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.define-an-object-model.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-model.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.model.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.define-an-object-model.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst new file mode 100644 index 0000000000..4a2a02b328 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.delete.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.delete-one-item.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.delete-one-realm-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.delete-object-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.delete-object-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-delete.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.delete.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst new file mode 100644 index 0000000000..c36ae764d1 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.filter.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.read-open-items.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.query-realm-objects-with-filter.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.filter-collection-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.filter-collection-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-read-filtered.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.filter.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst b/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst new file mode 100644 index 0000000000..43b786a7ae --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.include-header.cpp + :language: cpp + + - id: csharp + content: | + + .. code-block:: csharp + + using Realms; + + - id: dart + content: | + + .. code-block:: dart + + import 'package:realm_dart/realm.dart'; + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-realm.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-realm.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.import-realm.ts + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/LocalOnlyCompleteQuickStart.snippet.import-realmswift.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.import-realm.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst b/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst new file mode 100644 index 0000000000..646995ae5d --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.connect-to-backend.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.initialize-realm.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.init-app.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-the-app.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-the-app.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-initialize-app.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.connect-to-backend.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.initialize.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-open-database.rst b/source/includes/sdk-examples/quick-start/quick-start-open-database.rst new file mode 100644 index 0000000000..d265adfd88 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-open-database.rst @@ -0,0 +1,57 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.realm-open.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Program.snippet.get-instance.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/open_realm_test.snippet.open-realm.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.open-a-realm-local.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.open-a-realm-local.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.open-a-realm.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-open-a-local-realm.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/LocalOnlyCompleteQuickStart.snippet.quick-start-local-open-realm-without-config-param.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.open-a-realm.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst b/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst new file mode 100644 index 0000000000..0227944da9 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.open-synced-realm.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.bootstrap-a-subscription.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.add-sync-subscription.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.open-a-realm.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.open-a-realm.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.open-realm-with-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-open-a-synced-realm.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.open-synced-realm.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.open-realm-with-subscriptions.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst b/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst new file mode 100644 index 0000000000..127475148c --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.watch-for-changes.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.notifications.cs + :language: csharp + :emphasize-lines: 2 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.watch-for-changes-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.watch-for-changes-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.watch-a-collection.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-watch-for-changes.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/LocalOnlyCompleteQuickStart.snippet.quick-start-local-set-notification-token.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.watch-a-collection.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst new file mode 100644 index 0000000000..3a66747d86 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.get-all-todos.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.read-all.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.query-all-realm-objects.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.read-object-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.read-object-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-read.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.get-all-todos.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/quickstart.snippet.find-sort-and-filter-objects.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst b/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst new file mode 100644 index 0000000000..f6639b7df1 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.modify-write-block.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.upsert.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.update-realm-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.update-object-local.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.update-object-local.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-update.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/QuickStartFlexSync.snippet.modify-write-block.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst b/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst new file mode 100644 index 0000000000..5a705fa8a1 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst @@ -0,0 +1,56 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.write-to-synced-realm.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sync-memory-performance.rst b/source/includes/sync-memory-performance.rst index 46b66c19be..b8129679ee 100644 --- a/source/includes/sync-memory-performance.rst +++ b/source/includes/sync-memory-performance.rst @@ -1,5 +1,5 @@ Every write transaction for a subscription set has a performance cost. If you -need to make multiple updates to a Realm object during a session, consider +need to make multiple updates to a database object during a session, consider keeping edited objects in memory until all changes are complete. This -improves sync performance by only writing the complete and updated object to your -realm instead of every change. \ No newline at end of file +improves sync performance by only writing the complete and updated object to +your database instead of every change. diff --git a/source/sdk/crud/query-engines.txt b/source/sdk/crud/query-engines.txt index e03c337c8d..4339163c25 100644 --- a/source/sdk/crud/query-engines.txt +++ b/source/sdk/crud/query-engines.txt @@ -1,5 +1,3 @@ -.. _sdks-query-engines: - ============= Query Engines ============= diff --git a/source/sdk/crud/read.txt b/source/sdk/crud/read.txt index c8686404fc..de16c41b6f 100644 --- a/source/sdk/crud/read.txt +++ b/source/sdk/crud/read.txt @@ -19,3 +19,25 @@ Read Objects :class: singlecol Placeholder page for content related to reading realm objects. + +.. _sdks-read-results: + +SDK Results Collections +----------------------- + +Placeholder. Add some concept information about results being a special SDK +auto-updating collection type for read operations (except in Kotlin, where it's +frozen). + +.. _sdks-query-engines: + +Filter Data +----------- + +Placeholder. Add some concept information about the SDK having query engines, +and the one you use varying depending on the SDK you're using. i.e.: + +- RQL (C++ (subset only), C#, Dart, JS, Kotlin, TS, maybe also Java/Java Kotlin?) +- LINQ (C#) +- Swift SDK (Swift & Objective-C Type-Safe queries and NS Predicate queries) +- Java (Java & Kotlin, Fluent Interface) diff --git a/source/sdk/crud/threading.txt b/source/sdk/crud/threading.txt index e88063645a..2bf6b1d9e1 100644 --- a/source/sdk/crud/threading.txt +++ b/source/sdk/crud/threading.txt @@ -16,3 +16,8 @@ Threading :backlinks: none :depth: 2 :class: singlecol + +.. _sdks-modify-frozen-object: + +Update a Frozen Object +~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index a25708ff63..1de0ac8170 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -10,10 +10,15 @@ Define an SDK Object Model :depth: 3 :class: singlecol +.. _sdks-define-object-schema: + +Define an SDK Object Schema +--------------------------- + .. _sdks-define-objects: -Define an SDK Object --------------------- +Define an SDK Object Model +-------------------------- Placeholder page for defining an object model. @@ -45,3 +50,8 @@ Define Special Property Types Define a Full-Text Search Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-required-optional-property: + +Placeholder for .NET nullability info, and any other SDKs with similar +APIs/requirements diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 9cc61012de..74cc4b96ed 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -4,10 +4,480 @@ Quick Start =========== +.. meta:: + :description: Learn how to quickly get started with Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -Placeholder page for quick start content. +.. tabs-selector:: drivers + +This Quick Start demonstrates how to use Atlas Device SDK. +Before you begin, ensure you have :ref:`Installed the SDK `. + +Import the SDK +--------------- + +.. tip:: + + Atlas Device SDK was previously named Realm. The SDK library names still + reflect Realm naming. To import the SDK, you import Realm. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-import-realm-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/quick-start/quick-start-import-realm-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-import-realm-js-ts-description.rst + +.. include:: /includes/sdk-examples/quick-start/quick-start-import-realm.rst + +Define Your Object Model +------------------------ + +For a non-synced database, you can define your :ref:`object model +` directly in code. For a synced database, your client +object models require a matching schema in Atlas. For more details, refer to +:ref:`sdks-model-data-device-sync`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/quick-start/quick-start-define-your-object-model-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-define-your-object-model-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/quick-start/quick-start-define-your-object-model-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-define-your-object-model-js-ts-description.rst + +.. include:: /includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst + +Open a Database +--------------- + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-open-database-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/quick-start/quick-start-open-database-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-open-database-js-ts-description.rst + +.. include:: /includes/sdk-examples/quick-start/quick-start-open-database.rst + +For more information, refer to :ref:`sdks-configure-and-open-database`. + +Create, Read, Update, and Delete Objects +---------------------------------------- + +Once you have opened a database, you can modify it and its objects in a +:ref:`write transaction ` block. + +Create +~~~~~~ + +To instantiate a new object and add it to the database in a write block: + +.. include:: /includes/sdk-examples/quick-start/quick-start-create-objects.rst + +For more information about creating objects, refer to :ref:`sdks-crud-create`. + +Read and Filter +~~~~~~~~~~~~~~~ + +You can retrieve a :ref:`results collection ` of +all objects of a given type in the database: + +.. include:: /includes/sdk-examples/quick-start/quick-start-read-objects.rst + +For more information about reading objects, refer to :ref:`sdks-crud-read`. + +You can also filter that collection: + +.. include:: /includes/sdk-examples/quick-start/quick-start-filter-objects.rst + +For more information about the SDK query engines, refer to +:ref:`sdks-query-engines`. + +Update +~~~~~~ + +To modify an object, update its properties in a write transaction block: + +.. include:: /includes/sdk-examples/quick-start/quick-start-update-object-properties.rst + +For more information about updating objects, refer to :ref:`sdks-crud-update`. + +Delete +~~~~~~ + +Finally, you can delete an object: + +.. include:: /includes/sdk-examples/quick-start/quick-start-delete-objects.rst + +For more information about deleting objects, refer to :ref:`sdks-crud-delete`. + +Watch for Changes +----------------- + +You can watch a database, a collection, or an object for changes: + +.. include:: /includes/sdk-examples/quick-start/quick-start-react-to-changes.rst + +For more information about reacting to changes, including details about +unregistering the listener to stop watching and free up resources, refer to +:ref:`sdks-react-to-changes`. + +Close a Database +---------------- + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-close-database-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/quick-start/quick-start-close-database-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-close-database-js-ts-description.rst + +.. include:: /includes/sdk-examples/quick-start/quick-start-close-database.rst + +Add Device Sync +--------------- + +If you want to sync data across devices, you can enable Device Sync in Atlas. +For more information on Device Sync, refer to :ref:`sync`. + +Prerequisites +~~~~~~~~~~~~~ + +Before you can sync device data, you must: + +- :ref:`Create an App Services App ` +- :ref:`Enable anonymous authentication ` +- :ref:`Enable Device Sync ` with :ref:`Development Mode + ` toggled to ``On``. +- :ref:`Define the rules ` that determine which + permissions users have when using Device Sync. + +.. _cpp-quick-start-init-app: + +Initialize the App +~~~~~~~~~~~~~~~~~~ + +The SDK uses an ``App`` to connect to Atlas, manage users, and report certain +types of errors. Initialize the ``App`` connection. + +.. include:: /includes/access-app-id.rst + +.. include:: /includes/sdk-examples/quick-start/quick-start-initialize-app.rst + +For more details about configuring and initializing the App connection, refer +to :ref:`sdks-connect-to-atlas`. + +.. _cpp-quick-start-authenticate: + +Authenticate a User +~~~~~~~~~~~~~~~~~~~ + +In this quick start, you use :ref:`anonymous authentication ` +to log in users without requiring them to provide any identifying information. +After authenticating the user, you can open a database for that user. + +.. include:: /includes/sdk-examples/quick-start/quick-start-authenticate-user.rst + +The SDK provides many additional ways to authenticate, register, and link +users. For other authentication providers, refer to +:ref:`sdks-authenticate-users`. + +Open a Synced Database +~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-open-synced-database-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/quick-start/quick-start-open-synced-database-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/quick-start/quick-start-open-synced-database-js-ts-description.rst + +.. include:: /includes/sdk-examples/quick-start/quick-start-open-synced-database.rst + +For more details about opening a synced database, refer to +:ref:`sdks-configure-and-open-synced-database`. + +For more details about Sync subscriptions, refer to +:ref:`sdks-manage-sync-subscriptions`. + +Read, Write, and React to Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The syntax to :ref:`read `, :ref:`write +`, and :ref:`watch for changes ` +on a synced database is identical to the syntax for non-synced databases above. + +The only difference here is the addition of a property that we can use to +find the user's todos and set Sync permissions. We query for only the user's +todos in the subscription, and set Sync permissions to +:guilabel:`Users can only read and write their own data`. + +For more information about Sync permissions, refer to :ref:`sync-permissions`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/quick-start/quick-start-write-to-synced-db.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + +.. include:: /includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst + +While you work with local data, a background thread efficiently integrates, +uploads, and downloads changesets. + +.. include:: /includes/sync-memory-performance.rst + +Next: Check out the Template Apps and Tutorial +---------------------------------------------- + +Check out the :ref:`template apps ` to experiment with another +quick way to start coding with Atlas Device SDK. Each SDK has an application +that integrates Atlas Device SDK and Atlas Device Sync in a platform-idiomatic +todo app. + +If you're more interested in a guided experience, you can read our +:ref:`Device Sync tutorials ` to learn how to expand +on the template app. + +Finally, if you'd like to browse example applications for specific use cases, +check out our list of curated :ref:`realm-examples`. From 6369ee1e4b8fc7610cda27a5b6b2555cbd3fed5b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 12:59:55 -0400 Subject: [PATCH 02/18] Fix snooty build error --- .../quick-start/quick-start-open-database-description.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst index 36ddeb1573..2a137fca7b 100644 --- a/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst +++ b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst @@ -5,8 +5,8 @@ to open a database using default parameters. Pass your configuration to the :kotlin-sdk:`factory constructor ` to generate an instance of that database. -For more information on how to control the specifics of the +For more information on how to define the specifics of the :kotlin-sdk:`RealmConfiguration ` you would like to open (e.g. name, location, schema version), refer to -:ref:`sdks-sdks-configure-and-open-database`. +:ref:`sdks-configure-and-open-database`. From 1c5d85f4f0589886ab90b837d5da40abd9881388 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 13:57:38 -0400 Subject: [PATCH 03/18] Add Flutter quick start details --- source/frameworks/flutter/quick-start.txt | 103 +++++++++++++++++- source/frameworks/swiftui/quick-start.txt | 2 +- ...art-define-your-object-model-procedure.rst | 38 +++---- .../quick-start-import-realm-description.rst | 2 +- source/sdk/quick-start.txt | 2 + 5 files changed, 124 insertions(+), 23 deletions(-) diff --git a/source/frameworks/flutter/quick-start.txt b/source/frameworks/flutter/quick-start.txt index 646599638f..35f6866104 100644 --- a/source/frameworks/flutter/quick-start.txt +++ b/source/frameworks/flutter/quick-start.txt @@ -4,5 +4,106 @@ Quick Start with Flutter ======================== -Placeholder page for a Flutter quick start. +.. meta:: + :description: Learn how to use Atlas Device SDK with Flutter. + :keywords: Realm, Flutter, Flutter SDK, code example +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: dart + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This Quick Start demonstrates how to use Atlas Device SDK with Flutter. + +.. tip:: Standalone Dart or Flutter Project? + + This quick start contains information for using the SDK with a Flutter + project. The package that you import, and the way you create object + models, differs if you are using the SDK in a standalone Dart project. For + a quick start using a standalone Dart project, refer to + :ref:`sdks-quick-start`. + +Install the SDK +--------------- + +Install the ``realm`` package for use in Flutter applications. For more +information about installing the SDK in a Flutter project, refer to +:ref:`sdks-install`. + +Import the SDK +-------------- + +Import the package into any files where you use it. + +.. code-block:: dart + :caption: ExampleFile.dart + + import 'package:realm/realm.dart'; + +Define Your Object Model +------------------------ + +Your application's **data model** defines the structure of data stored within +the database. You can define your application's data model via Dart +classes in your application code with an SDK object schema. +You then have to generate the :flutter-sdk:`RealmObjectBase ` +class that's used within your application. + +For more information, refer to :ref:`Define an Object Schema +`. + +.. procedure:: + + .. step:: Create a Model Class + + Add an SDK model class. Give your class a private name + (starting with ``_``), such as a file ``car.dart`` with a class + ``_Car``. + + .. literalinclude:: /examples/generated/flutter/car.snippet.define-model-flutter.dart + :language: dart + :caption: car.dart + + .. step:: Generate an SDK Object Class + + Generate a RealmObject class ``Car`` from the data model class ``_Car``: + + .. code-block:: + + dart run realm generate + + Running this creates a ``Car`` class in a ``car.realm.dart`` file + located in the directory where you defined the model class. This ``Car`` + class is public and part of the same library as the ``_Car`` data model + class. The generated ``Car`` class is what's used throughout your + application. + + .. step:: Watch for Changes to the Model (Optional) + + You can watch your data model class to generate a new ``Car`` class + whenever there's a change to ``_Car``: + + .. code-block:: + + dart run realm generate --watch + +Perform CRUD Operations and More +-------------------------------- + +Installing the library and the commands to generate the models are specific +to using the SDK with a Flutter project or a standalone Dart project. But +all the other operations, from reading and writing data to syncing data across +devices, are the same for a Flutter or standalone Dart project. + +To learn more about performing these operations, refer to the main Quick Start. +Shared content starts with the :ref:`Open a Database ` +section. diff --git a/source/frameworks/swiftui/quick-start.txt b/source/frameworks/swiftui/quick-start.txt index f1b669b048..825d2922d7 100644 --- a/source/frameworks/swiftui/quick-start.txt +++ b/source/frameworks/swiftui/quick-start.txt @@ -7,7 +7,7 @@ SwiftUI QuickStart .. meta:: :description: Learn how to use Atlas Device SDK with SwiftUI property wrappers. - :keywords: code example + :keywords: Realm, Swift SDK, code example .. facet:: :name: genre diff --git a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst index 3330e40f85..4670261981 100644 --- a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst +++ b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst @@ -7,33 +7,31 @@ class that's used within your application. For more information, refer to :ref:`Define an Object Schema `. -.. procedure:: +**Create a Model Class** - .. step:: Create a Model Class +Add an SDK model class. Give your class a private name +(starting with ``_``), such as a file ``car.dart`` with a class +``_Car``. - Add an SDK model class. Give your class a private name - (starting with ``_``), such as a file ``car.dart`` with a class - ``_Car``. +**Generate an SDK Object Class** - .. step:: Generate an SDK Object Class +Generate a RealmObject class ``Car`` from the data model class ``_Car``: - Generate a RealmObject class ``Car`` from the data model class ``_Car``: +.. code-block:: - .. code-block:: + dart run realm_dart generate - dart run realm_dart generate +Running this creates a ``Car`` class in a ``car.realm.dart`` file +located in the directory where you defined the model class. This ``Car`` +class is public and part of the same library as the ``_Car`` data model +class. The generated ``Car`` class is what's used throughout your +application. - Running this creates a ``Car`` class in a ``car.realm.dart`` file - located in the directory where you defined the model class. This ``Car`` - class is public and part of the same library as the ``_Car`` data model - class. The generated ``Car`` class is what's used throughout your - application. +*Watch for Changes to the Model (Optional)* - .. step:: Watch for Changes to the Model (Optional) +You can watch your data model class to generate a new ``Car`` class +whenever there's a change to ``_Car``: - You can watch your data model class to generate a new ``Car`` class - whenever there's a change to ``_Car``: +.. code-block:: - .. code-block:: - - dart run realm_dart generate --watch + dart run realm_dart generate --watch diff --git a/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst index 42f74ae257..2647da5586 100644 --- a/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst +++ b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst @@ -4,5 +4,5 @@ Import the package into any files where you use it. This quick start contains information for using the SDK with a standalone Dart project. The package that you import, and the way you create object - models, differ if you are using the SDK in a Flutter project. For a quick + models, differs if you are using the SDK in a Flutter project. For a quick start using Flutter, refer to :ref:`frameworks-flutter-quick-start`. diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 74cc4b96ed..39a2a9f18b 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -141,6 +141,8 @@ object models require a matching schema in Atlas. For more details, refer to .. include:: /includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst +.. _sdks-quick-start-open-database: + Open a Database --------------- From 47a7c8e24e6533dd8c610961884a236c93a209d8 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 14:50:47 -0400 Subject: [PATCH 04/18] Minor fixes --- .../quick-start/quick-start-open-database-description.rst | 8 +++----- source/sdk/quick-start.txt | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst index 2a137fca7b..601c9407c7 100644 --- a/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst +++ b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst @@ -5,8 +5,6 @@ to open a database using default parameters. Pass your configuration to the :kotlin-sdk:`factory constructor ` to generate an instance of that database. -For more information on how to define the specifics of the -:kotlin-sdk:`RealmConfiguration -` -you would like to open (e.g. name, location, schema version), refer to -:ref:`sdks-configure-and-open-database`. +You can optionally define additional :kotlin-sdk:`RealmConfiguration +` details, such as name, +location, schema version, and more. diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 39a2a9f18b..1d67d605bb 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -326,7 +326,7 @@ Before you can sync device data, you must: - :ref:`Enable Device Sync ` with :ref:`Development Mode ` toggled to ``On``. - :ref:`Define the rules ` that determine which - permissions users have when using Device Sync. + permissions users have when using Device Sync. .. _cpp-quick-start-init-app: From 2c7eda4bd631c9e7484c3e6b4f0a9b1d280d159f Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 14:52:32 -0400 Subject: [PATCH 05/18] Minor fix on SwiftUI Quick Start page --- source/frameworks/swiftui/quick-start.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/frameworks/swiftui/quick-start.txt b/source/frameworks/swiftui/quick-start.txt index 825d2922d7..15fc15b0af 100644 --- a/source/frameworks/swiftui/quick-start.txt +++ b/source/frameworks/swiftui/quick-start.txt @@ -26,7 +26,7 @@ SwiftUI QuickStart Prerequisites ------------- -- :ref:`Install the Swift SDK. `. +- :ref:`Install the Swift SDK. ` - Meet the minimum Xcode and iOS targets required by the Swift SDK version. - Create a new Xcode project using the SwiftUI "App" template. From 82dc27b7087514a2bfa187da15f0a12037d00f10 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 15:27:57 -0400 Subject: [PATCH 06/18] Port the Unity quick start over to the consolidated docs --- ...rary-name-reflects-former-realm-naming.rst | 4 + source/platforms.txt | 2 + source/platforms/unity-quick-start.txt | 277 ++++++++++++++++++ source/sdk/quick-start.txt | 5 +- templates/consolidated-page.rst | 2 +- 5 files changed, 285 insertions(+), 5 deletions(-) create mode 100644 source/includes/tip-library-name-reflects-former-realm-naming.rst create mode 100644 source/platforms/unity-quick-start.txt diff --git a/source/includes/tip-library-name-reflects-former-realm-naming.rst b/source/includes/tip-library-name-reflects-former-realm-naming.rst new file mode 100644 index 0000000000..f439d080fe --- /dev/null +++ b/source/includes/tip-library-name-reflects-former-realm-naming.rst @@ -0,0 +1,4 @@ +.. tip:: + + Atlas Device SDK was previously named Realm. The SDK library names still + reflect Realm naming. To import the SDK, you import Realm. diff --git a/source/platforms.txt b/source/platforms.txt index e7e415ab08..8da0a2109c 100644 --- a/source/platforms.txt +++ b/source/platforms.txt @@ -17,6 +17,7 @@ Build for Platforms Apple IoT Linux + Unity Web Windows @@ -27,5 +28,6 @@ with Atlas Device SDK: - :ref:`sdks-build-for-apple` - :ref:`sdks-build-for-iot` - :ref:`sdks-build-for-linux` +- :ref:`dotnet-unity` - :ref:`sdks-build-for-web` - :ref:`sdks-build-for-windows` diff --git a/source/platforms/unity-quick-start.txt b/source/platforms/unity-quick-start.txt new file mode 100644 index 0000000000..59fb7a3929 --- /dev/null +++ b/source/platforms/unity-quick-start.txt @@ -0,0 +1,277 @@ +.. _dotnet-unity: + +================================ +Quick Start for Unity - .NET SDK +================================ + +.. meta:: + :description: Learn how to build a Unity project with Atlas Device SDK syncing data across devices. + :keywords: Realm, .NET SDK, code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: csharp + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page contains information on how to install and integrate Atlas Device SDK +for .NET into your Unity project. + +Prerequisites +------------- + +- Create a Unity project using `2020.3.12f1 (LTS) `_ + +.. note:: + + The .NET SDK may be compatible + with other versions of Unity, but ``2020.3.12f1 (LTS)`` is the version that + the SDK team uses for testing and development. We recommend + using this version to ensure your project works with the SDK and + that the install steps match the steps below since Unity's UI often changes + between versions. + +.. _unity-install-realm: + +Install the SDK +--------------- + +You could install the SDK manually with a tarball. However, we recommend +installing the .NET SDK through npm since it provides `notifications of version +updates through Unity's package manager +`_. + +.. tabs:: + + .. tab:: Install with NPM + :tabid: npm + + .. procedure:: + + .. step:: Add NPM as a Scoped Registry + + + Before you can download and use the sDK within your Unity project, you + must add :npm:`NPM <>` as a `scoped registry + `_. Adding NPM as a scoped + registry configures Unity to communicate with NPM, allowing you to install + packages, such as the .NET SDK. + + Open the `Unity package manager + `_ by clicking the + :guilabel:`Window` tab on the top of the Unity menu. Click :guilabel:`Package + Manager` from the :guilabel:`Window dropdown`. Then, click the gear icon on + the right-hand corner. Select the :guilabel:`Advanced Project + Settings` option from the dropdown. + + .. figure:: /images/unity-open-advanced-project-settings.png + :alt: Select "Advanced Project Settings" + + Fill out the scoped registry form with the details below and click the save + button. + + .. code-block:: none + + name = NPM + URL = https://registry.npmjs.org + Scope(s) = io.realm.unity + + .. figure:: /images/unity-add-scoped-registry-form.png + :alt: Download the latest release of the .NET SDK + + + .. step:: Add the SDK to the Project Manifest + + + Now that Unity can install the .NET SDK from NPM, you need + to add the SDK as a dependency in your project's `manifest file + `_. Open + "Packages/manifest.json" file in `Visual Studio + `_ or another text editor. At + the bottom of the dependency's object, add the field, "io.realm.unity" and + its value, the .NET SDK version number you want to use in quotes. + + .. code-block:: none + + "io.realm.unity": "" + + Remember to replace the ```` above with the actual version + number. You can find the latest release version at the + `realm-dotnet GitHub repo `__. + Your full manifest file should look something like the following: + + .. code-block:: none + + { + "dependencies": { + ... + "io.realm.unity": "10.21.0" + }, + "scopedRegistries": [ + { + "name": "NPM", + "url": "https://registry.npmjs.org/", + "scopes": [ + "io.realm.unity" + ] + } + ] + } + + When you save this file, Unity downloads the specified version of + the .NET SDK package from the NPM registry. + + .. step:: Verify the SDK Dependency and Check for Updates + + To verify that the SDK package has been downloaded from NPM, + open your Unity package manager by clicking the :guilabel:`Window` tab on the + top of the Unity menu. Click :guilabel:`Package Manager` from the + :guilabel:`Window` dropdown. You should see the SDK on the :guilabel:`"Packages: In + Project"` tab. + + .. figure:: /images/unity-realm-is-installed.png + :alt: Unity Realm Installed + + If you see a green check icon next to the version number of the + SDK package, that means your package is up-to-date. However, if + you see the up arrow icon, a new version of the package is available. Clicking + it gives you the option to upgrade to the latest release. + + + .. tab:: Manually Install a Tarball + :tabid: tarball + + .. procedure:: + + .. step:: Download the Latest .NET SDK Release + + + Before you begin using within your Unity project, you must + download the .NET SDK. + + Navigate to the :github:`realm-dotnet repository releases + ` page, and scroll down to the release you want + to use in your project. If you are unsure of which release to use, you can use + the one labeled **"latest release"** on the left row. + + .. figure:: /images/unity-find-latest-dotnet-release.png + :alt: Find the latest release of the .NET SDK + + Scroll down to the **"Assets"** dropdown of the release and click the link + labeled **"io.realm.unity-.tgz"** to download the SDK. + + .. figure:: /images/unity-download-tgz.png + :alt: Download the latest release of the .NET SDK + + + .. step:: Add the Tarball to Your Projects Package Manager + + + Move your downloaded .NET SDK tarball inside of your + project. You can do this by dragging and dropping the file into your project's + folder. Copying the tarball to your project folder and committing it to version + control ensures other developers working on the project can just clone the + repository and build without manually downloading the SDK dependency. + + Next, you must load the tarball into your project using the `Unity package manager + `_. + + To open the package manager, click the :guilabel:`Window` tab on the top of + the Unity menu. Click :guilabel:`Package Manager` from the :guilabel:`Window + dropdown`. Once the package manager model opens, click the :guilabel:`+` icon + in the top left corner of the model. Select the :guilabel:`Add package from + tarball...` option. + + .. figure:: /images/add-package-from-tar-unity.png + :alt: Add package from tarball Unity UI + + Select your **"io.realm.unity-bundled-.tgz"** file to + begin importing your project. + +.. _unity-integration-guide-import-realm: + +Import the SDK +-------------- + +.. include:: /includes/tip-library-name-reflects-former-realm-naming.rst + +`Create a C# script +`_ or use a C# +script you have already created. Open that script in `Visual Studio +`_ or another text editor and add +the following line to import your SDK package: + +.. code-block:: csharp + + using Realms; + +.. _unity-integration-guide-using-realm-in-project: + +Using the SDK in Your Unity Project +----------------------------------- + +When developing with .NET SDK, the API +methods are the same regardless of whether you use Unity or another platform. +However, since Unity has some `scripting restrictions +`_, you should keep +the following additional considerations in mind when developing your project: + +Managed Code Stripping +~~~~~~~~~~~~~~~~~~~~~~ + +Unity performs `managed code stripping `_, +discarding any unused code from a build to reduce binary size. This may lead to issues when +deserializing :manual:`BSON ` into C# classes. For platforms +that use `IL2CPP `_, such as iOS, +managed code stripping is enabled by default. When working with BSON, use +the `[Preserve] attribute `_ +to prevent managed code stripping on types properties that are only populated by +the serializer. Since those properties use +`reflection `_, +Unity cannot statically infer that the property setter is used. This means that +unless you apply the ``[Preserve] attribute``, Unity will strip those properties +away. For examples of when you may perform BSON deserialization, check out the +:ref:`Access MongoDB ` and :ref:`Call a Function +` documentation. + +Using the SDK While the Application is Quitting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The .NET SDK cannot be accessed within the +`AppDomain.DomainUnload Event `_ or +the `Application.quitting `_ event. +This means you cannot write data to a database while the player application is quitting. +If you need to store some data just before the app exits, consider using the +`Application.wantsToQuit `_ +event instead. + +.. note:: Known Issue When Developing With Unity on Windows + + On Windows, if you are using Device Sync, your project may crash when running + multiple instances of your project since multiple processes are attempting to + access the same synced database. If you are using a non-synced database, + you are able to run multiple instances of your project without crashes. + +Additional Examples +------------------- + +The community has created many projects that demonstrate the usage +of the .NET SDK. Check out the examples below that demonstrate the usage +of the .NET SDK with Unity! + +.. note:: + + The MongoDB Documentation team does not directly maintain these examples. + +- `MongoDB Devhub: Unity with Realm Articles `_ +- `MongoDB Youtube Channel: Getting Started with the SDK for Unity `_ +- `MongoDB Youtube Channel: Build an Infinite Runner Game with Unity and the SDK `_ +- `dodoTV42 Youtube Channel: How to SAVE and LOAD data in Unity3D with the SDK `_ diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 1d67d605bb..b6ba562581 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -30,10 +30,7 @@ Before you begin, ensure you have :ref:`Installed the SDK `. Import the SDK --------------- -.. tip:: - - Atlas Device SDK was previously named Realm. The SDK library names still - reflect Realm naming. To import the SDK, you import Realm. +.. include:: /includes/tip-library-name-reflects-former-realm-naming.rst .. tabs-drivers:: diff --git a/templates/consolidated-page.rst b/templates/consolidated-page.rst index 3fb572f40a..2c5d93510a 100644 --- a/templates/consolidated-page.rst +++ b/templates/consolidated-page.rst @@ -6,7 +6,7 @@ Page Title .. meta:: :description: Provide a short description of the consolidated page. This is critical for SEO. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre From 1d058bb105687585e0f42835910330b5a5516abb Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 15:30:25 -0400 Subject: [PATCH 07/18] Rename file --- source/platforms/{unity-quick-start.txt => unity.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/platforms/{unity-quick-start.txt => unity.txt} (100%) diff --git a/source/platforms/unity-quick-start.txt b/source/platforms/unity.txt similarity index 100% rename from source/platforms/unity-quick-start.txt rename to source/platforms/unity.txt From e2cfc8736541cd9648ec7fea827bed8b5a87c213 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 15:31:57 -0400 Subject: [PATCH 08/18] Reduce Unity quick start page depth due to tab OTP issues --- source/platforms/unity.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/platforms/unity.txt b/source/platforms/unity.txt index 59fb7a3929..bf2adacc08 100644 --- a/source/platforms/unity.txt +++ b/source/platforms/unity.txt @@ -19,7 +19,7 @@ Quick Start for Unity - .NET SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 1 :class: singlecol This page contains information on how to install and integrate Atlas Device SDK From 69423693b41bd4f4bcb88624e77b96eb8c602c1c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 30 May 2024 15:40:48 -0400 Subject: [PATCH 09/18] Port LiveData quick start to Android section --- source/platforms/android.txt | 5 + .../android/livedata-quick-start.txt | 260 ++++++++++++++++++ 2 files changed, 265 insertions(+) create mode 100644 source/platforms/android/livedata-quick-start.txt diff --git a/source/platforms/android.txt b/source/platforms/android.txt index 07e511aebf..6e5e5c2db5 100644 --- a/source/platforms/android.txt +++ b/source/platforms/android.txt @@ -4,6 +4,11 @@ Build for Android ================= +.. toctree:: + :titlesonly: + + Quick Start with Live Data + .. contents:: On this page :local: :backlinks: none diff --git a/source/platforms/android/livedata-quick-start.txt b/source/platforms/android/livedata-quick-start.txt new file mode 100644 index 0000000000..55a7b438f0 --- /dev/null +++ b/source/platforms/android/livedata-quick-start.txt @@ -0,0 +1,260 @@ +.. _java-livedata-quick-start: + +==================================== +Quick Start with LiveData - Java SDK +==================================== + +.. meta:: + :description: Learn how to use Atlas Device SDK for Java with Android LiveData. + :keywords: Realm, Java SDK, code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page contains instructions to quickly get Atlas Device SDK for Java +integrated into an example Android application that uses :android:`LiveData +`. This example application +allows a user to increment a counter using a button. + +Prerequisites +------------- + +This quick start guide uses :ref:`Sync ` to synchronize data +changes between clients. Before you begin, ensure you have: + +- :ref:`Installed the Java SDK `. +- :ref:`Created an App `. +- :ref:`Enabled anonymous authentication `. +- :ref:`Enabled Sync `. + +.. note:: Using LiveData without Sync + + To use this quick start without Sync, disable the sync features + in the SDK. You can do this by removing the following lines from your + app-level :file:`build.gradle` file: + + .. code-block:: gradle + + realm { + syncEnabled = true + } + + After removing the lines, re-synchronize the Gradle configuration to + reload the Java SDK in an offline-only state. Remove the lines + related to importing and using Sync Configuration, user login, and + partition values from the ``CounterModel`` file to use the Java SDK + without Sync. + +Clone the LiveData Quick Start Repository +----------------------------------------- + +To get started, copy the `example repo +`__ +into your local environment. + +We've already put together an Android application that has +most of the code you'll need. You can clone the client application +repository directly from GitHub: + +.. code-block:: console + + git clone https://github.com/mongodb-university/realm-android-livedata.git + +The repository contains two branches: +``final`` and ``start``. The ``final`` branch is a finished version +of the app as it should look *after* you complete this tutorial. +To walk through this tutorial, please check out the ``start`` +branch: + +.. code-block:: console + + git checkout start + +Import Dependencies +------------------- + +Now that you've cloned the repo, you need to add the dependencies you'll +need to run the Java SDK and Android LiveData. Begin by adding +the Java SDK dependency to the ``buildscript.dependencies`` +block of your project level :file:`build.gradle` file: + +.. literalinclude:: /examples/generated/java/sync/build.snippet.realm-dependency.gradle + :language: gradle + :emphasize-lines: 10 + :copyable: false + +You'll also have to add the Android LiveData Dependency to the +``dependencies`` block of your app level :file:`build.gradle` file: + +.. literalinclude:: /examples/generated/java/sync/build.snippet.livedata-dependency.gradle + :language: gradle + :emphasize-lines: 10 + :copyable: false + +Next, enable Sync in the SDK by creating the +following top-level block in your app level :file:`build.gradle` file: + +.. literalinclude:: /examples/generated/java/sync/build.snippet.sync-enable.gradle + :language: gradle + :copyable: false + +Then, enable DataBinding by creating the following block in the +``android`` block of your app level :file:`build.gradle` file: + +.. literalinclude:: /examples/generated/java/sync/build.snippet.databinding-enable.gradle + :language: gradle + :emphasize-lines: 15-17 + :copyable: false + +Finally, click the "Sync" button or select :guilabel:`Build > Rebuild Project` +in the application menu to reconfigure your Gradle configuration with +these changes and fetch the dependencies. + +LiveRealmObject +--------------- + +With all of the dependencies in place, it's time to create a +LiveData-compatible interface for our SDK objects. To do so, we'll +have to handle a few events: + +- The ``onActive()`` method enables an observer to subscribe to changes + to the underlying SDK object by adding a change listener. + + .. literalinclude:: /examples/generated/java/sync/LiveRealmObject.snippet.onactive.kt + :language: kotlin + :copyable: false + +- The ``onInactive()`` method enables an observer to unsubscribe to + changes to the underlying SDK object by removing the change listener. + + .. literalinclude:: /examples/generated/java/sync/LiveRealmObject.snippet.oninactive.kt + :language: kotlin + :copyable: false + +- When a change occurs, the ``listener`` member uses the ``setValue()`` + method of the ``LiveData`` parent class to pass the SDK object's + value to the UI unless the object was deleted, in which case the + change listener passes a value of ``null`` instead of passing along + a reference to an invalid, deleted object. + + .. literalinclude:: /examples/generated/java/sync/LiveRealmObject.snippet.listener.kt + :language: kotlin + :copyable: false + +.. seealso:: Using LiveData with ``RealmResults`` + + This example only uses LiveData to display ``RealmObjects`` in the UI. + For a sample implementation displaying ``RealmResults``, + see `LiveRealmResults `__. + +Instantiating LiveData in the ViewModel +--------------------------------------- + +This application stores all of its logic and core data within a ViewModel +called ``CounterModel``. When the application runs, it creates an instance +of ``CounterModel`` that is used until the application closes. That +instance contains the LiveData that displays on the UI of the application. +To create an instance of LiveData, we need to access a ``Counter`` object +stored in a database and pass it to the ``LiveRealmObject`` constructor. +To accomplish this: + +1. Connect to your App *with your* **App ID**. + +2. Authenticate a user. + +3. Connect to a specific database using Sync. + +4. Query the database for a ``Counter``, inserting a new ``Counter`` if + one hasn't already been created in this database. + +5. Instantiate a ``LiveRealmObject`` using the ``Counter`` instance and + store it in the ``counter`` member of ``CounterModel``. + +The following code snippet implements this behavior: + +.. literalinclude:: /examples/generated/java/sync/CounterModel.snippet.constructor.kt + :language: kotlin + +.. important:: Don't Read or Write on the UI Thread + + Database reads and writes are computationally expensive, so + the SDK disables reads and writes by default on the UI thread. + For simplicity, this example enables UI thread reads and writes with + the ``allowWritesOnUiThread()`` and ``allowQueriesOnUiThread()`` + config builder methods. In production applications, you should almost + always defer reads and writes to a background thread using + asynchronous methods. + +Connecting the ViewModel to the UI +---------------------------------- + +To display the data stored in the ``CounterModel`` on the application UI, +we'll need to access the ``CounterModel`` singleton using the +:android:`viewModels() ` +method when the application creates ``CounterFragment``. Once we've +instantiated the model, we can use the :android:`Android Data Binding +` library to display the model's +data in UI elements. + +To access the ``CounterModel`` singleton when the application creates +``CounterFragment``, place the following code in the ``onCreateView()`` +method of ``CounterFragment``: + +.. literalinclude:: /examples/generated/java/sync/CounterFragment.snippet.getcountermodel.kt + :language: kotlin + :copyable: false + +Next, set up the Data Binding hooks in the UI for the counter fragment: + +.. literalinclude:: /examples/generated/java/sync/counter_fragment.xml + :language: kotlin + :copyable: false + +Finally, connect the model to the binding so that the UI can display the +counter and iterate the counter on button press with the following code +in the ``onCreateView()`` method of ``CounterFragment``: + +.. literalinclude:: /examples/generated/java/sync/CounterFragment.snippet.binding.kt + :language: kotlin + :copyable: false + +Run the Application +------------------- + +Now you should be able to run the sample application. You should see an +interface that looks something like this: + +.. image:: /images/android-livedata-quickstart-app.png + :alt: The LiveData QuickStart Counter app. + +Clicking the "ADD" button should add one to the value of your counter. +With Sync, you can view your App logs to see individual increment +events. Android LiveData is lifecycle-aware, so rotating the screen or +freeing the application's state by clearing your device's RAM should +have no effect on the application state, which should seamlessly resume +and automatically resubscribe to events on resume using the state stored +in the model singleton and the encapsulated LiveData instance. + +Summary +------- + +- Use the the ``LiveRealmObject`` and ``LiveRealmResults`` classes as a template for encapsulating live SDK data in Android LiveData. +- Use a ViewModel to separate underlying data from the UI elements that display that data. +- DataBinding lets you declare relationships between model data and UI elements without explicitly setting values in an Activity or Fragment. + +Feedback +-------- + +Did you find this quick start guide helpful? Please let us know with the +feedback form on the right side of the page! From 8f4545699b778e5dc6e700085685c34ab92bc55f Mon Sep 17 00:00:00 2001 From: Dachary Date: Tue, 18 Jun 2024 09:44:43 -0400 Subject: [PATCH 10/18] Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --- source/frameworks/flutter/quick-start.txt | 15 ++++++++------- ...tart-define-your-object-model-description.rst | 5 +++-- ...ck-start-open-synced-database-description.rst | 2 +- ...-start-define-your-object-model-procedure.rst | 2 +- ...ck-start-open-synced-database-description.rst | 2 +- .../quick-start-import-realm-description.rst | 6 +++--- source/includes/dotnet-implement-interface.rst | 4 ++-- ...library-name-reflects-former-realm-naming.rst | 2 +- source/platforms/android.txt | 2 +- .../platforms/android/livedata-quick-start.txt | 16 ++++++++-------- source/platforms/unity.txt | 11 +++++------ 11 files changed, 34 insertions(+), 33 deletions(-) diff --git a/source/frameworks/flutter/quick-start.txt b/source/frameworks/flutter/quick-start.txt index 35f6866104..5a4d70244d 100644 --- a/source/frameworks/flutter/quick-start.txt +++ b/source/frameworks/flutter/quick-start.txt @@ -5,7 +5,7 @@ Quick Start with Flutter ======================== .. meta:: - :description: Learn how to use Atlas Device SDK with Flutter. + :description: Get started using Atlas Device SDK with Flutter in a Flutter application. :keywords: Realm, Flutter, Flutter SDK, code example .. facet:: @@ -22,13 +22,14 @@ Quick Start with Flutter :depth: 2 :class: singlecol -This Quick Start demonstrates how to use Atlas Device SDK with Flutter. +This quick start demonstrates how to use Atlas Device SDK with Flutter in a +Flutter application. -.. tip:: Standalone Dart or Flutter Project? +.. tip:: Flutter Project or Standalone Dart Project? - This quick start contains information for using the SDK with a Flutter - project. The package that you import, and the way you create object - models, differs if you are using the SDK in a standalone Dart project. For + This quick start contains information for using the SDK in a Flutter + project. The package that you import and the way you create object + models differs when using the SDK in a standalone Dart project. For a quick start using a standalone Dart project, refer to :ref:`sdks-quick-start`. @@ -42,7 +43,7 @@ information about installing the SDK in a Flutter project, refer to Import the SDK -------------- -Import the package into any files where you use it. +Import the ``realm`` package into any files where you use it. .. code-block:: dart :caption: ExampleFile.dart diff --git a/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst index 709e48a443..28b630e0a4 100644 --- a/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst +++ b/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst @@ -1,5 +1,6 @@ -In this quick start, you can remove ``ownerId`` unless you want to add the -optional Device Sync. +This quick start includes ``ownerId``, which is used when we add +Device Sync in a later step. +You can remove this property if you are not using Device Sync. .. important:: Define SDK Models within the realm namespace diff --git a/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst index c84b6d147d..1573a7d767 100644 --- a/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst +++ b/source/includes/api-details/csharp/quick-start/quick-start-open-synced-database-description.rst @@ -1,5 +1,5 @@ Once you have enabled Device Sync and authenticated a user, you can -open a synced database. Use a``FlexibleSyncConfiguration`` object to define +open a synced database. Use a ``FlexibleSyncConfiguration`` object to define the specifics of how your application synchronizes data with App Services. Then, add a Sync subscription that determines what data the user can read and write. diff --git a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst index 4670261981..64812df3dc 100644 --- a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst +++ b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst @@ -27,7 +27,7 @@ class is public and part of the same library as the ``_Car`` data model class. The generated ``Car`` class is what's used throughout your application. -*Watch for Changes to the Model (Optional)* +**Watch for Changes to the Model (Optional)** You can watch your data model class to generate a new ``Car`` class whenever there's a change to ``_Car``: diff --git a/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst index bc0693257a..0bbb5eb23c 100644 --- a/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst +++ b/source/includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst @@ -12,6 +12,6 @@ Now create a subscription to synchronize data with Atlas using Device Sync. Add the subscription within the :flutter-sdk:`SubscriptionSet.update() ` callback function. -The update block callback function, includes a :flutter-sdk:`MutableSubscriptionSet() +The update block callback function includes a :flutter-sdk:`MutableSubscriptionSet() ` object as an argument. Use ``MutableSubscriptionSet.add()`` to add a new subscription. diff --git a/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst index 7608985818..a4cb7d53b6 100644 --- a/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst +++ b/source/includes/api-details/kotlin/quick-start/quick-start-import-realm-description.rst @@ -1,8 +1,8 @@ .. note:: Using this Quick Start with KMP - If you're running this project in a fresh Kotlin Multiplatform (KMP) template project, you can - copy and paste the following snippets into the :file:`Greeting.greeting()` method in the - :file:`commonMain` module. + If you're following this quick start in a fresh Kotlin Multiplatform (KMP) template + project, you can copy and paste the snippets into the :file:`Greeting.greeting()` + method in the :file:`commonMain` module. At the top of your source files where you want to use the SDK, add the appropriate imports. For this quick start, we use these imports: diff --git a/source/includes/dotnet-implement-interface.rst b/source/includes/dotnet-implement-interface.rst index a7cba41021..5615c9cfd5 100644 --- a/source/includes/dotnet-implement-interface.rst +++ b/source/includes/dotnet-implement-interface.rst @@ -12,7 +12,7 @@ :dotnet-sdk:`AsymmetricObject ` base classes. This approach to SDK model definition is still supported, but does not include new features such as the :ref:`nullability annotations - `. In a future SDK release, the - base classes will become deprecated. You should use the interfaces for any + `. These base classes will be + deprecated in a future SDK release. You should use the interfaces for any new classes that you write and should consider migrating your existing classes. \ No newline at end of file diff --git a/source/includes/tip-library-name-reflects-former-realm-naming.rst b/source/includes/tip-library-name-reflects-former-realm-naming.rst index f439d080fe..d83dd5f7c1 100644 --- a/source/includes/tip-library-name-reflects-former-realm-naming.rst +++ b/source/includes/tip-library-name-reflects-former-realm-naming.rst @@ -1,4 +1,4 @@ .. tip:: Atlas Device SDK was previously named Realm. The SDK library names still - reflect Realm naming. To import the SDK, you import Realm. + reflect Realm naming. To import Atlas Device SDK, you import Realm. diff --git a/source/platforms/android.txt b/source/platforms/android.txt index 6e5e5c2db5..a24d8ce402 100644 --- a/source/platforms/android.txt +++ b/source/platforms/android.txt @@ -7,7 +7,7 @@ Build for Android .. toctree:: :titlesonly: - Quick Start with Live Data + Quick Start with LiveData .. contents:: On this page :local: diff --git a/source/platforms/android/livedata-quick-start.txt b/source/platforms/android/livedata-quick-start.txt index 55a7b438f0..ffa58b3d31 100644 --- a/source/platforms/android/livedata-quick-start.txt +++ b/source/platforms/android/livedata-quick-start.txt @@ -5,7 +5,7 @@ Quick Start with LiveData - Java SDK ==================================== .. meta:: - :description: Learn how to use Atlas Device SDK for Java with Android LiveData. + :description: Get started using Atlas Device SDK for Java with Android LiveData. :keywords: Realm, Java SDK, code example .. facet:: @@ -22,7 +22,7 @@ Quick Start with LiveData - Java SDK :depth: 2 :class: singlecol -This page contains instructions to quickly get Atlas Device SDK for Java +This quick start demonstrates how to get Atlas Device SDK for Java integrated into an example Android application that uses :android:`LiveData `. This example application allows a user to increment a counter using a button. @@ -30,13 +30,13 @@ allows a user to increment a counter using a button. Prerequisites ------------- -This quick start guide uses :ref:`Sync ` to synchronize data -changes between clients. Before you begin, ensure you have: +This quick start guide uses :ref:`Device Sync ` to synchronize data +changes between clients. Before you begin, ensure you: -- :ref:`Installed the Java SDK `. -- :ref:`Created an App `. -- :ref:`Enabled anonymous authentication `. -- :ref:`Enabled Sync `. +- :ref:`Install the Java SDK `. +- :ref:`Create an App `. +- :ref:`Enable anonymous authentication `. +- :ref:`Enable Device Sync `. .. note:: Using LiveData without Sync diff --git a/source/platforms/unity.txt b/source/platforms/unity.txt index bf2adacc08..8caa8f1e94 100644 --- a/source/platforms/unity.txt +++ b/source/platforms/unity.txt @@ -5,7 +5,7 @@ Quick Start for Unity - .NET SDK ================================ .. meta:: - :description: Learn how to build a Unity project with Atlas Device SDK syncing data across devices. + :description: Get started using Atlas Device SDK for .NET with a Unity project. :keywords: Realm, .NET SDK, code example .. facet:: @@ -22,7 +22,7 @@ Quick Start for Unity - .NET SDK :depth: 1 :class: singlecol -This page contains information on how to install and integrate Atlas Device SDK +This quick start demonstrates how to install and integrate Atlas Device SDK for .NET into your Unity project. Prerequisites @@ -253,7 +253,7 @@ If you need to store some data just before the app exits, consider using the `Application.wantsToQuit `_ event instead. -.. note:: Known Issue When Developing With Unity on Windows +.. important:: Known Issue When Developing With Unity on Windows On Windows, if you are using Device Sync, your project may crash when running multiple instances of your project since multiple processes are attempting to @@ -263,9 +263,8 @@ event instead. Additional Examples ------------------- -The community has created many projects that demonstrate the usage -of the .NET SDK. Check out the examples below that demonstrate the usage -of the .NET SDK with Unity! +Check out the examples below for community-authored projects that +demonstrate using the .NET SDK with Unity! .. note:: From 65388f4d991c38e22276650a75305d65a00402f2 Mon Sep 17 00:00:00 2001 From: Dachary Date: Tue, 18 Jun 2024 09:54:02 -0400 Subject: [PATCH 11/18] Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --- source/sdk/quick-start.txt | 73 ++++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index b6ba562581..3dc1dc1cfa 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -5,7 +5,7 @@ Quick Start =========== .. meta:: - :description: Learn how to quickly get started with Atlas Device SDK. + :description: Get started quickly using Atlas Device SDK. :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example .. facet:: @@ -24,8 +24,14 @@ Quick Start .. tabs-selector:: drivers -This Quick Start demonstrates how to use Atlas Device SDK. -Before you begin, ensure you have :ref:`Installed the SDK `. +This quick start demonstrates how to use Atlas Device SDK. +If you'd prefer a guided quick start experience using a :ref:`template app `, +check out our :ref:`Device Sync tutorials `. + +Before You Begin +---------------- + +Before you can get started, you must :ref:`Install the SDK `. Import the SDK --------------- @@ -84,9 +90,9 @@ Import the SDK Define Your Object Model ------------------------ -For a non-synced database, you can define your :ref:`object model -` directly in code. For a synced database, your client -object models require a matching schema in Atlas. For more details, refer to +You can define your :ref:`object model ` directly in code. +If you want to use Device Sync, your client +object models also require a matching schema in Atlas. For more details, refer to :ref:`sdks-model-data-device-sync`. .. tabs-drivers:: @@ -207,19 +213,19 @@ To instantiate a new object and add it to the database in a write block: .. include:: /includes/sdk-examples/quick-start/quick-start-create-objects.rst -For more information about creating objects, refer to :ref:`sdks-crud-create`. +For more information, refer to :ref:`sdks-crud-create`. Read and Filter ~~~~~~~~~~~~~~~ -You can retrieve a :ref:`results collection ` of +To retrieve a :ref:`results collection ` of all objects of a given type in the database: .. include:: /includes/sdk-examples/quick-start/quick-start-read-objects.rst -For more information about reading objects, refer to :ref:`sdks-crud-read`. +For more information, refer to :ref:`sdks-crud-read`. -You can also filter that collection: +To filter that same results collection: .. include:: /includes/sdk-examples/quick-start/quick-start-filter-objects.rst @@ -233,16 +239,16 @@ To modify an object, update its properties in a write transaction block: .. include:: /includes/sdk-examples/quick-start/quick-start-update-object-properties.rst -For more information about updating objects, refer to :ref:`sdks-crud-update`. +For more information, refer to :ref:`sdks-crud-update`. Delete ~~~~~~ -Finally, you can delete an object: +To delete an object from the database: .. include:: /includes/sdk-examples/quick-start/quick-start-delete-objects.rst -For more information about deleting objects, refer to :ref:`sdks-crud-delete`. +For more information, refer to :ref:`sdks-crud-delete`. Watch for Changes ----------------- @@ -310,8 +316,8 @@ Close a Database Add Device Sync --------------- -If you want to sync data across devices, you can enable Device Sync in Atlas. -For more information on Device Sync, refer to :ref:`sync`. +If you want to sync data across devices with the SDK, you can enable Device Sync in Atlas. +For more information on Device Sync, refer to :ref:`sync` in the App Services documentation. Prerequisites ~~~~~~~~~~~~~ @@ -331,10 +337,12 @@ Initialize the App ~~~~~~~~~~~~~~~~~~ The SDK uses an ``App`` to connect to Atlas, manage users, and report certain -types of errors. Initialize the ``App`` connection. +types of errors. .. include:: /includes/access-app-id.rst +To initialize the ``App`` connection: + .. include:: /includes/sdk-examples/quick-start/quick-start-initialize-app.rst For more details about configuring and initializing the App connection, refer @@ -345,13 +353,13 @@ to :ref:`sdks-connect-to-atlas`. Authenticate a User ~~~~~~~~~~~~~~~~~~~ -In this quick start, you use :ref:`anonymous authentication ` +This quick start uses :ref:`anonymous authentication ` to log in users without requiring them to provide any identifying information. After authenticating the user, you can open a database for that user. .. include:: /includes/sdk-examples/quick-start/quick-start-authenticate-user.rst -The SDK provides many additional ways to authenticate, register, and link +The SDK provides additional ways to authenticate, register, and link users. For other authentication providers, refer to :ref:`sdks-authenticate-users`. @@ -420,12 +428,19 @@ The syntax to :ref:`read `, :ref:`write `, and :ref:`watch for changes ` on a synced database is identical to the syntax for non-synced databases above. -The only difference here is the addition of a property that we can use to -find the user's todos and set Sync permissions. We query for only the user's -todos in the subscription, and set Sync permissions to -:guilabel:`Users can only read and write their own data`. +However, reads and writes to a synced databases have the following additional +constraints: + +- Sync permissions that determine whether users can read or write. +- Sync subscriptions that determine what data the synced database + can read or write. + +In the following example, we set Sync permissions to ``Users can only +read and write their own data``, and add a property that lets us +subscribe to only the current user's todos. +``Users can only read and write their own data``. -For more information about Sync permissions, refer to :ref:`sync-permissions`. +For more information about Device Sync permissions, refer to :ref:`sync-permissions` in the App Services documentation. .. tabs-drivers:: @@ -469,14 +484,10 @@ uploads, and downloads changesets. Next: Check out the Template Apps and Tutorial ---------------------------------------------- -Check out the :ref:`template apps ` to experiment with another -quick way to start coding with Atlas Device SDK. Each SDK has an application +Check out the :ref:`template apps ` to start coding +quickly with Atlas Device SDK. Each SDK has an application that integrates Atlas Device SDK and Atlas Device Sync in a platform-idiomatic todo app. -If you're more interested in a guided experience, you can read our -:ref:`Device Sync tutorials ` to learn how to expand -on the template app. - -Finally, if you'd like to browse example applications for specific use cases, -check out our list of curated :ref:`realm-examples`. +Check out our list of curated :ref:`realm-examples` to browse example applications +for specific use cases and implementations. From f150feb3f7b55c0b82d5e4f09cb6923ce4ecc45e Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 11:55:54 -0400 Subject: [PATCH 12/18] Apply review suggestions --- .../quick-start-close-database-description.rst | 7 ++++--- source/includes/dotnet-implement-interface.rst | 2 +- source/sdk/quick-start.txt | 13 +++++++------ 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst index 3c199a444b..3d1c6d345a 100644 --- a/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst +++ b/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst @@ -7,6 +7,7 @@ interacts with a database in a ``using (...)`` statement: .. literalinclude:: /examples/generated/dotnet/OpenARealmExamples.snippet.scope.cs :language: csharp -If you require a database object to be shared outside of a single method, -to manage its state by calling the -:dotnet-sdk:`Dispose() ` method: +If you require a database object to be shared outside of a single method, you +can manage its state manually. Call the +:dotnet-sdk:`Dispose() ` +method to release the reference: diff --git a/source/includes/dotnet-implement-interface.rst b/source/includes/dotnet-implement-interface.rst index 5615c9cfd5..e036cdc995 100644 --- a/source/includes/dotnet-implement-interface.rst +++ b/source/includes/dotnet-implement-interface.rst @@ -6,7 +6,7 @@ :dotnet-sdk:`IAsymmetricObject ` interface and must be declared ``partial`` classes. - In versions of the .NET SDK older than 10.18.0, objects derive from + In versions of the .NET SDK v10.18.0 and earlier, objects derive from :dotnet-sdk:`RealmObject `, :dotnet-sdk:`EmbeddedObject `, or :dotnet-sdk:`AsymmetricObject ` diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 3dc1dc1cfa..758da971b6 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -25,8 +25,9 @@ Quick Start .. tabs-selector:: drivers This quick start demonstrates how to use Atlas Device SDK. -If you'd prefer a guided quick start experience using a :ref:`template app `, -check out our :ref:`Device Sync tutorials `. +If you'd prefer a guided quick start experience using a +:ref:`template app `, check out our +:ref:`Device Sync tutorials `. Before You Begin ---------------- @@ -481,11 +482,11 @@ uploads, and downloads changesets. .. include:: /includes/sync-memory-performance.rst -Next: Check out the Template Apps and Tutorial ----------------------------------------------- +Next: Check out Demos and Example Projects +------------------------------------------ -Check out the :ref:`template apps ` to start coding -quickly with Atlas Device SDK. Each SDK has an application +Check out the :ref:`template apps ` to see an implementation of +a platform-specific Atlas Device SDK application. Each SDK has an application that integrates Atlas Device SDK and Atlas Device Sync in a platform-idiomatic todo app. From 70ec4ab29c9c8a30307f6550beb1da2674048a7c Mon Sep 17 00:00:00 2001 From: Dachary Date: Tue, 18 Jun 2024 11:58:08 -0400 Subject: [PATCH 13/18] Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --- source/frameworks/swiftui/quick-start.txt | 20 ++++++++++--------- ...t-define-your-object-model-description.rst | 5 +++-- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/source/frameworks/swiftui/quick-start.txt b/source/frameworks/swiftui/quick-start.txt index 15fc15b0af..fc640ecae1 100644 --- a/source/frameworks/swiftui/quick-start.txt +++ b/source/frameworks/swiftui/quick-start.txt @@ -2,11 +2,11 @@ .. _ios-swiftui-quick-start: ================== -SwiftUI QuickStart +Quick Start with SwiftUI ================== .. meta:: - :description: Learn how to use Atlas Device SDK with SwiftUI property wrappers. + :description: Use Atlas Device SDK for Swift with SwiftUI property wrappers. :keywords: Realm, Swift SDK, code example .. facet:: @@ -23,6 +23,13 @@ SwiftUI QuickStart :depth: 2 :class: singlecol +This quick start demonstrates how to use the Atlas Device SDK for Swift +with SwiftUI with a small working app. The app contains all of the code to +get you up and running with SwiftUI and the SDK quickly. + +If you'd prefer to learn from a working example app, check out the +SwiftUI :ref:`template app ` or the :ref:`swift-swiftui-tutorial`. + Prerequisites ------------- @@ -30,15 +37,10 @@ Prerequisites - Meet the minimum Xcode and iOS targets required by the Swift SDK version. - Create a new Xcode project using the SwiftUI "App" template. -Overview --------- -.. seealso:: Use SwiftUI with Atlas Device SDK - This page provides a small working app to get you up and running with - SwiftUI and Atlas Device SDK quickly. If you'd like to learn from a working - example app, instead, check out the the SwiftUI :ref:`template app - ` or the :ref:`swift-swiftui-tutorial`. +Example App Overview +-------------------- This page contains all of the code for a working SwiftUI and Atlas Device SDK app. The app starts on the ``ItemsView``, where you can edit a list of items: diff --git a/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst index 3403e894d7..db6437ec5f 100644 --- a/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst +++ b/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst @@ -1,2 +1,3 @@ -In this quick start, you can remove ``ownerId`` unless you want to add the -optional Device Sync. +This quick start includes ``ownerId``, which is used when we add +Device Sync in a later step. +You can remove this property if you are not using Device Sync. From dd0e45f3b32572fc183cdf5d8c2d23e3051f66a1 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 12:02:29 -0400 Subject: [PATCH 14/18] Fix underline/overline after changing page name --- source/frameworks/swiftui/quick-start.txt | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/source/frameworks/swiftui/quick-start.txt b/source/frameworks/swiftui/quick-start.txt index fc640ecae1..f4161d5187 100644 --- a/source/frameworks/swiftui/quick-start.txt +++ b/source/frameworks/swiftui/quick-start.txt @@ -1,9 +1,8 @@ -.. _ios-swiftui-combine-quick-start: .. _ios-swiftui-quick-start: -================== +======================== Quick Start with SwiftUI -================== +======================== .. meta:: :description: Use Atlas Device SDK for Swift with SwiftUI property wrappers. @@ -37,8 +36,6 @@ Prerequisites - Meet the minimum Xcode and iOS targets required by the Swift SDK version. - Create a new Xcode project using the SwiftUI "App" template. - - Example App Overview -------------------- From d3414b990c9e9dc373cf021d71b188d8648ed7eb Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 12:09:27 -0400 Subject: [PATCH 15/18] Remove LiveData quick start --- source/platforms/android.txt | 5 - .../android/livedata-quick-start.txt | 260 ------------------ 2 files changed, 265 deletions(-) delete mode 100644 source/platforms/android/livedata-quick-start.txt diff --git a/source/platforms/android.txt b/source/platforms/android.txt index a24d8ce402..07e511aebf 100644 --- a/source/platforms/android.txt +++ b/source/platforms/android.txt @@ -4,11 +4,6 @@ Build for Android ================= -.. toctree:: - :titlesonly: - - Quick Start with LiveData - .. contents:: On this page :local: :backlinks: none diff --git a/source/platforms/android/livedata-quick-start.txt b/source/platforms/android/livedata-quick-start.txt deleted file mode 100644 index ffa58b3d31..0000000000 --- a/source/platforms/android/livedata-quick-start.txt +++ /dev/null @@ -1,260 +0,0 @@ -.. _java-livedata-quick-start: - -==================================== -Quick Start with LiveData - Java SDK -==================================== - -.. meta:: - :description: Get started using Atlas Device SDK for Java with Android LiveData. - :keywords: Realm, Java SDK, code example - -.. facet:: - :name: genre - :values: tutorial - -.. facet:: - :name: programming_language - :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -This quick start demonstrates how to get Atlas Device SDK for Java -integrated into an example Android application that uses :android:`LiveData -`. This example application -allows a user to increment a counter using a button. - -Prerequisites -------------- - -This quick start guide uses :ref:`Device Sync ` to synchronize data -changes between clients. Before you begin, ensure you: - -- :ref:`Install the Java SDK `. -- :ref:`Create an App `. -- :ref:`Enable anonymous authentication `. -- :ref:`Enable Device Sync `. - -.. note:: Using LiveData without Sync - - To use this quick start without Sync, disable the sync features - in the SDK. You can do this by removing the following lines from your - app-level :file:`build.gradle` file: - - .. code-block:: gradle - - realm { - syncEnabled = true - } - - After removing the lines, re-synchronize the Gradle configuration to - reload the Java SDK in an offline-only state. Remove the lines - related to importing and using Sync Configuration, user login, and - partition values from the ``CounterModel`` file to use the Java SDK - without Sync. - -Clone the LiveData Quick Start Repository ------------------------------------------ - -To get started, copy the `example repo -`__ -into your local environment. - -We've already put together an Android application that has -most of the code you'll need. You can clone the client application -repository directly from GitHub: - -.. code-block:: console - - git clone https://github.com/mongodb-university/realm-android-livedata.git - -The repository contains two branches: -``final`` and ``start``. The ``final`` branch is a finished version -of the app as it should look *after* you complete this tutorial. -To walk through this tutorial, please check out the ``start`` -branch: - -.. code-block:: console - - git checkout start - -Import Dependencies -------------------- - -Now that you've cloned the repo, you need to add the dependencies you'll -need to run the Java SDK and Android LiveData. Begin by adding -the Java SDK dependency to the ``buildscript.dependencies`` -block of your project level :file:`build.gradle` file: - -.. literalinclude:: /examples/generated/java/sync/build.snippet.realm-dependency.gradle - :language: gradle - :emphasize-lines: 10 - :copyable: false - -You'll also have to add the Android LiveData Dependency to the -``dependencies`` block of your app level :file:`build.gradle` file: - -.. literalinclude:: /examples/generated/java/sync/build.snippet.livedata-dependency.gradle - :language: gradle - :emphasize-lines: 10 - :copyable: false - -Next, enable Sync in the SDK by creating the -following top-level block in your app level :file:`build.gradle` file: - -.. literalinclude:: /examples/generated/java/sync/build.snippet.sync-enable.gradle - :language: gradle - :copyable: false - -Then, enable DataBinding by creating the following block in the -``android`` block of your app level :file:`build.gradle` file: - -.. literalinclude:: /examples/generated/java/sync/build.snippet.databinding-enable.gradle - :language: gradle - :emphasize-lines: 15-17 - :copyable: false - -Finally, click the "Sync" button or select :guilabel:`Build > Rebuild Project` -in the application menu to reconfigure your Gradle configuration with -these changes and fetch the dependencies. - -LiveRealmObject ---------------- - -With all of the dependencies in place, it's time to create a -LiveData-compatible interface for our SDK objects. To do so, we'll -have to handle a few events: - -- The ``onActive()`` method enables an observer to subscribe to changes - to the underlying SDK object by adding a change listener. - - .. literalinclude:: /examples/generated/java/sync/LiveRealmObject.snippet.onactive.kt - :language: kotlin - :copyable: false - -- The ``onInactive()`` method enables an observer to unsubscribe to - changes to the underlying SDK object by removing the change listener. - - .. literalinclude:: /examples/generated/java/sync/LiveRealmObject.snippet.oninactive.kt - :language: kotlin - :copyable: false - -- When a change occurs, the ``listener`` member uses the ``setValue()`` - method of the ``LiveData`` parent class to pass the SDK object's - value to the UI unless the object was deleted, in which case the - change listener passes a value of ``null`` instead of passing along - a reference to an invalid, deleted object. - - .. literalinclude:: /examples/generated/java/sync/LiveRealmObject.snippet.listener.kt - :language: kotlin - :copyable: false - -.. seealso:: Using LiveData with ``RealmResults`` - - This example only uses LiveData to display ``RealmObjects`` in the UI. - For a sample implementation displaying ``RealmResults``, - see `LiveRealmResults `__. - -Instantiating LiveData in the ViewModel ---------------------------------------- - -This application stores all of its logic and core data within a ViewModel -called ``CounterModel``. When the application runs, it creates an instance -of ``CounterModel`` that is used until the application closes. That -instance contains the LiveData that displays on the UI of the application. -To create an instance of LiveData, we need to access a ``Counter`` object -stored in a database and pass it to the ``LiveRealmObject`` constructor. -To accomplish this: - -1. Connect to your App *with your* **App ID**. - -2. Authenticate a user. - -3. Connect to a specific database using Sync. - -4. Query the database for a ``Counter``, inserting a new ``Counter`` if - one hasn't already been created in this database. - -5. Instantiate a ``LiveRealmObject`` using the ``Counter`` instance and - store it in the ``counter`` member of ``CounterModel``. - -The following code snippet implements this behavior: - -.. literalinclude:: /examples/generated/java/sync/CounterModel.snippet.constructor.kt - :language: kotlin - -.. important:: Don't Read or Write on the UI Thread - - Database reads and writes are computationally expensive, so - the SDK disables reads and writes by default on the UI thread. - For simplicity, this example enables UI thread reads and writes with - the ``allowWritesOnUiThread()`` and ``allowQueriesOnUiThread()`` - config builder methods. In production applications, you should almost - always defer reads and writes to a background thread using - asynchronous methods. - -Connecting the ViewModel to the UI ----------------------------------- - -To display the data stored in the ``CounterModel`` on the application UI, -we'll need to access the ``CounterModel`` singleton using the -:android:`viewModels() ` -method when the application creates ``CounterFragment``. Once we've -instantiated the model, we can use the :android:`Android Data Binding -` library to display the model's -data in UI elements. - -To access the ``CounterModel`` singleton when the application creates -``CounterFragment``, place the following code in the ``onCreateView()`` -method of ``CounterFragment``: - -.. literalinclude:: /examples/generated/java/sync/CounterFragment.snippet.getcountermodel.kt - :language: kotlin - :copyable: false - -Next, set up the Data Binding hooks in the UI for the counter fragment: - -.. literalinclude:: /examples/generated/java/sync/counter_fragment.xml - :language: kotlin - :copyable: false - -Finally, connect the model to the binding so that the UI can display the -counter and iterate the counter on button press with the following code -in the ``onCreateView()`` method of ``CounterFragment``: - -.. literalinclude:: /examples/generated/java/sync/CounterFragment.snippet.binding.kt - :language: kotlin - :copyable: false - -Run the Application -------------------- - -Now you should be able to run the sample application. You should see an -interface that looks something like this: - -.. image:: /images/android-livedata-quickstart-app.png - :alt: The LiveData QuickStart Counter app. - -Clicking the "ADD" button should add one to the value of your counter. -With Sync, you can view your App logs to see individual increment -events. Android LiveData is lifecycle-aware, so rotating the screen or -freeing the application's state by clearing your device's RAM should -have no effect on the application state, which should seamlessly resume -and automatically resubscribe to events on resume using the state stored -in the model singleton and the encapsulated LiveData instance. - -Summary -------- - -- Use the the ``LiveRealmObject`` and ``LiveRealmResults`` classes as a template for encapsulating live SDK data in Android LiveData. -- Use a ViewModel to separate underlying data from the UI elements that display that data. -- DataBinding lets you declare relationships between model data and UI elements without explicitly setting values in an Activity or Fragment. - -Feedback --------- - -Did you find this quick start guide helpful? Please let us know with the -feedback form on the right side of the page! From 3d18e0d68841d004f56659cd1f1a3df3c19eed24 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 13:47:25 -0400 Subject: [PATCH 16/18] Remove Java SDK info from Quick Start page --- ...quick-start-close-database-description.rst | 4 -- ...t-define-your-object-model-description.rst | 2 - .../quick-start-import-realm-description.rst | 34 ----------- .../quick-start-open-database-description.rst | 4 -- ...start-open-synced-database-description.rst | 3 - .../quick-start-authenticate-user.rst | 14 ----- .../quick-start-close-database.rst | 14 ----- .../quick-start-create-objects.rst | 14 ----- .../quick-start-define-your-object-model.rst | 21 ------- .../quick-start-delete-objects.rst | 14 ----- .../quick-start-filter-objects.rst | 14 ----- .../quick-start/quick-start-import-realm.rst | 14 ----- .../quick-start-initialize-app.rst | 14 ----- .../quick-start/quick-start-open-database.rst | 12 ---- .../quick-start-open-synced-database.rst | 14 ----- .../quick-start-react-to-changes.rst | 14 ----- .../quick-start/quick-start-read-objects.rst | 14 ----- .../quick-start-update-object-properties.rst | 14 ----- .../quick-start-write-to-synced-db.rst | 12 ---- source/sdk/quick-start.txt | 60 +------------------ 20 files changed, 2 insertions(+), 304 deletions(-) delete mode 100644 source/includes/api-details/java/quick-start/quick-start-close-database-description.rst delete mode 100644 source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst delete mode 100644 source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst delete mode 100644 source/includes/api-details/java/quick-start/quick-start-open-database-description.rst delete mode 100644 source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst diff --git a/source/includes/api-details/java/quick-start/quick-start-close-database-description.rst b/source/includes/api-details/java/quick-start/quick-start-close-database-description.rst deleted file mode 100644 index 05acd377d6..0000000000 --- a/source/includes/api-details/java/quick-start/quick-start-close-database-description.rst +++ /dev/null @@ -1,4 +0,0 @@ -It is important to remember to call the :java-sdk:`close() -` method when done with a -database instance to free resources. Neglecting to close realms can lead to an -``OutOfMemoryError``. diff --git a/source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst b/source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst deleted file mode 100644 index 53f44f339b..0000000000 --- a/source/includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst +++ /dev/null @@ -1,2 +0,0 @@ -To define your application's data model, add the following class -definitions to your application code: diff --git a/source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst deleted file mode 100644 index 4f0e358fa2..0000000000 --- a/source/includes/api-details/java/quick-start/quick-start-import-realm-description.rst +++ /dev/null @@ -1,34 +0,0 @@ -Before you can use the SDK in your app, you must -initialize the Realm library. Your application should -initialize the SDK just once each time the application runs. - -To initialize the Realm library, provide an Android -``context`` to the ``Realm.init()`` static function. You can provide -an Activity, Fragment, or Application ``context`` for initialization with no -difference in behavior. You can initialize the library -in the ``onCreate()`` method of an `application subclass -`__ to -ensure that you only initialize the SDK once each time the -application runs. - -.. tip:: Register Your Application Subclass in the Android Manifest - - If you create your own ``Application`` subclass, you must add it to your - application's ``AndroidManifest.xml`` to execute your custom - application logic. Set the ``android.name`` property of your manifest's - application definition to ensure that Android instantiates your ``Application`` - subclass before any other class when a user launches your application. - - .. code-block:: xml - :emphasize-lines: 6 - :copyable: false - - - - - - diff --git a/source/includes/api-details/java/quick-start/quick-start-open-database-description.rst b/source/includes/api-details/java/quick-start/quick-start-open-database-description.rst deleted file mode 100644 index e9beceea91..0000000000 --- a/source/includes/api-details/java/quick-start/quick-start-open-database-description.rst +++ /dev/null @@ -1,4 +0,0 @@ -Use ``RealmConfiguration`` to control the specifics of the database you -would like to open, including the name or location of the database, -whether to allow synchronous reads or writes to a database on the UI -thread, and more. diff --git a/source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst b/source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst deleted file mode 100644 index 9aa8fecdbe..0000000000 --- a/source/includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst +++ /dev/null @@ -1,3 +0,0 @@ -Use ``SyncConfiguration`` to define the specifics of how your application -synchronizes data with App Services, including timeouts, synchronous -reads and writes on the UI thread, and more. diff --git a/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst b/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst index 424ffbaeac..90bf2b5cc1 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.log-in.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.authenticate-a-user.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.authenticate-a-user.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-close-database.rst b/source/includes/sdk-examples/quick-start/quick-start-close-database.rst index ae029c863e..fcc40e3ac5 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-close-database.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-close-database.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/open_realm_test.snippet.close-realm.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/OpenARealmTest.snippet.close-a-realm-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/OpenARealmTest.snippet.close-a-realm-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst index 687e5c24e8..d8aab442ec 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.create-realm-object.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.create-object-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.create-object-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst b/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst index 373524de0a..772a057897 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst @@ -20,27 +20,6 @@ :language: dart :caption: car.dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/DefinitelyNotJavaTask.snippet.define-object-model-local.java - :language: java - :caption: Task.java - :copyable: false - - .. literalinclude:: /examples/generated/java/local/TaskStatus.snippet.define-object-model-local.java - :language: java - :caption: TaskStatus.java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.define-object-model-local.kt - :language: kotlin - :caption: Task.kt - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst index 4a2a02b328..ec666b8422 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.delete-one-realm-object.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.delete-object-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.delete-object-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst index c36ae764d1..53f6991e7c 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.query-realm-objects-with-filter.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.filter-collection-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.filter-collection-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst b/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst index 43b786a7ae..e0bc3d6bf7 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst @@ -21,20 +21,6 @@ import 'package:realm_dart/realm.dart'; - - id: java - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-realm.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-realm.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst b/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst index 646995ae5d..2f6b75be2f 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.init-app.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-the-app.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-the-app.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-open-database.rst b/source/includes/sdk-examples/quick-start/quick-start-open-database.rst index d265adfd88..6ea9045fe1 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-open-database.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-open-database.rst @@ -19,18 +19,6 @@ .. literalinclude:: /examples/generated/flutter/open_realm_test.snippet.open-realm.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.open-a-realm-local.java - :language: java - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.open-a-realm-local.kt - :language: kotlin - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst b/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst index 0227944da9..634edc1343 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_sync_test.snippet.add-sync-subscription.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.open-a-realm.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.open-a-realm.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst b/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst index 127475148c..a2237a40e4 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst @@ -20,20 +20,6 @@ .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.watch-for-changes-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.watch-for-changes-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst b/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst index 3a66747d86..8faf5756de 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.query-all-realm-objects.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.read-object-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.read-object-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst b/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst index f6639b7df1..05d7819153 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst @@ -19,20 +19,6 @@ .. literalinclude:: /examples/generated/flutter/quick_start_test.snippet.update-realm-object.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.update-object-local.java - :language: java - :copyable: false - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/generated/java/local/MainActivity.snippet.update-object-local.kt - :language: kotlin - :copyable: false - - id: javascript content: | diff --git a/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst b/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst index 5a705fa8a1..43d553c73d 100644 --- a/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst +++ b/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst @@ -19,18 +19,6 @@ .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart - - id: java - content: | - - .. literalinclude:: /examples/MissingPlaceholders/example.java - :language: java - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt - :language: kotlin - - id: javascript content: | diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 758da971b6..eb855cd9aa 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -6,7 +6,7 @@ Quick Start .. meta:: :description: Get started quickly using Atlas Device SDK. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre @@ -14,7 +14,7 @@ Quick Start .. facet:: :name: programming_language - :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + :values: cpp, csharp, dart, javascript/typescript, kotlin, swift .. contents:: On this page :local: @@ -56,16 +56,6 @@ Import the SDK .. include:: /includes/api-details/dart/quick-start/quick-start-import-realm-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/quick-start/quick-start-import-realm-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/quick-start/quick-start-import-realm-description.rst - .. tab:: :tabid: javascript @@ -113,16 +103,6 @@ object models also require a matching schema in Atlas. For more details, refer t .. include:: /includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/quick-start/quick-start-define-your-object-model-description.rst - .. tab:: :tabid: javascript @@ -167,16 +147,6 @@ Open a Database .. include:: /includes/api-details/dart/quick-start/quick-start-open-database-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/quick-start/quick-start-open-database-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/quick-start/quick-start-open-database-description.rst - .. tab:: :tabid: javascript @@ -282,16 +252,6 @@ Close a Database .. include:: /includes/api-details/dart/quick-start/quick-start-close-database-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/quick-start/quick-start-close-database-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/quick-start/quick-start-close-database-description.rst - .. tab:: :tabid: javascript @@ -384,16 +344,6 @@ Open a Synced Database .. include:: /includes/api-details/dart/quick-start/quick-start-open-synced-database-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/quick-start/quick-start-open-synced-database-description.rst - .. tab:: :tabid: javascript @@ -456,12 +406,6 @@ For more information about Device Sync permissions, refer to :ref:`sync-permissi .. tab:: :tabid: dart - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - .. tab:: :tabid: javascript From ce1a360fa155c7fb95504cbf94c92207de53d9a9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 13:57:03 -0400 Subject: [PATCH 17/18] Move the callout --- .../dart/quick-start/quick-start-import-realm-description.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst index 2647da5586..9fb096c63f 100644 --- a/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst +++ b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst @@ -1,8 +1,8 @@ -Import the package into any files where you use it. - .. tip:: Standalone Dart or Flutter Project? This quick start contains information for using the SDK with a standalone Dart project. The package that you import, and the way you create object models, differs if you are using the SDK in a Flutter project. For a quick start using Flutter, refer to :ref:`frameworks-flutter-quick-start`. + +Import the package into any files where you use it. From 5d39838e2124d9540be9ce62e8cc1cf827aa54bb Mon Sep 17 00:00:00 2001 From: Dachary Date: Tue, 18 Jun 2024 13:57:40 -0400 Subject: [PATCH 18/18] Update source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --- .../swift/quick-start/quick-start-import-realm-description.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst b/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst index ca02e49c45..df0efe1292 100644 --- a/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst +++ b/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst @@ -1,4 +1,4 @@ -.. seealso:: +.. tip:: If your app uses SwiftUI, check out the :ref:`SwiftUI Quick Start `.