Full-Featured Client-Side Shopping Cart.


Instructions for CPG 1.4x

This is a client-side Java (.js) shopping cart script, often referred to as a 3rd party cart. The script serves as an interface between your on site Paypal pages and PayPal. Users only interact with your shopping page so there are no official, encrypted "PayPal button" for this mod. Only when the user is done shopping, will s/he send information to the PayPal site for his/her final checkout. This provides a very secure shopping environment for your users. Everything you need is included in this module, you simply need to edit the standard_mounts.php and/or custom_mounts.phppage to suit your needs.

You can preview this mod at my site: "Artists in Hawaii", or you can test drive this mod, yourself, without having to install it permanently. Simply copy the files into the appropriate coppermine folders and open an intermediate view of any file. Next, replace the "displayimage.php" in the URL located in the address bar of your browser with "standard_mount.php" or "custom_mount.php and click 'enter' or 'go'. Making it a permanent installation that works with any product or picture in your Coppermine gallery only requires a few lines of code to be added to files that reside in the coppermine folders. See installation directions at the bottom of this page.

Files included in this installation: (copy gif files into CPG/images and themes/images folder; remaining files go into the CPG root directory.)
ecart1.gif < -- navbar button1
ecart2.gif < -- navbar button2
csecards.gif < -- credit card image for cart
cseprint.gif < -- printer icon for cart
cseset.js < -- admin controls for cart.
csecart.js < -- javascript to run cart.
csecart.php < -- client-side cart.
custom_mounts.php < -- user interface for custom mounts of pictures.
standard_mounts.php < -- user interface for standard mounts of pictures.
CS_Paypal_Instructions.html < -- this file

What we have here is a client-side cart that temporarily exists on the user's machine, not on a remote server, which provides your users with a very secure shopping environment. As all purchase information is stored in a cookie, there are some limitations. Most notably, users can purchase any quantity of no more than 15 different items at one time. This limitation is due to the session cookies used to remember cart contents across your website's pages. If this limitation doesn't bother you, then you will find this to be an extremely professional, fast and efficient shopping cart with a host of features normally not available to you with server-side carts.

To take full advantage of what this cart has to offer you will need to learn the calls that drive this cart - these calls are detailed, below.

The cart reads through the various < FORM > elements of your site and extracts the necessary input data from the value, or text, fields of these elements. It then takes the user selected options to build the product description that ultimately ends up in the user's paypal order form. Notice how the cart works for the two differently formatted FORMs in the examples that come with this mod. It works with the select (one or multiple), checkbox, radio, or text FORM fields. View the source of your ecart.php to see how the interface works.

Making the right 'call':

Here we start getting a little technical, so you may want to print the ecart.php and js scripts to make it easier to follow along.

1. The "SetAmtxx" and "SetCartxx" 'calls' use the variables (pc,a1,c1,a2,c2...). The first argument [pc] stands for product category (Only five are allowed, with the default value of zero). The "product category" here is for setting special shipping, tax, discount charges for different types of products. Next come [a1..a2..a3..etc.] which are the breakpoints, representing a set quantity or volume) and [c1..c2..c3..etc] which are amount($) or percent(%) changes that are to be applied at the various breakpoints, these are input as pairs of data following the product category (pc, a1, c1, and a2, c2, so on and so forth).

For example:

SetCartSH (0, 1, 2, 3, 4); (SetcartSH is used to set the quantity-based shipping parameters and sets the Product Category 0.)
    1 to 2 items cost $2.00 to ship,
    3 - items cost $4.00

And (in the 'call' definitions area we use the following call values -- see call section below to see how these call values follow the same pattern.),
    pc = product category (class)
    a = amount
    c = charge
    p = percent
    q = quantity
    w = weight

Calls

Rules

All of the item-based calls except the ReadForm call may be executed anywhere within your page. However, they are best executed within a FORM because that structure gives you access to many different event handlers, and provides a natural mechanism for allowing the user to select options that may be available for an item.

The following rules are apply to all calls executed within a < FORM > code block < /FORM > that surrounds a single item for sale...

INSTALLATION NOTES.

The accompanying files are for the installation of the basic cart. Almost all of it may be customized, but it is probably best to start with the default setup, make sure that it works for you, before changing things.

This is a client-side cart that installs on your system (server hosting your site) - it does not reside on some other server, somewhere. The cookiesthat were mentioned earlier reside on your customer's system, not on your system - and you should never abuse their use.

  1. These are the files that make up the entire cart system. All but the two .gif files files need to be installed in your coppermine root directory. The GIF files must be installed in the Coppermine/Images folder. They must be installed in their php or js forms and edited using a properly configured text editor NOT in some crazy Word Processing, FrontPage auto-correct, or Dreamweaver auto-correct format. Strange file formats are the primary reason things do not work!
  2. If you use this cart's shipping values, and not PayPal's, you must make sure that you set your PayPal preferences to allow shipping overrides at Paypal. If you fail to do this, then this cart shall not function properly.

