Supported functions

All P4VJS functions return a JavaScript Promise, an object representing the eventual completion (or failure) of an asynchronous operation and its resulting value.

In addition to the functions listed below, you can also call the functions of the MapApi support.

p4vjs.p4( command [,form] [,callback] )

Runs the specified p4 command.

You might pass the command as follows:

p4vjs.p4(command).then( ....

Recommended format for the command
`command = [ 'changes', '-s', 'submitted', '-l', '-m', '100', '-u', 'bob' ];`
We recommend that you use brackets to enclose the command and its arguments in an array of strings. If an argument needs to be quoted or escaped, P4V can take care of it because every argument is explicit.

Recommended format for the command

command = [ 'changes', '-s', 'submitted', '-l', '-m', '100', '-u', 'bob' ];

We recommend that you use brackets to enclose the command and its arguments in an array of strings.

If an argument needs to be quoted or escaped, P4V can take care of it because every argument is explicit.

Format prior to 2021.1
`command = 'p4 changes -s submitted -l -m 100 -u bob';`
P4V has to parse the string to extract each argument. The prior format is still supported.

Format prior to 2021.1

command = 'p4 changes -s submitted -l -m 100 -u bob';

P4V has to parse the string to extract each argument.

The prior format is still supported.

Another comparison of the two formats:

Recommended	`p4vjs.p4(["fstat", "//depot/file with spaces.txt"])`
Prior Format	`p4vjs.p4("fstat \"//depot/file with spaces.txt\"")`

Command results are returned as JavaScript objects containing data in JSON format, composed of the following properties:

{
  [str] data: when tagged data returned, array of tag/value pairs
  int size: number of members in data array
  [str] error: only if there are errors, tagged error data is returned as an array of tag/value pairs 
  [str] warning: only if there are warnings, tagged warning data is returned as an array of tag/value pairs
  [str] info: only if there is some info, tagged info data is returned as an array of tag/value pairs
}

p4vjs.closeWindow()

Closes the hosting floating window. Only works with HTML Windows (not with HTML Tabs).

p4vjs.getApiVersion()

Returns a string containing the version (level) of the JavaScript API.

p4vjs.getCharset()

For Unicode-mode servers, returns a string containing the character set in use (P4CHARSET).

p4vjs.getClient()

Returns a string containing the client workspace name (P4V only).

p4vjs.getFileIcon(path)

Returns the icon that appears in the context menu when selecting a file in P4V. The icon includes the badges (such as ) that indicate the current state of that file, such as checked out and globally locked, or shelved.

The value for path can be a local (workspace) path or a depot path.

Note

See Examples that run in demo mode, which mentions the Demo Submit example at <P4VJS Directory>\examples\submitDialog\submitdialog.js

p4vjs.getImage(image)

Returns a string containing the specified P4V image in HTML-embedded format. Use the names returned by getImageNames().

p4vjs.getImageNames()

Returns a string array containing a list of images used by P4V to indicate file type and status. For consistency with P4V, use these images in your applications.

p4vjs.getParameter(param)

Depending on what HTML tool you are running, P4V injects parameters into you HTML page. These parameters are available from P4VJS, and can be used to interpret the context.

For example, if you create an HTML Tool, and set the argument type to : %t : Selected Stream, when the user selects a Stream in P4V, the HTML Tool will be available.

Let’s say you select a stream named //StreamDepot/Project1/mainStream

In the HTML page implementing this HTML Tool, you can use getParameter to get the name of the stream selected.

var streamName = p4vjs.getParameter("stream");

The value of streamName is now //StreamDepot/Project1/mainStream

See the complete list of Argument types, which is included in the HTML Windows topic.

p4vjs.getPort()

Returns a string containing the Helix Server connection setting.

p4vjs.getSelection()

Returns a list of the folders and files that are currently selected in the depot pane.

p4vjs.getServerRootDirectory()

Returns a string containing the directory on the host machine where Helix Server stores its metadata files.

p4vjs.getServerSecurityLevel()

Returns a string containing the server’s security level.

p4vjs.getServerVersion()

Returns a string containing the server version number.

p4vjs.getUrlIParameter("change")

Returns the value of the changelist. This is a P4VJS function for Submit in an HTML Action.

p4vjs.getUrlIParameter("submitshelved")

Returns true if the Submit dialog was launched from Submit Shelved Files. This is a P4VJS function for Submit in an HTML Action.

p4vjs.getUser()

Returns a string containing the current user.

p4vjs.isServerCaseSensitive()

Returns a string containing true or false, indicating whether the server is case-sensitive.

p4vjs.isServerUnicode()

Returns a string containing true or false, indicating whether the server is running in Unicode mode.

p4vjs.nextPage()

Shows the P4V Submit page. This is a P4VJS function for Submit in an HTML Action.

p4vjs.openUrlInBrowser(url)

Launches the default web browser and displays the specified URL.

p4vjs.refresh(<object type>, <object name>)

(2020.1 release) Refreshes any of the specified P4V items:

p4vjs.ObjectType.BRANCH
p4vjs.ObjectType.PENDINGCHANGE
p4vjs.ObjectType.SUBMITTEDCHANGE
p4vjs.ObjectType.CLIENT
p4vjs.ObjectType.GROUP
p4vjs.ObjectType.JOB
p4vjs.ObjectType.LABEL
p4vjs.ObjectType.STREAM
p4vjs.ObjectType.USER
p4vjs.ObjectType.REPO

Examples

The P4VResources\p4vjs\examples\Demo Edit <form> example shows how to refresh updated items in P4V. You make changes to the form you are editing, then apply the changes before closing the HTML Window. A snippet from the editform.html example includes:

//save the form, and wait.
await p4vjs.p4(cmd(formType, '-i'), formData);
// now refresh the updated object in P4V
if (formType === 'branch')
    p4vjs.refresh(p4vjs.ObjectType.BRANCH, formName);
else if (formType === 'client')
    p4vjs.refresh(p4vjs.ObjectType.CLIENT, formName);

The p4vjs/examples/refresh/refresh.html example lists all possible object types.

p4vjs.refreshAll ()

Forces a refresh of P4V.

p4vjs.refreshFiles(<array of files>)

(2020.1 release) Refreshes an array of files in P4V.

Example

p4vjs/examples/checkout/checkoutfiles.html

Create a HTML Window that takes %F as an argument.
Select some files.
Launch the tool.
The files are listed.
Checkout the files by clicking the Checkout button.

The files will be refreshed in P4V when P4V gets the input focus.

p4vjs.selectedDirectories()

Returns an array of the selected directories:

(HTML Action) - in the Submit Action pre-page, when submitting from the Workspace or Depot tree
(HTML Window) - when launching an HTML Tool while using depot syntax to specify a file or folder with the %d argument type, or multiple files or folders with the %D argument type

p4vjs.selectedFiles()

Returns an array of the selected files:

(HTML Action) - in the Submit Action pre-page, when submitting from the Workspace or Depot tree
(HTML Window) - when launching an HTML Tool while using workspace syntax to specify a file with the %f argument type, or multiple files with the %F argument type

p4vjs.setP4VErrorDialogEnabled(true|false)

Enables/disables the display of server errors in popup windows. (By default, display of server errors is enabled.)

p4vjs.setSelection(selectionList)

Given a list of paths and files, selects them in the depot pane.

p4vjs.useDarkTheme()

Returns true if P4V is in dark theme mode.