Method and Command Reference

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.").

Method	Description
centralSettingsKey()	Returns a string containing the key that was specified when the central settings file was executed.
refreshAll()	Forces a refresh of P4V or P4Admin.

Method

Description

centralSettingsKey()

Returns a string containing the key that was specified when the central settings file was executed.

refreshAll()

Forces a refresh of P4V or P4Admin.

Method	Description
addAlert(msg [,image])	Adds an alert to the P4Admin Alerts widget. 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().
deleteAlert(ID)	Deletes the specified alert from the Alerts widget on the P4Admin Home tab. Returns false if the specified alert is not found.
openUrlInBrowser(url)	Launches the default web browser and displays the specified URL.
startAlertRefreshTimer(int)	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.

Method

Description

addAlert(msg [,image])

Adds an alert to the P4Admin Alerts widget.

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().

deleteAlert(ID)

Deletes the specified alert from the Alerts widget on the P4Admin Home tab. Returns false if the specified alert is not found.

openUrlInBrowser(url)

Launches the default web browser and displays the specified URL.

startAlertRefreshTimer(int)

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.

Method	Description
getApiVersion()	Returns a string containing the version (level) of the JavaScript API.
getCharset()	For Unicode-mode servers, returns a string containing the character set in use (P4CHARSET).
getClient()	Returns a string containing the client workspace name. (P4V only)
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. Return values are: super, admin, write, open, read, list, no access.
getPort()	Returns a string containing the Perforce server connection setting.
getServerRootDirectory()	Returns a string containing the directory on the host machine where the Perforce server stores its metadata files.
getServerSecurityLevel()	Returns a string containing the server security level.
getServerVersion()	Returns a string containing the server version number.
getSubmitChange()	Returns an integer containing the changelist number passed to a replacement Submit dialog
getUser()	Returns a string containing the current user.
isServerCaseSensitive()	Returns a string containing "true" or "false," indicating whether the server is case-sensitive.
isServerUnicode()	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: { [str] data: when tagged data returned, array of tag/value pairs. int size: number of members in data array str error: server error text, if any str info: server info text, if any str text: text returned only by diff2 command }

Method

Description

getApiVersion()

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

getCharset()

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

getClient()

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

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.

Return values are: super, admin, write, open, read, list, no access.

getPort()

Returns a string containing the Perforce server connection setting.

getServerRootDirectory()

Returns a string containing the directory on the host machine where the Perforce server stores its metadata files.

getServerSecurityLevel()

Returns a string containing the server security level.

getServerVersion()

Returns a string containing the server version number.

getSubmitChange()

Returns an integer containing the changelist number passed to a replacement Submit dialog

getUser()

Returns a string containing the current user.

isServerCaseSensitive()

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

isServerUnicode()

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:

{

[str] data: when tagged data returned, array of tag/value pairs.

int size: number of members in data array

str error: server error text, if any

str info: server info text, if any

str text: text returned only by diff2 command

}

