IMatch Documentation Tutorial: Structure of <code>app.json</code> Files

The app.json

The integrated App Manager relies on app.json files to manage and run IMatch Apps.

app.json

Each app must include an app.json file. The AppWizard in IMatch automatically creates this file when you create a new app.

app.json files are standard JSON text files in UTF-8 encoding. There are mandatory and optional elements. app.json supports localization of apps via language-specific strings.

Example

The following example shows the app.json for the IMatch AppWizard.

{
    "type" : "app",
    "id": "photools.com.IMatch.AppWizard",
    "index": 1,
    "version" : "1.0",
    "author": ["Mario M. Westphal & photools.com"],
    "name": {
            "en": "IMatch AppWizard",
            "de": "IMatch AppWizard"
            },
    "description": {
            "en": "Use the IMatch AppWizard to create new apps quickly and easily.",
            "de": "Verwenden Sie den IMatch AppWizard, um neue Apps schnell und einfach zu erstellen."
            },
    "defaultDocument": "index.html",
    "icon" : {
            "" : "im-appwiz-icon.png"
            },
    "runAs": "modal",
    "windowSizing" : {
        "sizing" : "both",
        "width": 700,
        "height" : 650
    }
}

Elements

The following table describes each element in an app.json file. The file must be valid JSON, element names are case-sensitive.

Element Mandatory Description

id A unique id for this app. Only alphanumerical characters are allowed.
It is recommended to use a GUID for this. But every unique string will do.
Use your name and the name of your app for exampple: photools.com-MyCoolApp. Or use one of the many free web-based GUID generators, like www.guidgen.com/.
The IMatch AppWizard automatically generates a GUID for new apps.

version The version of the app. If no version is specified, 1.0 is assumed.

hidden Boolean. If this value is specified and true, the app is hidden from the App Manager and the drop-down list in App Panels.

index This integer number can be used to control the native sort order for apps in the AppManager.
Default is 0. The App Manager sorts apps by this index and their name.
The user can later re-arrange apps to whatever order he prefers.

type

Describes the type of the app. The following values are supported:

Value	Description
`app`	This is a regular app. I can be run in an App Panel or in a modal App window. Apps of this kind are displayed in the IMatch AppManager and in the drop-down app list in App Panels.
`import`	This is an import app for importing data. IMatch integrates it into the Import & Export Panel.
`export`	This is an export app for exporting data. IMatch integrates it into the Import & Export Panel.
`import-export`	This is an app that can be used for import and export. IMatch integrates it into the Import & Export Panel.
`hybrid`	This app is integrated into the Import & Export Panel and also shows up in the App Manager. Note: If you mark an app as hybrid you have to write it so it handles both the execution via the Import & Export panel (`IMatch.getDropContext()` returns with result = 'ok') and execution via the App Manager (IMatch.getDropContext() fails).
`service`	This app is a Service App and runs in the background. It is automatically started by IMatch during the startup process and terminated during the shut-down process. By default, service apps are invisible and do not interact with users. There are endpoints in IMatch which allow you to hide the usually invisible host window, for testing purposes. You can also debug service apps in your browser, like any other app. If you use the Chrome browser, you can even attach at runtime to your service app, to see what it is doing. The size of the service app window is 320x200 pixel by default. You can change this via the `windowSizing` parameter.

If no value is specified, "app" is assumed.

supportsDrop For Import/Export apps only. If this is true, the app can handle dropped objects.
See Import and Export Apps for more information.

defaultDocument The name of the html file to load when this app is started.
If this is not specified, the App Manager checks for index.html, index.htm, default.html and default.htm. If none of these documents is found, the app is not loaded and an error is written to the application log file.

author String or array of strings with the names of the script authors. This information is displayed in the AppManager panel.

title An object with language-specific titles for the app. The title is used in the AppManager Panel.
Tip: Use a short, one-word title for your app so it fits on-screen in the smaller icon modes.

name

An object with language-specific names for the app. The name is displayed in the AppManager Panel **if no title is available**.
The format is "lang" : "value" where lang is either "" for the neutral language or a standard ISO language code like "en" or "de".
When running an app, IMatch checks for the app name in the same language used for the IMatch user interface. If no match is found, IMatch falls back to the neutral "" language or "en" if no neutral language name exists.
Example:

"name": 
    {
        "": "Map Panel",
        "en": "Map Panel",
        "de": "Karten-Panel"
    },
    ...

description A description for this app. This description is displayed in the AppManager Panel. Supports language-specific descriptions in the same format as name.

icon An optional icon in PNG format. Recommended size is at least 256x256 pixels. Transparencies are supported.
IMatch displays this icon in the App Manager and various other controls. If no icon is specified, a stock icon is used.
Icons can be language-specific, using the same format as name.

runAs

This option controls how the app is run by the App Manager. Supported values are:

Value	Description
`default`	The App runs in an App Panel.
`modal`	The App runs in a separate app modal window. This kind of app is ideal for apps which need to present a dialog to the user or which need to block the IMatch user interface while running. For modal apps you also need to specify `windowSizing` options.

windowSizing

Mandatory for model apps. This is an object with the following elements:

Element Description

sizing

This value controls how the user can resize the modal app window. The following values are supported:

Value	Description
`none`	The user cannot resize the modal app window.
`both`	The user can change the width and height of the modal app window.
`width`	The user can change the width of the modal app window.
`height`	The user can change the height of the modal app window.
`ewsNoneNoCaption`	For special purposes only. The user cannot resize or move the modal app window. No caption bar is used for the window. The only way to close the modal window is Ctrl+F4 or via buttons/commands provided by the app itself. The window is automatically centered relative to the IMatch application window.

