(DOCSP-39503): Consolidate Relationships page

source/includes/api-details/cpp/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,7 @@
+To define an inverse relationship, use ``linking_objects`` in your object 
+model. The ``linking_objects`` definition specifies the object type and 
+property name of the relationship that it inverts.
+
+In this example, we define a ``Person`` having a to-one relationship with
+a ``Dog``. The ``Dog`` has an inverse relationship to any ``Person`` 
+objects through its ``owners`` property.

source/includes/api-details/csharp/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,18 @@
+To define the inverse relationship, define a getter-only ``IQueryable<T>``
+property in your object model, where ``T`` is the source type of the
+relationship. Then, annotate this property with a 
+:dotnet-sdk:`[Backlink(sourceProperty)] <reference/Realms.BacklinkAttribute.html>` 
+attribute, where "sourceProperty" is the name of the property on the other 
+side of the relationship. The following example shows how to do this with the 
+"User has many Items" scenario.
+
+In this example, note that:
+
+- The Item object's ``Assignee`` property is a ``User`` object.
+
+- The ``User`` object's ``Items`` property inverts the relationship and 
+  refers to all ``Item`` objects that contain this specific ``User`` in their 
+  ``Assignee`` property. 
+
+This, then, allows us to query the ``Item`` collection to get all ``Items``
+assigned to a specific ``User``.

source/includes/api-details/dart/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,6 @@
+Use the `Backlink <https://pub.dev/documentation/realm_common/latest/realm_common/Backlink-class.html>`__
+property annotation to define an inverse relationship.
+Pass a `Symbol <https://api.dart.dev/stable/2.18.4/dart-core/Symbol/Symbol.html>`__
+of the field name of the to-one or to-many field for which you are creating the
+backlink as an argument to ``Backlink()``. Include an ``Iterable`` of the
+object model you are backlinking to in the field below the annotation.

source/includes/api-details/java/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,9 @@
+To define an inverse relationship, define a ``LinkingObjects`` property in your
+object model. The ``LinkingObjects`` definition specifies the object type and
+property name of the relationship that it inverts.
+
+Fields annotated with ``@LinkingObjects`` must be:
+
+- marked ``final``
+- of type ``RealmResults<T>`` where ``T`` is the type at the opposite
+  end of the relationship

source/includes/api-details/javascript/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,28 @@
+To define an inverse relationship, define a ``linkingObjects`` property in your
+object model. ``linkingObjects`` specifies the object type and
+property name of the relationship that it inverts.
+
+.. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-inverse.js
+   :language: javascript
+
+**Dynamically Obtain an Inversely Linked Object**
+
+You can dynamically retrieve an object with an inverse relationship without
+defining a ``linkingObjects`` type in its schema. Remove the
+``linkingObjects`` type from your schema, so your schemas look like a standard
+**to-many** relationship. When you need to retrieve the linked object, call the
+:js-sdk:`Realm.Object.linkingObjects() <classes/Object.html#linkingObjects>`
+query.
+
+In the following continuation from the inverse relationship example, we 
+have removed the ``manufacturer`` field with type 'linkingObjects' from 
+the ``Car`` schema. An application developer creates several manufacturers 
+and car objects, and the application pushes the newly-created cars into a 
+manufacturer's ``cars`` field. 
+
+To find the manufacturer who makes a specific car object, call ``.linkingObjects()``
+and pass the "Manufacturer" class name and "cars" field as parameters.
+
+The ``.linkingObjects()`` method returns a Results collection of objects whose
+property inverts the relationship. In this example, only one manufacturer makes
+the Sentra car model, so we can expect that manufacturer to be named Nissan.

source/includes/api-details/kotlin/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,13 @@
+To define an inverse relationship between objects, first define a 
+collection property in the parent object whose type is a 
+``RealmList<E>``, ``RealmSet<E>``, or ``RealmDictionary<E>``, where 
+``<E>`` is a ``RealmObject`` object type defined in your data model. 
+This can be a different Realm object type or the same Realm object 
+type:
+
+.. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-inverse-property-parent.kt
+  :language: kotlin
+
+Then, define an immutable :kotlin-sdk:`backlinks 
+<io.realm.kotlin.ext/backlinks.html>` property in the child object of
+``RealmResults<E>``, where ``<E>`` is the parent object type:

source/includes/api-details/objectivec/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,7 @@
+To define an inverse relationship, use
+:objc-sdk:`RLMLinkingObjects
+<Classes.html#/c:objc(cs)RLMLinkingObjects>` in your object model.
+Override :objc-sdk:`+[RLMObject linkingObjectProperties]
+<Classes/RLMObject.html#/c:objc(cs)RLMObject(cm)linkingObjectsProperties>`
+method in your class to specify the object type and property name
+of the relationship that it inverts.

