Dynamic modification of PayPal data.

 std.css

Revision History.
* 05 May 2007 - Added a discussion of the how hashing can hide client-side values.
* 6 September 2006 - added hash algorithm for things like passwords.
* 17 October, 2005 - One select can modify following selects on a page.
* 14 May, 2005 - Expanded the "Simple" scripts quite a bit. Item name indicates where to store value.
* 25 April, 2005 - Added description of how to send FORM to 2nd HTML page.
* 3 January, 2005 - Added list of free aids to your website. Some good stuff here! (at the bottom)
* 17 October, 2004 - Added Article on limiting quantities.
* 30 August, 2004 - Added secure (encrypted data) article.
* 28 June, 2004 - How to Auto clear FORM after submission.
* 5 March, 2004 - Explained modifications to the View Cart button.
* 18 January, 2004 - Added discussion of separate email support.
* 10 January, 2004 - Enhance upload programs for taxes.
* 4 January, 2004 - auto.js deleted (too many problems) - go to a cart.
* 27 December, 2003 - All top-level pages migrated to XHTML1.1 standards.
* 22 October, 2003 - Added topics for hiding email from spambots, and data encrypion.

ABSTRACT: The default PayPal shopping-cart or Single Item Purchase system only allows for the selection of a single item for any of their fields. And there is no interaction among them to permit the increase in cost for larger sizes, a discount for large quantities, the construction of a complex description field composed of several options, or a host of other possibilities. However, it is possible to dynamically modify any of these fields with JavaScript (JS) before the actual call to the PayPal add-to-cart page is made.

Any of the parameters of the PayPal call may be modified in the JS code. We can establish a base price for an item, modify that price according to size, offer discounts for large quantities, build a description field composed of many options, or whatever we want.

Included in this article are two distinct methods of getting all of this done. First, there are "plug-and-play" sections where all you have to do is include some JavaScript code in your HTML and just make use of it without really having to understand what it does. The second part is for the more knowledgeable HTML/JavaScript programmer who can appreciate other options I suggest.

NOTE The JavaScript used in this presentation is NOT browser specific, or linked to a specific version of any browser. It works for ALL browsers from IE4.0 and NN4.7 to the present. If your browser supports JS (version 1.1, or greater), it is able to execute this code. No exceptions! Plus, this is all client-side support of PayPal, and requires no server code!

Links available in this article. All code is available (HTML and JavaScript):

Plug-in code.

Overview: Here I provide some JavaScript (JS) that you incorporate into your site that allows you to interface with the PayPal data in dynamic ways. You do not have to know a thing about JS - you just use it with a simple call structure, or flag characters within FORM elements, to build data that is eventually sent to the PayPal shopping cart. You may set and then modify fields of the shopping cart such as the description, price and option data. You may also apply quantity discounts to specific items. You do this by making calls to the JS from event handlers within your HTML.

From your point of view everything is controlled from your HTML and you do not have to pay any attention to the JS at all. The interface is designed to work out of the HTML FORM structure, and all you have to do is to put each item on your page into a separate FORM and the rest is virtually automatic.

PayPal data is created, and modified if necessary, by a combination of calls to JS routines, and the contents of the FORM you build for each item. All you need to be aware of are the calls available to you, and the use of special flag characters within the FORM data you create in your HTML page.

Techniques: I provide the JS that you just add to your site, and you may then make calls that do what I am talking about from the HTML. You may set and then modify any PayPal cart field before these things are passed to PayPal.

Go to the pages that describe the plug-ins - their requirements are different. Those pages describe how to install and use the PLUGIN JavaScripts.

Notes for experienced HTML/JavaScript programmers.

Overview: The HTML/JavaScript interface allows the user to accumulate (in a dynamic manner) arguments that can be assembled into a description string, or a modified cost value, that can then be passed into the window.open function that calls the PayPal shopping cart window. There are several ways of doing this, and I shall include some specific examples, and suggest some other ways of doing this that should allow the experienced HTML/JavaScript programmer to visualize techniques that may be employed to dynamically build these fields.

