Config.json
- Create a config.json
- Showpad administrator makes changes
- Publishing the Experience App
- Using the 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:
- Developer creates a config.json
- Showpad Administrator can make changes in the Online Platform
- 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
- Example asset reference:
"key": {"type": "asset", "value": ["bd184adb8ad2a2cdce69413c8b42c93f"], "description": "A description for the admin"}
- Contents cannot have
value
as key - Description is optional
- Although value is an array only one asset is supported at the moment
Labels
- Example label:
"key": {"value": "My app title", "description": "The application title", "limit": 30}
- Example label:
"key": "My app title"
- Labels cannot have
value
as key. - Description and limit are optional for 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:
- Resolving all requested content (through tags and assets)
- Adding an
assets
-array to the JSON - Persisting all changes from the admin into the JSON
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.pdf",
"type": "document",
"description": "A description", // Can be null
"permissions": {
"share": true, // File can be shared
"annotate": true, // File can be annotated
"download": true // File can be downloaded
},
"tagIds": ["5debee5405cfd4e2797b553037ceb78c",...],
"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();