Building a Custom Platform for ManifoldJS

What does it take to add my own platform?

To get an idea of what you need to do, or can do with a ManifoldJS platform, you can crack open the npm of any of our existing platforms. Each existing platform is rebuilt using our "folds" system, so they all follow the same construct. From a high level, your fold needs to contain these few components:

1. Any assets that need to be included in your package (such as default icon images, or offline files)
2. Validation rules used to make sure your platform manifest is generated properly
3. Post generation guidance (directions for developers to submit to stores or listings)
4. Manipulation code. This generally consists of three files that work in two different steps
   • constants.js: as you would expect, where you keep your constants
   • platform.js: a set of override methods that handle the creation of the platform app, these are tasks like moving icons and assets into the generated app folder
   • manifest.js: code that is ran specifically to generate the W3C Manifest into the manifest of your platform. Generally, these platform manifests are either JSON or xml, but they are always transformed from the W3C manifest

It's that simple. Once these components are assembled, you'll add them to a local folder, a git repo or an NPM package, and then add them as a platform to ManifoldJS.

Getting Started with "Bring Your Own Platform"

What better new platform to add, then one that is already a pure hosted web app, just like our other core platforms. Office Add ins (formally known as Office Web Apps). Most folks probably don't even realize that Microsoft Office can have add-ins, let alone that there is a whole market of apps. However, generating apps for Office is quite straight forward. To do this, we'll actually clone our ManifoldJS strawman repo from here:

https://github.com/manifoldjs/manifoldjs-strawman.git

You'll see the files we need are already there waiting to be completed. Before we go any further, we'll want to make this into our own git repo. I've already done this, and pushed it to the ManifoldJS github: https://github.com/manifoldjs/manifoldjs-office.git

It's a good idea to settle on your naming ahead of time so you use the same platform name everywhere. Also, try to pick a platform name that others will not try to use, we don't do any conflict management for platform names, the last one installed always wins. In this case, I've chosen the platform name "office".

Housekeeping

Next, you'll want to take care of housekeeping files like your package.json, your readme, license and the fun stuff like that. It's again a good idea to do this up front, and be consistent about your naming.

Know what you want to go

In my scenario, I'm going to end with folder named "office" that contains two files. The first is an icon suitable for pinning to a office app bar, the second is an XML manifest with values pulled from my W3C manifest. My end Manifest should look like this:

<?xml version="1.0" encoding="utf-8"?> 
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:type="TaskPaneApp"> 
<Id>9e921eb3-4e8a-83be-a53f-5f5001d6682d</Id> 
<Version>1.0</Version> 
<ProviderName>Microsoft</ProviderName> 
<DefaultLocale>EN-US</DefaultLocale> 
<DisplayName DefaultValue="My Cool App"/> 
<Description DefaultValue="My Cool App Discription"/> 
 <IconUrl DefaultValue="defaultIcon.png" />
<Hosts> 
  <Host Name="Document"/> 
  <Host Name="Workbook"/> 
</Hosts>
   <AppDomains>
    <AppDomain>https://www.myCoolApp.com/</AppDomain>  
  </AppDomains>
<DefaultSettings> 
  <SourceLocation DefaultValue="https://www.myCoolApp.com/"/> 
</DefaultSettings> 

<Permissions>ReadWriteDocument</Permissions>
 
</OfficeApp> 

Update my Srawman

You can do about anything you want in each of these file, but I suggest you start with the srawman (this is a template for your platform), and read through the programmatic step suggested in the strawman. From a high level, this is what you'll want to accomplish with each of these files:

• constants.js: you'll want to add any constants that are referenced across files here. Things like the platform name and version are good to keep in this file.
• manifest.js: Manifest.js is all about performing your conversion from the W3C manifest (all apps in ManifoldJS start with this manifest) to the manifest for your platform. In some cases, you'll be converting the W3C JSON to JSON of another format, other times you'll be converting it to XML (as we are in this office example). In some cases you may be configuring data in multiple places, this can all be done inside the manifest.js file.
• platform.js: this file handles much of the housekeeping on your platform. This would be things like copying over files, pulling in the images or even substituting default images when the required image sizes are missing. Follow the inline comments of this file to make sure you have everything covered. If you have a pretty standard implementation, you may not change this file much (or at all).
• validation rules: This folder may contain a number of js files that will all be ran when the platform is being built. Think of these as "tests" to help guide the user to success. Build validation rules for all the necessary steps. For example, the Office app requires a image size 32x32, if that image is missing, the validation rules will throw a warning stating that the default image will be used.
• assets: This will be items you want to use in your new app. Default images, offline content or even manifest templates can be stored here.
• docs: It's important to guide the user to submitting the app, use this document (which will be copied into the root folder of each app that is generated) to instruct them on submitting an app the store.

Adding your platform to ManifoldJS

Once you've build your new platform, you'll want to publish it for others to use. Platforms can be loaded from a local folder, but we recommend distributing via a git repo or npm package instead. Adding your new platform to ManifoldJS is quite simple:

manifoldjs platform add myNewPlatformName https://github.com/boyofgreen/myNewPlatformLocation.git

This will add the platform to ManifoldJS, however the code will not be "installed" until the first time the platform is needed, so the next step is to actually build a new app with your platform:

manifoldjs http://www.myNewapp.com -p myNewPlatformName

Just as it does with any other ManifoldJS platform, this will pull down the manifest (or generate one if you don't have one) from the website, and build your new platform app. Since we used the "-p" flag in launch, we limited it to only generate apps for this new platform, but if no platform is specified, then ManifoldJS will generate apps for every platform you've added.