source/includes/api-details/swift/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,4 @@
+To define an inverse relationship, use :swift-sdk:`LinkingObjects
+<Structs/LinkingObjects.html>` in your object model. The
+``LinkingObjects`` definition specifies the object type and
+property name of the relationship that it inverts.

source/includes/api-details/typescript/model-data/relationships-inverse-relationship-description.rst

@@ -0,0 +1,28 @@
+To define an inverse relationship, define a ``linkingObjects`` property in your
+object model. ``linkingObjects`` specifies the object type and
+property name of the relationship that it inverts.
+
+.. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-inverse.ts
+   :language: typescript
+
+**Dynamically Obtain an Inversely Linked Object**
+
+You can dynamically retrieve an object with an inverse relationship without
+defining a ``linkingObjects`` type in its schema. Remove the
+``linkingObjects`` type from your schema, so your schemas look like a standard
+**to-many** relationship. When you need to retrieve the linked object, call the
+:js-sdk:`Realm.Object.linkingObjects() <classes/Object.html#linkingObjects>`
+query.
+
+In the following continuation from the inverse relationship example, we 
+have removed the ``manufacturer`` field with type 'linkingObjects' from 
+the ``Car`` schema. An application developer creates several manufacturers 
+and car objects, and the application pushes the newly-created cars into a 
+manufacturer's ``cars`` field. 
+
+To find the manufacturer who makes a specific car object, call ``.linkingObjects()``
+and pass the "Manufacturer" class name and "cars" field as parameters.
+
+The ``.linkingObjects()`` method returns a Results collection of objects whose
+property inverts the relationship. In this example, only one manufacturer makes
+the Sentra car model, so we can expect that manufacturer to be named Nissan.

source/includes/sdk-examples/model-data/relationships-inverse-relationship.rst

@@ -0,0 +1,61 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp-sdk
+       content: |
+
+         .. literalinclude:: /examples/generated/cpp/relationships.snippet.define-inverse-relationship.cpp
+            :language: cpp
+            :emphasize-lines: 13
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/Relationships.snippet.inverse.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/backlinks_test.snippet.backlink-models.dart
+            :language: dart
+
+     - id: java
+       content: |
+
+         .. include:: /examples/generated/java/local/FrogInverseRelationshipExample.snippet.complete.java.rst
+
+     - id: java-kotlin
+       content: |
+
+         .. include:: /examples/generated/java/local/FrogInverseRelationshipExampleKt.snippet.complete.kt.rst
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.obtain-inverse-relationship-dynamically.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-inverse-property-child.kt
+            :language: kotlin
+
+     - id: objectivec
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Relationships.snippet.inverse-relationship.m
+            :language: objectivec
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Relationships.snippet.inverse-relationship.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.obtain-inverse-relationship-dynamically.ts
+            :language: typescript

source/includes/sdk-examples/model-data/relationships-to-many-relationship.rst

@@ -0,0 +1,61 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp-sdk
+       content: |
+
+         .. literalinclude:: /examples/generated/cpp/relationships.snippet.to-many-relationship.cpp
+            :language: cpp
+            :emphasize-lines: 7
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/Relationships.snippet.one-to-many.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/schemas.snippet.many-to-many-models.dart
+            :language: dart
+
+     - id: java
+       content: |
+
+         .. include:: /examples/generated/java/local/FrogManyToManyExample.snippet.complete.java.rst
+
+     - id: java-kotlin
+       content: |
+
+         .. include:: /examples/generated/java/local/FrogManyToManyExampleKt.snippet.complete.kt.rst
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-one-to-many.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-to-many-relationship.kt
+            :language: kotlin
+
+     - id: objectivec
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Relationships.snippet.to-many-relationship.m
+            :language: objectivec
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Relationships.snippet.to-many-relationship.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-one-to-many.ts
+            :language: typescript

source/includes/sdk-examples/model-data/relationships-to-one-relationship.rst

@@ -0,0 +1,61 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp-sdk
+       content: |
+
+         .. literalinclude:: /examples/generated/cpp/relationships.snippet.to-one-relationship.cpp
+            :language: cpp
+            :emphasize-lines: 13
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/Relationships.snippet.one-to-one.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/schemas.snippet.many-to-one-models.dart
+            :language: dart
+
+     - id: java
+       content: |
+
+         .. include:: /examples/generated/java/local/FrogManyToOneExample.snippet.complete.java.rst
+
+     - id: java-kotlin
+       content: |
+
+         .. include:: /examples/generated/java/local/FrogManyToOneExampleKt.snippet.complete.kt.rst
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-one-to-one.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-to-one-relationship.kt
+            :language: kotlin
+
+     - id: objectivec
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Relationships.snippet.to-one-relationship.m
+            :language: objectivec
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/Relationships.snippet.to-one-relationship.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-one-to-one.ts
+            :language: typescript