LIMITATIONS. These are the limitations that need to be understood for both cart and data going to the PayPal.


Installing this program: (copy gif files into CPG/images and themes/images folder; remaining files go into the CPG root directory.) Choose one, two, or all three of the following options.


To install into Coppermine:

Open your Coppermine theme's themes.php file. Just under line 23, or so, which reads:
if define('THEME_IS_XHTML10_TRANSITIONAL',1);
Add the following: The above needs to be incorporated into your theme's theme.php file regardless of which method you chose from below. The code above creates a function to clean up any "illegal" or unacceptable characters in various description and input fields and replaces them with a blank space prior to being processed by the mod's javascript. This means that apostrophes in titles and filenames will appear with a space rather than an apostrophe in the paypal cart. It will not affect your coppermine display whatsoever. The three lines at the bottom of the code define variables that we will use to display the proper item and grab details from the database in relationship to the item.

To install this mod as buttons under the intermediate image:

If you are using a custom theme search to see if the following block of code exists:  
// HTML template for intermediate image display
If this section exists in your theme.php file, then, near the end of that block of code, where it reads:
<!-- END caption -->
                         </table>
add the following just after:

Then delete the: <!-- END img_desc --> that follows the code that you just added to this section. DON'T delete the one at the top of the code you just added.

If the above block of code doesn't exist in your theme.php file,
add the following block of code:

Finally, change the Paypal user ID information, the currency information, and weight choice "gm" or "" leave it null for ounces in the cseset.js file.
That's it. Have fun and prosper!



To install into Coppermine as links in the info fields under the intermediate image:
You will need to edit both your language file and displayimage.php for this to work.

In displayimage.php, search for:
if ($owner_link) {
$ipinfo = '/ ';
} else {
$ipinfo = '';
}
}

Just below that, add:
$pos2 = isset($_GET['pos']) ? (int)$_GET['pos'] : 0;
$cat2 = isset($_GET['cat']) ? (int)$_GET['cat'] : 0;
$album2 = isset($_GET['album']) ? $_GET['album'] : '';
Next, search for:
$info[$lang_picinfo['Filename']] = htmlspecialchars($CURRENT_PIC_DATA['filename']);
Below that, add:
$info[$lang_picinfo['Title2']] = ($CURRENT_PIC_DATA['title']);
$info[$lang_picinfo['Description']] = ($CURRENT_PIC_DATA['caption']);
$info[$lang_picinfo['StandardMount']] = "<a href=standard_mounts.php?album=$album2&amp;cat=$cat2&amp;pos=$pos2>" . $lang_picinfo['StandardMount2'] . '';
$info[$lang_picinfo['CustomMount']] = "<a href=custom_mounts.php?album=$album2&amp;cat=$cat2&amp;pos=$pos2>" . $lang_picinfo['CustomMount2'] . '';
Arrange these as you want them listed under your intermediate picture and save displayimage.php.

