Home

Getting Started

The Movable Ink Platform offers unprecedented power and control over creating dynamic content for 1:1 personalized experiences, and with the release of the Movable Ink Developer Kit we're giving developers access to the same powerful tools that we use internally to create beautiful, engaging apps with complex business logic.

Requirements

People who wish to participate in the Developer Preview should be comfortable with the following technologies:

• HTML, Javascript, and CSS
• Basic command-line tools (cd, ls, etc)
• git version control

Additionally, the Developer Preview has only currently been tested on Mac and Linux. Windows support will be added in the future.

Overview

The MDK is comprised of two parts: a command-line tool, and a GUI. These two parts complement each other; many tasks can either be completed in the MDK GUI using easy, discoverable controls or developers can drop down to the command-line and edit files directly. And the abstractions are designed to be consistent: you can either your app's configuration files directly on the filesystem and the GUI will stay in sync.

Workflow

This is a high-level overview of how you use the MDK to create content for emails:

1. Use the MDK's new command to create a project repository on your local machine.
2. Use the MDK's deploy command to deploy the project repository to the Movable Ink platform.
3. Configure platform access controls to determine who can see your app in the App gallery
4. A user (either you, or another individual who builds campaigns) chooses your app from the app gallery, and a new platform app is instantiated for that user based on the code in your project repository.
5. The user inserts the app that they have created into their email campaigns.

Setup

The MDK has the following dependencies:

• MacOS or Linux
• Node.js 8.0 or higher
• Yarn (a node package manager)

The easiest way to get Node.js and Yarn on MacOS is via homebrew. You install homebrew by following the instructions at https://brew.sh/.

You can check to see if you have Node.js already installed by opening Terminal.app on MacOS or any terminal on linux and running:

$ node -v

(note: the $ is just the prompt displayed, you do not need to type it as part of the command)

If you see "command not found" or your Node version is less than 8.0, you can install Node via:

$ brew install node

You can then install Yarn by running:

$ npm install -g yarn

Finally, you can install the MDK itself with yarn:

$ yarn global add @movable/cli

This command doubles as both the installation and upgrade command. If you ever need to remove the MDK, you can do so with:

$ yarn global remove @movable/cli

You can check to see that the MDK has been correctly installed with:

$ movable --version
movable-cli: 0.11.2
node: 8.9.4
os: darwin x64

Usage

You can run movable --help to see a list of all possible commands and arguments.

Creating a new project

Each app has an associated project repository, and while your app can be named anything, the project repository name should not contain spaces or special characters. We suggest a convention of lowercasing the app name and replacing dashes with spaces. So for instance, if you want to name your app My Current Weather, you would call your repository my-current-weather.

You can place your projects anywhere you want; in this guide we will assume that you want to create a projects directory in your home directory. You can do it like so:

