Mavo

Formats

By default, Mavo saves and reads data in JSON. While you don’t need to understand JSON to use Mavo, you may need to use a different file format at some point. This is exactly what mv-format is for.

Basic usage

You can select a file format in one of two ways:

  1. Explicitly, by using the mv-format attribute on your Mavo root. Its value is a keyword, depending on the format, e.g. text, markdown, csv etc.
  2. Implicitly, depending on the extension of your file in mv-storage. E.g. if you use a URL to a CSV file, Mavo will automatically use the CSV format.

Often, you need to specify a different format for the mv-storage, mv-source, and mv-init attributes. You can do this by using the mv-storage-format, mv-source-format, and mv-init-format attributes respectively.

Available formats

Mavo comes with some formats out of the box, but you can add more via Plugins. Read the documenation of the format you’re using carefully, because formats may come with restrictions about the structure of your properties. These restrictions are only about which properties will be used for displaying and saving data. If you have more properties in your Mavo, they will just be ignored. For example, you can have additional properties that are read-only or contain expressions.

CSV

Uses the popular PapaParse library for reading and writing CSV, fetched dynamically via cdnjs.

Keyword csv
File extensions *.csv, *.tsv
Restrictions Only one collection. Property names inside collection must correspond to headers in CSV file.

Text

Keyword text
File extensions *.txt
Restrictions Only one property.

Creating your own formats

To create your own formats, all you need is to create a class that extends from Mavo.Formats.Base. For information on how the $.Class() class helper works, look in Bliss’ documentation.


		Mavo.Formats.MyFormat = $.Class({
			// Mandatory. You may instead extend another format, e.g. Mavo.Formats.Text
			extends: Mavo.Formats.Base,

			// Initialization code (optional)
			constructor: function(backend) {
				// ...
			},

			static: {
				// File extensions
				extensions: [".foo", ".bar"],

				// Any dependencies (optional)
				dependencies: [{
					test: () => "CoolLibrary" in window, // is the library already loaded?
					url: "URL/to/library" // URL to fetch if the library is not loaded
				}],

				// must specify this if you’re using dependencies
				ready: Mavo.Formats.Base.ready,

				// Mandatory: Convert a string to an object for rendering
				// serialized: The string, as it was read from the remote file
				// me: Instance of Mavo.MyFormat, optional
				parse: function (serialized, me) {
					// ...
				},

				// Mandatory: Convert an object to a string for saving
				// data: The object
				// me: Instance of Mavo.MyFormat, optional
				stringify: function (data, me) {
					// ...
				}
			}
		});
	

You can see examples of format declarations in src/formats.js

If your format may be useful to other people, please consider adding it to the Plugin directory!