Next, open your language file and search for:
$lang_picinfo = array(
Paste the following in that section (Translate each descriptive string after => as necessary. Make sure each entry is surrounded by single quotes[']):
'Title2' =>'Picture Title',
'Description' =>'Description',
'StandardMount' =>'Standard Options',
'StandardMount2' =>'Click here to view our standard mount options.',
'CustomMount' =>'Custom Options',
'CustomMount2' =>'Click here to view our custom mount options.',
Save your language file.

That's it. You may want to go to the Admin/CONFIG menu and disable the showing of captions under your thumbnail and intermediate images as these will now display in a field in the info section under your intermediate images. This will encourage your guests to scroll down below the picture to read any caption you have added to the image.



To install into Coppermine as a button in the navbar over the intermediate image display:

This works well if you know how to create your own gif files to use as buttons. You will need to create your own buttons as I am not a button designer. But for our installation purposes we will use the ecart1.gif and ecart2.gif buttons provided. For themes that have their own navbar buttons (fruity, eyeball, igames, hardwired,and rainyday) you will need to copy these two gif files into the theme's images folder.

Open your theme's theme.php


Save your theme.inc.php or theme.php file.

That is it! Your ecart is now installed!

If your theme.php file does not contain the above sections, then you will simply have to add the following:
Add to your theme.php file

Edit to your heart's content and remove any buttons or items that you deem superfluous for your setup.


Review the cseset.js options above and edit/set them to your needs.

Edit custom_mounts.php and/or standard_mounts.php to your specific needs and tastes. You can use both as I do, or just use one if that is all that you need. Just adjust the installation procedures as necessary. Should you decide to rename these files, make sure you change the appropriate references to these files in the installation steps above. Remember that this mod uses one of your image's custom description fields to assign different price options for different pictures. The current default is the first field. Default entries are Standards, Squares, and Panoramics. (See the if/else options block in the standard_mounts.php and custom_mounts.php files).

If you need to use a custom description field other than the first field, you will have to change the "$user1" variable in the: if ($user1=="Panoramics"||$user1=="panoramics") line of standard_mounts.php and custom_mounts.php to $user2, $user3, or $user4, as appropriate. (The same applies to the if ($user1=="Squares"||$user1=="squares") and if ($user1=="Standards"||$user1=="standards") lines of the same code block. Edit the if/else block as is appropriate to your needs, in order to set pricing. If the entry in the assigned description field does not match any of words, pricing will default to the last if/else options in that block of code.


Setting Your Cart Options

csecart.js      : is the javascript that runs this mod and should not be edited.

cseset.js       : jscript that adds the values for the cart form and turns on/off various cart options (coupons, agree to terms, etc) This is where you set your paypal ID and currency types. You should go through this file line by line. There are notes embedded in this file to help you make sense of the many options available.

csecart.php  : is the client-side shopping cart form that lists all purchases. Csecart.php is a very complex form and should not be edited needlessly. Much of this form's functions and display options can be controlled by on/off switches in the csecart.js file.
In csecart.php edit the following only:

    (Edit line 372 as necessary or remove):


    (Edit lines 397 to 418 as necessary -- do not remove this option, you can turn off its display in csecart.js):




In custom_mount.php and standard_mount.php search for: "$pricing_setup = $user1;".
Change $user1 to $user2, $user3, or $user4 if you are already using the first custom image description field for something else. If you leave the assigned custom image description field blank for any image, the pricing will default to the last option in the subsequent if/else block described below.

Above this you will see the list of variables that have been defined that can be used to custom tailor your descriptive text for purchase options with regards to the image being displayed. For example, " $pic_title is available as a $user1 print. " could translate to something like "Ala Moana Sunset is available as a standard print. " (

Just below these is the following " IF/Else Set Pricing Block "
if ($pricing_setup=="Panoramics"||$pricing_setup=="panoramics") //custom field entry is "Panoramics"
{
$Option1 = " Matted size: 10\" x 20\" (image size: 6\" x 16\") @35.00 ";
$Desc1 = " &nbsp; 10\" x 20\" @ $35.00 USD&nbsp;( image size: 6\" x 16\") " ;
$Option2 = " Matted size: 14\" x 28\" (image size: 9\" x 23\") @95.00 ";
$Desc2 = " 14\" x 28\" @ $95.00 USD&nbsp;( image size: 9\" x 23\") ";
$Option3 = " Matted size: 16\" x 32\" (image size: 11\" x 27\") @125.00 ";
$Desc3 = " 16\" x 32\" @ $125.00 USD&nbsp;( image size: 11\" x 27\") ";
$Option4 = " Matted size: 18\" x 36\" (image size: 12\" x 30\") @135.00 ";
$Desc4 = " 18\" x 36\" @ $135.00 USD&nbsp;( image size: 12\" x 30\")";
$Option5 = " Matted size: 20\" x 40\" (image size: 13\" x 33\") @150.00 ";
$Desc5 = " 20\" x 40\" @ $150.00 USD&nbsp;( image size: 13\" x 33\")"; $Option6 = "";
$Desc6 = "";
$Option7 = "";
$Desc7 = "";
$Option8 = "";
$Desc8 = "";
$Option9 = "";
$Desc9 = "";
$Option10 = "";
$Desc10 = "";
}
else
// 11-20 for 2nd option or "Squares"
if ($pricing_setup=="Squares"||$pricing_setup=="squares") //custom field entry is "Squares"
{
$Option1 = " Matted size: 8\" x 8\" (image size: 6\" x 6\") @15.00 ";
$Desc1 = " &nbsp; 8\" x 8\" @ $15.00 USD&nbsp;( image size: 6\" x 6\") " ;
$Option2 = " Matted size: 10\" x 10\" (image size: 8\" x 8\") @30.00 ";
$Desc2 = " 10\" x 10\" @ $30.00 USD&nbsp;( image size: 8\" x 8\") ";
$Option3 = " Matted size: 12\" x 12\" (image size: 9\" x 9\") @40.00 ";
$Desc3 = " 12\" x 12\" @ $40.00 USD&nbsp;( image size: 9\" x 9\") ";
$Option4 = " Matted size: 14\" x 14\" (image size: 11\" x 11\") @60.00 ";
$Desc4 = " 14\" x 14\" @ $60.00 USD&nbsp;( image size: 11\" x 11\")";
$Option5 = " Matted size: 16\" x 16\" (image size: 12\" x 12\") @75.00 ";
$Desc5 = " 16\" x 16\" @ $75.00 USD&nbsp;( image size: 12\" x 12\")";
$Option6 = " Matted size: 18\" x 18\" (image size: 13\" x 13\") @90.00 ";
$Desc6 = " 18\" x 18\" @ $90.00 USD&nbsp;( image size: 13\" x 13\")";
$Option7 = "";
$Desc7 = "";
$Option8 = "";
$Desc8 = "";
$Option9 = "";
$Desc9 = "";
$Option10 = "";
$Desc10 = "";
}
else
// 21-30 for third option or "Standards and all else"
if ($pricing_setup=="Standards"||$pricing_setup=="standards"||$pricing_setup=="")
{
$Option1 = " Matted size: 8\" x 10\" (image size: 5\" x 7\") @15.00 ";
$Desc1 = " &nbsp; 8\" x 10\" @ $15.00 USD&nbsp;( image size: 5\" x 7\") " ;
$Option2 = " Matted size: 11\" x 14\" (image size: 6\" x 9\") @30.00 ";
$Desc2 = " 11\" x 14\" @ $30.00 USD&nbsp;( image size: 6\" x 9\") ";
$Option3 = " Matted size: 16\" x 20\" (image size: 11\" x 15\") @50.00 ";
$Desc3 = " 16\" x 20\" @ $50.00 USD&nbsp;( image size: 11\" x 15\") ";
$Option4 = " Matted size: 18\" x 24\" (image size: 13\" x 19\") @75.00 ";
$Desc4 = " 18\" x 24\" @ $75.00 USD&nbsp;( image size: 13\" x 19\")";
$Option5 = " ";
$Desc5 = " ";
$Option6 = " ";
$Desc6 = " ";
$Desc8 = " ";
$Option9 = " ";
$Desc9 = " ";
$Option10 = " ";
$Desc10 = " ";
}
else
// fall back when nothing matches, SAME AS STANDARDS.
{
$Option1 = " Matted size: 8\" x 10\" (image size: 5\" x 7\") @15.00 ";
$Desc1 = " &nbsp; 8\" x 10\" @ $15.00 USD&nbsp;( image size: 5\" x 7\") " ;
$Option2 = " Matted size: 11\" x 14\" (image size: 6\" x 9\") @30.00 ";
$Desc2 = " 11\" x 14\" @ $30.00 USD&nbsp;( image size: 6\" x 9\") ";
$Option3 = " Matted size: 16\" x 20\" (image size: 11\" x 15\") @50.00 ";
$Desc3 = " 16\" x 20\" @ $50.00 USD&nbsp;( image size: 11\" x 15\") ";
$Option4 = " Matted size: 18\" x 24\" (image size: 13\" x 19\") @75.00 ";
$Desc4 = " 18\" x 24\" @ $75.00 USD&nbsp;( image size: 13\" x 19\")";
$Option5 = " ";
$Desc5 = " ";
$Option6 = " ";
$Desc6 = " ";
$Desc8 = " ";
$Option9 = " ";
$Desc9 = " ";
$Option10 = " ";
$Desc10 = " ";
}
Each option field ($Option#) is paired with a corresponding description field ($Desc#). The $Option# field is what the script reads and posts to your paypal cart. The $Desc# field is what your customer sees in the dropdown lists. The \" is an 'escaped' expression for double quotes("), representing inches. You must use the escaped expressions for special characters in the Options fields for the script to work. &nbsp " is used to add extra spaces between words to space things out aesthetically. The @ character followed immediately by numbers is how the script reads prices to send to paypal. You can have as many Options as you want in your dropdown list. Just remember to pair them accordingly.

The IF/ELSE code above reads the custom image display field and if an entry matches, "Panoramics, Squares, or Standards" it will display the appropriate price group to the customer. If it does not find any matching word, it will display the last group of options. Which by default are the same as the "Standards" group. From Admin Mode in your CONFIG options, enter a name for the custom image description field of your choice. If you can't think of anything better, use "Available Editions" (If you only need one set of dropdown list of prices, don't bother with this step and just edit the last ELSE block for your needs).

Search for:
Start Standard Paypal Purchase Form -->
This is the user interface purchase < FORM > code block.
You will need to edit the text in this form for your particular needs.
These include but are not limited to:
Select Finished size and Medium
Select matted size
Select print type
Select print medium
Select Mat Color
Decorative Mat Overlay (Optional, Double Matting)
You will probably want to edit the various "Select Type" dropdown list options as well.
Pay close attention to how % surcharges and + fixed value charges are handled in the value= options. The + or % sign is immediately followed by the value without a space between the sign and number. The left half of each entry is what is read into the cart. The right half is what your user will see.

NOTE: If you added more options in the if/else block above, you will have to add an equal amount of <OPTIONS value = > lines below " <OPTION value='$Option10'> $Desc10 </OPTION> " in the first dropdown list in the form. Edit the rest of the file as you see fit. Enjoy.