IMatch and IMatch WebServices™

Copyright 1998-2022 Mario M. Westphal & photools.com.
Version: 2021.16.2

This documentation covers the IMatch and IMWS class libraries which provide convenient wrappers for functionality provided by IMatch for Windows and IMatch Anywhere WebServices™.

Tutorials, Code Recipes & Tips

The Code Recipes page contains many examples you can copy/paste right into your code. It also explains about the common pitfalls and problems you might run into.

IMWS and IMatch

When you write apps for IMatch, you use API endpoints provided by the embedded IMWS running in IMatch. These endpoints give your app access to the IMatch database, metadata, files, folders, categories and more. The embedded web server running in IMatch offers the same functionality as the stand-alone IMatch WebServices™ product included in IMatch Anywhere™ - but it only allows access from same computer IMatch is running on.

IMatch adds additional API endpoints which enable your app to access file window contents, open dialog boxes and other user interface feaures. Although these are implemented as web service endpoints, you often don't access them directly. Instead you use them comfortably via the methods provided by the IMatch JavaScript Library.

IMWS

This class is used to access functionality provided by IMatch WebServices (IMWS). It is a very thin layer, only containing some convenience functions and constants which make it easier to work with IMWS.

Include File: <script src="/system/imws/imwslib.js"></script>

IMWS Methods and Functions

Integrated IMWS Documentation

IMWS documents itself via the /discover endpoint. This endpoint returns a JSON object which explains every endpoint available. You can use the IMatch WebServices™ Documentation app included in IMatch to browse the IMWS documentation comfortably. In IMatch WebViewer™ you can review the documentation via the Discover IMatch command in the Gear menu.

IMatch

This class is used to access functionality provided by IMatch for Windows. This includes features like dialog boxes to select files, folders, categories or collections, routines to access the local file system and handling of IMatch events like 'selection in file window has changed'.

Include File: <script src="/system/imatch/imatchlib.js"></script>

IMatch Methods and Functions

Developer Mode

Under Edit > Preferences > Application: Developer Options you can enable the developer mode. This is just a flag that is available to every app via the imatch/info endpoint or the corresponding method in the IMatchLib class. The setting is returned in the developerMode element.

Use this flag to enable/disable features, logging and other functions in your app, depending on whether the app runs on your PC (with developer mode enabled) or on the PC of a regular user.

Example:

// During the startup of your script, fetch information about IMatch.
IMatch.IMatchInfo().then(response => {
    IMatchInfo = response;
    if (IMatchInfo.developerMode) {
        // You can now use this throughout your code to do things.
        console.log('We are running in developer mode!');
    }
});

In this mode, the App Manager in IMatch also displays the sample apps included with IMatch. In the normal user mode, these apps are hidden from view.

The /userdatafolder/

This special URL has an URL rewrite attached that points to %APPDATA%\photools.com\IMatch6.
You can use this special URL to access files and other resources provided by the user in his/her user data folder.

For a hypothetical user named DONALD, the URL

/userdatafolder/imws/mystyles.css

is internally translated to access the physical file

C:\Users\DONALD\AppData\Roaming\photools.com\IMatch6\imws\mystyles.css

on the user's machine.
This makes it very easy to include user-supplied resources in apps.

IMatchTranslate

This helper class is used to translate IMatch apps into multiple languages. It uses external resource files and has some nifty features which makes translating entire apps a snap.

Include File: <script src="/system/imatch/imatch-translate.js"></script>

IMatchTranslate Methods and Functions

IMatchModals

This helper class makes it easy to work with Bootstrap modal windows and external HTML templates.

Include File: <script src="/system/imatch/imatch-modals.js"></script>

IMatchModals Methods and Functions

IMatchFileWindow

This base class wraps the functionality of IMatch File Window Apps.

Include File: <script src="/system/imatch/imatch-filewindow.js"></script>

The IMatchFileWindow Class

