TIP PerforcePlugin is not installed on Foswiki.org.

Perforce plug-in

ALERT! 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.

Format variable substitution

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

Plug-in Author: TWiki:Main.StephaneLenclud
Copyright: © 2008, TWiki:Main.StephaneLenclud
License: GPL (GNU General Public License)
Plug-in Version: 16 Apr 2008 (V0.8)
Change History:
16 Apr 2008: Adding -d flag to integrate command. Fixing integrate command line parser.
02 Mar 2008: Adding usage recommendations. Fixed documentation following TWiki:Main.PeterThoeny review.
28 Feb 2008: Adding P4CHANGESPI and its REST interface.
27 Feb 2008: Adding $pipe variable.
26 Feb 2008: Removing some \n from ajax mode output. Other minor fix.
21 Feb 2008: Support method parameter in AJAX mode. Default AJAX method is now POST. URL encoding parameters value in GET mode. Now encoding HTML entities in description field.
20 Feb 2008: Fixing bug preventing TWiki:InterWikiPlugin to auto link at beginning and at the end of changes description lines
Fixing missing last changes entry in long description mode ( -l and -L options )
15 Feb 2008: Documentation, more parameters, ajax/jquery support
14 Feb 2008: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: Perforce command line p4.exe
Foswiki:Extensions.JQueryPlugin or Foswiki:Extensions.JQueryDevPlugin optional. Only for AJAX functionality
Perl Version: 5.005
Benchmarks: GoodStyle nn%, FormattedSearch nn%, PerforcePlugin nn%
Plug-in Home: http://foswiki.org/Extensions/PerforcePlugin
Feedback: http://foswiki.org/Extensions/PerforcePluginDev
Appraisal: http://foswiki.org/Extensions/PerforcePluginAppraisal

Related Topics: Plugins, DeveloperDocumentationCategory, AdminDocumentationCategory, DefaultPreferences, SitePreferences

Topic revision: r7 - 09 Dec 2009, CrawfordCurrie - This page was cached on 24 Aug 2016 - 16:04.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License