These examples are not plug-in code - you cannot expect a JS file here to be something that will support your HTML without modification. Your JS must be built (using these examples as a guide) to go with your HTML.

Techniques: In order to build these fields dynamically we have to move data around either within a single HTML page, or between pages. Adding JavaScript to the picture we have all the tools required to move, collect and assemble data into a dynamically built PayPal call.

URL query strings: This is a little known, but effective, way of passing data between HTML pages. The query string is appended to a normal URL by starting the data with a "?" and having comma separated name=value pairs following (note that the data must be escaped, e.g. no spaces, and the name field must be in the form of a valid JavaScript variable):

   http://yoursite.com/page2.html?name1=val+1,name2=val+2

In the called HTML page this data may be extracted from the location property of the window with JavaScript, and the values placed into global JS variables for later assembly.

An example of when this might be used is if you have a main catalog-type page that lists items and their prices. If the user wants to buy that item he clicks on it and is taken to a page where further information (size, color, etc.) is collected. That item-price information is then combined with other style, or additional price, data in the called page and a complex description is built before the call to PayPal. There is an example of this a little later.

Arguments in JavaScript calls: Within an HTML page you may include calls to JavaScript functions and include arguments that can be used to augment the PayPal fields. This is usually done as part of some event handler, onclick for example.

    onclick = "Funct('style 1','style 2');"

Where "style 1" and "style 2" are some style information you wanted to include in the PayPal data fields.

JavaScript global variables (where to accumulate the data): In the JavaScript you need to establish variables with a global scope. One way to do this is to list all such variables before any functions are defined. These variables may then be addressed from any JavaScript code, either in the script file, or from the HTML as a result of some event.

After collecting all the bits you can string them together, or add them, and plug them into the PayPal data fields.

Code Example: Here we are going to use the methods above just to demonstrate how they work. In your main page you have something like this (note data in query string is escaped):

  <p>Suit Type 1. [picture] blah, blah.<br />
  - Brown suit $95.00
  <a href ="size.html?iname=Suit+Type+1,icolor=Brown,iamt=95.00">
  select size and add to cart</a><br />
  - Blue suit $96.00
  <a href = "size.html?iname=Suit+Type+1,icolor=Blue,iamt=96.00">
  select size and add to cart</a>
  </p>

And in SIZE.HTML: We can take some of the canned JS (auto, above) and add what is necessary to get the information from the query string. This creates a new JS file called size.js. Include it, as before, right after the <body> in your HTML. NOTE that it works without processing a FORM!

  <body>
  <script type = "text/javascript"
          src  = "size.js">
  </script>
  ...
  <a href=# onclick="AddDesc('40R');
                     CallPay ();"> 
    40 Regular </a><br />
  <a href=# onclick="AddDesc('40L');
                     CallPay ();"> 
    40 Long </a><br />
  <a href=# onclick="AddDesc('Fat Man');
                     AddPrice (13.00);
                     CallPay ();"> 
    Fat Man ($13.00 extra) </a><br />
  ...

What the above code does is to first extract the URL query string (in the script) and use that data to plug initial values into the PayPal call data. When the user selects a "size" a call is made to a JavaScript function just as in the canned example, and then makes the call to the PayPal cart with this accumulated data.

And in SIZE.JS you have how you get the data, assemble it and pass it to PayPal along with the calls in the canned JS... SIZE.JS source

Using FORMS to select data: You could have a site page with "FORM" items. The user selects an item from each of the fields, and then clicks on a single "add to PayPal cart" button that vectored him into a JavaScript function that read the form fields, ensured he made a selection from each of them, combined them into a single string, escaped them, and plugged them into the description field of the PayPal call.

How to read from and write to FORM fields. HTML has onclick "Read(this.form);"
elements[n] is the element of the item within the FORM.
FORM
Element		 Reading the element Writing the element
"text",
"textarea" 
function Read (obj1) {
var obj = obj1.elements[n];
  strn = obj.value;
}