WebSockets : How IMatch and IMWS Speak to Your App

IMatch and IMWS send messages to apps and scripts via websockets. This allows these modules to communicate events like file window selection changed or category modified to interested apps.
If your app needs to know when something happens, it just needs to open a websocket and start listening.

Handling IMatch messages.
Handling IMatch WebServices™ messages.

The App Wizard

The App Wizard is an app that enables you to create new apps easily. It automatically creates the folders, basic HTML and app.json file for you. Just add HTML and code. You'll find it in the App Manager panel in IMatch.

App Configuration

All apps are configured via their app.json JSON configuration file. This file is created when you create the app via the App Wizard app included in IMatch. See the Structure of app.json files for more information.

Modal and Regular Apps

IMatch can run apps in app panels / views and in modal windows. A modal window is similar to a dialog box. It blocks the IMatch user interface until the user closes the modal window.
This kind of app is ideal for things like import processes, batch updates of metadata.

The mode of an app is configured in the app.json configuration file for the app. Set the runAs to "modal" when you create your app in the App Wizard.

Service Apps

Service apps run in the background and don't provide a user interface. IMatch starts them automatically during the startup process and terminates them during shut-down.
Service apps are ideal to run code in the background, e.g., while monitoring IMatch or IMWS events.

To make an app run as a service, set the type element to service in the app.json:
"type" : "service"
IMatch provides a number of endpoints to control service apps. See IMatch Methods and Functions for more info.

Usually you will write your service app to monitor IMWS/IMatch events and then to perform operations when interesting events are received.

Important

Note that IMatch never waits for service apps during shut-down. Your app is responsible for shutting down cleanly.

A bad service app can severely interfere with normal IMatch operations. It is your responsibility to write your app as cooperative as possible.

Service App Security

Since service apps run in the background, IMatch asks the user for permission when a service app is launched for the first time.
IMatch protects service apps via a checksum and asks the user again when the service app has changed.

Developer Mode

While working on a service app, the developer should enable the developer mode under Edit > Preferences > Application in IMatch to avoid being prompted after every modification to the app.

Example App

IMatch includes an example for a service app in the C:\ProgramData\photools.com\IMatch6\webroot\imatch\samples\service-app folder. This app logs some output to the console every 5 seconds as long as IMatch is running.
The app is disabled by default. To enable it, rename the _app.json to app.json and then start IMatch.
 

Adding Apps to IMatch Menus

Apps can be integrated directly into selected menus, including the Database, Tools and File Window menus. You can include your app into several menus to make it easy to reach from all contexts.
To add your app to one or more menus, add a linkpoint` section to the app.json file of your app.

For more information, see the corresponding section in the app.json JSON configuration file tutorial.

File Window Apps

File Window Apps allow you to create new File Window layouts. The content shown by App-driven File Window layouts is controlled entirely by the File Window App. IMatch takes care for managing the scope and the File Window toolbar, updating panels etc.

File Window Apps allow developers to create new representation and interaction concepts for folders, categories, collections and the timeline.

View Apps

View apps are added by IMatch to the existing views (Media & Folders, Categories, ...) and can be activated by the user via the View menu in IMatch.

View apps cover the entire workspace area (except the space occupied by panels). Views are free to work with all the data contained in IMatch databases.

Tutorials

Click on Tutorials link in the menu bar at the top of this page to see all available tutorials.

Examples

IMatch ships with a large number of example apps which demonstrate the use of any important function and endpoint.
You can find all samples and apps shipped with IMatch in the App Manager panel.
Most examples are designed to demonstrate a related set of functions. Each sample is fully documented via comments in the source code. Open the samples in your code editor to see the comments.

IMatch Developer Center

The IMatch Developer Center contains tutorials, resources, tools and examples for IMatch and IMWS programming.

The photools.community

The photools community has a dedicated board for questions and discussions related to IMatch and IMWS programming.