Subitems

Unito refers to subitems as a syncable relation of an item. Imagine you could leave notes next to each pokémon, and you'd like these notes to be synchronized alongside other pokémon properties. These notes would be considered as subitems of pokémons.

From a connector standpoint, subitems are defined as relations like any other relation would be.

{
  fields: {
    name: "Pikachu",
  },
  relations: [
    {
      name: "notes",
      label: "Notes",
      path: "/pokedex/1/pokemons/1/notes",
      schema: {
        label: "Note",
        fields: [
          {
            name: "content",
            label: "Content",
            type: FieldValueType.STRING
          }
        ]
      }
    }
  ]
}

But from Unito's standpoint, things are a bit more complicated. You see, as it stands, we don't know that notes exist until we select a given pokémon. Imagine that our pokédex sits empty — how could Unito possibly know that there will be a relation called notes, and that this relation is to be expected on each item of the relation?

Enters RelationSummary. When describing the schema of your items, you can inform Unito that one or more relations are to be expected on each item of that collection. Armed with that knowledge, Unito will then be able to offer that relation as a potential syncable subitem, alongside all other fields.

{
  fields: {
    id: 1,
    name: "John Doe's Pokédex",
  },
  relations: [
    {
      name: "pokemons",
      label: "Pokémons",
      path: "/pokedex/1/pokemons",
      schema: {
        label: "Pokémon",
        fields: [
          {
            name: "name",
            label: "Name",
            type: FieldValueType.STRING
          },
          ...
        ],
        relations: [
          {
            name: "notes",
            label: "Notes",
            schema: {
              label: "Note",
              fields: [
                {
                  name: "content",
                  label: "Content",
                  type: FieldValueType.STRING
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Summaries are incomplete by nature given how relation properties, like the path, can be dependent on the item owning the relation. The summarized schema might be incomplete too, given how custom fields might also vary from one item to another. They're meant to describe the commonalities one could expect from the relations common to all of the items of that relation.

Sync the parent of an item

In the Unito synchronization engine, there's a need to know which are the parents of an item to properly sync subitems. To achieve this, an item must define a field with the parent semantic. This way, Unito can add/remove the parent of an item.

{
  fields: {
    id: 1,
    name: "John Doe's Pokédex",
  },
  relations: [
    {
      name: "pokemons",
      label: "Pokémons",
      path: "/pokedex/1/pokemons",
      schema: {
        label: "Pokémon",
        fields: [
          {
            name: "name",
            label: "Name",
            type: FieldValueType.STRING
          },
          ...
        ],
        relations: [
          {
            name: "notes",
            label: "Notes",
            schema: {
              label: "Note",
              fields: [
                {
                  name: "content",
                  label: "Content",
                  type: FieldValueType.STRING
                },
                {
                  name: "pokemon",
                  label: "Pokémon",
                  type: FieldValueType.REFERENCE,
                  referencePath: "/pokedex/1/pokemons",
                  semantic: Semantic.PARENT,
                },
              ],
            }
          }
        ]
      }
    }
  ]
}