Writing mock data

miyagi tries to make using mock data as convenient as possible. Therefore you can create multiple variants in one file, reference other mock files, reference template files and join those. It is even possible to use CommonJS modules if you want to asynchronously create mock data.

NOTE: Please do not use keys that start with $ as miyagi uses these for specific functionality (more about that below).

NOTE: The concept of inheriting mock data works best with template engines which allow you to pass data objects into an include. Please check the section supported template engines for limitations with certain template engines.

Default data

The most basic mock file would look something like this:

{
  "label": "Save",
  "type": "submit"
}

In the UI this would be shown as a variant with the name "default". If you want to change this name, you can add a $name property:

{
  "$name": "save",
  "label": "Save",
  "type": "submit"
}

Variants

You can also add variants, which would be merged with the default data:

{
  "label": "Save",
  "type": "submit",
  "$variants": [
    {
      "$name": "reset disabled",
      "label": "Disabled",
      "disabled": true
    }
  ]
}

So, the data of the variation "reset disabled" would be:

{
  "label": "Disabled",
  "type": "submit",
  "disabled": true
}

NOTE: You can also omit the default data if you have variants defined.

Merging arrays

When you have an array in your default mock data as well as your variant mock data, by default they are merged by concatenation. Example:

{
  "array": [1, 2, 3],
  "$variant": [
    {
      "$name": "variant",
      "array": [4, 5, 6]
    }
  ]
}

becomes

{
  "array": [1, 2, 3, 4, 5, 6]
}

If you want to change this behavior, you can use $opts to define a different merging strategy.

overwrite

overwrite simply replaces the first array with the second array:

{
  "array": [1, 2, 3],
  "$variant": [
    {
      "$name": "variant",
      "array": [4, 5, 6],
      "$opts": {
        "array": "overwrite"
      }
    }
  ]
}

becomes

{
  "array": [4, 5, 6]
}

combine

combine is the most complex way to merge two arrays. It does a deep merge of objects at the same index. Other values will be replaced:

{
  "array": [1, { "a": 2 }, { "a": null }],
  "$variants": [
    {
      "$name": "variant",
      "array": [2, { "b": 2 }, { "a": 3 }],
      "$opts": {
        "array": "combine"
      }
    }
  ]
}

becomes

{
  "array": [2, { "a": 2, "b": 2 }, { "a": 3 }]
}

Referencing other mock files

Instead of manually defining data, you can also reference other mock files like this:

{
  "$ref": "some/other/component"
}

It is not necessary to explicitely reference "some/other/component/mocks.json". Instead, pointing to the component folder is enough.

When referencing other mock files, you can also overwrite its values:

// some/other/component/mocks.json

{
  "oneVar": "oneValue",
  "anotherVar": "anotherValue"
}

// The referencing mock file:

{
  "$ref": "some/other/component",
  "oneVar": "someOtherValue"
}

would result in

{
  "oneVar": "someOtherValue",
  "anotherVar": "anotherValue"
}

Referencing a variation

If you need to reference a variation from another mock file, you can do so by using #:

{
  "$ref": "some/other/component#variation-name"
}

NOTE: You need to use the normalized variation name, so instead of using "#Variation name", use "#variation-name".

Referencing template files

By referencing a template file using $tpl, the object would be converted into a HTML string:

{
  "oneVar": {
    "$tpl": "some/other/component",
    "$ref": "some/other/component"
  }
}

would result in

{
  "oneVar": "<someHtml></someHtml>"
}

"<someHtml></someHtml>" would be the result of rendering the template file in "some/other/component" using the data of the mock file in "some/other/component".

Joining templates

If you want to use multiple components for one HTML string, you can do that by using $render:

{
  "html": {
    "$render": [
      {
        "$tpl": "some/component"
      },
      {
        "$tpl": "another/component"
      }
    ]
  }
}

In this case html would be the joined result of rendering "some/component" and "another/component".

Asynchronous mock data

If you want to fetch mock data from an API or do any other asynchronous operations, you can change the type of your mock files to js and use CommonJS modules:

module.exports = async function returnMockData() {
  const data = await fetchData();

  return data;
};

NOTE: Please note, that the returned value should be a JSON object with the same format as described above.

Hiding the default variation

If you want to define default mock data, so your variants inherit it, but not render the default variation, you can do that using $hidden:

{
  "$hidden": true,
  "someKey": "someData",
  "$variants": [...]
}

Global mock data

You can define global mocks by creating a data.json (data.js or data.yaml) in your components.folder. This mock data will be merged into your components mock data. The components mock data has higher priority, hence overwrites keys with the same name.