Supported functions
The file p4vjs.js defines the P4VJS commands that you can use in your HTML page to communicate with P4V. To use the following functions, you need to include this file.
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 |
---|
|
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 |
---|
|
P4V has to parse the string to extract each argument. The prior format is still supported. |
Another comparison of the two formats:
Recommended |
|
Prior Format |
|
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.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.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.