A CLI tool to help you build your own Experience App

Config.json

The config.json file is part of the package and should hold everything that can be configured/changed by the administrator in the Online Platform.

Right now, this is only “labels” and “contents”.

Working with this configuration, consists of 3 stages:

  1. Developer creates a config.json
  2. Showpad Administrator can make changes in the Online Platform
  3. Publishing the Experience App

Create a config.json

When calling showpad experience init, an empty config.json file is created. The goal is to put all references to assets or text in there, so it can be changed by the administrator.

This file is part of the created package and is thus uploaded to the Online Platform.

An example:

{
    "version": 1,
    "contents": {
        "homepage": {
            "row1": { 
                "type": "asset",
                "value" : ["bd184adb8ad2a2cdce69413c8b42c93f"], // always an array
                "description": "Some description on what these assets mean" //optional description
            }, 
            "row2": { "type": "tags", "value": { "or": ["tag1","tag2"] } },// assets with any of these tags
            "row3": { "type": "tags", "value": { "and": ["tag1","tag2"] } }, // assets with all of these tags
            "link": { "type": "url", "value": "https://www.showpad.com"},
        },
        "slide1": {
            "link1": { "type": "url"}, // no default value, could be https://www.showpad.com or showpad://file/xyz123
            "link2": { "type": "folder", "value": "showpad://folder/xyz123"} // the "slug" url
            "asset1": { "type": "asset"}, // no default value, so any asset could be returned
            "page1": { "type": "page"}, // no default value, so any page could be returned
            "tag1": { "type": "tags"},
            "pagetag1": { "type": "page-tags"},
            "link3": { "type": "channel"} // will become something like showpad://profile/1234
        }
    },
    "labels": {
        "title": { 
            "value": "My application title", //the default value
            "description": "A title description", //optional description
            "limit": 30  //max number of chars
        },
        "homepage": {
            "title": "My Cool Title", //if it's a string, description is the key and no limit is imposed
            "subtitle": "Another subtitle",
            "description": "A very long text that could include \n newlines and stuff. No HTML though"
        },
        "slides": {
            "overview": "My Slides Overview",
            "slide1": {
                "title": "Slide 1",
                "footer": "Something!"
            }
        }
    }
}

Requirements

JSON requirements

JSON Keys cannot contain the $ and . characters.

Contents

Labels

For a more detailed explanation of all content-types and their respective representations in the Experience App Editor check the following page.

Get Showpad Asset id’s

A cli tool will be provided to search for asset-ids in Showpad.

Coming soon…

Showpad administrator makes changes

When the Experience App is uploaded to Showpad, the above JSON is parsed, validated and processed. During this phase, the mentioned tag-names are converted to tag-ids.

This JSON is used to display a lightweight builder in the Online Platform where the administrator can make changes to the contents or labels.

At this point, a draft is created which should be published by the admin.

Warning

When uploading a new version of an experience app previously set values with the same key are not overwritten. This is to prevent changes made by an admin from being overwritten.

Publishing the Experience App

During the publishing step, the final JSON is generated by the Showpad platform.

This means:

The resulting JSON could look like something like this:

{
    "version": 1,
    "contents": {
        "homepage": {
            "row1": {
                "type": "asset",
                "value" : ["bd184adb8ad2a2cdce69413c8b42c93f"],  // always an array
                "description": "Some description on what these assets mean" //optional description
            },
            "row2": { 
                "type": "tags",
                "value": {"and": ["43ba233e6b3997cc9750833ffe1a1cb3", "7ddf78c0a0abce10f1758a4c9041a73d"]},
                "result": ["bd184adb8ad2a2cdce69413c8b42c93f", "bd184adb8ad2a2cdce69413c8b42c93f", "bd184adb8ad2a2cdce69413c8b42c93f" ,...],
            "row3": { 
                "type": "tags", 
                "value": { "or": ["7ddf78c0a0abce10f1758a4c9041a73d","43ba233e6b3997cc9750833ffe1a1cb3"] },
                "result": ["bd184adb8ad2a2cdce69413c8b42c93f", "bd184adb8ad2a2cdce69413c8b42c93f", "bd184adb8ad2a2cdce69413c8b42c93f" ,...]
            },
            "link": { "type": "url", "value": "https://www.showpad.com"}
        },
        "slide1": {
            "link1": { "type": "url", "value":  "showpad://file/fileslugxyz123"},
            "link2": { "type": "folder", "value": "showpad://folder/xyz124"} // url to a folder
            "link2": { "type": "asset", "value": ["bd184adb8ad2a2cdce69413c8b42c93f", ...]}
        }
    },
    "labels": {
        "title": { 
            "value": "Mijn Applicatie", //the default value
            "description": "A title description", //optional description
            "limit": 30  //max number of chars
        },
        "homepage": {
            "title": { "value": "Mijn titel" },
            "subtitle": { "value": "Een ondertitel" },
            "description": { "value": "Mo vint toch een super lange omschrijving" }
        },
        "slides": {
            "overview": { "value": "My Slides Overview" },
            "slide1": {
                "title": { "value": "Slide 1" },
                "footer": { "value": "Something!" }
            }
        }
    },
    "assets": { // map of assets
        "bd184adb8ad2a2cdce69413c8b42c93f": {
            "id": "bd184adb8ad2a2cdce69413c8b42c93f",
            "slug": "bdfklje739v930g0d",
            "appLink": "showpad:\/\/file\/bdfklje739v930g0d"
            "name": "my_brochure.pdf",
            "displayName": "My Brochure fo 2017.pdf",
            "type": "document",
            "description": "A description", // Can be null
            "size": 475689,
            "permissions": {
                "share": true, // File can be shared
                "annotate": true, // File can be annotated
                "download": true // File can be downloaded
            },
            "tagIds": ["5debee5405cfd4e2797b553037ceb78c",...],
            "previewUrl" : "https://endpoint/asset/abc123/preview", // Same as response from getAssetPreviewUrl
            "createdAt": 1234567898,
            "updatedAt": 1234567898,
            "expiresAt": null // or timestamp
        },
        
        ...
    }
}

Using the config.json

When the Experience App is opened, the configUrl is provided as a query parameter (index.html?configUrl=xxx).

The final JSON (example above) is available when loading this configUrl.

  var xhr = new XMLHttpRequest();
  xhr.addEventListener("load", function() {
    if (xhr.readyState === xhr.DONE && xhr.status === 200) {
      var config = JSON.parse(xhr.responseText);
    }
  });
  xhr.open("GET", configUrl);
  xhr.send();