They connect Examplary to other platforms and extend it with new question types. Workspace owners and admins can install apps from the Apps & Integrations section in their workspace settings.
Our own integrations, like Google Classroom, Woots, Schoolyear and Safe Exam Browser, are built as apps, using the same tools described here.
The anatomy of an app
An app is a package that defines a set of Capabilities. These capabilities determine what the app can do within Examplary, such as adding new question types, integrating with external services, or providing custom dashboard pages.
An app is a folder with an app.ts file that describes it, and other files that
contain the actual logic and UI components of the app.
Getting started
Create a new app with the Examplary CLI:
npx @examplary/cli init acme-gradebook --id acme.gradebook --name "Acme Gradebook"This creates a folder with an app.ts, and a package.json with the Examplary
packages and scripts to run and publish the app.
Make sure that your app.ts has a defineApp call that defines your app and
exports it as the default export.
import { defineApp } from "@examplary/apps";
import exportOption from "./capabilities/export";
const app = defineApp({
id: "acme.gradebook",
name: { en: "Acme Gradebook" },
description: { en: "Send tests to your Acme classes" },
icon: "./icon.svg",
});
app.addSetting({
key: "apiToken",
label: { en: "Acme API token" },
help: { en: "You'll find it in your Acme account settings." },
type: "password",
secret: true,
});
app.addCapability(exportOption);
export default app;The id identifies your app on the platform and can't be changed later.
Use a reverse domain-like name, in lowercase: <your-org>.<app-name>.
To try it out in your workspace while you build it, run this:
npm run devTo publish it to your organization, or submit it for public use, follow the steps in the publishing guide.
App properties
The defineApp function is used to define your app and its properties:
| Property | Description |
|---|---|
id | Unique ID, like acme.gradebook. Required. |
name | Display name. Required. |
description | One-line description, shown on the app's card. Required. |
icon | Path to a square icon (SVG or PNG). |
readme | Path to a Markdown file with a longer description. |
previewImage | Path to a preview image. |
website | Where to read more about the app. |
version | Your own version number, like 1.2.0. |
scope | Who fills in the settings by default: the workspace (org) or each teacher (user). See settings. |
apiScopes | The Examplary API scopes your hooks can use, like ["audit-logs:read"]. See hooks. |
public | Whether every Examplary workspace can find and install the app. See publishing. |
deprecated | Existing installations keep working, but the app can no longer be installed. |
requiredPlans | The plans a workspace needs to install the app or change its settings: any of free, pro or enterprise. All plans when left out. |
Texts like name and description are translatable: give an object with a
value per language ({ en: "…", nl: "…" }). Paths are relative to the app's
root folder; the CLI uploads the files they point at.
Directory structure
Apart from app.ts, you're free to organize your app however you like.
A typical app might look like this:
acme-gradebook/
├── app.ts
├── package.json
├── icon.svg
├── README.md
├── capabilities/
│ └── export.ts
├── components/
│ └── connect-button.tsx
└── lib/
└── acme-api.tsapp.ts can import from other files and npm packages, as long as they don't
rely on Node.js APIs. See hooks for what's available.