manifest.yml

The manifest.yml file lives in the root of your project repository and contains configuration for your app. When you deploy your app, we validate and read the manifest. It needs to be in YAML format, and must contain the required keys. (and cannot include additional keys) Comments are allowed in the manifest, and start with #.

The manifest is specified using JSON Schema, and the latest schema can be found at https://app.movableink.com/schemas/manifest.v1.json

name [required]

This is the name displayed in the Movable Ink App Gallery.

# example
name: Current Weather

authors [required]

This contains one or more authors of the app. Even with a single author, it needs to be in array format. This is not displayed anywhere within the platform, it is purely for reference.

# example
authors:
  - Jane Doe <[email protected]>
  - John Doe <[email protected]>

html_file

Apps default to using ./index.html for the HTML panel of an app, but you may override it with a path to a file in your project repository. MDK apps use app/index.html.

# example
html_file: app/index.html

css_file

Apps default to using ./style.css for the CSS panel of an app, but you may override it with a path to a file in your project repository. MDK apps use app/styles/style.css. Most of your styling should be handled within Studio whenever possible, and you should keep CSS declarations to a minimum. Studio sets style attributes on tags, so if you declare CSS rules in a separate file you may have to use !important declarations.

javascript_file

Apps default to using ./index.js for the JavaScript panel of an app, but you may override it with a path to a file in your project repository. MDK apps use app/js/index.js.

description

A short description that is displayed below the app name in the App Gallery.

# example
description: Displays current weather at user's location

category

Designates which category an app falls into. Possible values are: content: social, content: media, context: location, context: time, custom, and data: rendering.

# example:
category: data: rendering

width and height

Sets the default width and height attributes for the Studio workspace, in pixels. This can be overridden at display time by the app using an element with id mi_size_container and resizing that element.

# example
width: 500
height: 200

documentation

A link to an external documentation URL. Displayed when a user creates the app, opens in a new window.

# example
documentation: https://example.com/docs/current-weather.html

expose_advanced_options

Activates the Advanced tab within the platform for your app. The Advanced tab allows your users to control advanced options, such as: cache time, timeout, ignored query parameters, and animation options.

# example
expose_advanced_options: true

icon_v2

An identifier that references an icon your app will use in the platform, on the App Gallery page and while a user edits your app. This is currently limited to a small subset, and we recommend that you configure the value using the MDK GUI.

# example
icon_v2: weather

query_params

A map of query params to append to your app's page URL during render. Values can either be static, or can refer to a query param from the email embed code, or can be special tokens.

# example
query_params:
  name: '[first_name]'
  mi_lat: '[mi:lat]'
  mi_lon: '[mi:lon]'
  device: 'mobile'

When a user loads an embed code formatted like:

<img src="http://sub.domain.com/p/rp/12345.png?name=robert">

Your app will be loaded from a page with an URL like:

index.html?name=robert&mi_lat=40.1&mi_lon=-74.2&device=mobile

fields

An array of custom fields presented in the sidebar when a user configures your app. Each field gets rendered as its specified form component. Your fields can specify simple text inputs, or select dropdowns, or even Data Source dropdown.

# example
fields:
  - name: iconSet
    type: image
    label: Icon Set
  - name: forecastDataSource
    label: Forecast Data Source
    type: data-source
    template: weather_forecast

fields[0].name

Specifies the key for accessing the field from your JavaScript code. We recommend this be formatted for easily accessing as a variable. (no spaces or special characters)

Within a StudioApp, you can reference fields using

const iconUrl = this.fields.iconSet;
// => { name: 'iconSet', type: 'image', value: 'http://example.com/...' }

fields[0].type

The type of component to render into the sidebar. Valid values include: text, select, data-source, checkbox, color, hidden. Check the manifest definition for all supported types.

fields[0].label

Form label displayed above the field component in the sidebar.

fields[0].placeholder

For input-like forms, placeholder value displayed in the HTML input.

fields[0].value

The default value for a field.

fields[0].description

A short description, displayed below the field component.

fields[0].template

For fields of type data-source, you can include an inline Data Source template to auto-create a Data Source.

studio_options

