Powertools App

This app requires using a Legacy Install Procedure

You can download and install the Powertools app via the legacy process.

Powertools is a Showpad App we've created to make things a little easier for you.

It provides you the following administrator capabilities:

• Analytics Export - A GUI to export from Showpad's Content Reporting tables.
• SDM Admin - A Structured Data Manager for all of your Showpad Apps.

Analytics Export

The Analytics Export functionality enables downloading every Content Reporting table as an Excel or CSV file.

The following instructions apply only to the Analytics Export functionality.

Install

Follow the steps defined in this install process.

Publish

1. While still in the Showpad Online Platform, select the Library tab. If relevant, select a division.

2. Click the Open Experience Builder button.

3. Select Create a New Experience.

4. Enter a title in the Experience Label text area.

5. Select Powertools and click the Create button. The app is automatically displayed in Preview mode.

6. Click the Publish Experience button.

That's it! This functionality works immediately in your Showpad instance without any configuration required.

Export Data

1. Log into Showpad as an administrator.

2. In the Content menu, select the Experiences tab and click on Powertools.

3. Select Analytics Export in the left navigation. All of the Content Reporting tables are displayed.

   

   From here, you can select your export options.

   • All Tables - Select the Table checkbox.

   

   • Specific Tables - Select the checkboxes for the individual tables to export.

   

   • You can also specify parameters to retrieve specific events:

   

4. Click the Export to Excel or Export to CSV button. Your file will download automatically.

SDM Admin Section

The SDM Admin Section provides a single user interface that can be used for all of your Showpad Apps so you no longer need to write an administration section to manage your data (define the structure and add, edit, and remove records).

Almost every Showpad App uses some kind of structured data which can be stored in AppsDB. The SDM (Structured Data Manager) simplifies getting your data into and out of AppsDB. Being backed by AppsDB means all content in the SDM is also available offline.

The SDM is split over two components:

	Component	Description
SDM Admin Section	Powertools	A user interface to manage your data.
SDM Consumer functions	Experience App SDK	Functions to use data in a Showpad App: getRecords() getRecordById() getStoreRecords()

Concepts

The following concepts are essential to using the SDM Admin Section with your Showpad Apps.

• Schema - This should be seen as a content type in which you can define fields. The SDM allows you to define Schemas and multiple fields per Schema in JSON Schema format.

  

  An article could, for example, be defined as:

  {
    "title": "Article",
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "The title for your article",
        "minLength": 4,
        "default": "A new article"
      },
      "body": {
        "type": "string",
        "description": "The body for your article",
        "minLength": 4,
        "default": "A new article body",
        "format": "textarea"
      }
    },
    "required": ["title", "body"]
  }

  

• Content Store - This holds Content Store Records. You can use it any way you want, but the idea is that 1 Experience App holds 1 Content Store.

  

  The SDM allows you to define multiple Content Stores. A Content Store can hold Content Store Records of any Schema you have defined on your instance.

  

• Content Store Records - Once you have defined your Schemas, the SDM allows you to create, edit and delete Content Store Records.

  

  

  It's also possible to import and export Content Store Records in bulk.

  

  

Setup

The following describes the steps necessary to use the SDM Admin Section with your Showpad Apps.

OAuth setup

You will need a configured OAuth client to create data in the SDM. The following information should be sufficient for the Edit OAuth Client form:

• Name: AppsDB Client
• Redirect URL: https://your-domain.showpad.biz/
• Description: OAuth client to facilitate Showpad App development.
• Website: https://your-domain.showpad.biz/
• Scope (This client needs to): AppsDB online integrations

Install

Follow the steps defined in this install process.

Configure

1. Fill in the clientId and the clientSecret of your OAuth client.

   Also fill in the list of allowedEmails (as a JSON array, using single quotes) of the users that should be able to create content. An empty array lets all users that have been assigned to the Experience App will have access to Powertools.

   allowedEmails: ['name1@mycompany.com','name2@mycompany.com']

caution

We strongly discourage leaving this array empty.

Consume Data

The Experience App SDK has functions to retrieve SDM data. Using these functions is described in the following sections.

Convert JSON Schema

SDM Schemas are defined in JSON Schema format format. The Experience App CLI has a function to convert those definitions to TypeScript types and print the output to the console.

npm

npx experience-app-cli generateSdmTypes

yarn

yarn experience-app-cli generateSdmTypes

tip

You should only provide write access to people who authorized to create Schemas and content. This can be done by adding their email addresses to the allowedEmails array in the Powertools configuration. Anyone not in this list will only have read access.

SDM data

We highly recommend using getRecords() and getRecordById() as much as possible as the result will immediately be typed correctly.

import { Showpad, Sdm } from '@showpad/experience-app-sdk';

// Created by the experience-app-cli generateSdmTypes
type Article = {
  title: string;
  body?: string;
};

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

  try {
    // Gets all "Article"s from "myAppStore"
    const articles = await Sdm.getRecords<Article>('mystore', 'Article');
    // Every article will be typed as a "Sdm.SdmRecord<Article>".
    // This means it will hold the fields as defined in the "Article" type
    // enriched with the technical fields: "id", "sdmStoreId" and "sdmSchemaId".

    // Gets the "Article" with id "articleId"
    const article = await Sdm.getRecordById<Article>('mystore', 'articleId');
    // The article will hold the same fields as above.
  } catch (error) {
    // Show a native error toast.
    Showpad.handleErrorWithToast(error);
  }
};

main();

There may be cases where you want to use getStoreRecords(). In this case, you should use type guards to correctly type your records as explained below.

import { Showpad, Sdm } from '@showpad/experience-app-sdk';

// Created by the experience-app-cli generateSdmTypes
type Article = {
  title: string;
  body?: string;
};

type Car = {
  brand: string;
  color: string;
};

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

  try {
    // Gets all records of a store
    const records = await Sdm.getStoreRecords('mystore');
    // Every record will be typed as a "Sdm.SdmRecord".
    // This means it will hold the original fields as defined in the Schema
    // enriched with the technical fields: "id", "sdmStoreId" and "sdmSchemaId".
    //
    // As a store can hold content of multiple Schemas, type guards should be used to
    // know the exact type of a record. Something like:

    const isArticle = (
      record: Sdm.SdmRecord
    ): record is Sdm.SdmRecord<Article> => record.sdmSchemaId === 'Article';

    const isCar = (record: Sdm.SdmRecord): record is Sdm.SdmRecord<Car> =>
      record.sdmSchemaId === 'Car';

    records.forEach((record) => {
      if (isArticle(record)) {
        // From here on record is correctly typed as a Sdm.SdmRecord<Article>
        console.log(record.title);
      }
      if (isCar(record)) {
        // From here on record is correctly typed as a Sdm.SdmRecord<Car>
        console.log(record.brand);
      }
    });
  } catch (error) {
    // Show a native error toast.
    Showpad.handleErrorWithToast(error);
  }
};

main();