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..5a4d70244d --- /dev/null +++ b/source/frameworks/flutter/quick-start.txt @@ -0,0 +1,110 @@ +.. _frameworks-flutter-quick-start: + +======================== +Quick Start with Flutter +======================== + +.. meta:: + :description: Get started using Atlas Device SDK with Flutter in a Flutter application. + :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 in a +Flutter application. + +.. tip:: Flutter Project or Standalone Dart Project? + + 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`. + +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 ``realm`` 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.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..f4161d5187 --- /dev/null +++ b/source/frameworks/swiftui/quick-start.txt @@ -0,0 +1,420 @@ +.. _ios-swiftui-quick-start: + +======================== +Quick Start with SwiftUI +======================== + +.. meta:: + :description: Use Atlas Device SDK for Swift with SwiftUI property wrappers. + :keywords: Realm, Swift SDK, code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: swift + +.. contents:: On this page + :local: + :backlinks: none + :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 +------------- + +- :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. + +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: + +- 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..28b630e0a4 --- /dev/null +++ b/source/includes/api-details/cpp/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,8 @@ +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 + + 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..3d1c6d345a --- /dev/null +++ b/source/includes/api-details/csharp/quick-start/quick-start-close-database-description.rst @@ -0,0 +1,13 @@ +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, you +can manage its state manually. Call the +:dotnet-sdk:`Dispose() ` +method to release the reference: 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..1573a7d767 --- /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..64812df3dc --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst @@ -0,0 +1,37 @@ +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 +`. + +**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``. + +**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. + +**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..9fb096c63f --- /dev/null +++ b/source/includes/api-details/dart/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,8 @@ +.. 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. 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..0bbb5eb23c --- /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/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..a4cb7d53b6 --- /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 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/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..601c9407c7 --- /dev/null +++ b/source/includes/api-details/kotlin/quick-start/quick-start-open-database-description.rst @@ -0,0 +1,10 @@ +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. + +You can optionally define additional :kotlin-sdk:`RealmConfiguration +` details, such as name, +location, schema version, and more. 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..db6437ec5f --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-define-your-object-model-description.rst @@ -0,0 +1,3 @@ +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. 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..df0efe1292 --- /dev/null +++ b/source/includes/api-details/swift/quick-start/quick-start-import-realm-description.rst @@ -0,0 +1,7 @@ +.. tip:: + + 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..e036cdc995 100644 --- a/source/includes/dotnet-implement-interface.rst +++ b/source/includes/dotnet-implement-interface.rst @@ -1,18 +1,18 @@ .. important:: Inheritance - All Realm objects inherit from the + All SDK objects inherit from the :dotnet-sdk:`IRealmObject `, :dotnet-sdk:`IEmbeddedObject `, or :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 ` - 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 - 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/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..90bf2b5cc1 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-authenticate-user.rst @@ -0,0 +1,45 @@ +.. 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: 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..fcc40e3ac5 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-close-database.rst @@ -0,0 +1,45 @@ +.. 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: 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..d8aab442ec --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-create-objects.rst @@ -0,0 +1,45 @@ +.. 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: 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..772a057897 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-define-your-object-model.rst @@ -0,0 +1,46 @@ +.. 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: 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..ec666b8422 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-delete-objects.rst @@ -0,0 +1,45 @@ +.. 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: 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..53f6991e7c --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-filter-objects.rst @@ -0,0 +1,45 @@ +.. 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: 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..e0bc3d6bf7 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-import-realm.rst @@ -0,0 +1,46 @@ +.. 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: 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..2f6b75be2f --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-initialize-app.rst @@ -0,0 +1,45 @@ +.. 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: 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..6ea9045fe1 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-open-database.rst @@ -0,0 +1,45 @@ +.. 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: 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..634edc1343 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-open-synced-database.rst @@ -0,0 +1,45 @@ +.. 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: 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..a2237a40e4 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-react-to-changes.rst @@ -0,0 +1,46 @@ +.. 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: 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..8faf5756de --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-read-objects.rst @@ -0,0 +1,45 @@ +.. 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: 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..05d7819153 --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-update-object-properties.rst @@ -0,0 +1,45 @@ +.. 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: 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..43d553c73d --- /dev/null +++ b/source/includes/sdk-examples/quick-start/quick-start-write-to-synced-db.rst @@ -0,0 +1,44 @@ +.. 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: 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/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..d83dd5f7c1 --- /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 Atlas Device 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.txt b/source/platforms/unity.txt new file mode 100644 index 0000000000..8caa8f1e94 --- /dev/null +++ b/source/platforms/unity.txt @@ -0,0 +1,276 @@ +.. _dotnet-unity: + +================================ +Quick Start for Unity - .NET SDK +================================ + +.. meta:: + :description: Get started using Atlas Device SDK for .NET with a Unity project. + :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: 1 + :class: singlecol + +This quick start demonstrates 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. + +.. 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 + 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 +------------------- + +Check out the examples below for community-authored projects that +demonstrate using 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/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..eb855cd9aa 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -4,10 +4,435 @@ Quick Start =========== +.. meta:: + :description: Get started quickly using Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, 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. +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 +--------------- + +.. include:: /includes/tip-library-name-reflects-former-realm-naming.rst + +.. 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: 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 +------------------------ + +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:: + + .. 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: 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 + +.. _sdks-quick-start-open-database: + +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: 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, refer to :ref:`sdks-crud-create`. + +Read and Filter +~~~~~~~~~~~~~~~ + +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, refer to :ref:`sdks-crud-read`. + +To filter that same results 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, refer to :ref:`sdks-crud-update`. + +Delete +~~~~~~ + +To delete an object from the database: + +.. include:: /includes/sdk-examples/quick-start/quick-start-delete-objects.rst + +For more information, 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: 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 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 +~~~~~~~~~~~~~ + +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. + +.. 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 +to :ref:`sdks-connect-to-atlas`. + +.. _cpp-quick-start-authenticate: + +Authenticate a User +~~~~~~~~~~~~~~~~~~~ + +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 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: 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. + +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 Device Sync permissions, refer to :ref:`sync-permissions` in the App Services documentation. + +.. 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: 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 Demos and Example Projects +------------------------------------------ + +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. + +Check out our list of curated :ref:`realm-examples` to browse example applications +for specific use cases and implementations. 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