IMatch Documentation

Class: IMatch

IMatch

This class gives access to methods implemented by IMatch. These methods complement the methods of the IMWS class.

Embedded vs. External

The majority of functions has been implemented as endpoints for the IMatch WebServices embedded in IMatch. This makes it possible to test and debug apps in external web browsers. These function return a standard Promise object.

Certain functions require specific IMatch functionality that is only available for apps running embedded in IMatch (e.g., in an app panel). These are marked with an embedded badge below.
If you need to use these functions from a browser, you need to simulate their functionality in your code somehow. You can use the isEmbedded function to test if your app is running in a web browser or embedded in IMatch.

The Global IMatch object

When you include this library in your code, a global IMatch object is automatically created.
You can access all functionality with IMatch.<Function Name>.

IMatch WebServices™ (IMWS)

To write an app you combine functions provided by IMatch itself with functions provided by the IMWS embedded in IMatch. The embedded IMWS provides all features that are also available in the standalone server product.
For efficient access to IMWS features you can use the IMatch WebServices Interface Class shipped with IMatch.

new IMatch()

Members

ERROR_CODES :number

Enum for IMatch error messages. These error codes are returned in the JSON reponse as part of HTTP status codes <> 200 OK.
Note: Not all error responses contain additional JSON data. Always check for the existence of a JSON body via
error.responseJSON (if you use jQuery) or similar libraries.

Type:
  • number
Properties:
Name Type Default Description
IMATCHWS_ERR_CODE_DIALOG_OPEN number 5000

Another dialog window or message box is already open. Only one dialog can be open at a time.
IMATCHWS_ERR_CODE_DIALOG_OPEN number 5100

Command failed. See details in the response for more information.
IMATCHWS_ERR_CODE_RESULTWINDOW_OPEN number 5200

Failed to open a result window. IMatch may be in the wrong state to open a result window.
IMATCHWS_ERR_CODE_RESULTWINDOW_NOTFOUND number 5201

Result window does not exist. This error is returned when a result window no longer exists but
an app tries to update it via its instanceId.
Example
IMatch.callFunction('v1/method').then(response => {
    ...
},error => {
    if (error.responseJSON && (error.responseJSON.error.code == IMatch.ERROR_CODES.IMATCHWS_ERR_CODE_DIALOG_OPEN)) {
    }
});

idlist :String

This enum defines the names of pre-defined idlists you can use in your code. These idlists are dynamic and automatically kept up-to-date by IMatch. You can use these names with the idlist parameter in all endpoints which accept an idlist, e.g., /files.

Type:
  • String
Properties:
Name Type Default Description
fileWindowSelection String @imatch.filewindow.active.selection

This idlist contains all files currently selected in the active file window.
fileWindowFocusedFile String @imatch.filewindow.active.focusedfile

This idlist contains the currently focused file in the active file window.
fileWindowFiles String @imatch.filewindow.active.files

This idlist contains all files in the active file window (after filters and the search bar have been applied).
The ids in the list are sorted using the currently active sort profile in the active file window.
This is what the user 'sees' in the file window.
Files hidden by a collapsed stack are removed.
fileWindowFilesTotal String @imatch.filewindow.active.files.total

This idlist contains all files in the active file window (before filters and the search bar have been applied).
The ids in the list are sorted using the currently active sort profile in the active file window.
Files hidden by a collapsed stack are removed.
If the file window displays multiple groups (e.g. multiple folders) the unique file ids of all groups are combined and then sorted.
If you want to retain the group order, choose an appropriate sort profile or use the file window group operations.
selectedFolders String @imatch.selectedFolders

This idlist contains the ids of all selected folders.
selectedCategories String @imatch.selectedCategories

This idlist contains all currently selected categories.
selectedCollections String @imatch.selectedCollections

This idlist contains all currently selected collections.
selectedTimelineNodes String @imatch.selectedTimelineNodes

This idlist contains all currently selected timeline nodes.
allFiles String @IMWS.allfiles

This idlist contains all files in the database.
Example
// Retrieve the id and file name for all files currently selected in the file window:
 IMWS.get('v1/files' {
     idlist: IMatch.idlist.fileWindowSelection,
     fields: 'id,filename'
}).then ...

DEFAULT_WS_URL

