Update object-attribute-system.md

docs/object-attribute-system.md

@@ -8,7 +8,7 @@
 
 In the "Object Attributes" section of the "Object Edit" Page, the first row is a form to create and append a new attribute. It requires two elements, the name of the attribute and its type (`String`, `Number`, `Boolean`, `Array`, `Object`, `Function`, `Null`). Click 'Add' to create the attribute.
 
-> Within a same Object, each attribute's name must be uniq.
+> Within a same Object, each attribute's name must be unique.
 
 Once created, the new attributes appears right bellow and the ability to associate a value to it is now available. Depending on the type of the attribute, the interface will vary.
 
@@ -30,17 +30,14 @@ Here an example of how the section looks like.
 When an attributes is set to an Object, other Objects, associated to this particular Object, will have access to it. Which means that, if an Object A is added as a child of an Object B, A will embed its attributes within the instance of B.
 
 Object's attributes follow a hierarchy when associated to an other Object.
-The Original Attributes of a child, the ones defined in the original Object are the weakest ones. A Children Attribute is applied to all the children and overload the Original Attributes. Finally, child attribute is the strongest one, it overlaod Original Attributes and Children Attributes.
+The **defaults attributes** of a child, the ones defined in the original Object are the weakest ones. A **children attribute** is applied to all the children and override the default attributes. Finally, **relation attribute** is the strongest one, it override Default Attributes and Children Attributes.
 
-When an object and its relationship are resolved, the three structures ("attrs", "childrenAttrs", "childAttrs") are flattened.
+When an object and its relationship are resolved, the three structures (`attrs`, `childrenAttrs`, `childAttrs`) are merged.
 
-The following json shows how the next object would be resolved.
+The following json shows how the object would be represented:
 
 ```json
 {
-  "childrenAttrs": {
-    "xp": 800
-  },
   "children": {
     "printalphabet": {
       "duration": 3600,
@@ -56,3 +53,110 @@ Children
 
 Child
 ![chilld-capture](https://user-images.githubusercontent.com/15313830/56679320-b189e580-66bc-11e9-90ab-c8f69f531876.png)
+
+## Detailed example
+
+Let's create a few `exercises` objects
+
+> swap
+
+```js
+{
+  "id": 12344,
+  "title": "swap",
+  "attrs": {
+    "language": "go",
+    "duration": 7200
+  }
+}
+```
+
+> printalphabet
+
+```js
+{
+  "id": 12345,
+  "title": "printalphabet-v2",
+  "attrs": {
+    "language": "go",
+    "duration": 3600
+  }
+}
+```
+
+We can now create a parent object that will reference them and link them.
+
+This allow you to specify the structuration of your pedagocial content.
+
+I'll make a quest that regroup those 2 exercises:
+
+> quest-03
+
+```js
+{
+  "id": 12346,
+  "title": "quest-03",
+  "attrs": {},
+  "childrenAttrs": {
+    "xp": 800,
+    "duration": 4800,
+  },
+  "children": {
+    "printalphabet": {
+      "ref": 12345,
+      "index": 0,
+      "attrs": {
+        "duration": 7200
+      }
+    },
+    "swap": {
+      "ref": 12344,
+      "index": 1,
+      "attrs": {}
+    }
+  }
+}
+```
+
+All done, now when rendering an object, attributes are merged like so:
+
+> rendered quest object
+
+```js
+{
+  "id": 12346,
+  "title": "quest-03",
+  "attrs": {},
+  "children": {
+    "printalphabet": {
+      "ref": 12345,
+      "index": 0,
+      "attrs": {
+        "language": "go",
+        "xp": 800,
+        "duration": 7200
+      }
+    },
+    "swap": {
+      "ref": 12344,
+      "index": 1,
+      "attrs": {
+        "language": "go",
+        "xp": 800,
+        "duration": 4800
+      }
+    }
+  }
+}
+```
+
+First we apply the **default attributes** from the referenced object.
+> Here `duration` and `language` are applied.
+
+Then we apply the **children attributes** to every child.
+> In this case we override every `duration` to 4800 and add the new `xp` attribute.
+
+After that we apply the **relation attributes**, that are the most specific and as such,
+override all others attributes.
+> In this case only the `printalphabet` relation had attributes and so we apply
+the given `duration` to the final merged object.