$ mkdir ~/projects
$ cd ~/projects`

From within your projects directory, you can use the movable command to create a new project:

$ movable new my-current-weather
installing app
  create .editorconfig
  create README.md
  create app/img/.gitkeep
  create app/index.html
  create app/js/index.js
  create app/styles/style.css
  create bin/setup-deploy
  create .gitignore
  create karma.conf.js
  create manifest.yml
  create package.json
  create rollup.config.js
  create tests/helper.js
  create tests/tests.js
  create yarn.lock
Yarn: Installed dependencies
Successfully initialized git.
Movable app successfully created. To start the dev environment, run `movable serve` from the app's directory. For more details, use `movable help`.

You should see that the MDK has created a ~/projects/my-current-weather. You can change to that directory with

$ cd my-current-weather

The MDK has create a project skeleton--a fully working app with some reasonable defaults from which you can build. Some files of note:

• manifest.yml - This file contains all of the app's specification and configuration settings.
• app/index.html - This HTML file becomes the code inside the HTML panel in the platform, and is used to render the content.
• [app/js/index.js[(index.js) - Becomes the code inside the JavaScript panel in the platform, and contains your business logic.
• app/styles/style.css - Becomes the content inside the CSS panel in the platform, and can override the visual styling of your app.
• tests/tests.js - You can write acceptance tests for common use cases of your app, to give you confidence that the app is working correctly.
• package.json - Contains any javascript npm dependencies your app may have.
• node_modules/ - Directory containing all of your npm dependencies, it is listed in .gitignore so is intentionally not checked into your repository.

Development

You can work on your app locally using the editor of your choice. If you don't have a preferred editor, you might consider Atom, VSCode, or SublimeText.

As you make changes, you'll likely want to see what your changes look like. While you could open app/index.html in your browser, we have specially built tools for more easily previewing:

$ movable serve
Build successful (1120ms) – Serving on http://localhost:4200/

This starts a local webserver on port 4200. You can open up your web browser to http://localhost:4200/ and see the MDK GUI. The GUI enables previewing and also has a number of editing capabilities:

Previewing

You can easily see how your app works along two dimensions: you can test various contexts such as location, device, etc similar to the Preview Panel in the Movable Ink platform, but you can also test various app configurations marketers may set. For instance, if your Weather app contains a dropdown for the marketer to display weather in Celsius or Fahrenheit, you can locally test how your app will look with each set. You have two different previewing modes, which you can toggle with the switch in the top left:

Local Previewing

Local previewing renders the app within your browser's rendering engine. The advantage of this is that it's very quick, and you can use browser tools such as the JavaScript Console and Debugger while developing your app.

Rendered Previewing

Rendered previewing sends a preview of your app to the Movable Ink platform and converts it to an image. It is a bit slower, but will allow you to see how it gets rendered by the Movable Ink rendering engine.

Studio Tools

Create new Tools for marketers to use in your app, and imbue them with logic by referencing them in code.

Think of Tools as reusable components that your users can add to your app while editing it. For instance, for a countdown timer, minutes and hours numbers would each be tools. Tools don't get any special logic on their own, but instead get added to the workspace as Tags with tool-[toolname] css classes which you can use to access them via your javascript.

When you click Save on the tools page, the tools you've added will be persisted to the tools key in manifest.yml.

Fields (app sidebar configuration)

Many times when you create an app, you want people who use your app to be able to configure it to their use cases by exposing options. For instance, a Current Weather app may want the app user to be able to decide whether to display the temperature in fahrenheit, celsius, or automatically detect it. You could use a Field to create a dropdown in the app sidebar with those three options.

When you click Save on the Fields page, the fields you've added will be persisted to the fields key in manifest.yml.

Settings

This configures general settings around the app itself. You can change the displayed name, the icon, or add query parameters that get automatically passed to the app page.

When you click Save on the Settings page, the settings you've changed will be persisted in manifest.yml.

Cold State (Studio GUI editing)

Build new app UIs as easily as composing elements in Photoshop. Assign them class names if you want to drop down to CSS or JavaScript to modify them.

Anything you build in the cold state will get saved in app/index.html.

Deploying

When you deploy your project repository to the Movable Ink platform, most of what happens is server-side. The following happens:

• The contents of your repository are synced to Movable Ink's servers.
• The platform uses the repository name to determine the project's "key"--if the platform already has an existing app with the same key, it will attempt to update that app, otherwise it will create a new app in the platform.
• The platform examines your package.json file and installs any dependencies.
• The platform executes yarn run build, which takes all of the javascript from your project's app/ directory and compiles it into files in a dist directory.
• The platform pushes the contents of your repository, including the newly created dist/ files, to Movable Ink's asset servers.
• The platform updates the app to use this latest release for any new apps users create. Any existing app instances users have created will continue to use the release that was active at the time the app instances were created.

As of right now, setting up your project deployment initially will require running:

$ bin/setup-deploy

This command is subject to change soon, though.

To deploy your app, first ensure that you don't have any uncommitted changes by running git status (and run git commit -am 'your-message' to commit them) then run:

$ movable deploy production

This will push your repo's master branch to the production platform app.