Controls a few settings used when working in Studio.

studio_options.tools

Adds custom Tools for your users to use when modifying your app, beyond standard Text, Image, and Box tools. You should consider creating a Tool for any Tag you use within Studio that has custom JavaScript-defined behavior. For instance, in the Current Weather app, the city_name, temperature_degrees, and weather_icon are each tools. Tools make it easy for users to add extra Tags beyond what is present in your Cold State.

# example
studio_options:
  tools:
    - type: text
      name: days
      icon: clock
      class_names: days
      locked: true
      defaults:
        text: '[days]'
        previewText: '00'
        width: 50
        height: 50
    - type: text
      name: days tens digit
      icon: clock
      class_names: days-tens-digit
      locked: true
      defaults:
        text: '[daysTensDigit]'
        previewText: '0'
        width: 25
        height: 50

studio_options.tools[0].name [required]

The name displayed to the user in the Custom Tools dropdown.

studio_options.tools[0].type [required]

The type of tool; this specifies what base type of Tag will be created when a user adds the tool. Valid values are: image, text, rectangle.

studio_options.tools[0].icon [required]

Icon displayed next to the tool in the Custom Tools dropdown. Uses the same list as the top-level icon_v2 and is best configured via the MDK GUI.

studio_options.tools[0].class_names

Extra HTML class names assigned to the element. You can use these for styling via CSS or manipulating via JavaScript. Note that most Studio tags set styles using inline style attributes, so you may have to use !important declarations in your CSS.

studio_options.tools[0].locked

When the Tool creates a Tag in the Studio workspace, default it to locked state, meaning that it cannot be dragged by the user. This is useful for backgrounds, etc. The user can unlock the Tag via the layer list.

studio_options.tools[0].defaults

An Object containing keys and values of Tag attributes to set by default. These are typically CSS properties such as backgroundColor, width, height, etc. Additionally you can set default text and previewText values for tools of type text.

studio_options.tools[0].fields

An array that allows the app creator to define and store custom values on each tag created using a specific tool. These are similar to top-level manifest fields. These fields are similar to the top-level fields, but only allow a type of select, textarea, text, and checkbox. A name is also required, and is used for an internal lookup key.

studio_options.preview_fields

When your users flip between Edit Mode and Review Mode when using your apps, in Review Mode they are able to preview different states of the apps. preview_fields defines an array of contextual controls they can use. Valid values are location and date-time.

# example
studio_options:
  preview_fields:
    - location
    - date-time

data_source_definitions

You can now declare Data Source definitions within your app's manifest.yml file. Note that these are not Data Sources themselves, but are used by Studio to automatically create Data Sources for the user. You first need a field with type: data-source and template: [your-definition-type] where [your-definition-type] is replaced by the key in this object. If your field specifies a template:, two things happen: first, the last item in the dropdown will be "Create new Data Source", and clicking it will automatically create and select a Data Source for the user, based on the definition. Second, the list of Data Sources in the dropdown will be limited to only those created from the definition.

# example
data_source_definitions:
  weather_forecast:
    name: Current Weather
    type: ApiDataSource
    url: https://api.darksky.net/forecast/[apiKey]/[lat],[lon]
    content_type: application/json
    sample_responses:
      - name: Cold in Anchorage
        path: sample_data/anchorage.json
      - name: Clear in NYC
        path: sample_data/nyc.json

data_source_definitions[definitionName].name

The name attribute specifies the default name of the newly created Data Source. The user is free to choose a different name.

data_source_definitions[definitionName].type

The only available Data Source type right now is ApiDataSource.

data_source_definitions[definitionName].url

The Data Source's endpoint URL for the API you are using. This value supports merge tags; anything in brackets will get replaced by query parameters you pass to the data source.

data_source_definitions[definitionName].sample_responses

An array of sample response objects. Each one includes a name and path. Within the MDK GUI, when you are previewing your app these will populate as sample Data Sources in your data-source field. The name will be the display name of the data source, and the path references a file in your project repository containing a sample response, including headers. You can create sample responses using curl -i. Sample responses should begin with a line like HTTP/1.1 200 OK.