If you use this class from an external web browser (IMatch#isEmbedded == false) you can use this default URL to connect to the IMatch websocket.
The default is ws://127.0.0.1:50519
Change the port number as needed for your environment (see: Edit > Preferences > Application).
Using this constant and managing the hard-coded URL for development purposes makes it easier to maintain.

Example
if (IMatch.isEmbedded()) {
     IMatch.openWebSocket();
}
else {
     // If this runs in a browser, we assume that IMatch listens
     // on the default IP address and port.
      IMatch.openWebSocket(IMatch.DEFAULT_WS_URL);
}

DEFAULT_URL

If you use this class from an external web browser (IMatch#isEmbedded == false) you can use this default URL to connect to IMatch.
The default is http://127.0.0.1:50519
Change as needed for your environment.
Using this constant and managing the hard-coded URL for development purposes makes it easier to maintain.
Note If you run the app 'on' the IMatch web server, you don't need to specify an URL.

Methods

isEmbedded() → {Boolean}

This method determines if the script is running embedded in IMatch or in an external web browser.
If an app is running inside IMatch, it has access to some additinal features, methods and properties provided by the app environment in IMatch.
These functions and properties are indiciated by the embedded badge in this documentation.

Returns:

true if the script is running inside an App Panel or View in IMatch.

Type
Boolean

instanceId() → {string}

embedded
Determines the instance identifier of the script.
The instance id is used for authentication purposes.

Returns:

instance id or an empty string if the script is not running inside IMatch.

Type
string

appId() → {String}

embedded
Determines the id (from the app.json file) of the currently running app.
This only works when the script is running embedded in IMatch.

Returns:

App id or an empty string if the script is not inside IMatch.

Type
String
Example
// Output the id of the app to the JavaScript console
console.log(IMatch.appId());

IMWSUrl() → {String}

embedded

Returns:

The URL of the embedded IMWS in IMatch.
If this function is called from a web browser, an empty string is returned.

Type
String

getImageUrl(id, size)

Returns the image url (for the src= attribute) for the specified file.

Parameters:
Name Type Description
id Number

The id of the image
size String

The image size to return, e.g. 'dbthumbnail', 'imatchcache' or 'MEDIUM'. See /v1/files for more information.

processId() → {String}

embedded
Returns the process id of the browser host process.

Returns:
Type
String

langId() → {String}

embedded
Returns the lang id ('en','de',...) for the current IMatch session.

Returns:
Type
String

authToken() → {String}

embedded
Returns the auto_token of the current session.

Returns:
Type
String

IMatchInfo() → {Promise}

embedded
Returns information about IMatch, the used Chromium and CEF versions, the location of some special folders, the platform (32- or 64-bit) and more.

Returns:
Type
Promise

IMWSWebSocketUrl() → {String}

embedded

Returns:

The URL of the web socket for the embedded IMWS in IMatch.
If this is called from an external web browser, an empty string is returned.

Type
String

modalClose()

This function closes a modal window. Use this e.g., to present a 'Close' button in your modal window.
Note: The user can close modal windows always with the X button in the caption bar.
Note: The function has no effect if the app is not running in a modal window.
returns {Promise} The function does not return any useful result.

Example
// Bind a handler function to the button with the id *btn-close*
// and close the modal window when the user clicks the button.
$('#btn-close').click(function() {
     IMatch.modalClose();
});

modalDisableClose(disable)

Enables or disables the ability for the user to close a modal window.
If the user cannot close it, the app MUST provide a way to close the modal (e.g. a button to call modalClose)
This endpoint should only be used when needed, because when the app crashes or fails to provide a way to
close the modal, the user must forcefully shut-down IMatch!

Parameters:
Name Type Description
disable *

Boolean Enable/Disable the close

modalGetWindowRect() → {Promise}

This method determines the position and size of the modal window.

Returns:

A JSON object with the window position and dimensions.
If this script is not running in a modal window, an error is returned.

Type
Promise

modalSetWindowRect(rect) → {Promise}

This function changes the window position and size of a modal window.
Note: IMatch automatically stores and restores the size and position of modal app windows
if the windowSizing is not fixed.

Parameters:
Name Type Description
rect String

JSON object with left,right,top,bottom screen coordinates in pixels.
Returns:
Type
Promise

windowSetFocus() → {Promise}

This function sets the focus to the (modal) app window and makes it the active window.
This function has no effect when called from an external browser.

Returns:
Type
Promise

consoleClear()

Clear the IMatch Script output panel.
Use this insteac of the standard console.clear which is not yet supported by Chromium/CEF.

openBanner(params)

Open a banner in the IMatch notification area.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
html String

The HTML code to display in the banner. You can use standard CSS and
even animate.css styles.
str1 String

The optional Bootstep (4) class to use for the banner background
str1 String

The optional Bootstep (4) class to use for the X button
Example
IMatch.openBanner({
    html: '<h3>Hello World!</h3><p>More text in the second line.</p>',
    str1: 'bg-info text-dark',
    str2: 'text-dark',
});

// A warning, with animation
IMatch.openBanner({
    html: `<div class="animated slideInLeft"><h3>Hello World!</h3><p>More text in the second line.</p></div>`,
    str1: 'bg-warning text-dark',
    str2: 'text-dark',
});

localeInitMomentJS(userInfo)

Initialize moment.js globally for the locale to use for formatting.
The locale is either derived from userInfo.appLocale or userInfo.langId.

Parameters:
Name Type Description
userInfo Object

: The result of the IMatch.userInfo() endpoint. If this is undefined,
the browser language is used.

safeTagValue(value)

Returns an empty string if the provided value is undefined or null, else the value.
You can use this when you request tags from IMWS which may not contain values.

Parameters:
Name Type Description
value Object

get(endpoint, parameters) → {Promise}

This method takes the name of an endpoint (without leading /) and an optional parameter object.
It perform a GET request on this endpoint with the given parameters and returns a promise.

The method automatically performs authentication using config.auth_token. You don't need to specify the auth_token parameter.

Parameters:
Name Type Description
endpoint string

The endpoint to call. Include the version number as needed.
parameters object

Optional parameters to send to IMWS.
Returns:

a promise object

Type
Promise
Example
// Calls the imatch/user/info endpoint to retrieve data about the IMatch user.
IMatch.get('v1/imatch/user/info').then(function(response) {
     console.log(response.userName);
});

post(endpoint, parameters) → {Promise}

This method takes the name of an endpoint (without leading /) and an optional parameter object.
It perform a POST request on this endpoint with the given parameters and returns a promise.

The method automatically performs authentication using config.auth_token. You don't need to specify the auth_token parameter.*

Parameters:
Name Type Description
endpoint String
parameters Object

Optional object with parameters to send to the server.
Returns:
  • A promise object that is resolved once the server has responded.
Type
Promise
Example
// Call an endpoint which requires the POST method:
IMatch.post('name of endpoint', ...)

delete(endpoint, parameters) → {Promise}

This method takes the name of an endpoint (without leading /) and an optional parameter object.
It perform a DELETE request on this endpoint with the given parameters and returns a promise.

The method automatically performs authentication using config.auth_token. You don't need to specify the auth_token parameter.

Parameters:
Name Type Description
endpoint String
parameters Object

Optional object with parameters to send to the server.
Returns:
  • A promise object that is resolved once the server has responded.
Type
Promise
Example
// Call an endpoint which requires the DELETE method:
IMatch.delete('name of endpoint', ...)

webSocket() → {WebSocket}

This function gives access to a web socket that allows your script to exchange
messages with IMatch/IMWS and to receive information about events or changes made
to the database.

The socket can been opened with IMatch#openWebSocket.

Returns:

or null if no web socket has been opened yet.

Type
WebSocket

fileWindowAppSocket() → {WebSocket}

This function gives access to a web socket that allows your File Window App to exchange
messages with IMatch and to receive information about events related to file windows.

The socket can been opened with IMatch#openFileWindowAppSocket.

Returns:

or null if no web socket has been opened yet.

Type
WebSocket

openWebSocket(url, onConnectedCallback)

Open a web socket for the /imatch url. The socket can then be used to send and receive messages from IMatch.
This method automatically authenticates the socket after creating it.
If this is called from an app hosted in IMatch (not in a browser) you can call this function without parameter.
Otherwise specify the full URL and port, e.g. 'ws://127.0.0.1:50519' or use the IMatch.DEFAULT_WS_URL constant.
Use IMatch.webSocket().onmessage(function(e) { ... }) to listen to evens afterwards.
IMatch messages documentation

Parameters:
Name Type Description
url String

Optional. The url for the socket.
onConnectedCallback function

Optional. The callback to call when the socket has been opened and authorized.

openFileWindowAppSocket(url, instanceId)

Open a web socket for File Window apps.
If this is called from an app hosted in IMatch (not in a browser) you can call this function without parameter.
Otherwise specify the full URL and port, e.g. 'ws://127.0.0.1:50519' or use the IMatch.DEFAULT_WS_URL constant.
Use IMatch.webSocket().onmessage(function(e) { ... }) to listen to evens afterwards.

Parameters:
Name Type Description
url String

Optional. The web socket Url to connect to. You can use IMatch.DEFAULT_WS_URL if you are calling this from an external browser.
instanceId String

Optional. The file window instance id. Set this to the instance if of the file window to monitor. 1, 2, 3 , ...

userInfo() → {Promise}

Retrieve info about the user. Name, language etc.
/imatch/user/infoendpoint.

Returns:
Type
Promise
Example
// Retrieve the name, UI language etc. for the current IMatch user:
IMatch.userInfo().then(function(response) {
  console.log(JSON.stringify(response,null,2));
});
// The resulting output looks like this:
{
     "result": "ok",
     "userName": "Mario",
     "langId": "en-US"
 }

getSelectedFiles() → {Promise}

Get the selected files in the active file window. Use this if you need to work with the idlist directly.
The function calls the /idlist endpoint with the IMatch.fileWindowSelection name for the idlist parameter.

Returns:

A promise that is resolved once IMatch has responded.

Type
Promise
Example
// Retrieve the selected files in the file window and dump them into the browser console.
IMatch.getSelectedFiles().then(function(response) {
  console.log(JSON.stringify(response,null,2));
});

// The output looks like this:
{
  "size": 3,
  "index": 0,
  "id": [
      6393,
      6394,
      6395
  ]
}

getFocusedFile() → {Promise}

Get the focused file in the active file window. Use this if you need to work with the idlist directly.
The function calls the /idlist endpoint with the IMatch.fileWindowFocusedFile name for the idlist parameter.

Returns:

A promise that is resolved once IMatch has responded.

Type
Promise

fileWindowState(instanceId) → {Promise}

Retrieves information about the state of the specified file window.

ElementDescription
contentTypeThe type of content the file window is displaying: db, disk, media, folder, category, collection, timeline, result.
contentIdThe id of the content (folder id, category id, ...). Together with the contentType this makes each scope unique.
titleThe title of the file window, as shown in the caption bar..
instanceIdThe instance id of the file window (.
pausedtrue when the file window is currently paused.
pauseThresholdPause threshold
filterActivetrue if the filter panel is active and has at least one active filter.
searchBarActivetrue if the contents of the file window are restricted by the search bar.
sortprofileThe name of the selected sort profile.
levelsThe level setting. 0:Show all levels, 1..n: Show 1 to n levels.
levelsEnabledtrue when level display is enabled.
Parameters:
Name Type Description
instanceId number

The optional instance id of the file window to query. If not specified or 0, the active file window is used.
Returns:

If the promise resolves, the returned JSON object contains information about the current state of the file window.

Type
Promise

fileWindowPaste(params)

Performs a clipboard paste operation in the current file window.

Parameters:
Name Type Description
params Object

A parameter object

Properties
Name Type Description
mode String

'copy' or 'paste'
id String

A list of file ids, separated by ,

fileWindowReload()

Reloads the active file window.

fileWindowListLayouts()

Returns a list with information about file window layouts.

fileWindowSetLayout(instanceId, layout)

Sets a new layout for the specified file window

Parameters:
Name Type Description
instanceId Number

The instance id of the file window
layout String

The name of the layout to load

selectFiles(params) → {Promise}

This function allows to change the selection in the active file window.

Parameters:
Name Type Description
params Object

This object controls which files are selected.

Properties
Name Type Argument Default Description
id= Array <optional>

Comma-separated list of file ids. These files are selected. To un-select all files, specify an empty list.
idlist= String <optional>

Name of the idlist containing the files to select. Either id or idlist must be specified. If none is specified, the selection is reset.
focus= Number <optional>

The id of the file to focus. If not specified, the current focus is not changed. If this is given as 0, the focus is removed.
combine Boolean <optional>
 false

If this is specified as true, the files specified here are combined with the existing selection.
See:
Returns:
Type
Promise
Examples
// Select the files 1,2,3. An existing selection is removed. Focus the file 1.
IMatch.selectFiles({
     id '1,2,3',
     focus: 1
});
// Select the files 4,6,200 in addition to files already selected. The focused file is not changed.
var params = {
     id: '4,6,200',
     combine: true
}
IMatch.selectFiles(params);

// Tip: If you have an array of file ids, use join(','): 

var params = {
     id: myFileArray.join(','),
     combine: true
}

focusFile(params) → {Promise}

This function changes the focused file in the active file window.

Parameters:
Name Type Description
params Object

The id of the file to focus. If this is 0, the focus is removed.

Properties
Name Type Argument Default Description
id Number

The id of the file to focus. If this is 0, the focus is removed.
select Boolean <optional>
 true

If true, an the specified is focused and selected.
resetselection Boolean <optional>
 false

If true, an existing selection is removed.
ensurevisible Boolean <optional>
 true

True to scroll the focused file into view.
See:
Returns:
Type
Promise

appInfo(params) → {Promise}

Returns information about an app.
Either appid or instanceid must be specified in params.

Parameters:
Name Type Description
params Object

Login data

Properties
Name Type Description
appid String

The id of the app (from the app.json configuration file. See IMatch#appId
instanceid String

The instance id of the app. See IMatch#instanceId
Returns:
Type
Promise
Example
// Retrieve information about the current app. This works only when the script is running inside IMatch.
     IMatch.appInfo({
         appid: IMatch.appId()
     }).then(function(response) {
         console.log(JSON.stringify(response.app,null,2));
     });

appList() → {Promise}

Retrieves a list of all installed apps and information for each app.

Returns:
Type
Promise

appsReorder(params) → {Promise}

This method allows a script to change the order in which apps appear in the App Manager.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
appids array

The id of the apps in the order in which they should appear.
Returns:
Type
Promise

appRun(params [, query=]) → {Promise}

This function runs the specified app. If the app is a modal app, IMatch opens a modal window to run the app.
Otherwise the app is run in the active app panel.

Parameters:
Name Type Argument Description
params Object
Properties
Name Type Argument Default Description
appid String

The id of the app to run.
You get this from the appList or appInfo functions. Or look into the app.json file directly.
target String <optional>

Where to open the app.
If the app is configured as a modal, it will always be opened in a modal window.
Otherwise you can specify one of {app-panel-1 to app-panel-4} to open the app in a specific app panel (1 to 4).
The target app-panel-selected opens the app in the currently selected app panel. If no app panel is selected, it opens the app in app panel 1.
The targets model and modal-fixed open any app in a model app window. modal-fixed means that the user cannot resize the modal window.
If you specifcy a modal target, you also have to specify width and height.
width Number | String <optional>

Required for targets modal or modal-fixed. Width of the modal in pixel or as a percentage of the monitor width.
Specifiying the width/height in percentages allows the modal app window to scale seamlessly to the physical screen size.



NumberWidth in pixel.
StringWidth as a percentage of the screen width: "50%".
StringWidth as a percentage of the screen width and a minimumn width in pixel: "50%,600".
height Number | String <optional>

Required for targets modal or modal-fixed. Height of the modal in pixel or as a percentage of the monitor height.



NumberHeight in pixel.
StringHeight as a percentage of the screen height: "50%".
StringHeight as a percentage of the screen height and a minimumn height in pixel: "50%,600".
allowstoresize Boolean <optional>
 true

For target = modal. The user can resize the modal, but the size will not be saved when this is set to false. Use this to always show the modal with a specific initial size.
query= String <optional>

An optional URLENCODED query string that is passed forward to the app. Don't use a ? at the beginning and url-encode the string properly using the encodeURI function. Example: param1=true&param2=Mike.
This parameter enables you to run an app and provide additional data. The app can access this data via the JavaScript URLSearchParams class or by other means.
Returns:
Type
Promise
Example
// Run the VarToy app
IMatch.appRun({
   appid: 'photools.com.IMatch.VarToy',
   target: 'app-panel-selected',
});

// Run the VarToy App in a resizable modal window
IMatch.appRun({
   appid: 'photools.com.IMatch.VarToy',
   target: 'modal',
   width: 600,
   height: 800,
});

appSetResult(params)

Remember a result for the specified app for the current session.
This can be used, for example, if one app runs another app and needs to retrieve some kind of result or data package (JSON) from the other app.
IMatch emits the message "appmanager.appResult.set" via the web socket when an app sets the result.

NOTE: Results are only remembered for the current IMatch session. If IMatch shuts down, results are forgotten.
If you need to remember data across sessions, use the /data endpoint family.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
appid String

The id of the app to set the result for.
You get this from the appList or appInfo functions. Or look into the app.json file directly.
data String

The result data to remember for the current session.

sendAppMessage(params)

Send an app message over the IMatch message bus.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
message String

The message to send
param1 Number

1st numeric parameter, depends on message.
param1 Number

2nd numeric parameter, depends on message.
str1 String

1st string parameter, depends on message.
str2 String

2nd string parameter, depends on message.

appGetResult(params)

Retrieve the result set by another app.
The result is returned in the 'data' member in the response. If the app has not set a result, the returned data is empty.
NOTE: Results are only remembered for the current IMatch session. You cannot query app result from a previos session.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
appid String

The id of the app result to query.

refresh( [ignoreCache])

This function refreshes the app panel / view containing the current app, optionally ignoring the browser cache.
This can be helpful if the browser cache interferes with changes done to an app externally in an editor.
This function can only be used when the script runs in embedded mode and isEmbedded returns true. Else the function has no effect.

Parameters:
Name Type Argument Default Description
ignoreCache Boolean <optional>
 true

If this is true, the app is reloaded and ignoring the browser cache.

splitPath(fileName) → {Promise}

Split a path into its components (drive, dir, name, ext).
THis function uses the same method to split file names as used by IMatch internally.

Parameters:
Name Type Description
fileName String

The file name to split.
Returns:
  • If the promise is fulfilled, a JSON object with the individual file name parts.
Type
Promise
Example
var filename = 'c:\\images\\beach.jpg';
IMatch.splitPath(filename).then(function(response) {
  console.log(JSON.stringify(response));
});
// The resuult lokks like this:
{
     drive: "c:", 
     dir: "\images\", 
     name: "beach",
     ext: ".jpg"
}

createGUID() → {Promise}

Create a new GUID (Globally Unique Identifier). This can be useful if you want to uniquely identify things when working with the /data endpoints or for similar purposes.
Don't use this for mass GUID generation because each call requires an endpoint call.
This endpoint produces GUIDs in the nnnnnnnn-nnnn-nnnn-nnnnnnnnnnnnnnnnn format.

Returns:
Type
Promise

createGUIDs(numberOfGuids) → {Promise}

Create multiple GUIDs in one call.

Parameters:
Name Type Description
numberOfGuids Number

The number of GUIDs to produce (1-1000).
Returns:

The response contains an array with the requested GUIDs.

Type
Promise

normalizeString(str [, true]) → {String}

Normalize the string using JavaScripts normalize function and also replace
diacritics (UNICODE range U+0300 → U+036F) (see: https://en.wikipedia.org/wiki/Combining_Diacritical_Marks).
Use the result for string compares which ignore diacritics.

Parameters:
Name Type Argument Description
str String

The string to normalize
true Boolean <optional>

lc If this is true, the returned string is transformed to lower-case.
Returns:
Type
String
Example
normalizeString('hotel') == normalizeString('hôtel')

fileBrowserFS(params) → {Promise}

This function displays a standard Windows file system file browser dialog. It can be used to allow the user to select a file in the file system.
**Tip: ** Store the returned folderName in a variable and use it as the initialFolder when you call this function again.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
type String <optional>
 open

Values: 'open' : file open dialog, 'save' : file save dialog.
title String <optional>

The title/prompt to display in the dialog.
initialdir String <optional>

The initial directory to select in the dialog. If this is not specified, Windows selects the initial folder. If you specify a fully-qualified file name, only the path portion will be used.
filename String <optional>

The initial file name and extention to use in the dialog. If you specify a fully-qualified file name, only the name and extension will be used.
filter String

A list of file masks, separated by | and terminated by ||.
Example: Text Files (.)|.txt||
Example: Text Files (.)|.txt|JSON Files (.json)|.json|All Files (.)|.||
defext String

The extension to use when the user does not select one.
Returns:

On success returns a JSON object in this format:

{
    "result" : "ok" or "cancelled"
    "fileName" : Fully-qualified file name including folder name
    "folderName" : The fully qualified folder name.
}
Type
Promise
Example
// Let the user select a text file.
IMatch.fileBrowserFS({
     type: 'open',
     title: 'Please select a file:',
     filter: 'Text Files (*.txt)|*.txt|All Files (*.*)|*.*||'
}).then(function(response) {
     console.log(JSON.stringify(result,null,2));
});

fileInfo(fileName) → {Promise}

This function returns information about a file in the file system.

Parameters:
Name Type Description
fileName String

The name of the file you want to retrieve information for.
Returns:
Type
Promise
Example
// Query information about the file c:\TEMP\test.txt. 
// Don't forget to use \\ instead of \. \ has a special meaning in JavaScript.
IMatch.fileInfo('C:\\TEMP\\test.txt').then(function(response) {
    console.log(JSON.stringify(response,null,2));
});

readTextFile(params) → {Promise}

This function reads a text file from the local file system and returns the file system contents in a string.
With this function you can easily read and process text files. It supports files with several megabytes of text, which is more than sufficient for virtually all script purposes.
The JSON response includes the result code, the mime type of the file and the contents of the file as a string in the data member.

Parameters:
Name Type Description
params Params
Properties
Name Type Description
filename String

The name of the file to read.
Returns:
Type
Promise
Example
// Read the contents of the file c:\TEMP\test.txt. 
IMatch.readTextFile({
    filename: 'C:\\TEMP\\test.txt'
}).then(function(response) {
    console.log(JSON.stringify(response,null,2));
});

writeTextFile(params) → {Promise}

This method writes data to a (text) file. The data can be of any length.
Use this to update or create files in text, JSON or XML formats. The default UTF-8 format is usually best for maximum portability.
The function automatically writes a byte order mark for all files not stored in UTF-8 encoding.

If data is appened to an existing file, the specified encoding must match the encoding of the file. Append can be used when a script produces very large text files and it is not possible to hold all the data in a string at once.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
filename String

The name of the file to writes. If the file does not exist, it is created. Existing files are overwritten.
data String

The data to write.
encoding String

(Optional). The file encoding to use. The default is utf-8. Supported are also: 'ascii', 'utf-16-le', 'utf-16-be'.
append Boolean

(Optional). If this parameter is specified as true, an existing file is not replaced. Instead the new data is appended to the existing data in the file.
Returns:
Type
Promise
Example
// This code fragment creates a new HTML file in c:\temp\test.html. You can open the file in your browser afterwards.
IMatch.writeTextFile({
   filename: 'C:\\TEMP\\test.html',
   data: '<!DOCTYPE html><html><head><title>Hello World.</title></head><body><h1>Hello World.</h1></body></html>'
}).then(function(response) {
   console.log(JSON.stringify(response,null,2));
});

fileCopy(params) → {Promise}

This method copies a file in the file system.
Note This will not update the database. Don't use this function to copy files indexed in an IMatch database.
Use the corresponding endpoints provided by IMatch WebServices instead.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
source String

The fully-qualified name of the file to copy.
target String

The fully-qualified target file name. If a file with that name already exists, it is replaced.
failifexists Boolean

(Optional). If this parameter is specified as true and the destination file exists, the function fails.
Returns:
Type
Promise

fileMove(params) → {Promise}

This method moves a file in the file system.
Note This will not update the database. Don't use this function to move files indexed in an IMatch database.
Use the corresponding endpoints provided by IMatch WebServices instead.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
source String

The fully-qualified name of the file to move.
target String

The fully-qualified target file name. If a file with that name already exists, it is replaced.
failifexists Boolean

(Optional, default: false). If this parameter is specified as true and the destination file exists, the function fails.
Returns:
Type
Promise

fileDelete(params, params) → {Promise}

This method deletes a file in the file system.
Note This will not update the database. Don't use this function to delete files indexed in an IMatch database.
Use the corresponding endpoints provided by IMatch WebServices instead.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
filename String

The name of the file to delete.
recycle Boolean

(Optional, default: true). By default, the deleted file is moved into the Windows recycle bin (unless the file is to big and Windows cannot move it into the recycle bin). Set this to false to truly delete the file.
params any
Returns:
Type
Promise

fileCreateZIP(zipFileName, sourceFiles) → {Promise}

This method creates a ZIP file from the given source files.
Use this method to quickly zip one or more files and store the resulting ZIP file in the file system.
All files are added to the top-level of the ZIP file. Sub-directories are not supported.

Parameters:
Name Type Description
zipFileName String

The fully qualified name of the ZIP file to create. Existing files will be overwritten.
sourceFiles Array

One or more fully-qualified file names. Use this to ZIP files external to the current database.
Returns:
Type
Promise
Example
// Create a ZIP file in c:\temp\imatch.zip and add for files:

files = [
    'C:\\ProgramData\\photools.com\\IMatch6\\webroot\\system\\imatch\\imatchlib.js',
    'C:\\ProgramData\\photools.com\\IMatch6\\webroot\\system\\imatch\\imatch.css',
    'C:\\ProgramData\\photools.com\\IMatch6\\webroot\\system\\imatch\\imatch-translate.js',
    'C:\\ProgramData\\photools.com\\IMatch6\\webroot\\system\\imws\\imwslib.js'
]

IMatch.fileCreateZIP('c:\\temp\\imatch.zip',files).then(function(response) {
    console.log(JSON.stringify(response,null,2));
},function(error) {
    console.log(JSON.stringify(error,null,2));
});

addLogFileEntry(text) → {Promise}

This method adds a new entry to the IMatch log file. Entries added by apps are marked with an A> indicator
and IMatch automatically adds a time stamp and thread id.

Parameters:
Name Type Description
text *

The text to add to the log file.
Returns:
Type
Promise

fileChecksum(filename, type) → {Promise}

This method calculates a checksum for the given file.

Parameters:
Name Type Description
filename String

The fully-qualified file name of the file to process
type String

The type of checksum to generate. Supported are: md5, crc32, sha1 and sha256
Returns:
Type
Promise
Example
// Create a sha1 checksum for the given file:
IMatch.fileChecksum('c:\\temp\\imatch.zip','sha1').then(function(response) {
  console.log(JSON.stringify(response,null,2));
},function(error) {
  console.log(JSON.stringify(error,null,2));
});

specialFolders() → {Promise}

This method retrives information about special folders in the file system.
Special folders are for example the TEMP folder, the user Documents folder and similar. Knowing the locations of these folders is required for many apps.

The returned JSON response contains a folders object which lists the most frequently used folders.

TEMPThe TEMP folder for the currently logged-in user.
IMWS_DOCROOTThis is the *document root* folder for the IMWS embedded in IMatch.
IMATCH_APPDATAThis is the folder that contains *per-user* application data for IMatch.
IMATCH_COMMON_APPDATAThis is the folder than contains global IMatch application data, e.g., presets, templates, the settings database, ...
COMMON_APPDATAThis is where Windows stores common application data.
COMMON_DOCUMENTSCommon folder for documents.
COMMON_MUSICCommon folder for music files.
COMMON_PICTURESCommon folder for images.
COMMON_VIDEOCommon folder for videos.
MYDOCUMENTSDocuments folder for the current (logged-in) user (*My Documents*).
MYPICTURESImage folder for the current user.
MYVIDEOVideo folder for the current user.
MYMUSICMusic folder for the current user.
PROGRAM_FILESThe Program Files folder.
PROGRAM_FILESX86The Program Files folder for 32-Bit applications.
Returns:
Type
Promise
Examples
// This code fragment retrieves the special folders and dumps them into the browser console.
IMatch.specialFolders().then(function(response) {
    console.log(JSON.stringify(response,null,2));
});
// The output looks like this:
"folders": {
  "TEMP": "c:\\temp\\",
  "IMWS_DOCROOT": "C:\\ProgramData\\photools.com\\IMatch6\\webroot\\",
  "IMATCH_APPDATA": "C:\\Users\\Mario\\AppData\\Roaming\\photools.com\\IMatch6\\",
  "IMATCH_COMMON_APPDATA": "C:\\ProgramData\\photools.com\\IMatch6\\",
  "APPDATA": "C:\\Users\\Mario\\AppData\\Roaming\\",
...

folderBrowserFS(params) → {Promise}

This function displays a standard Windows file system folder browser dialog.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Description
title String <optional>

The title/prompt to display in the dialog.
initialdir String <optional>

The initial directory to select in the dialog. If this is not specified, Windows selects the initial folder.
Returns:

On success returns a JSON object in the following format:

{
    "result" : "ok" or "cancelled"
    "folderName" : Fully-qualified folder name
}
Type
Promise
Example
// Let the user select a folder.
IMatch.folderBrowserFS({
     title: 'Please select a folder:'
}).then(function(response) {
     console.log(JSON.stringify(result,null,2));
});

folderScan(params) → {Promise}

embedded
This method scans one or more file system folders and returns information about the files and folders found.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
path String

The fully-qualified name of the folder to scan.
filemask String

Comma-separated list of file masks. Example: *.* or *.txt,*.doc,*.json
recursive Boolean

(Optional, default: false) Set this to true to scan the folder recursively (include sub-folders).
regexp Boolean

(Optional, default: false) Set this to true if the filemask is a regular expresion. In that case only one expression is supported.
Returns:

On success the method returns a response in JSON format.

Type
Promise
Examples
// This code fragment retrieves information for of all *.jpg files in the c:\data\images folder, recursively: 
IMatch.folderScan({
     path: 'c:\\data\\images',
     filemask: '*.jpg,*.jpeg',
     recursive: true
}).then(function(response) {
     console.log(JSON.stringify(response,null,2));
});
// The output looks like this:
        {
        "folders": [
            {
                "path": "C:\\data\\",
                "files": [
                    {
                        "fileName": "readme.txt",
                        "name": "readme",
                        "extension": ".txt",
                        "folder": "C:\\data\\",
                        "size": 128,
                        "created": "2017-05-13T08:33:21",
                        "lastModified": "2017-02-11T17:22:21",
                        "lastAccessed": "2017-05-28T06:59:53",
                        "attributes": [
                            "archive"
                        ]
                    }
                ]
            }
        ]
        }

folderExists(params) → {Promise}

This function tests if a folder exists.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
path String

The name of the folder to test.
Returns:
Type
Promise

folderCreate(params) → {Promise}

This method creates one or more folders in the file system.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
path String

The name of the folder to create.
If a path like c:\data\images\family is specified, all levels of the path are created, down to the leaf level (family).
Returns:
Type
Promise

folderDelete(params) → {Promise}

This function deletes a folder in the file system.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
path String

The name of the folder to delete.
recycle Boolean

(Optional, default: true). If this is true, the folder is moved into the Windows recycle bin when possible.
Returns:
Type
Promise

folderCopy(params, (Optional,) → {Promise}

This method copies a folder (and all included files and sub-folders) to another location.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
source String

The name of the folder to copy.
target Boolean

The destination folder name.
(Optional, Boolean

default: false). If this is true, the standard Windows Copy folder dialog is displayed.
Returns:
Type
Promise

folderMove(params, (Optional,) → {Promise}

This method moves/renames a folder.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
source String

The name of the folder to move/rename.
target Boolean

The new location / name of the folder.
(Optional, Boolean

default: false). If this is true, the standard Windows Move folder dialog is displayed.
Returns:
Type
Promise

shellExecute(params) → {Promise}

This function implements the Windows ShellExecute function.
It allows scritps to start externakl programs, open Windows Explorer windows, open files in associated applications etc.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
executable String

The name of the application to run. To open Windows Explorer windows, use explorer.exe.
verb String

The verb, e.g. open or edit.
parameters String

The parameters to suppy to the executable.
directory String

The initial directory for the executable (start folder).
showwindow Boolean

(Optional, default: true). If this is specified as false, the application window is hidden.
See:
Returns:
Type
Promise
Examples
// This example opens the folder c:\temp in a Windows Explorer window:
IMatch.shellExecute({
    'executable' : 'explorer.exe',
    'verb' : 'open',
    'parameters' : 'c:\\temp',
    'showwindow' : true
}).then(function(response) {
    console.log(JSON.stringify(response,null,2));                            
});     
// This example opens the file c:\images\picture.psd with the associated application:
IMatch.shellExecute({
    executable : 'explorer.exe',
    verb : 'open',
    parameters : 'c:\\images\\picture.psd',
    showwindow : true
}).then(function(response) {
    console.log(JSON.stringify(response,null,2));                            
});     
// This example opens the file c:\images\picture.psd in Windows Explorer:
IMatch.shellExecute({
    executable : 'explorer.exe',
    verb : 'open',
    parameters : '/n, /select,\"c:\\images\\picture.psd\"',
    showwindow : true
}).then(function(response) {
    console.log(JSON.stringify(response,null,2));                            
});     
// This example opens the photools.com web site in the default web browser:
IMatch.shellExecute({
    executable : 'explorer.exe',
    verb : 'open',
    parameters : '"https://www.photools.com"',  // Use " " if your URL contains parameters!
    'showwindow' : true
});     
// This example opens the default email client with a recipient, a subject line and a body.
Notice that we use the special mailto: syntax and that the entire string is wrapped in " and ".
IMatch.shellExecute({
    executable : '"mailto:john@example.com?subject=No SPAM&body=Hi, John. This is just a test email."',
    verb : null,
    parameters : null
});

processRun(params) → {Promise}

This function runs and monitors an external process.
Use this function e.g., to launch an external program, collect output produced by that program (stdout and stderr) and to get noticed when the program exits.
A typical use-case for this function is to run a command-line utility and to capture the output into a string.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
executable String

The name of the executable to run. Must include a FULL PATH if the executable is not in the Windows 'Path'.
parameters String

The parameters to suppy to the executable.
timeout Number

(Optional. Default: 30). The number of seconds to wait for the external program to finish.
If the program is still running after this timeout has expired, it is closed automatically.
showwindow Boolean

(Optional, default: true). If this is specified as false, the application window is hidden.
Returns:
Type
Promise
Example
// This example runs the systeminfo command-line utility which is part of Windows.
// This utility gathers information about the system and prints it into the console window.
// processRun captures the output and returns it as part of the JSON response produced by this function.
// For more information about the cmd.exe and the systeminfo utility see the Windows help or your favorite search engine.
// Make sure to use /C with cmd.exe to prevent it from blocking forever. See the cmd.exe help for details.
IMatch.processRun({
    executable : 'cmd.exe',
    parameters : '/C systeminfo /FO list',
    showwindow : false,
    timeout : 30
}).then(function(response) {
    if (response.result == 'ok') {
        console.log(response.output);
    }
    else {
        console.log(JSON.stringify(response,null,2));                            
    }
});

clipboardCopy(params) → {Promise}

This function copies text or IMatch objects into the Windows clipboard.
It can be used to transfer text from an app to another application, or, for example, to copy IMatch files or categories into the clipboard which the user then can paste into a folder or category.

Parameters:
Name Type Description
params any
Properties
Name Type Description
format String

The format of the data to copy. Supported values are:

textCopy text into the clipboard. This text can be pasted into all other applications. The text to copy must be specified in the text parameter.
filesCopies a list of IMatch file ids into the clipboard. The ids must be specified in the id parameter. This also copies the file names in the HDROP (Windows standard format) and TEXT formats. You can later use 'Paste' in IMatch to paste the files.
foldersCopies a list of IMatch folders ids into the clipboard. Also the folder names in TEXT format. The ids must be specified in the id parameter.
categoriesCopies a list of IMatch category ids into the clipboard. Also the category names in TEXT format. The ids must be specified in the id parameter.
collectionsCopies a list of IMatch collection ids into the clipboard. Also the collection names in TEXT format. The ids must be specified in the id parameter.
text String

(For format = 'text') The text to copy into the clipboard.
id String

(Optional) A list of one or more ids, separated with a comma. Supported are enumerations 1,2,3 and ranges 1-10.
idlist String

(Optional) The name of an idlist to use. You can use this instead of id.
Returns:
Type
Promise
Example
This code fragment copies some text into the Windows clipboard:
IMatch.clipboardCopy({
    'format' : 'text',
    'text' : 'This is the text to copy into the Windows clipboard.'
});

clipboardClear() → {Promise}

Empties the Windows clipboard.

Returns:
Type
Promise

clipboardPaste() → {Promise}

Pastes text or IMatch object ids.
If data in a supported format (text, UNICODE text or IMatch objects) is found in the clipboard, it is returned in the data element in the JSON result.
Note: Many applications copy multiple formats at the same time into the clipboard. This function delivers all formats it understands.

Returns:
Type
Promise
Example
IMatch.clipboardPaste().then(function(response) {
    console.log(JSON.stringify(response,null,2));
});
// The output looks like this:
{
  "text": {
    "data": "Some text that was copied into the Windows clipboard."
  },
  "result": "ok"
}

clipboardFormats() → {Promise}

This function evaluates the clipboard contents and lists all supported formats.
Use it to check if supported data is available in the clipboard.

Returns:
Type
Promise

varParse(params) → {Promise}

This method parses the given variable expression. It works similar to the /variables endpoint available in IMWS,
but also has access to IMatch-specific variables.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
var String

A free mix of literal text and IMatch variables. All formatting functionsn are supported.
userlocale Boolean <optional>
 false

By default, numeric variables are formatted using the standard English US numeric format. Set this to true to use the numeric format for the current user instead.
id String

The id of the file to use when the variable is evaluated. This is required for {File.*} variables.
idlist String

Alternatively, specify the name of an idlist. The first file in that list will be used.
Returns:
Type
Promise
Example
// This code fragment parses the given variable expression for the file with the id 37:
IMatch.varParse({
    var: 'This is the name of the file: {File.FullName}',
    id: 37
}).then(function(response) {
    console.log(JSON.stringify(response,null,2));
});

// The output looks like this:
{
  "result": [
    {
      "id": 37,
      "value": "This is the name of the file: C:\\data\\images\\food\\fruit\\145016.psd"
    }
  ]
}

varList() → {Promise}

This method returns a list o all variables defined in IMatch. This includes variables provided by IMWS as well as application variables.

Returns:
Type
Promise

varBrowser(params) → {Promise}

embedded
This method displays a variable browser dialog box. The user can select one or more variables in the dialog.
If a file id is provided in sampleFile, the dialog uses this file to preview data in tooltips.
If 0 is specified, the dialog uses the currently focused file in the file window, or the first selected file if no file is focused.
This function can only be used from apps running in IMatch. If it is used from a web browser, the function returns an empty string.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
samplefile Object <optional>
 null

The file to use to display data in the dialog.
Returns:

{
"result" : "ok" or "cancelled"
"var" : Name of the selected variable.
}

Type
Promise
Example
// Show a variable browser, using the file with the id 100 as the sample file.

IMatch.varBrowser({
      samplefile: 0
 }).then(function(response) {
     if (response.result == 'ok') {
         console.log(response.var);
     }
 });
var res = IMatch.varBrowser(100);
if (res.result == 'ok') {
   console.log(res.var);
}

metadataTagBrowser(params) → {Promise}

This function displays a metadata tag browser dialog box. The user can select one or multiple metadata tags.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
allowmultisel Bool <optional>
 false

If this is true, the user can select multiple folders.
hidereadonlytags Bool <optional>
 false

If this is true, read-only tags are hidden. Use this if you allow the user to choose a tag for updating.
Returns:

On success, the endpoint returns a JSON object. The object contains an array with all selected tags. For each tag the id, key and display name is returned.
{
"result" : "ok" or "cancelled"
"tags" : [
{
id : "",
key: "",
name: ""
}
]
}

Type
Promise
Example
// Let the user select one metadata tag, show read-only tags.
var result = IMatch.metadataTagBrowser(false,false);
console.log(JSON.stringify(result,null,2));

categoryBrowser(Params) → {Promise}

embedded
This function displays a category browser dialog box. The user can select one or multiple categories.

Parameters:
Name Type Description
Params Object
Properties
Name Type Argument Description
initialselection Array.<Number> <optional>

The categories to initially select.
options= Array.<String> <optional>

Comma-separated list of options:

OptionDescription
defaultCombines `allowall, allowsystem, allowdynamic, allowsealded, allowkeywordroot, allowkeywordchild, allowalias`.
recursiveAllow to select categories recursively (including child categories).
singleselOnly one category is selectable. If this is not set, the user can select any number of categories.
allowallThe @All category is selectable.
allowsystemSystem categories like @Builder are selectable.
allowdynamicData-driven categories are selectable.
allowsealedSealed categories are selectable.
allowkeywordroot@Keywords is selectable.
allowkeywordchildChild categories of @KKeywords are selectable.
allowaliasAlias categories are selectable.
Returns:

If the user selects a category, the endpoint returns a JSON response.
{
"result" : "ok" or "cancelled"
"id" : List of category ids
}

Type
Promise
Examples
// Let the user select one category.
IMatch.categoryBrowser({
     options: 'default,singlesel'
}).then(function(response) {
     $('#result').text(JSON.stringify(response,null,2));
});
// Let the user select multiple categories. Initially select the categories 8 and 11.
IMatch.categoryBrowser({
     initialselection: '8,11',
     options: 'default'
}).then(function(response) {
     $('#result').text(JSON.stringify(response,null,2));
});

folderBrowser(params) → {Promise}

This function displays a folder browser dialog box for the folders indexed by the active database.
The user can select one or multiple folders.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
initialselection Array.<Number> <optional>

The folders to initially select.
allowmultisel Bool <optional>
 false

If true, the user can select multiple folders.
allowrecursivesel Array.<Number> <optional>
 false

If true, the user can use the recursive selection modes to include sub-folders.
Returns:

The retuned JSON output looks like this:

{
    "result" : "ok" or "cancelled"
    "id" : List of folder ids
}
Type
Promise
Examples
// Let the user select one folder. We use the default settings.
IMatch.folderBrowser({}).then(function(response) {
     console.log(JSON.stringify(response,null,2));
});
// Let the user select one or more folders, including recursive folder selection (child folders are included when the parent folder is selected).
// The folder with the id 49 is initially selected and focused.
IMatch.folderBrowser({
     initialselection: 49,
     allowmultisel: true
     allowrecursivesel: true
}).then(function(response) {
     console.log(JSON.stringify(response,null,2));
});

collectionBrowser(Params) → {Promise}

This function displays a collection browser dialog box. The user can select one or multiple collections.

Parameters:
Name Type Description
Params Object
Properties
Name Type Argument Default Description
initialselection Array.<Number> <optional>

The folders to initially select.
allowmultisel Bool <optional>
 false

If true, the user can select multiple collections.
Returns:

On successful execution returns a JSON object in this format:
{
"result" : "ok" or "cancelled"
"id" : List of collection ids
}

Type
Promise
Example
// Let the user select one or more collections.
var result = IMatch.collectionBrowser({},true);
console.log(JSON.stringify(result,null,2));

gotoFolder(params) → {Promise}

Switches to the Media & Folders View and selects the given folder and optionally a file.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Description
id Number <optional>

The id of the folder to select. If this is null, the folder for the specified file is used.
fileId Number <optional>

The id of the file to select and focus
Returns:
Type
Promise

gotoCategory(categoryId [, fileId]) → {Promise}

Switches to the Category View and selects the given category and optionally a file.

Parameters:
Name Type Argument Default Description
categoryId Number

The id of the category to select
fileId Number <optional>
 0

The id of the file to select and focus. If this is not specified, the 'first' file is selected.
Returns:
Type
Promise

gotoCollection(collectionId [, fileId]) → {Promise}

Switches to the Collection View and selects the given collection and optionally a file.

Parameters:
Name Type Argument Default Description
collectionId Number

The id of the collection to select
fileId Number <optional>
 0

The id of the file to select and focus. If this is not specified, the 'first' file is selected.
Returns:
Type
Promise

gotoTimeline(fileId) → {Promise}

Switches to the Timeline View and selects the given file.

Parameters:
Name Type Description
fileId Number

The id of the file to select and focus.
Returns:
Type
Promise

gotoPerson(personId [, fileId]) → {Promise}

Switches to the People View and selects the given person.

Parameters:
Name Type Argument Default Description
personId Number

The id of the person to select and focus.
fileId Number <optional>
 0

The id of the file to select and focus. If this is not specified, the 'first' file is selected.
Returns:
Type
Promise

gotoEvent(personId [, fileId]) → {Promise}

Switches to the Event View and selects the given evewnt.

Parameters:
Name Type Argument Default Description
personId Number

The id of the event to select and focus.
fileId Number <optional>
 0

The id of the file to select and focus. If this is not specified, the 'first' file is selected.
Returns:
Type
Promise

focusWindow(name) → {Promise}

Sets the input focus to the window with the given name. Windows then sends commands and keyboard input to this window.

Note: The function can fail (silently) if the user is interfering (clicking on another window), a dialog box is currently open etc.
To see if the function was successful, monitor IMatch messages and wait for the corresponding *.setfocus message (matching the name used when calling this function).

For example, if you call focusWindow('mediafolders.tree'), IMatch sends a 'mediafolders.tree.setFocus' message if the window has received the input focus.
If this does not happen, either the user has interfered or maybe a dialog box is open. Sometimes Windows works in mysterious ways and you may want to retry after a second if the first attempt fails.

Parameters:
Name Type Description
name String

The name of the window to focus.

NameDescription
filewindow.activeSet the input focus to the active file window (in whatever View is currently selected).
mediafolders.treeSet the input focus to the tree in the Media & Folders View. The view is automatically selected if it is currently not the active view.
mediafolders.filewindowSet the input focus to the file window in the Media & Folders View.
categories.treeSet the input focus to the tree in the Category View.
categories.filewindowSet the input focus to the file window in the Category View.
collections.treeSet the input focus to the tree in the Collection View.
collections.filewindowSet the input focus to the file window in the Collection View.
timeline.treeSet the input focus to the tree in the Timeline View.
timeline.filewindowSet the input focus to the file window in the Timeline View.
Returns:
Type
Promise
Example
// This fragment switches to the Media & Folders View and sets the input focus to the file window.
IMatch.focusWindow('mediafolders.filewindow');

getActiveView() → {Promise}

This method returns the name of the currently active view: folders, categories, timeline, collections, results.

Returns:

In the JSON response, the name of the active view.

Type
Promise

getAppContext() → {Promise}

Returns information about the current application context.
In the JSON response both the id of the context and, if available, a textual name are returned.
The context allows apps to tell the current situation in which IMatch is operating, e.g. the focused window, if a dialog is open.... IMatch uses this information for the context-sensitive help.

Returns:

JSON response

Type
Promise

setAppContext(name) → {Promise}

Set the current application context from the provided name.
This can be used to open the correct help topic when the user presses
The names come from the c:\ProgramData\photools.com\IMatch6\resources\imatchres_help.xml

Parameters:
Name Type Description
name String

The name of the context to set
Returns:
Type
Promise

getWorkspaceInfo() → {Promise}

Returns information about the currently loaded workspace (name, ...).
This information may be useful if you want to store workspace-specific settings in your apps. Just incorporate the workspace name in the key under which you store the data.

Returns:

JSON response with workspace data

Type
Promise

openResultWindow(params) → {Promise}

embedded
This function opens a new result window for the specified files.

Parameters:
Name Type Description
params Object

Object with parameters.

Properties
Name Type Argument Description
name String

The name to show for the result window.
caption String <optional>

The optional sub-caption for the File Window caption bar.
layout String <optional>

The name of the file window layout to use for the new result window.
id String <optional>

Comma-separated list of file ids. Use either this or idlist.
idlist String <optional>

Name of an idlist to load into the result window.
Returns:

The returned JSON response contains the instance id of the created result window.

Type
Promise

findResultWindow(params) → {Promise}

embedded
This function checks if a result window with the given instance id exists. Optionally the window is activated.

Parameters:
Name Type Description
params Object

Object with parameters.

Properties
Name Type Argument Default Description
instanceid Number

The instance id of the result window to find.
activate Boolean <optional>
 false

If this is true, the result window is activated.
Returns:

JSON response, with result either 'ok' or 'failed'.

Type
Promise

listResultWindows() → {Promise}

embedded
This function returns a JSON object with information about all currently open result windows.

Returns:

JSON response, with result set to either 'ok' or 'failed'.
The resultWindows array contains information about all open result windows.

Type
Promise

updateResultWindow(params) → {Promise}

embedded
This function updates an existing result window with new files. You can use this to reuse an result window created earlier by your app.

Parameters:
Name Type Description
params Object

Object with parameters.

Properties
Name Type Argument Default Description
instanceid Number

The instance id of the result window to update.
id String <optional>

Comma-separated list of file ids. Use either this or idlist.
idlist String <optional>

Name of an idlist to load into the result window.
name String <optional>
 ''

An optional new name for the result window. If this is not specified, the current name is retained.
activate Boolean <optional>
 true

If this is true, the result window is activated.
Returns:

JSON response, with result either 'ok' or 'failed'.

Type
Promise

closeResultWindow(id) → {Promise}

embedded
This function closes a new result window. Note: This may change the instance ids of other result windows.

Parameters:
Name Type Description
id Number

The instance if of the result window to close. Use id = 0 to close all result windows.
Returns:
Type
Promise

getIMatchSetting(set, id) → {Promise}

This function allows access to internal IMatch settings by their name.
For internal purposes only.

Parameters:
Name Type Description
set String

The name of the set to access. Supported are: {ui|app|geo}
id Number

The id of the setting to retrieve.
Returns:

On successful execution, returns a JSON object with the requested setting.

Type
Promise

setIMatchSetting(set, id, value) → {Promise}

This function updates the IMatch setting with the given id to value.

Parameters:
Name Type Description
set String

The name of the set to access
id Number

The id of the setting to update.
value String

The new value. IMatch will coerce the value into the correct data type if possible.
Returns:
Type
Promise

showProtectedFiles() → {Promise}

This function determines if the display of protected files is currently enabled.
If not enabled, endpoints like files/image will return an error if an app tries to access a protected file,
whether ot not the current user has the privilege to access protected files or not.

Returns:

On successful execution, returns a JSON object with the requested setting.

Type
Promise

getDropContext() → {Promise}

This method accesses the drop context available for import & export apps running in the Import & Export Panel.
When the user launches such an app by dropping files or other folders onto the module in the Import & Export Panel,
the dropped objects can be accessed via this method.
Note: If you use this from a web browser, it returns an empty object.

Returns:

On successful return, a JSON object describing the scope.

Type
Promise
Example
IMatch.getDropContext().then(function(response) {
   dropContext = JSON.parse(response.scope);
   console.log(dropContext.type);
 });
See Import and Export Apps tutorial for details about import and export apps and this function.

fileWindowFilterUpdate(params) → {Promise}

This function sets or updates the file window filter for the specified app. The filter is global and effective for all file windows in all views.
When a filter is created or modified, IMatch sends the app.appfilter.created or app.appfilter.updated messages.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
appid String

The id of the app
id String <optional>

Comma-separated list of file ids to use for the filter
idlist String <optional>

The name of an idlist to use for the filter. Either id or idlist must be specified.
mode String <optional>
 include

The mode of operation.Supported are:

ValueDescription
includeAll files not in id or idlist are removed from the file window.
excludeAll files in id or idlist are removed from the file window. This is the inversion of include.
Returns:
Type
Promise
Example
// This snippet removes all files from the file window, except 1,2,5...,298
IMatch.fileWindowFilterUpdate({
     appid: IMatch.appId(),
     mode: 'include',
     id: '1,2,5,9,87,191,298'
});

fileWindowFilterDelete(appId) → {Promise}

This method removes the file window filter for the app with the given id.
When a filter is removed, IMatch sends the app.appfilter.removed message.

Parameters:
Name Type Description
appId String

The id of the app for which to clear the file window filter.
Returns:
Type
Promise
Example
// This snippet clears the file window filter for the given app
IMatch.fileWindowFilterDelete(IMatch.appId());

fileWindowFilterList() → {Promise}

This method returns an array with the app ids of all currently
active app file window filters.

Returns:
Type
Promise
Example
// This snippet clears the file window filter for the given app
IMatch.fileWindowFilterList();

setGPSCoordinates(params) → {Promise}

This method sets the GPS coordinates for one or more files.
If automatic reverse geo-coding is enabled in IMatch, the process is automatically performed on the files.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
lat Number <optional>

The latitude in decimal format.
lng Number <optional>

The longitude in decimal format.
alt Number <optional>
 0

The altitude in decimal format.
destlat Number <optional>

The latitude in decimal format.
destlng Number <optional>

The longitude in decimal format.
target String <optional>
 'created'

Which coordinates to update: created, dest or both.
With created the GPS lat/lon coordinates (1-4) are updated (location created). With dest the coordinates (19-22) are updated (location shown). both updates both. There is no separate altitude for location shown.

See the EXIF speficiation and the XMP metadata specification for detailed information.
id String <optional>

Comma-separated list of file ids. Either id or idlist must be specified.
idlist String <optional>

The name of the idlist representing the files to update.
Returns:
Type
Promise

findNearbyFiles(params) → {Promise}

This method searches for files nearby the given coordinates.
A dialog box is presented to the user where he can configure the details of the search.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
lat Number

The latitude in decimal format.
lng Number

The longitude in decimal format.
alt Number <optional>
 0

The altitude in decimal format.
Returns:
Type
Promise

reverseGeoCode(params) → {Promise}

This method opens the reverse geo-code dialog box to allow the user to perform reverse geo-coding.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
id String

Comma-separated list of file ids. Either id or idlist must be specified.
idlist String

The name of the idlist representing the files to update.
Returns:
Type
Promise

createGeoLocation(params) → {Promise}

This method creates a new geo-location for the specified coordinate.
IMatch displays a dialog where the user can modify the values and perform an address lookup.
Note: IMWS also has endpoints for creating, updating and deleting locations.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
lat Number

The latitude in decimal format.
lng Number

The longitude in decimal format.
alt Number <optional>
 0

The altitude in decimal format.
templatefile String <optional>
 0

Optional file id to use to pre-fill the location properties like country, city, location.
Returns:
Type
Promise

editGeoLocation(params) → {Promise}

This method edits a geo-location by opening a dialog box.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Description
guid String <optional>

The GUID of the location to edit. If no guid is specified, the edit location dialog does not use an initial selection.
Returns:
Type
Promise

commandList() → {Promise}

This function produces a list of all available IMatch commands (menu commands, keyboard shortcuts, etc.).
You can use the returned id with the commandExecute function to execute any IMatch command.
This produces output like

{

"id": "ID_CMD_RATING_NONE",

"text": "Reset &Rating",

"displayText": "Reset &Rating\t0 ; 0 (zehnertastatur)",

"hotKey": "0 ; 0 (zehnertastatur)",

"helpText": "Remove the rating from the current selection (0 ; 0 (zehnertastatur))"

}

Returns:
Type
Promise
Example
// Dump all IMatch commands to the console.
IMatch.commandList().then(function(response) {
    console.log(JSON.stringify(response,null,2));
});

commandExecute()

This function executes the IMatch command with the given id. You can get the ids from the commandsList function.
This makes it very easy to execute a certain IMatch menu command or keyboard shortcut, to open dialogs and similar.
To successfully execute a command you need to ensure that the correct window has the input focus using the focusWindow function.
Then call this function to execute the command.

Note: Avoid executing long-running commands or commands which open dialog boxes. The IMWS thread processig the endpoint is blocked while the commands runs and this may cause performance issues or timeouts.

Example
// This command executes the ID_CMD_RATING_NONE command, which removes the XMP rating from all files currently selected in the file window.
// To make sure that the command works, it first sets the focus to the file window in the active view.
IMatch.focusWindow('filewindow.active');
IMatch.commandExecute('ID_CMD_RATING_NONE');

favoritesList(params) → {Promise}

This method returns a list of all IMatch Favorites defined for the current database.
You can use the GUID elements from this list in conjuncton with favoritesExecute to execute Favorites directly from your app.

Note: Only user-defined Favorites are listed, not the system-controlled 'recent folders' or 'recent categories' lists.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
workspace Boolean <optional>
 false

If this is true only favorite sets loaded in the current workspace are returned.
Returns:
Type
Promise
Example
// List all favorites and dump the info to the console.
IMatch.favoritesList().then(function(response) {
   console.log(JSON.stringify(response,null,2));
});

favoriteExecute(params)

This function executes the specified Favorite. To run a Favorite you need its unique GUID, which you get from the favoritesList function.

Note: Avoid executing long-running Favorites or Favorites which open dialog boxes. The IMWS thread processig the endpoint is blocked while the Favorite runs and this may cause performance issues or timeouts.
For Renamer Favorites avoid using running presets which open dialog boxes (Prject Code!) or which perform complex steps like copy or move. Such operatiosn should be done by apps directly.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Default Description
guid String

The GUID of the Favorite to execute.
op String <optional>
 primary

This parameter specifies whether the primary (left mouse button) or seondary (right mouse button) operation should be used. By default, the primary operation is used. Note that not all Favorites have secondary operations.
id String <optional>

Comma-separated list of file ids. This parameter is only required for Favorites which work on files, e.g. category Favorites.
idlist String <optional>

Name of the idlist to use. Use either id or idlist for Favorites which work on files.
Example
// This example runs the primary operation of the specified favorite. The Favorite uses/works with the files currently seleced in the active file window.
IMatch.favoriteExecute({
   guid: '12A9308C-662D-4E58-8DC3-48A4BE21F15C',
   op: 'primary',
   idlist: IMatch.idlist.fileWindowSelection
});

cacheGetFileName(params) → {Promise}

This function retrieves the physcial IMatch cache file names for one or more files.
The server returns a JSON response with an array of objects. Each object contains the file id and the cache file name. If no cache image exists, an empty string is returned.
The returned file name can be used to create a file url in the form file://, e.g., to use the cache image in an <img> tag.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Description
id String

Comma-separated list of file ids. Use either id or idlist.
idlist String

Name of an idlist.
type= String <optional>

The type of cache image to retrieve.

TypeDescription
visualproxyRetrieve the visual proxy. If no visual proxy exists, an empty string is returned.
printRetrieve the print proxy. If no visual proxy exists, an empty string is returned.
webRetrieve the for web usage proxy. If no visual proxy exists, an empty string is returned.
conversionRetrieve thefor conversion proxy. If no visual proxy exists, an empty string is returned.
emailRetrieve the for email proxy. If no visual proxy exists, an empty string is returned.
versionstackproxyRetrieve the version stack proxy. If no visual proxy exists, an empty string is returned.
Returns:
Type
Promise
Example
// Retrieve the cache file names for the files 40 and 913 (using join to produce a comma-separated list from the array).
IMatch.cacheGetFileName({
   id: [40,913].join(',')
}).then(function(response) {
   console.log(JSON.stringify(response,2,null));
});

serviceAppShow(appId, show) → {Promise}

Service apps run invisibly in the background by default. IMatch maintains an invisible window to host the app.
This method allows to make this window visible for testing purposes. The window displays the regular HTML contents created by the default document of the app (index.html).

Parameters:
Name Type Description
appId String

The app id (from the app.json) of the service app to show or hide.
show Boolean

Controls wheter to show or hide the app.
Returns:
Type
Promise

serviceAppClose(appId) → {Promise}

This method can be used to terminate a service app. It can be called by the app itself, or by another app.

Parameters:
Name Type Description
appId String

The app id (from the app.json) of the service app to show or hide.
Returns:
Type
Promise

getFilterPanelState(name) → {Promise}

Query the state (loaded, enabled, expanded) of the filter panel with the specified name.

Parameters:
Name Type Description
name String

The name of the filter panel to query.
Supported are: manager,rli,metadata,file_attributes,collections,datetime,categories,folders,filename,file_format,file_size,dimensions,gps,value1,value2,value3,value4,value5,color,match,attributes,events,people
Returns:
Type
Promise

formatFileSize(size)

This function formats the given size in the standard IMatch file size format (Byte, KB, MB, GB)

Parameters:
Name Type Description
size Number

The file size to format.
Returns:

The formatted file size as a string

debounce(func, waitTime)

Returns a function, that, as long as it continues to be invoked, will not be triggered. The function will be called after it stops being called for waitTime milliseconds.
This function is very useful if you want to delay an operation until a user stops typing or for similar purposes.

Parameters:
Name Type Description
func function

The funcion to call
waitTime Number

de-bounce time
Example
// As long as delayIt is being called (with every keyup) it does not
// do anything. When the user does not press a key for 500ms, the
// doSomething() function is called.
// The arguments used to call the delayIt function are available via the <code>arguments</code> variable 

let delayIt = IMatch.debounce(function() {
     doSomething(arguments[0]);  // = 'Hello'
}, 500);

 $('#id').keyup(function(e) {
     e.preventDefault();
     delayIt('Hello');  // This parameter can be used in the debounced function.
     return false;
});

escapeRegExp(stringValue)

This function escapes all characters considered as special characters in a regular expression.
You can use it to sanitize user input before using it with IMWS functions that expect a regular expression.

Parameters:
Name Type Description
stringValue String

The string to escape
Returns:

The input string with all special characters escaped by \

Example
console.log( IMatch.escapeRegExp('A (day at) the beach.*') );

appendBackslash(stringValue) → {String}

Appends a \ to stringValue if it not already ends with a \

Parameters:
Name Type Description
stringValue String

The string to append to
Returns:

stringValue with exactly one \ at the end.

Type
String

openLinkInDefaultBrowser(url)

v2018
Open the specified URL in the default web browser.
By default, the embedded browser in IMatch opens links with target = _blank in a separate Chromium window, not in the
default web browser condigured by the user.

Parameters:
Name Type Description
url String

The url to open.
Example
// This binds all <a> tags with the class "a-link" and opens their target in the default web browser.
$('.a-link').click(function(e) {
    let url = $(this).attr('href');
    if ((url != '') & (url != '#')) {
        IMatch.openLinkInDefaultBrowser(url);
    }
    e.preventDefault();
    return false;
});

openIMatchWebHelp(params)

This method opens the IMatch online help at photools.com in the default web browser and loads the specified document.

Parameters:
Name Type Description
params String

The name of the document to open. Optionally include a deep link to an anchor tag in the form document.htm?dl=anchor.
Example
// Open the File Window Help
IMatch.openIMatchWebHelp('fw_basics.htm');
// Open the File Window Help and jump to the 'Rating and Label Bar' section.
IMatch.openIMatchWebHelp('fw_basics.htm?dl=h-26');

setIMatchBusy(busy [, showOverlay]) → {Promise}

This method switches IMatch into busy mode for 5 seconds, or brings it out of the busy mode.
Use this if you perform some long-running task in your app and you want to indicate that to the user.

Parameters:
Name Type Argument Default Description
busy boolean

If this is true, IMatch is switched to busy mode for 5 seconds. Then it automatically
comes out of busy mode. If you want to keep IMatch in busy mode, call this method every couple of seconds.
showOverlay boolean <optional>
 true

In combination with busy = true: 'Mute' the IMatch user interface with an overlay window.
Returns:
Type
Promise

getIMatchBusy() → {Promise}

Test if IMatch is currently 'busy'.

Returns:
Type
Promise

getDialogOpen() → {Promise}

Test if a dialog box is currently open.

Returns:
Type
Promise

undoInfo()

This method returns information about the current undo state.
This includes the name of the topmost undo entry and the total number of undo entries on the stack.

undoApply()

Apply the topmost undo entry on the stack.
This is similar to the user running Edit > Undo.

undoDelete()

Delete the topmost undo entry on the stack.
This removes the topmost undo entry without actually performing an undo

undoPushMetadata(params [, undefined])

Create an undo task for metadata changes.
This operation copies the current metadata for one or more files onto the undo stack.
Changes done to metadata for these files can be undone by the user or by calling IMatch.undoApply()

Parameters:
Name Type Argument Description
params Object
Properties
Name Type Description
id Array

List of file ids. Use either this or idlist.
idlist String

Name of the idlist to use
undefined Array <optional>

params.tag The optional list of tag ids to include.
This parameter can be used to limit the undo to certain tags, to conserve memory and for better performance.

validateXAML(text) → {Promise}

Validates XAML markup with the same XAML engine used by IMatch.
IMatch responds with a JSON answer. If the XAML is valid, the result member of the response is 'valid', else 'invalid'.
If the XAML is invalid, the response also containes a more detailed error description in the 'error' member.

Parameters:
Name Type Description
text String

The XAML markup to validate.
Returns:
Type
Promise
Example
IMatch.validateXAML('<TextBlock>Hello</TextBlock>').then(response => ...

blendColors(color1, color2, percentage)

Blend the two colors specified as #RGB

Parameters:
Name Type Description
color1 String

The color to blend. Example: #ff0000
color2 String

The other color.
percentage Number

(0..1) The percentage to blend color2 into color2.

preventDragDrop()

Helper to prevent drag & drop into app windows.
Call this to disable dragging and dropping globally.

preventContextMenu()

Helper to supress the standard browser context menu.