Define Experience Config

caution

This step is only for Experience Type extensions.

It's now time to define the labels and contents for your Showpad App. When you develop an Experience type, you can define the labels and contents (aka config) that will be editable through the Experience App Editor and consumed by your Experiences.

Once your app has been uploaded to Showpad, it'll be assigned to organizations using the Experience App Editor.

The Experience App Editor is a tool on the Showpad Online Platform that enables admins to easily modify the contents of a Showpad App. The interface and structure of the editor is derived from the structure and contents of the config.json file. You can define your own tree structure which is visually represented in the Experience App Editor. The top level keys labels and contentsare removed.

tip

Create the same tree structure in labels and contents to group them visually together in the Experience App Editor.

Warning

The following words are reserved. They can not be used as keys. They can only be used inside a label or content object:

• type
• value

Labels

Labels allow you to add strings in your app.

{
  "version": 1,
  "labels": {
    "title": {
      "value": "My application title", //the default value
      "description": "A title description", //optional description
      "limit": 30  //max number of chars
  },
  "contents": {}
}

• description and limit are optional
• value is a reseved word and can not be used as a key

tip

Underscores in labels are transformed into spaces once uploaded to Showpad.

Contents

Contents allow you to add assets, pages, urls, folders, and channels in your Showpad App.

An organization is granted permission to assets and pages defined in the config.json when assigned to the app. This means the organization can also find the assets and pages while searching.

{
  "version": 1,
  "labels": {},
  "contents": {
    "asset_example": {
      "type": "asset"
    },
    "tags_example": {
      "type": "tags"
    },
    "page_example": {
      "type": "page"
    },
    "page_tags_example": {
      "type": "page-tags"
    },
    "url_example": {
      "type": "url"
    },
    "folder_example": {
      "type": "folder"
    },
    "channel_example": {
      "type": "channel"
    }
  }
}

asset

When using the asset content-type, the editor will display a handy selector in which administrators can search and select the asset or URL asset they wish to include.

Example

"key": {
  "type": "asset",
  "value": ["bd184adb8ad2a2cdce69413c8b42c93f"],
  "description": "A description for the admin"
  }

• description is optional
• value is a reseved word and can not be used as a key
• The value array supports a single asset
• Filenames must include the file extension

channel

When using the channel content-type, the editor will display a handy selector in which administrators can search and select the channel they wish to include.

folder

The folder content-type displays as a regular text field in the editor with the added requirement that the provided value matches a folder app link (showpad://folder/123).

page

When using the page content-type, the editor will display a handy selector in which administrators can search and select the page they wish to include.

page-tags

When using the page-tags content-type, administrators are presented with a way to easily search, select, and combine tags.

tags

When using the tags content-type, administrators are presented with a way to easily search, select, and combine tags.

url

The url content-type displays as a regular text field in the editor with the added requirement that the provided value is a valid URL.

Working Example

Initially, you'll add labels and assets to your config.json file:

{
  "version": 1,
  "labels": {
    "label_example": ""
  },
  "contents": {
    "asset_example": {
      "type": "asset"
    }
  }
}

We've prepared an extensive example that you can copy and replace the contents of the main.ts file. Instead of saying "Hello username", you get the contents of label_example and a button which will open the configured asset from asset_example in the Showpad asset viewer. It includes inline comments to explain each step.

Working Example

import { Showpad } from '@showpad/experience-app-sdk';
import './style.css';

interface Config extends Showpad.EnrichedConfigJSON {
  labels: {
    label_example: Showpad.Label;
  };
  contents: {
    asset_example: Showpad.ContentAsset;
  };
}

// Make sure the index.html has a div with id="app"
const app = document.querySelector<HTMLDivElement>('#app')!;

const main = async (): Promise<void> => {
  // Always wait for ShowpadLib to be loaded
  await Showpad.onShowpadLibLoaded();

  try {
    // Destructure labels, contents, and assets retrieved from the
    // Showpad.parseEnrichedConfig() method.
    // Pass the defined Config interface which extends Showpad.EnrichedConfigJSON
    // as a generic.
    const { labels, contents, assets } = await Showpad.parseEnrichedConfig<Config>();

    // Select the label_example label value.
    const exampleLabel = labels.label_example.value;

    // Select the computed result of the asset_example content value,
    // this will be the asset Id.
    const exampleAsset = contents.asset_example.result?.[0];

    // Display the label as our title
    app.innerHTML = `<h1>${exampleLabel}!</h1>`;

    // Check if the asset_example contains a result.
    if (exampleAsset) {
      // Select the asset from the assets object by using the key of the result.
      const asset = assets[exampleAsset];
      const button = document.createElement('button');

      // Set the asset display name as the text of our button.
      button.innerHTML = `Open ${asset.displayName}`;

      // Open the Showpad assetviewer with our selected asset when pressing the button.
      button.addEventListener('click', () => Showpad.openAssetViewer(asset.slug));

      app.append(button);
    }
  } catch (error) {
    // Show a native error toast.
    Showpad.handleErrorWithToast(error);
  }
};

main();

caution

The Working Example must be bundled and uploaded for best results.