This guide includes instructions for embedding an A.nnotate panel within your own application. It assumes you have already installed a local copy of a.nnotate. There is a sample page included with the server at php/sample-proof.php live demo [source code] which demonstrates how to embed an A.nnotate view of a PDF panel in an iframe. Clients can add comments without needing to log in or create an account, and your in-house team can access and deal with the suggestions.

How it works

The sample at php/sample-proof.php [source code] includes a worked example which you can use as a starting point; the sample is in PHP, but you can use any web scripting language to embed an A.nnotate panel (ASP, JSP, Perl, Python etc). You can save the PHP source code as a file on your own PHP enabled web server (rename it from 'sample-proof.txt' to 'sample-proof.php') and it should show an embedded A.nnotate PDF viewer / annotate window.

The sample first does a HTTP GET to upload a PDF, then embeds an IFRAME into the page which points to the annotatable version. To integrate it with your own system, you would want to pass parameters such as the link to the PDF / Word document and the user name to sign notes with (e.g. "guest"). In this example, the clients are not logged on to the A.nnotate system, but are authorized to add notes to a single document at a time.

Step 0: Create a user account for the uploaded PDFs

You should create a separate user account for the uploaded PDFs. You can do this by registering an email address as normal (via the 'index.php' link in your local A.nnotate installation). You may wish to change the password from the automatically generated random password on the account page. All uploads can be pooled into a single account if needed, as the clients are only ever authorized to view and annotate a single document at a time.

Step 1: Specify the PDF file to annotate

The first step is to get your script to perform a HTTP GET request to php/swfupload.php, passing a number of parameters: a URL link to the PDF to display, the user email / password for the user account specified in step 0, a version number (optional). This script will return a link to the converted document which you can use as the src= of an iframe, to be embedded in your web page.

// The sample URL below shows the GET parameters.
// *NB* You need to URI encode the values (%40 inplace of @ etc)
// and it needs to be all on one line.
http://a.nnotate.com/php/swfupload.php?      % Replace with path to your A.nnotate server
  fmt=txt
  &url=http://test.nnotate.com/php/test.pdf     % Replace with URL of your PDF
  &user=test@textensor.com                      % The PDF will be uploaded to this account
  &password=test                                % ... with this password
  &version=1                                    % (optional) change the version number if the pdf changes
  &nocache=0                                    % (optional) set to 1 if you want subsequent GETs to reupload


// Fetch the result from an HTTP GET of the above URL
// The result will the plain text string "OK " + a link relative to the php/ dir of your a.nnotate server
OK pdfnotate.php?d=2008-01-01&c=abcdef&aac=zzzz

// or, if there was a problem uploading the PDF it will return:
ERR {error message}

A note on caching

The swfupload.php script will first check whether the given URL has already been uploaded to the account, and if it has it will return the link immediately without reconverting the PDF. You can change this behaviour (e.g. for debugging) by setting the 'nocache=1' flag. If the PDF is updated, but its URL link remains the same, you can also increment the version=123 parameter, or set it to the file modification time to reupload.

Step 2: Use the returned URL as the src= link of an iframe

The pdfnotate.php?...link returned above is relative to the php/ directory of your A.nnotate server (e.g. http://mysite.com/php/). You should append a couple of GET arguments to the link: &nobanner=1&asig=guest123. The nobanner=1 switches off the banner which is usually displayed at the top of documents in A.nnotate (with the Documents / Notes / Account menu, probably not relevant to guest users). asig=guest123 specifies the signature to use for the anonymous user. A sample is given below:-

<iframe src='http://mysite.com/php/pdfnotate.php?d=2008-01-01&c=abcdef&aac=zzzz&nobanner=1&asig=guest123' 
  style='border:1px solid black' width='99%' height='80%'>
</iframe>

Step 3: Generating a link to send to in-house team to review customer comments

The pdfnotate.php?... link returned in step 1 includes an authorization code for adding anonymous comments to the documents in the &aac=zzzz parameter. To generate a link which you can send to your in-house team to view the document with comments in the full A.nnotate view, you should chop off this parameter, and just include the d=...&c=... parameters, e.g. pdfnotate.php?d=2008-01-01&c=abcdef This could be emailed to reviewers, or added to a local database or log using your own code.

Putting it all together - the PHP sample code

A complete example is given below which uses PHP - the process for other scripting languages should be similar. In PHP, file_get_contents can be used to do a HTTP GET if passed a URL. [download source code]

  // Upload the PDF to the annotate server

  //
  // URL of the local annotate server's php                       
  // e.g. 'http://mysite.com/annotate/php/
  //
  $annotate_server = "http://a.nnotate.com/php/";

  // *** Change this to be the url of the pdf you want to annotate
  $pdfurl = $annotate_server."test.pdf";
 
  // *** The PDF will be uploaded to the following a.nnotate account,
  // and notes will be signed using the account's user name,
  // if you are not already logged in.
  // You will need to create an account for this user, and validate their
  // license. Go to their 'account' page to change the password from
  // the automatically generated one.
  $annotate_email = "test@textensor.com";
  $annotate_password = "test101";

  // Guest notes will be signed as follows.
  $guestsig = "client123";

  $version = "2";  // can add a version number if the url stays the same, but the file version changes.
  $nocache = "0"; 
  // $nocache='1'; // to force a refetch of the same pdf URL each time

  // This call fetches the PDF from the given URL and returns
  // a link which you can use as the src of an iframe.
  $uploadurl = $annotate_server."swfupload.php?fmt=txt&url=".rawurlencode($pdfurl). 
        "&user=".rawurlencode($annotate_email).
        "&password=".rawurlencode($annotate_password).
        "&version=".$version."&nocache=$nocache";

  $ret = file_get_contents($uploadurl);
      
  // The return value is something like: 
  // "OK pdfnotate.php?d=2008-01-01&c=abcdef&aac=zzzz"
  // or "ERR <error message>"
  // The aac value is an anonymous auth code which lets
  // guests add notes to this document without logging in.
  
  if (substr($ret, 0, 2) == "OK") {
     $embedsrc = $annotate_server.trim(substr($ret, 3));
     $linksrc = $embedsrc;

     // strip off the aac= parameter if present for the link
     // to give out to in-house people with annotate accounts.
     $pos = strpos($linksrc, "&aac=");
     if ($pos) { $linksrc = substr($linksrc, 0, $pos); }

     // The link to allow people to view these notes.
     print "<p style='margin:1em'>You can also ";
     print "<a target='_blank' href='".$linksrc."'>open the page in a new window</a></p>\n\n";

     // Include an iframe which embeds the pdf
     print "<iframe src='".$embedsrc."&nobanner=1&asig=".$guestsig.
           "' style='border:1px solid black' width='99%' height='80%'></iframe>\n\n";
  }
  else {
    print "<p>There was a problem uploading $pdfurl ( $ret )  ".
          "from the annotate server at URL: $annotate_server (url : $uploadurl)</p>\n";
  }
      

Please email any questions to support [at] nnotate.com.