Integrating RMBcart

From RMBwiki

RMBcart is an integrated part of RMBstore, but it is designed to be able to stand alone and used by itself on a website that someone else wrote. If you have a website already and need a new or better shopping cart, Integrating RMBcart into your website might be the choice for you. RMBcart can also take payments through Paypal's service Website Payments Pro.

It doesn't matter if you only sell one or two products that you are never going to change and are hand-coded into your web page or you have 1000 products defined in a database and have custom code to display the product list. If you wrote a PHP website, you can integrate RMBcart into it, and here's how:

Contents 1 Obtain Code 2 Choose Installation Point 3 Modify rmbcartconfig.php 3.1 Shopping cart helpers 3.1.1 getProductInfo_rmbcart() 3.1.2 getShippingInfo_rmbcart() 3.1.3 changeProductInventory_rmbcart() 4 Create integration files in your web tree 4.1 The Shopping Cart Page 4.2 The Checkout Page 4.3 The Paypal Checkout Page 4.4 The Processing Page 4.5 The Paypal Processing Page 4.6 The Receipt Page 5 Tying it all together 5.1 Making "Add to Cart" Links 5.2 Showing the cart anywhere 5.3 Checkout Link 6 AJAXing it up (optional) 6.1 Using the "cartmagic" Javascript code 6.2 Editing your "Add to Cart" links 6.3 Using the compact cart display

Obtain Code

Download the source code for RMBcart.

Choose Installation Point

RMBcart comes packaged in a subdirectory called rmbcart. Leaving the files in the subdirectory and dropping the subdirectory into your existing web tree is the preferred method of installation, and the least invasive to your existing web site. Installation instructions assume that you are going to do this. If you would prefer a different installation method, be aware that you will have to modify these installation directions to suit yourself.

Example:

Existing website:

~/public_html/
              index.php
              contact.php
              store.php

After dropping the source in:

~/public_html/
              index.php
              contact.php
              store.php
              rmbcart/
                      rmbcart.php
                      rmbconfig.php
                      shoppingcarthelpers.php
                      .
                      .
                      .
                      etc.

Modify rmbcartconfig.php

The rmbcart distribution comes with rmbcartconfig.php.tmpl. It is a template for the actual rmbcart config file. Copy this file to the parent directory of rmbcart (probably your web root) and rename it to rmbcartconfig.php

cd /web/root
cp rmbcart/rmbcartconfig.php.tmpl ./rmbcartconfig.php

Then you will need to edit the config file to tailor rmbcart to your needs. Mostly you are just filling in the blanks. There are a lot of variables to define, and they all have a comment above them to help you decide what they should be. Examples of what you need to fill out in this file include:

• Store Name
• Store Mailing Address
• MySQL prefix, user, database, host and password

Shopping cart helpers

These are functions which you have to write to help RMBcart merge into your website.

Yes, you have to write a little code to do this, but don't worry, it's not too hard!

getProductInfo_rmbcart()

Depending on the complexity of your website, it will be an easy to moderately difficult task. RMBcart is being added in to a website it knows nothing about, you need to write this little helper function so that it knows how to handle your products. Think of it as a translator between your website product database and RMBcart.

When your customer tries to add a product to the shopping cart, the shopping cart uses this function to figure out just what the product is. Example:

Customer: Shopping cart, I would like to have 10 item number TX-312 please.

Cart: Um, sure, coming right up!

Cart(to getproductInfo_rmbcart()): Psst! Hey buddy! What the heck is a TX-312?

getproductInfo_rmbcart(): You dummy, it's a funderblat! Price is $32.50, shipping cost is $4.00, we have 45 in stock, and you can find a picture of it at /images/funderblat.jpg!

Cart: Thanks

Cart(to customer): Ah yes, the Funderblat! Excellent choice! You now have 10 in your cart, your current subtotal is $325 and the Funderblat looks like this: /images/funderblat.jpg

Customer: Great! Thanks!

Function Prototype

Here is plain english prototype for this function:

Basically, this function takes one parameter as it's input, and that is the Product ID. It returns a PHP array of values.

"Umm, excuse me, I don't have "Product IDs". I am selling hand-made rocking chairs and ottomans out of my garage!"

