Previous Table of Contents Index Next
Perforce 2013.1: Javascript API for Visual Tools

Appendix A
JavaScript API Methods
You can use the following methods to code the logic in your central settings files. These methods are contained by the P4JsApi object (so be sure to prefix all method calls with "P4JsApi.").
Central Settings Logic Methods
Returns a string containing the key that was specified when the central settings file was executed.
Alert Methods
addAlert(msg [,image])
msg: Text or HTML to be rendered in the alert. If you specify a link (<a href=...>), the target is displayed by launching the default Web browser on the client machine.
image: Specifies an image to be displayed to the left of the alert text. Use the HTML img tag. By default, the image is displayed as 18 x 18 pixels. To override this default, specify height and width attributes in the img tag.
Returns an int identifier that can be passed to updateAlert() or deleteAlert().
Deletes the specified alert from the Alerts widget on the P4Admin Home tab. Returns false if the specified alert is not found.
Directs P4Admin or P4V to issue a refresh request to the server after the specified number of seconds (one or more) has elapsed instead of refreshing automatically.
updateAlert(int, str [, image])
For the specified alert ID, replaces the currently-displayed text with the specified message. To update the image that is displayed with the alert, specify the optional image parameter using the HTML img tag, as described for the addAlert method.
Server Data Methods
For Unicode-mode servers, returns a string containing the character set in use (P4CHARSET).
getPermission(name, isUser, depotPath [, host])
Returns a string containing the level of access to the specified depot path for the specified user or group. (P4Admin only)
If the name parameter specifies a user, set isUser to true. If name specifies a group, set isUser to false.
To further qualify the calculation of permissions, specify the host parameter using the same syntax that is used to specify host in the Perforce permissions table. For details, see the Perforce System Administrator's Guide.
Returns a string containing the directory on the host machine where the Perforce server stores its metadata files.
Returns an integer containing the changelist number passed to a replacement Submit dialog
Returns a string containing "true" or "false," indicating whether the server is case-sensitive.
Returns a string containing "true" or "false," indicating whether the server is running in Unicode mode
p4(command [,form] [,callback])
Runs the specified Perforce p4 command. Runs asynchronously if the callback function parameter is specified. Command results are returned as JavaScript objects containing data in JSON format, composed of the following properties.
To pass form data to a command, you can specify the form as a string or a JSON data object. For details, see Issuing Perforce Commands.
If run asynchronously, command results are returned to the specified callback function and an empty object is returned by the p4 method. The following JSON data structure is returned:
Utility Functions
Encodes characters to prevent XSS attacks injected into dynamic data. For details, see Preventing Cross-Site Scripting (XSS) Attacks.
Enables or disables the Inspect item in the context menu, which displays the WebKit WebInspector for debugging.
Returns a string containing the specified P4V image in HTML embedded format. Use the names returned by 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.
Returns a list of the folders and files that are currently selected in the depot pane.
Enable/disable display of server errors in popups. (By default, server errors are displayed in popups.
Specify true to enable, false to disable.
Given a list of paths and files, selects them in the depot pane and, if specified, executes the optional callback function.
Enables you to construct an optimized workspace mapping for a client workspace specification that your application creates or modifies.
The Map Function: Details
The P4JsApi.Map function enables your application to manipulate Perforce client view mappings. Client view mappings define which depot files are accessible for a specified workspace, and where they reside on the local disk. For detailed information about client view mappings, refer to the P4 User's Guide and the Perforce Command Reference Manual discussion of the p4 client command.
Class level methods
P4JsApi.Map.join(map1, map2): Returns the map that results from joining the two input maps.
map: A list of mapping lines.
Instance methods
Inserts a mapping line into the map. If right is provided, left and right are the left and right hand sides of the mapping line. If right is not provided, left is assumed to contain both sides of the map. Any spaces in the mapping strings must be quoted
Constructs a new Map object. s can be a single mapping line string or a list containing mapping line strings
Returns a new P4JsApi.Map object with the left and right sides of the mapping swapped
Translates path through the map and return the result. If reverse is true, translate from right to left
The following code maps the mainline in the depot to a directory on Tony's local machine, then requests the local path for the Web site home page.
m = new P4JsApi.Map();
m.insert("//depot/main/...", "//tonyclient/...");
m2 = new P4JsApi.Map("//tonyclient/... /home/tony/workspace/...");
localPath =      P4JsApi.Map.join(m,m2).translate("//depot/main/www/index.html");
// Preceding call returns the following path:
//    /home/tonyclient/workspace/www/index.html
Supported p4 Commands
For security purposes, the JavaScript API controls the p4 commands that can be executed in each context (that is, in custom tabs, alerts, and the central settings file). Applets cannot run any command that alters the state of a server other than the currently-connected server.
The following table lists the p4 commands that can be issued in various types of applets.

Only returns value of a specified counter

Supports only -p and -s flags

Supports only the show parameter

All flags except -y permitted


Previous Table of Contents Index Next

Perforce 2013.1: Javascript API for Visual Tools
Copyright 2010-2013 Perforce Software.