Getting Started

Fernando Tubio edited this page Jul 16, 2015 · 1 revision

In this walkthrough, you will use ManifoldJS to build a hosted web app that can run on multiple platforms.

Prerequisites

Node.js (version 0.12.0 or later)

Installing ManifoldJS

Open a command prompt or terminal window and type the following command:

npm install manifoldjs -g

Note: Before installing ManifoldJS, you must first install Node.js.

Hosting a Web Application

For this introduction, you will create a new application to host Shiftr, a fictional demo app which lets developers vote on developer frameworks.

For the best results, the site needs to publish a W3C manifest that provides information that can be useful when hosting site as an app, which Shiftr already does. If you visit the site in your browser and examine the HTML source for its home page, inside the <head> element you will notice a <link> element with a rel attribute and a value of manifest. The href attribute of this element contains a (relative) URL that points to the W3C manifest published by Shiftr.

<head>
    ...
    <title>Shiftr</title>
    <link rel="manifest" href="manifest.json">
    ...
</head>

Go ahead and download the manifest file from http://shiftr.azurewebsites.net/manifest.json.

{
    "lang": "en",
    "name": "Shifter connections",
    "short_name": "Shiftr",
    "icons": [
        {
            "src": "/resources/windows/screens/SplashScreen.scale-100.png",
            "sizes": "620x300"
        },
        {
            "src": "/resources/windows/screens/SplashScreen.scale-180.png",
            "sizes": "1116x540"
        },
        {
            "src": "/resources/windows/icons/Square150x150Logo.scale-100.png",
            "sizes": "150x150"
        },

        ...

        {
            "src": "resources/android/icons/icon-96-xhdpi.png",
            "sizes": "96x96"
        }
    ],
    "start_url": "",
    "scope": "/",
    "mjs_access_whitelist": [
        { "url": "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css" },
        { "url": "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/fonts/glyphicons-halflings-regular.woff" }
    ],
    "display": "fullscreen",
    "orientation": "portrait",
    "theme_color": "aliceblue"
}

This manifest is a JSON-formatted document providing details about the site, including its name, the icons to use for various platforms, and how the site should be presented on the screen when hosted as an app.

If the site that you intend to host does not publish a manifest, don't worry; ManifoldJS will create one for you, though you will miss out on some of the benefits that a manifest provides, such as taking advantage of the site's own branding.

Now, point ManifoldJS against Shiftr's home page. From a command prompt or terminal window, use the following command line to generate an application.

manifoldjs http://shiftr.azurewebsites.net

When you run ManifoldJS against a site, it downloads the page from the specified URL and attempts to locate the site's W3C manifest by looking for a <link> entry of type manifest within the page's HTML. If it finds one, it downloads the manifest from the location specified in the link and then parses it.

If a site does not provide its own manifest, ManifoldJS creates one for it, although it will only contain its starting URL and a short name synthetized from the site's URL.

{
    "start_url": "http://www.yoursite.com/",
    "short_name": "WwwYoursiteCom"
}

ManifoldJS analyzes and validates the manifest's content and informs you if it finds any errors. If a manifest does not specify all the icons it needs to generate an application for any given platform, it will recommend adding any missing images in its console output. Nevertheless, it will provide a set of default icon files with the ManifoldJS logo in place of the missing icons. You can always replace these later on.

Console output showing manifest validation messages

Provided the validation doesn't find any errors, the tool proceeds to download all the icons defined in the manifest from their current location and then embeds them as resources in the individual platform projects, choosing which icons are appropriate for each platform based on their size and resolution.

Unless you specify otherwise, ManifoldJS creates a folder in the output directory containing projects for each of the platforms it supports, which includes Windows, iOS, Android, Chrome OS, and Firefox OS. If you don't require all of them, you can specify a subset of these platforms with the (-p | --platforms) parameter and the tool will generate only the ones that you specify.

By default, the tool creates the application in the current directory. You can change the output location by specifying a different path with the (-d | --directory) command line parameter.

Output folder showing the projects for each platform

That is all that you need to generate a hosted app that runs on multiple platforms!

Shiftr Running on Multiple Platforms

Inside each platform folder, you will find a "Next Steps" document that briefly describes how to test the application and publish it to the corresponding app store.

Platform next steps document