Perforce plug-in
NOTE: This plug-in has a server side dependency on the Perforce command line
p4.exe
Provide access to information from a Perforce server.
Perforce is a well known software configuration management system.
Syntax Rules
TWiki plug-in variables
P4CHANGES
Simply gives you the output of the
p4 changes command.
%P4CHANGES{"p4changesoptions" format="format" header="header" footer="footer" ajax="ajax" label="label"}%
| Parameter |
description |
example |
default value |
| p4changesoptions |
This must be some valid p4 changes options |
-m 10 |
none |
| format |
A template string used to format each change record. See below for the supported variables. If none specified the output of the command is returned with HTML br element append to each line. |
| $changelist | $description | |
none |
| header |
Specify a header for the formatted output. |
| *Parameter* | *description* | *default value* | |
none |
| footer |
Specify a footer for the formatted output. |
nice footer |
none |
| ajax |
Tell the plug-in to delay running of the p4 command. Instead of the command output it displays a button that will allow the user to fetch the information from Perforce on demand. The given value defines the id of the div element to be loaded upon ajax request completion. |
ajaxdivid1 |
none |
| label |
Used only in ajax mode. It defines the label of the ajax button. |
Fetch changes |
Fetch Perforce changes |
| method |
Used only in ajax mode. Do not use that parameter unless you know what you are doing. Although both modes work fine on TWiki 4.2 we could not get GET to function on 4.1.2. Can be POST or GET. |
GET |
POST |
P4CHANGESPI
Gives you the changes pending for integration for a specified branch specification. It is achieved by parsing the output of a single
p4 integrate -n command and gathering the corresponding changes by running n times the relevant
p4 changes commands.
%P4CHANGESPI{"branch" format="format" header="header" footer="footer" description="description" reverse="reverse" ajax="ajax" label="label" }%
| Parameter |
description |
example |
default value |
| branch |
The name of the branch used for integration |
mybranchname |
none |
| format |
A template string used to format each change record. See below for the supported variables. If none specified the output of the command is returned with HTML br element append to each line. |
| $changelist | $description | |
none |
| header |
Specify a header for the formatted output. |
| *Parameter* | *description* | *default value* | |
none |
| footer |
Specify a footer for the formatted output. |
nice footer |
none |
| description |
Can be long ( use p4 changes -L flag ) or full ( use p4 changes -l flag ). |
full |
none |
| reverse |
Set to on to perform a reverse integration. ( use p4 integrate -r flag ) |
on |
none |
| ajax |
Tell the plug-in to delay running of the p4 command. Instead of the command output it displays a button that will allow the user to fetch the information from Perforce on demand. The given value defines the id of the div element to be loaded upon ajax request completion. |
ajaxdivid1 |
none |
| label |
Used only in ajax mode. It defines the label of the ajax button. |
Fetch changes |
Fetch Perforce changes |
| method |
Used only in ajax mode. Do not use that parameter unless you know what you are doing. Although both modes work fine on TWiki 4.2 we could not get GET to function on 4.1.2. Can be POST or GET. |
GET |
POST |
REST interface
p4changes
%SCRIPTURLPATH%/rest/PerforcePlugin/p4changes?topic=%WEB%.%TOPIC%&_DEFAULT=p4changesoptions&format=format&header=header&footer=footer
p4changesoptions,
format,
header and
footer parameters are the same as for the TWiki plug-in variable. Parameters
ajax and
label are not supported.
p4changespi
%SCRIPTURLPATH%/rest/PerforcePlugin/p4changespi?topic=%WEB%.%TOPIC%&_DEFAULT=branch&format=format&header=header&footer=footer&description=description&reverse=reverse
branch,
format,
header,
footer,
description and
reverse parameters are the same as for the TWiki plug-in variable. Parameters
ajax and
label are not supported.
The following symbols specified in the
format parameter are substituted with the record information.
| Variable |
description |
example |
$changelist |
Perforce change list number |
12345 |
$year |
Changelist year as defined by Perforce |
2008 |
$month |
Changelist month as defined by Perforce |
02 |
$day |
Changelist day as defined by Perforce |
28 |
$date |
Changelist date as defined by Perforce |
2008/02/28 |
$user |
Perforce user to which the changelist belong to |
myperforceuser |
$client |
Perforce client to which the changelist belong to |
myperforceclient |
$status |
Changelist status. Can be submitted or pending |
pending |
$description |
Perforce change description |
I fixed Bug:123 |
| Variable |
description |
example |
$nop |
Replaced with nothing. |
|
$quot |
Replaced with a double quote |
" |
$percnt |
Replaced with a percent |
% |
$pipe |
Replaced with a pipe.
Useful when embedded in TWiki table |
| |
$dollar |
Replaced with a dollar |
$ |
$n |
New line character |
\n |
Examples
See
PluginTestPerforcePlugin.
Get the last ten change list
%P4CHANGES{" -m 10" format="| $changelist | $date | $description | $user | $status | $n"}%
Get the last ten change lists on a branch
%P4CHANGES{" -m 10 //depot/branches/rel_1_0_1/..." format="| $changelist | $date | $description | $user | $status | $n"}%
Get change lists on a branch between change 100 and change 200
%P4CHANGES{" //depot/branches/rel_1_0_1/...@100,200" format="| $changelist | $date | $description | $user | $status | $n"}%
Usage recommendations
Keep in mind that this plug-in runs potentially time consuming commands on your web server.
When using
P4CHANGES always limit the number of results by either:
- Using the
-m Perforce option.
- Restricting the scope of your
p4 changes command to a specific Perforce depot path or file.
- Restricting the scope of your
p4 changes command to a range of changes.
For best user experience we recommend you make use of the REST interfaces through AJAX. Novice web programmer will find the
ajax parameter useful. Experienced web programmer can make use of the
jquery.spinner.js provided with
Foswiki:Extensions.JQueryDevPlugin and soon also available in
Foswiki:Extensions.JQueryPlugin. Be aware that notably the
P4CHANGESPI request can take a significant amount of time to complete and goes much smoother when displaying an animation such as a spinner.
Plug-in Settings
As per the new plug-in development guidelines this plug-in do not make use of preferences variables for settings and configuration. Instead settings are stored in
/lib/LocalSite.cfg. See the installations instructions below.
Plug-in Installation Instructions
Note: You do not need to install anything on the browser to use this plug-in. The following instructions are for the administrator who installs the plug-in on the TWiki server.
- Download the ZIP file from the Plug-in Home (see below)
- Unzip
PerforcePlugin.zip in your twiki installation directory. Content:
| File: |
Description: |
data/System/PerforcePlugin.txt |
Plug-in topic |
data/Sandbox/PluginTestPerforcePlugin.txt |
Plug-in examples |
lib/Foswiki/Plugins/PerforcePlugin.pm |
Plug-in Perl module |
- Configure the Plug-in:
- Run the configure script to enable the Plug-in
- Change the Plug-in settings as needed
- Edit
/lib/LocalSite.cfg and define the following values according to your Perforce environment:
$TWiki::cfg{Plugins}{PerforcePlugin}{p4port} = "perforce-srv:1666" ;
$TWiki::cfg{Plugins}{PerforcePlugin}{p4client} = "myp4clientname" ;
$TWiki::cfg{Plugins}{PerforcePlugin}{p4user} = "mylogin";
$TWiki::cfg{Plugins}{PerforcePlugin}{p4password} = "mypassword";
NOTE: It turns out that you don't even need to specify an existing
p4client to run
p4 changes commands.
- If the installation was successful you should get valid information in the table below:
| Changelist |
Date |
Description |
User |
Status |
|
%P4CHANGES{"-m 10" format="| $changelist | $date | $description | $user | $status | $n"}%
Plug-in Info
Related Topics: Plugins,
DeveloperDocumentationCategory,
AdminDocumentationCategory,
DefaultPreferences,
SitePreferences
PerforcePlugin is not installed on Foswiki.org.
md5 
tgz 
Legal Imprint Privacy Policy