README #5

                 Release Notes for P4JsApi Sample Code
                            Version 2010.1

Introduction

In order to give beginning to experienced Javascript programmers
an overview of the capabilities of the Perforce JavaScript API
(P4JsApi), we've included some examples of a variety of coding
techniques, from simple HTML to complex examples utilizing the
Ext JS frameworks and Google™ visualization code to add graphs
and other ways to display data in P4V and P4Admin.

These notes should give you an idea of what you will need to
successfully run these examples.

NOTE: These scripts ares example only, and should be modified to
work in a production environment. No warranty is expressed or
implied. Scripts should be tested thoroughly on a test server
before using in a production environment.

Unless otherwise specified, all code is Copyright (c) 2010,
Perforce Software, Inc.  All rights reserved. See the bottom of
these release notes for the complete Copyright statement.

--------------------------------------------------------------------------
Standalone Tab Examples:

    imageListNoFramework.html

    - Demonstrates the P4JsApi .getImage and .getImageNames
      methods.

    serverInfoNoFramework.html

    - Displays basic server info.

Note: While these are standalone examples, they contain the
following commented code:

    <!--<script type='text/javascript'
        src='https://getfirebug.com/firebug-lite.js'>
    </script>-->

Un-commenting this code will give you access to Firebug Lite, a
light weight version of the Mozilla web developer tool. You will
need to have access to the internet for this feature to work. All
of the HTML files in the P4JsApi example code will have this line
for your convenience.

--------------------------------------------------------------------------
Examples using Ext JS (Extend Javascript) Frameworks

Installing Ext JS:

The Ext JS frameworks are a set of javascript files and resources
to allow Javascript developers to develop complex graphical
front-ends for their Javascript code. Perforce applets can use these
frameworks to provide a better end user experience with Perforce
applets. Ext JS is available with open source and commercial
licenses.

Before you can use these examples you will need to download the
Ext JS from:

    http://www.extjs.com/products/js/download.php

For complete API documentation for Ext JS, please refer to:

    http://www.extjs.com/deploy/dev/docs/

Select the "Public Release".

After you completed downloading the Ext JS archive, decompress
it. You should have a folder called Ext-(version), such as
"Ext-3.2.0".

Change the name of the folder to "ext" and place it in the "js"
folder. When you're done, the folder structure should appear as:

    - examples
        + css
        + images
        - js
            + alerts
            + dashboard
            + ext

--------------------------------------------------------------------------
Ext Js Tab Examples

    imageList.html
    imageList.js

    - Demonstrates the P4JsApi .getImage and .getImageNames
      methods using Ext Js.

    serverInfo.html
    serverInfo.js

    - Displays basic server info, plus demonstrates how
      additional server information can be added and moved between
      multiple columns..

The P4JsApi examples have been tested with Ext JS 3.0.0 and 3.2.0.

--------------------------------------------------------------------------
Advanced Ext Js Example

    dashboard.html
    dashboard.js

    - The dashboard example is an example of how Perforce
      administrators can implement a rich GUI environment as a P4V
      or P4 Admin applet. It includes a set of example widgets and
      support scripts in the js/dashboard directory:

          changelist.js
          changes.js
          charts.js
          counters.js
          dbstat.js
          license.js
          processes.js
          spotlight.js
          users.js

      Additional widgets can be created for the dashboard applet.

--------------------------------------------------------------------------
Alert Examples

P4JsApi can be used to add customized alerts to the P4 Admin
alerts pane, located on the home tab.

    securityAlert.js

    - This is a simple alert that adds a message if the security
      level (as determined from "p4 counter security") is set to 1
      or 0. It does not track the alert ID, which means alerts
      issued from this code will remain in the alerts pane until
      the P4 Admin window is refreshed.

    processThresholdAlert.js

    - Uses "p4 monitor show" and uses it to issue an alert if
      the number of current processes exceeds a given threshold.
      This alert demonstrates how to track the alert, updating or
      deleting it as needed.

    driveCapacityAlert.js

    - Uses the "df" command and an archive trigger to obtain the
      current drive usage on the Perforce server, and issues an
      alert if any of the drives are above a given percentage of
      capacity.

      Note: Requires the addition of a trigger table entry. This
      process is outlined in the next section.

--------------------------------------------------------------------------
Using Archive Triggers to Obtain Non-Perforce Command Line Output

To avoid security issues, the P4JsApi code does not provide a way
to issue non-perforce commands directly to the Perforce server.
That said, this tip will allow you to obtain output from almost
any command line utility.

Note: This example assumes a Unix based OS, or Windows using
installed unix commands, such as Cygwin.

    - Add a trigger table entry for the command:

          df_cmd archive //depot/triggers/df df

Note: The path should be a section of the depot not accessible by
non-super users.

    - Create the file for the trigger at the depot location
      specified in the trigger:

          touch /workspace/depot/triggers/df

    - Add the file to the Perforce server as file type +X (archive

      trigger required):

          p4 add -t +X /workspace/depot/triggers/df

    - Submit the file:

          p4 submit -d 'Added df trigger file'

Note: If you see an error message similar to:

    No archive trigger defined for //depot/triggers/df

Check your trigger table entry for typos.

You can test this trigger using "p4 print":

    p4 print //depot/triggers/df

Which should produce output similar to:

    //depot/triggers/df#1 - edit change 1226 (text+X)
    Filesystem    512-blocks    Used       Available    Capacity    Mounted on
    /dev/disk1s2  976101344     248519216  727070128    26%         /
    (...)

This same technique can be used to obtain other server statistics or output.

--------------------------------------------------------------------------
Customizing the Submit Dialog

    submitNoFramework.html
    submitNoFramework.js
    submitNoFramework.css

    - Replaces the standard P4V submit dialog with an HTML document.
      While this does not use a framework, it does use a style sheet
      to create a rich UI.

Note: If you are locked out of submitting files to your test
server while developing a new submit dialog using the P4JsApi,
your options are:

    - Turn off applets in P4V's applet preferences.
    - Disable the central settings file in the Protections spec.
    - Use the command line (or other) Perforce client to

      submit a fixed submit dialog.

--------------------------------------------------------------------------
Copyright (c) 2010, Perforce Software, Inc.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  1.  Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

  2.  Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.