function Write (obj1, strn) {
var obj = obj1.elements[n];
  obj.value = strn;
}
"checkbox",
"radio" 
function Read (obj1) {
var obj = obj1.elements[n];
  if (obj.checked) {
    strn = obj.value;
  }
}

function Write (obj1) {
var obj = obj1.elements[n];
  obj.checked = true;
}
"select-one" 
function Read (obj1) {
var obj = obj1.elements[n];
var pos = obj.selectedIndex;
  strn = obj.options[pos].value;
}

function Clear (obj1) {
  obj1.elements[n].options.length = 0;
}

function Write (obj1) {
var opt = new Option (strn);
var s = obj1.elements[n];
var l = s.options.length;
  s.options[l] = opt;
}

function Clear (obj1) {
  obj1.elements[n].options.length = 0;
}
"select-
multiple" 
function Read (obj1) {
var i=0, j, strn=new Array ();
var obj = obj1.elements[n];
  for (j=0; j<obj.options.length; j++) {
    if (obj.options[j].selected) {
      strn[i] = obj.options[j].value;
      i=i+1;  // bump array index
    }
  }
}

function Write (obj1, temp, i) {
  // new entry in dropdown
  opt = new Option (temp); // create
  s = obj1.elements[i];  // where
  s.options[s.options.length] = opt;
}

Summary: One of the things that was not made clear was that this was only a technique offering. The really important things about the techniques are...

  1. The formation of JavaScript global data that can be "plugged" with accumulated data from the HTML - either from JS calls, or from the FORM data you create.
  2. An example of some ways to plug values into this data before the JavaScript "call" to PayPal can be made.
  3. NO server code is required - it is all done in your code! And you have complete and total control of it.
  4. There is but a single call to the PayPal cart anywhere in your code! If you have many items on your page you don't need 10-20 lines of HTML for each call to PayPal - just one or two lines of JS to get it done. Less lines of code means it is easier to maintain, and it takes a lot less time to get the page loaded.

Once this is understood, then you can see how we can use other methods to get data to plug into the PayPal data fields. I just give some simple examples that open the door. The real power of the above is that there are MANY ways to dynamically build the PayPal data fields within an HTML/JavaScript environment that depend only on your knowledge and imagination.

APPENDIX A - Variables in the JS call to PayPal. NOTE. These variables are of two types: documented, and undocumented. What this means is that PayPal supports some of these variables in their current "cart" documentation, and others seem to WORK, but are not documented, and may not be supported in the future. Those questionable items are marked with an asterisk.

The way you use them is to put them into the "blkn" items of the JS variables, and reference them from the remainder of the JS code, such as the CallPay routine.

The usage is in the manner of a "URL query string", in that you include them in the form of a name=value pairing after a URL reference. Of course, all URL query strings MUST BE ESCAPED.

?cmd
This tells the PayPal CGI webscreen server code which command is going to be processed. There are two commands that are of interest to us: some sort of "cart" processing, or some sort of "one-time-click" processing. For this document we shall only deal with the "cart" processing options. ("?cmd=_cart").
_cart
The object of a "cmd" directive that causes some sort of interaction with the PayPal shopping cart. Either to "add" to the cart, or to "display" its contents.
_xclick
The object of a "cmd" directive that causes some sort of interaction with a one-time entry method into the PayPal database. It is either the order of a single item from PayPal, or something like the pre-population of Instant Payment Notification (IPN) data. The "Cart" software does not use this command directive.
add
A variable that if set true ("&add=1") indicates the addition of information to the PayPal shopping cart (which also displays the results). The other option is the "display" option - you may either add to the cart, or display its contents.
display
A variable that if set true ("&display=1") causes the display of the current contents of the PayPal shopping cart. The other option is the "add" option - you may either add to the cart, or display its contents.
currency_code
A code that specifies the currency you will accept for your products. The default (nothing specified) is U.S. Dollars. Here are the codes...
item_name
The name of the item (or items) being ordered. Limited to 127 characters that must be excaped when used in JavaScript.
item_number
A pass-through field that is not shown to the customer, but is available to you from IPN to track orders (associate credit card verification/denial with who placed the order).
lc
Country Code. If you sell to a single country you should use this code to ease your customer signup. It formats things like phone number according to the countr. You especially need to use it if you prepopulate PayPal fields for your customers. Certain things like telephone numbers will not prepopulate until you have specified the country code.
on0
The name of the first option field. Limited to 64 escaped characters. The value of this field is provided by the corresponding "os0" field. It appears in the order form as "name = value".
on1
The name of the second option field. Limited to 64 escaped characters. The value of this field is provided by the corresponding "os1" field. It appears in the order form as "name = value".
os0
The value to be associated with the first option field name. Limited to 200 escaped characters.
os1
The value to be associated with the second option field name. Limited to 200 escaped characters.
quantity
This item is defined in the "single-item" order interface (_xclick), and seems to work in the "cart" window (so far). It defines the number of items you are ordering.
upload
Subcommand of "?cmd=_cart". For uploading multiple items such as would be found in 3rd party shopping carts. Set to "true" (=1) to activate this mode. See "Adding PayPal Checkout to Your 3rd party Shopping Cart" (in the Paypal PDN) to see how this is done.