"A furniture maker *slash* web guru! I applaud your well-rounded specialties! A true 'Rennasiance Person'"

"Aww shucks. . . hey, I still don't have 'Product IDs'."

"Sure you do! Just make them up! How about "chair" and "ottoman"? That will work no problem!"

"Umm, Okay. . ."

As I was saying, it returns a PHP array of info on this product. The array indeces and values are below:

• price - Price for this product in US dollars
• name - Name of the product
• thumb - url to a thumbnail image of the product
• inventory - How many of this product you have in stock
  • A word about "inventory - The shopping cart uses the inventory for only one thing, and that is to prevent customers from putting more of an item in their cart than you actually have on hand. Unless the customer attempts to put more in the cart than you have on hand, the customer will never see this number. If you are selling something intangible, like a file download, e-book, software licenses, etc.: you can set this value to something rediculously high, like a million. Alternatively, you can block the sale of a product by returning an inventory of 0.

How to write this function

Here is an example of how to write this function if you only have two products:

function getProductInfo_rmbcart($productID) {
  if ($productID == 'chair') {
    return array('price'     => 199.99,
                 'name'      => "Genuine Adirondack Rocking Chair",
                 'thumb'     => "/images/chair_small.jpg",
                 'inventory' => 10);
  }
  else if ($productID == 'ottoman') {
    return array('price'     => 99.99,
                 'name'      => "Genuine Adirondack Ottoman",
                 'thumb'     => "/images/otto_small.jpg",
                 'inventory' => 15);
  }
  else {
    return array('name'      => "Unknown Product";
                 'inventory' => 0);
  }
}

Not too bad, right?

Here's an example on how to write this function if you only sell one product, The Widgit:

function getProductInfo_rmbcart($productID) {
  return array('price'     => 19.99,
               'name'      => "The Widgit",
               'thumb'     => "/images/widgit_thumbnail.jpg",
               'inventory' => 1000);
}

Easy!

Here is an example of how to write this function if all your product data is stored in a SQL database:

function getProductInfo_rmbcart($productID) {
  $query = "SELECT price, productname, thumbnailimage, amountinstock" .
           "  FROM myproducttable" .
           "  WHERE prodid='" . $productID . "'";
  $result = mysql_query($query);
  $row = mysql_fetch_assoc($result);
  return array('price'     => $row['price'],
               'name'      => $row['productname'],
               'thumb'     => $row['thumbnailimage'],
               'inventory' => $row['amountinstock']);
}

So, as you can see, writing this one little function is not all that hard, certainly not as hard as all the work you've put into your website so far.

getShippingInfo_rmbcart()

Description coming soon.

changeProductInventory_rmbcart()

If you care about the your website keeping your inventory for you, you can write this function to allow the cart to update your inventory for you. the cart will call changeProductInventory_rmbcart($productID, $amount) Where $productID is the product ID of the product whose inventory needs to be changed, and $amount is a number to change it by. If $amount is negative, you should decrement the inventory, if the amount is positive, you should increase the inventory.

Example: If an order is completed for 5 widgits, the cart will call changeProductInventory("widgit", -5);

This function is provided for those who are managing their products through a database and want to allow the cart to update the database for them. If you don't want your cart to do this for you, you can simply have this function return TRUE no matter what.

Create integration files in your web tree

The RMBcart code will live inside the rmbcart subfolder, and you will choose urls/files in your main web tree that will provide the RMBcart functionality.

The reason for doing things this way instead of simply placing all the rmbcart files in your main web tree and editing them to your liking is to allow you to upgrade your RMBcart installation easily without losing your work. It also gives you complete control over your URL sceme and allows for a easier integration into pages that you may have already written.

All of these files can be created from scratch, use the examples and modify them to your tastes. You can also merely incorporate the vital components into existing files instead of creating new ones.

You will choose the name and location of these files. You need to teach RMBcart where the files are by setting the proper values inside rmbconfig.php. For example, if you put the vital components for the "The Shopping Cart Page" inside /thisismyshoppingcart.php, you need to set

$rmbCartLocation = "/thisismyshoppingcart.php";

inside rmbconfig.php. There are similar variables to set for the other five integration files.

The Shopping Cart Page

