Introduction

If your app is blendable, it might be used in complex UI systems consisting of multiple apps coming from different vendors.

To make sure that apps play well together, we recommend that you follow certain conventions.

These conventions exist for two reasons:

1. to prevent conflicts between apps in the same database

2. to provide a common ground, expectable user experience

Mapping File

Each app that have blendable views should have a <AppName>.map.md file which contains the list of them.

The file should be provided at the root of the App Warehouse package. If the app is open source, the file should be provided in the code repository, preferably at the root.

Every view must be explained in the file and preferably illustrated with a screenshot.

In the future, the information in this file is used for automated blending as well as for testing purposes.

Sample Images.map.md (source):

# Blendable views
​
## /images/partials/contents/{[Simplified.Ring1.Content](https://github.com/Starcounter/Simplified/blob/master/Ring1/Content.cs)}
​
Shows a simple page for `Content` preview, image or video. In case of unexisting
content, shows empty file preview image.
​
![screenshot](docs/screenshot-content.png)

Entry Point URI

Every blendable web app should have the entry point URI that follows the pattern /<appname>, e.g. /kitchensink (lowercase).

When you access this URI, the app main screen should be presented.

If there is no main screen, show a splash screen saying that the app is running.

Sample MainHandlers.cs (source):

Handle.GET("/people", () =>
{
    return Self.GET("/people/organizations");
});

UI Metadata

By convention, a blendable web app must provide a metadata JSON that responds to the app-name blending token.

System apps and navigation apps like Launchpad will display a link to the entry point URI using the app name from this metadata. They will also use the icon, if provided.

The response JSON can consist of the following properties:

Sample MainHandlers.cs (source):

Handle.GET("/cssvariablesmanager/app-name", () => new AppName());

Sample BlendingHooks.cs (source):

Blender.MapUri("/cssvariablesmanager/app-name", "app-name");

Sample AppName.json (source):

{
  "name": "CssVariablesManager",
  "description": "CssVariablesManager",
  "html": "/cssvariablesmanager/AppIcon.html"
}

App Icon

The icon is an image (preferably inline SVG) in the HTML file which path is provided as the html property in the app-name metadata.

Check out the Icons cookbook to learn more about icons.

Sample AppIcon.html (source):

<template>
    <svg slot="cssvariablesmanager/app-icon" viewBox="0 0 185 185" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
        <use xlink:href="/cssvariablesmanager/images/cssvariablesmanager.svg#css-file" />
    </svg>
    <template is="declarative-shadow-dom">
        <slot name="cssvariablesmanager/app-icon"></slot>
    </template>
</template>

Required and Sample Data

The app should not create required nor sample data without the user's consent.

Required Data

If the app requires any data to operate (for example a list of the world's countries in the Country table), it should present a nagging information with a button that creates the data:

• on the top of the main page

• possibly in every view that needs the required data

Sample Data

If the app offers some nice-to-have sample data, it should offer a button that creates this data:

• on the main page, in a welcome message that is dismissible once (not per user)

• on the Settings page​

Settings Page

If your app is configurable, it's good for to provide a user interface for changing the app settings.

By having a settings page mapped to the common token, your configuration UI can appear along settings pages from other apps. This is good because it gives the end user a single go-to place to configure all apps.

The common pattern is to have the settings page addressable by /<appname>/settings, blended to the token settings.

The settings page might contain a button to do a "Factory Reset" of the app (restores required data) or a "Sample data" button that populates the database with sample data.

Sample and prefab apps that have a settings page:

• ​https://github.com/Starcounter/Products​

• ​https://github.com/Starcounter/SignIn​

Submitting to the App Warehouse

To make your app discoverable by others, you're invited to publish it in the App Warehouse.

Submitting apps to the App Warehouse requires an invitation.

​Contact Starcounter for more information.