There are other values, but you can figure them out from the "PayPal Shopping Cart Manual". They are documented. And where the HTML says... 

    <input type="hidden" name="amount" value="6.66">

You may replace it in the JS with... 

    "&amount=6.66";

It's really simple. I hope I have helped you.

APPENDIX B - PayPal images in your page. A site like PayPal offers you "buttons" that you may include in the display of your page (PayPal Button Factory output). The only problem is that it can take many seconds for your page (as executed by the user) to open a connection to PayPal, and download that image.

The solution to this problem is for you to put these images on your site (which is already open to the user) and not load them from PayPal! It is very simple to do, but I have not seen a PayPal developer that is using these techniques.

In Internet Explorer (IE), when you find an image you like (when signed onto the PayPal site, for example), you just right-click on that image. You are then given a list of things to do with it that includes a "save as" selection. This gives you the opportunity to save it to your site, and save it under the name you want. Then (in your HTML) you reference the image that you have recorded, and not the image from PayPal. This makes your site much faster to load.

Here are some images I got from PayPal. Notice that they are within MY user space, and do not come from PayPal. AND, my page loads very fast, huh? The loading of my page depends only on the availability of my resources, and not on the current busy-ness of the PayPal site.

Cart Add Add Cart Cart View Cards pic

If you want to use any of these images, just try the right-click method to extract them from my user space into your own.

APPENDIX C - neat free stuff for your web site! These links offer valuable information, and it's all FREE! There are often versions of this stuff that you can subscribe to, but the free things can be an invaluable aid to you in making your site work better. I have no financial ties with any of these sites, and use many of them myself. (check at the bottom of this page)

  1. How are people finding your site? Search engines? Links from other sites? How many hits you getting? Which of your keywords are allowing people to find your site? What are their browsers? What countries are they in? This is the most interesting site I have found in a long time. Check it out! eXTReMe tracking! Tells you everything you ever wanted to know about how people find your site. MY HIGHEST RECOMMENDATION.
  2. Check out your HTML with a verifier! There are sites that offer free verification of your HTML. Is it up to the standards you specify? Perhaps not! You can check it out, and see. I state that my pages are verified at XHTML1.1 Strict standards - check me out! Click on the W3C buttons, below. An excellent learning and teaching site, too! Or go to w3c.org for the complete site. EXCELLENT site! Find out what is wrong with your HTML before you ask for help. That's what verifiers are for!
  3. Rank your site against other similar sites. Beware - this can be frought with problems. Some sites spend all their energy making sure they are at the top of a specific category. This will at least introduce you into the world of meta-tag use. This is an interesting read, at least - for other references just Google "site rank". You might also want to Google "meta tags". You can start by looking at the top of this page where meta tags are used.

Image: XHTML 1.1 certified! Image: CSS2 certified! Image: Multi-user accessibility!

Contact me concerning this article at paypalhelper@aol.com. Mention "main article" in your note.

Individual help starting at $25.00 for simple JS solutions.