P4Web User Guide - P4Web URL Reference

You can link to Perforce depot information from within your own HTML documents by constructing URLs that direct P4Web to return specified data. Such URLs can be used in email, in web pages (static or CGI-generated), and in any context where URLs are useful. You can create scripts that construct such URLs and pass them to a Web browser, enabling users to display Perforce information without requiring them to install Perforce client applications on their computer. In constructing the URLs, use the same options and flags that you use on the command line.

Some simple examples:

To simplify the process of creating these custom URLs, P4Web includes a convenient Permalink in the lower right-hand corner of each page it generates.

URL Syntax

http://p4webhostname:port/[@parameters@][/]/object[[?ac=n][&parameters]]

P4Web uses a variety of other elements in the URLs that it constructs, but you can omit these elements in the URLs that you construct for your queries. The basic elements of URLs for P4Web are as follows.

To specify a folder or file that resides in the Perforce server, use the following syntax:

//depot_path/[@revision_specifier]

where //depot_path/ specifies the file or folder and revision_specifier is a changelist number, label, or date in yyyy/mm/dd format. The depot path can be preceded by a single slash or the Perforce standard double slash.

To specify special-purpose characters in URLs, use the standard escape sequence %hex-value. You must escape the following special-purpose characters:

• #
• ?
• &
• =

For example, to display a list of labels owned by user bruno, you can create a URL that includes the p4 labels command. The following URL uses the %20 escape sequence to specify the spaces required to separate the syntactic elements of the command:

http://myserver.perforce.com/p4%20labels%20-u%20bruno?ac=201

Action Codes

The following table lists the action codes that are supported for P4Web URLs. There are no action codes for commands that require administrator privileges.

Commonly-Used Parameters

P4Web uses a variety of parameters in the URLs it constructs. Many of the parameters are for internal use and are not relevant for scripting. To construct the precise URL for the information you seek, browse using P4Web until you have the desired results displayed, then copy the URL from the address bar and use it as the basis to construct your own URL. Commonly-used parameters are as follows.

Parameter	Description
&cd=path	Path to a folder
&nx=n	Maximum number of items to display
&pat=file_matching_pattern	Wildcard expression for matching a set of files
&rev1=n, @rev2=n	Specifies a pair of revisions, for example, for diffing files
&sho=flag	Specifies the partial results that you want returned, as described below
&sr=@revision_specifier	A Perforce revision specifier (revision number, label, date, or changelist number)

Displaying Sections of Results Pages

To display specified sections of the full-page results that P4Web normally returns, add sho=section[, section...] parameters to the URL.

Example: sho=title,filter,body. This feature enables you to embed specified portions of P4Web pages into your own web pages.

Valid sections are as follows:

To ensure that any generated links in results pages return the same sections, place the sho parameter between the "at" signs (@) in the URL that you send to P4Web. For example:

http://p4webhost:8080/@sho=logo,body@//?ac=83

The page returned by the preceding URL contains only the logo and body. All generated links in this results page also contain the sho=logo,body parameter and return only the logo and body when you click them. To ensure that all generated links in the results page return full pages, place the sho parameter at the end of the URL.