This page is responsible for catching all the commands to add or remove items from the shopping cart. It adds or removes the item from the cart and then displays the current shopping cart contents, inclusing buttons and link to change the amount of items in your cart.

There are three vital components to this page:

• Including rmbcart.php" require_once 'rmbcart/rmbcart.php';
• Invoking the command to modify the cart contents: $currentorder->processCartCommands();
• Displaying the cart: $currentorder->showCart("totals");

Here is an example cart page.

<?php
   require_once 'rmbcart/rmbcart.php'; 
   $currentorder->processCartCommands();
?>
<html>
 <head><title>Your shopping cart</title></head>
 <body>
   <h2>Cart Contents</h2>
   <?php $currentorder->showCart("totals"); ?>
 </body>
</html>

Feel free to call this file anything you wish, cart.php might be a good name, but make sure you set $rmbCartLocation properly in rmbconfig.php

The Checkout Page

This is the checkout. This is where the customer fills out all their info in preparation to make the purchase.

Vital Components:

• Including rmbcart.php: require_once 'rmbcart/rmbcart.php';
• Displaying the order totals: $currentOrder->checkoutDisplay();
• Displaying the link to the paypal checkout: $currentorder->paypalLink();
• Displaying the Checkout Form: $currentorder->checkoutForm();

Example Checkout Page:

<?php
  require_once 'rmbcart/rmbcart.php';
?>
<html>
  <head><title>Checkout</title></head>
  <body>
    <h2> Pay with Paypal </h2>
      <?php $currentorder->paypalLink(); ?>
    <h2> Pay with Card or Check </h2>
      <?php $currentorder->checkoutForm(); ?>
  </body>
</html>

Feel free to call this page whatever you want, checkout.php is a good name. Just be sure to set the value $rmbCheckoutLocation properly in rmbconfig.php

The Paypal Checkout Page

This page is responsible for communicating with the paypal server and allowing your customers to use their paypal account to check out. This is the most complicated one you will have to write, but it isn't that hard.

Vital Components:

• Checking for the presence of $_REQUEST['token'] AND:
  • Including rmbcart/paypalcheckout.php right away if $_REQUEST['token'] is not set
  • Making a pretty web page first before including rmbcart/paypalcheckout.php if $_REQUEST['token'] is set

Two examples:

Example 1 (If you hand-code all your pages, this is easier):

<?php
  if (! isset($_REQUEST['token']) ) {
    include 'rmbcart/paypalcheckout.php';
  }
?>
<html>
  <head><title>Paypal Checkout</title></head>
  <body>
    <h2> Order Info </h2>
    <?php include 'rmbcart/paypalcheckout.php'; ?>
  </body>
</html>

Example 2 (If you use a function or an include to generate the header and opening to your pages, this method is neater):

<?php
  if ( isset($_REQUEST['token']) ) {
    // Webpage-generating function or include statement here
  }

  include 'rmbcart/paypalcheckout.php';

  // Closing function or include here
?>

Again, name this file whatever you wish, and set the proper variable in rmbconfig.php

If you are too smart to blindly follow these examples, and are BURNING to know why this works, here's the basic rundown: When the user first hits the paypal checkout page, there is no token set. rmbcart/paypalcheckout.php will detect the lack of a token and bounce the user over to the paypal site where they login to paypal and select a billing method. After that, they get bounced back to the paypalcheckout page, this time WITH a token. Now that there is a token, we can display a nice webpage instead of bouncing them back to paypal.

The Processing Page

This is the page responsible for processing the order from the checkout. There is only one passible way to create this page:

<?php
  include 'rmbcart/processorder.php';
?>

Call it whatever you want, your users do not see it. Make sure to set the $rmbprocessorLocation properly in rmbconfig.php

It is imperative that you do not insert any code into this page that generates any output. This page is the target for the checkout form, and will process the information and then redirect to the receipt page. If you want to insert code into this page for the purposes of collecting checkout data, go ahead and do it, but do not insert code that will output anything, you will break the redirect.

The Paypal Processing Page

Very similar to the checkout processing page. It's a process/redirect page, so you are not allowed to add any code to this file that generates output!

Example:

<?php
  include 'rmbcart/processpaypalorder.php';
?>

Again, name this file whatever you wish, and set the proper variable in rmbconfig.php

The Receipt Page

