From 273529fde5587cf0699ae507be0f620d5469c2df Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Tue, 9 Jul 2024 18:12:00 +0300
Subject: [PATCH] docs: added chapter on managing relationships (#8043)

---
 .../data-models/manage-relationships/page.mdx | 71 +++++++++++++++++++
 www/apps/book/sidebar.mjs                     |  4 ++
 2 files changed, 75 insertions(+)
 create mode 100644 www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx

diff --git a/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx b/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx
new file mode 100644
index 0000000000..cd2864e77b
--- /dev/null
+++ b/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx
@@ -0,0 +1,71 @@
+export const metadata = {
+  title: `${pageNumber} Manage Relationships`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to manage relationships between data models when creating or updating their records using the module's main service.
+
+<Note type="soon" title="Important">
+
+Data model relationships are in active development and may change.
+
+</Note>
+
+## Manage One-to-One and One-to-Many Relationship
+
+When you create a record of a data model that belongs to another, pass the ID of the other data model's record in the `{relation_name}_id` property.
+
+For example, assuming you have the [User and Email data models from the previous chapter](../relationships/page.mdx#one-to-one-relationship):
+
+export const belongsHighlights = [
+  ["4", "user_id", "The ID of the user the email belongs to."],
+  ["11", "user_id", "The ID of the user the email belongs to."]
+]
+
+```ts highlights={belongsHighlights}
+// when creating an email
+const email = await helloModuleService.createEmail({
+  // other properties...
+  user_id: "123"
+})
+
+// when updating an email
+const email = await helloModuleService.updateEmail({
+  id: "321",
+  // other properties...
+  user_id: "123"
+})
+```
+
+In the example above, you pass the `user_id` property when creating or updating an email to specify the user it belongs to.
+
+---
+
+## Manage Many-to-Many Relationship
+
+When you create or update a record of a data model that has a many-to-many relationship to another data model, pass an array of IDs of the other data model's records in the `{relation_name}_ids` property.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](../relationships/page.mdx#many-to-many-relationship):
+
+export const manyHighlights = [
+  ["4", "order_ids", "The IDs of the orders associated with the product."],
+  ["11", "product_ids", "The IDs of the products associated with the order."]
+]
+
+```ts highlights={manyHighlights}
+// when creating a product
+const product = await helloModuleService.createProduct({
+  // other properties...
+  order_ids: ["123", "321"]
+})
+
+// when updating an order
+const order = await helloModuleService.updateOrder({
+  id: "321",
+  // other properties...
+  product_ids: ["123", "321"]
+})
+```
+
+In the example above, you pass the `order_ids` property when you create (or update) a product, and you pass the `product_ids` property when you update (or create) an order.
diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs
index de3353ff0c..98699e4305 100644
--- a/www/apps/book/sidebar.mjs
+++ b/www/apps/book/sidebar.mjs
@@ -152,6 +152,10 @@ export const sidebar = sidebarAttachHrefCommonOptions(
               path: "/advanced-development/data-models/relationships",
               title: "Relationships",
             },
+            {
+              path: "/advanced-development/data-models/manage-relationships",
+              title: "Manage Relationships",
+            },
             {
               path: "/advanced-development/data-models/index",
               title: "Index",