width

The (initial) width of the modal app window in pixel. If the app window is resizable, the user can change the width and IMatch automatically saves and restores the user-controlled width in future sessions.

The following formats are supported:

Format	Type	Description
Pixel	Number	The width (or minimal width if resizable) in pixel. Example: `"width": 600` Width: 600 pixel.
Percentage{,minimal width}	String	The width as a percentage of the screen width. Optionally add a minimal width in pixel. Example: `"width": "50"` 50% of the screen width. `"width": "50,800"` 50% of the screen width, minimum 800 pixel.

height

The (initial) height of the modal app window in pixel. If the app window is resizable, the user can change the height and IMatch automatically saves and restores the user-controlled height in future sessions.

The following formats are supported:

Format	Type	Description
Pixel	Number	The height (or minimal height if resizable) in pixel. Example: `"height": 600` Height: 600 pixel.
Percentage{,minimal height}	String	The height as a percentage of the screen height. Optionally add a minimal height in pixel. Example: `"height": "50"` 50% of the screen height. `"height": "50,600"` 50% of the screen height, minimum 600 pixel.

allowRefresh Version 2017.6.8
If this option is specified as true, pressing F5 in an app no longer causes a refresh/reload.
This option can be used to prevent the user from accidentally reloading an app.

handleF1 Version 2020.3.6
By default, IMatch handles the F1 key automatically and opens the help system when the user presses this key. If your app has a custom handling for F1 and you don't want IMatch to handle F1 while the app is focused in an App Panel, set this to true.

modalAllowClose For modal apps only. Version 2017.6.8
By default, IMatch allows the user to close modal apps at any time using the X button in the caption bar or the Alt + F4 keyboard shortcut.
If this option is specified as true, IMatch displays a message box, asking the user to confirm closing the app.
This option should be used if it is problematic for an app to be closed in mid-run. It has no effect on the IMatch.modalClose function.

modalNoClose For modal apps only. Version 2021
If this option is set to true, the Close command in the system menu, the [X] button in the caption and the Alt+F4 keyboard shortcuts are disabled. This option should be used very carefully, because if the app fails to provide a way to close the modal, the user will be stuck.
This has no effect on IMatch.modalClose function.

ignoreChanges

IMatch monitors the app folders for changes and automatically reloads apps when you make changes to them in your editing environment.
This is very convenient because your changes are immediately visible and all apps are up-to-date all the time.

However, if your app manipulates files in its own folder (e.g., configuration or data files), this can interfere with you using the app. Because IMatch reloads the app every time your app makes changes to the file system inside the app folder.

To prevent this, use this member to specify an array or folder / file name patterns to ignore.

Example:

Ignore all changes in the data folder inside the app's folder:

"ignoreChanges" : [
    "data\\.*"
]

linkPoints

Version 2019
Link points allow you to link (display) your app in IMatch menus and toolbars. This makes it easier for the user to run your app. App can be included in multiple menus/toolbars by specifying multiple link points.

Supported Link Points

The following link point types are supported:

Type	Your App shows in
`database`	Database menu
`databaseTools`	Database > Tools menu
`commands`	Commands menu
`search`	Search menu
`tools`	Tools menu
`fileWindow`	All File Window context menus
`fileWindowMediaFolders`	In the Media & Folders File Window context menu
`fileWindowCategories`	In the Categories File Window context menu
`fileWindowEvents`	In the Event View File Window context menu
`fileWindowPeople`	In the People View File Window context menu
`fileWindowCollections`	In the Collections File Window context menu
`fileWindowTimeline`	In the Timeline File Window context menu
`fileWindowResults`	In Result Windows
`treeMediaFolders`	In the Media & Folders tree control context menu
`treeCategories`	In the Categories tree control context menu
`treeCollections`	In the Collections tree control context menu
`treeTimeline`	In the Timeline control context menu
`toolbarFileWindow`	In all File Window toolbars
`toolbarFileWindowMediaFolders`	In the Media & Folders File Window toolbar
`toolbarFileWindowCategories`	In the Categories File Window toolbar
`toolbarFileWindowCollections`	In the Collections File Window toolbar
`toolbarFileWindowTimeline`	In the Timeline File Window toolbar
`toolbarFileWindowResult`	In the Result Window toolbar

Syntax


"linkPoints" : {
    "database" : {
        "name": {
            "en": "Run My Cool App...",
            "de": "Meine coole App ausführen..."
        }
    },
    "fileWindow" : {
        "name": {
            "en": "Run My Cool App...",
            "de": "Meine coole App ausführen..."
        }
    }
}

This causes IMatch to link the app in both the Database menu and all File Window Context menues

The name element is required and defines the command text used in the menu. For apps included in File Window toolbars, the app description is used as the tooltip.

IMatch starts apps from menus and the toolbar as if they were started from the App Manager. This means the app is either loaded into an App Panel or runs as a modal app.

Modal or Normal Apps?

Normal apps run in an App Panel. As soon as a user loads a normal app into an App Panel, it becomes active and needs to display 'something'. It can also monitor IMatch and IMWS messages and react.

A modal app opens in a separate window and blocks the IMatch user interface. Very similar to a dialog box. This type of app is ideal for apps which do some sort of 'processing' or which need to display a dialog to which the user has to respond before the app an continue.

Responsive Design

You should always design your apps to be responsive. This means that your app automatically adapts to different screen sizes, App Panel or modal app window sizes. CSS frameworks like Bootstrap or similar help you with that. The IMatch AppWizard by default includes the Bootstrap CSS library for a responsive design.
Use fixed-size modal app windows only for very specific purposes.