This is the page where the customer winds up after having checked out either with the regular or paypal checkouts.

Vital Components:

• Including rmbcart/checkoutreceipt.php: include 'rmbcart/checkoutreceipt.php';

Example:

<html>
 <head><title>Receipt</title></head>
 <body>
   <h2>Thank you for your order</h2>
   <?php include 'rmbcart/checkoutreceipt.php'; ?>
 </body>
</html>

Set the location of this file as $rmbReceiptLocation in rmbconfig.php and you are done

Tying it all together

Now the moment you've been waiting for:

How to tie everything together!

At this point you should have completed these tasks:

• Set all the options inside rmbconfig.php
• Chosen Product Identifiers for each product
• Written the functions you need inside shoppingcarthelpers.php
• Placed your six integration files inside your web tree, and edited them so that they fit the look and feel of your site.
  • Reminder: Remember not to customize the checkout processor or the paypal checkout processor with any code that generates output.

All set? Good.

Making "Add to Cart" Links

Now, getting your customer to use the shopping cart is as simple as writing the "Add to Cart" link for each of your products. The format of the link (in HTML) is below:

<a href="CARTPAGE?action=add&item=PRODUCTID">Add to Cart</a>

Here is an example assuming that your cart page is "/cart.php" and the ProductID we are going to add to the cart is "ottoman"

<a href="/cart.php?action=add&item=ottoman">Add to Cart</a>

Not so hard is it?

Danger: Make sure that you don't put a Product ID in an "Add to Cart" link that doesn't make sense to the getProductInfo_rmbcart() function. As soon as the user clicks the link that ends in &item=ottoman, the cart is going to call getProductInfo_rmbcart("ottoman"). If you didn't define that Product ID in shoppingcarthelpers.php, unpredictability may ensue.

Showing the cart anywhere

When the customer clicks on your "Add to Cart" links, they are taken to the cart page, which will show them their current cart contents.

However, you may want to show the customer a quick view of their cart as they browse your products. This can be easily done through a simple API call to the cart:

$currentorder->showCart('vertcart');

Anywhere you put that PHP code, a compact version of the customer's shopping cart will appear. It displays each item in their cart with name, thumbnail, quantity and links to the cart page and to add or remove items.

You will need to include rmbcart.php to use this API call.

Checkout Link

There will automatically be links to the checkout page on the cart viewing page, but you may want to provide your customers with a direct link to the checkout. A simple link to the checkout page is all that is needed.

AJAXing it up (optional)

RMBcart is AJAX-enabled, and has the ability to do really smooth and fast shopping cart transactions using asynchronous HTTP requests. This step is optional, but if you don't mind a little bit more work to get a huge increase in the quality of your customers' shopping experience, you should take these extra steps.

What's the difference?

Without enabling AJAX, your customer will be taken to the cart page each time they add a product to their shopping cart. They will either need to use their "back" button or click another link in order to continue shopping. This is pretty common in the world of E-Commerce, but RMBcart (and RMBstore) aim to be a step ahead.

With AJAX enabled, RMBcart uses the power of DHTML, Javascript, and Asynchronous HTTP requests to update the Customer's shopping cart in real time, without taking them to a new page. If you are using the Compact Cart Display (recommended), it will update itself one the current page without the customer being taken anywhere.

Using the "cartmagic" Javascript code

In any page where the user might click an "Add to Cart" link, you need to insert a <script> tag into the <head> portion of the html for the page. It should look like this:

<script type="text/javascript" src="/rmbcart/cartmagic.js.php"></script>

Editing your "Add to Cart" links

In order to AJAX-enable your shopping cart, your "Add to Cart" link needs to be modified slightly. you need to add in an onClick attribute to the link.

Standard "Add to Cart" link:

<a href="/cart.php?action=add&item=ottoman">Add to Cart</a>

AJAX-Enabled "Add to Cart" link:

<a href="/cart.php?action=add&item=ottoman" onClick="return cartadditem('ottoman')">Add to Cart</a>

Using the compact cart display

If you aren't using the compact cart display (see: Showing the cart anywhere, above), you should do so on any page that has "Add to Cart"" links, before enabling AJAX.

The AJAX library will search for the compact cart display on the current page and update it to show the current cart when the customer adds an item to their cart.