Method	Description
encodeForHTML(str) encodeForHTMLAttribute(str) encodeForJavaScript(str)	Encodes characters to prevent XSS attacks injected into dynamic data. For details, see Preventing Cross-Site Scripting (XSS) Attacks.
setWebKitDeveloperExtrasEnabled(bool)	Enables or disables the Inspect item in the context menu, which displays the WebKit WebInspector for debugging.
getImage(imagename)	Returns a string containing the specified P4V image in HTML embedded format. Use the names returned by getImageNames().
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.
getSelection	Returns a list of the folders and files that are currently selected in the depot pane.
setP4VErrorDialogEnabled(true\|false)	Enable/disable display of server errors in popups. (By default, server errors are displayed in popups. Specify true to enable, false to disable.
setSelection(selList[,function(callback)]	Given a list of paths and files, selects them in the depot pane and, if specified, executes the optional callback function.
Map	Enables you to construct an optimized workspace mapping for a client workspace specification that your application creates or modifies.

Method

Description

encodeForHTML(str)

encodeForHTMLAttribute(str)

encodeForJavaScript(str)

Encodes characters to prevent XSS attacks injected into dynamic data. For details, see Preventing Cross-Site Scripting (XSS) Attacks.

setWebKitDeveloperExtrasEnabled(bool)

Enables or disables the Inspect item in the context menu, which displays the WebKit WebInspector for debugging.

getImage(imagename)

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

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.

getSelection

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

setP4VErrorDialogEnabled(true|false)

Enable/disable display of server errors in popups. (By default, server errors are displayed in popups.

Specify true to enable, false to disable.

setSelection(selList[,function(callback)]

Given a list of paths and files, selects them in the depot pane and, if specified, executes the optional callback function.

Map

Enables you to construct an optimized workspace mapping for a client workspace specification that your application creates or modifies.

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.

P4JsApi.Map.join(map1, map2): Returns the map that results from joining the two input maps.

map: A list of mapping lines.

Method	Description
clear()	Clears the mapping lines
count()	Returns the number of mapping lines
empty()	Returns true if the map is empty
includes(path)	Returns true if path is mapped
insert(left, [right])	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
join(map)	Returns a new map of this object joined with map.
left()	Returns a list of the left side of the mapping
new([s])	Constructs a new Map object. s can be a single mapping line string or a list containing mapping line strings
reverse()	Returns a new P4JsApi.Map object with the left and right sides of the mapping swapped
right()	Returns a list of the right side of the mapping
translate(path, reverse)	Translates path through the map and return the result. If reverse is true, translate from right to left

Method

Description

clear()

Clears the mapping lines

count()

Returns the number of mapping lines

empty()

Returns true if the map is empty

includes(path)

Returns true if path is mapped

insert(left, [right])

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

join(map)

Returns a new map of this object joined with map.

left()

Returns a list of the left side of the mapping

new([s])

Constructs a new Map object. s can be a single mapping line string or a list containing mapping line strings

reverse()

Returns a new P4JsApi.Map object with the left and right sides of the mapping swapped

right()

Returns a list of the right side of the mapping

translate(path, reverse)

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

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.

Command	Central Settings and Alerts	P4V and P4Admin Tab	Submit Dialog
add		Yes
add -n	Yes		Yes
annotate	Yes	Yes	Yes
archive		Yes
attribute		Yes
branch		Yes
branch -o	Yes		Yes
branches	Yes	Yes	Yes
broker	Yes	Yes	Yes
change		Yes	Yes
change -o	Yes
changelist	Yes	Yes	Yes
changelists	Yes	Yes	Yes
changes	Yes	Yes	Yes
client		Yes
client -o	Yes		Yes
clients	Yes	Yes	Yes
configure		Yes
copy		Yes
copy -n	Yes		Yes
counter 1	Yes	Yes	Yes
counters	Yes	Yes	Yes
cstat	Yes	Yes
dbschema		Yes
dbstat	Yes	Yes	Yes
delete		Yes
delete -n	Yes		Yes
depot		Yes
depot -o	Yes		Yes
depots	Yes	Yes	Yes
describe	Yes	Yes	Yes
diff	Yes	Yes	Yes
diff2	Yes	Yes	Yes
dirs	Yes	Yes	Yes
edit		Yes
edit -n	Yes		Yes
export		Yes
filelog	Yes	Yes	Yes
files	Yes	Yes	Yes
fix		Yes	Yes
fixes	Yes	Yes	Yes
fstat	Yes	Yes	Yes
grep	Yes	Yes	Yes
group		Yes
group -o	Yes		Yes
groups	Yes	Yes	Yes
have	Yes	Yes	Yes
help	Yes	Yes	Yes
info	Yes	Yes	Yes
integrate		Yes
integrate -n	Yes	Yes	Yes
integrated	Yes	Yes	Yes
interchanges	Yes	Yes	Yes
istat		Yes
istat none	Yes		Yes
job		Yes	Yes
job -o	Yes
jobs	Yes	Yes	Yes
label		Yes
label -o	Yes		Yes
labels	Yes	Yes	Yes
license		Yes
license -o	Yes		Yes
lock		Yes
lockstat	Yes	Yes	Yes
logger	Yes	Yes
login 2		Yes
logout		Yes
logstat	Yes	Yes	Yes
logtail	Yes	Yes	Yes
merge		Yes
merge -n	Yes		Yes
monitor 3		Yes
move		Yes
move -n	Yes		Yes
obliterate 4	Yes	Yes	Yes
opened	Yes	Yes	Yes
passwd		Yes
print	Yes	Yes	Yes
protect		Yes
protect -o	Yes		Yes
protects	Yes	Yes	Yes
reopen		Yes
replicate		Yes
resolve		Yes
resolve -n	Yes		Yes
resolved	Yes	Yes	Yes
restore		Yes
revert		Yes
revert -n	Yes		Yes
review		Yes
reviews	Yes	Yes	Yes
shelve		Yes
sizes	Yes	Yes
sizes		Yes	Yes
spec		Yes
spec -o	Yes		Yes
stream		Yes
stream -o	Yes		Yes
streams		Yes
streams -o	Yes		Yes
submit		Yes	Yes
sync		Yes
sync -n	Yes		Yes
tag		Yes
tag -o	Yes		Yes
triggers		Yes
triggers -o	Yes		Yes
typemap		Yes
typemap -o	Yes		Yes
unlock		Yes
unshelve		Yes
unshelve -n	Yes		Yes
user		Yes
user -o	Yes		Yes
users	Yes	Yes	Yes
verify		Yes
where	Yes	Yes	Yes
workspace		Yes
workspace -o	Yes		Yes
workspaces	Yes	Yes	Yes

Command

Central Settings
and Alerts