P4VJS Documentation | 2025.1

# MapApi support

P4VJS offers a set of utility functions that give you access to the MapApi functionality documented in the Helix Core C/C++ API Documentation. The functions listed below can be used to inspect, validate, and merge `clientview maps` and `branch maps` from an HTML page.

Client view mappings define which depot files are accessible for a specified workspace, and where they reside on the local disk. One use case is to verify that a particular set of files are part of a given client view mapping.

Each map consists of entries (lines), with each entry presenting a source (left) and a target (right) path. P4VJS loads a client view or branch map as an array of strings. Each string represents an entry in the map.

## Examples

An example of a client view presentation in JavaScript :

    var p4map = [
        '//depot/v70.2/patty/... patty/...',
        '//project1/mozart/v72.2/... ...',
        '-//project1/mozart/v72.2/patty/auth/... mozart/auth/...',
        '-//project1/mozart/v72.2/patty/broker/... mozart/broker/...',
        '-//project1/mozart/v72.2/patty/dbopen2/... mozart/dbopen2/...',
        '-//project1/mozart/v72.2/patty/dbpipe/... mozart/dbpipe/...'];

An installation of P4V includes examples that illustrate the use the map utility functions:

In the `<installation_root>\Perforce\P4VResources\p4vjs` or `<installation_root>/Perforce/P4VResources/p4vjs` folder:

`examples/mapTest/mapLeftRightReverse.html` shows how to use `mapLeft`, `mapRight`, and `mapReverse`.

`examples/mapTest/mapIncludeTranslate.html` shows how to use `mapInclude`, and `mapTranslate`.

`examples/mapTest/mapCountJoin.html` shows how to use `mapCount`, and `mapJoin`.

## p4vjs.mapCount(p4map)

the number of entries currently in a mapping. For example:

    var mpcount = await p4vjs.mapCount(resultmap);

## p4vjs.mapLeft(p4map)

Returns the left (source) side of the map provided. For example:

    p4vjs.mapLeft(p4map).then(function(result) {
        var resultmap = result.map;
        .......
    });

## p4vjs.mapRight(p4map)

Returns the right (target) side of the map provided. For example:

    p4vjs.mapRight(p4map).then(function(result) {
        var resultmap = result.map;
        .......
    });

## p4vjs.mapReverse(p4map)

Swaps left and right, and returns the modified map. For example:

    p4vjs.mapReverse(p4map).then(function(result) {
        var resultmap = result.map;
        .......
    });

## p4vjs.mapIncludes(p4map, path)

Indicates if a given path would be mapped by either the left or right side of the map. For example:

    var path = '//project1/mozart/v72.2/zippy/auth/authldap.h';
    p4vjs.mapIncludes(p4map, path).then(function(result) {
        var match = result.mapside;
        if (match === p4vjs.MapSide.LEFT)
        .......
        else if (match === p4vjs.MapSide.RIGHT)
        .......
        else if (match === p4vjs.MapSide.BOTH)
        .......
        else // (match === p4vjs.MapSide.NEITHER)
        ......
    });

## p4vjs.mapTranslate(p4map, path, side)

Indicates if a given path can be translated by this map, and if so it gives you the translation. In this example, the string `'patty/automation/runtestldap.h'` is translated to a depot path:

    var path = 'patty/automation/runtestldap.h'
    p4vjs.mapTranslate(p4map, path, p4vjs.MapSide.LEFT).then(function(result) {
        var succeeded = result.success;
        if (succeeded) {
            var pathmappedto = result.translation;   // the translation is : //depot/v70.2/patty/automation/runtestldap.h
            .......
        }
        else {
            // no mapping this direction
            .......
        }
    });

The possible values for the side parameter are:

- `p4vjs.MapSide.LEFT`

- `p4vjs.MapSide.BOTH`

- `p4vjs.MapSide.RIGHT`

## p4vjs.mapJoin(p4map1, p4map2)

Joins two maps together to produce a combined mapping. For example:

    p4vjs.mapJoin(p4map1, p4map2).then(function(result) {
        resultmap = result.map;
        .....
    });

Your search for returned results