How to use Cataloger module + Paypal to make a simple Ecommerce site

[vaughnt]

I've received several inquiries regarding how I integrated Cataloger + Paypal on this site: 
http://www.althaea.biz,
and I have since used the same method on my own website,
http://www.vaughnsphotoart.com.
I'm making this post to explain it. But first, a disclaimer: This is not a one-size-fits all solution, and I know that. It will only work for certain types of e-commerce sites. If yours is one of them, you lucked out.

We're going to be using Paypal's cart. I don't know if that is available to all Paypal account types, you'll have to check.

I recommend that you download and install Cataloger, and play around with it some before reading much further, it will make a lot more sense once you've seen the app.

ABOUT CATALOGER

Cataloger it is a module that adds three new content types to CMSMS, Catalog-Category, Catalog-Item, and Printed-Catalog. For this project, we only need the first two, Catalog-Category and Catalog-Item. You can define custom attributes for categories and for items, which are universal. In other words, all categories share the same set of attributes, and all items share the same set of attributes. But, you can pick and choose which ones you want to display in a given circumstance... more on that later.

Cataloger uses sub-templates to format how a Category or Item should appear. You can have multiple Category templates, and multiple Item templates. This is particularly handy for our purposes, because it means that when you define a new item, you get to pick which sub-template you are going to display it with, allowing for customized presentation of different types of items.

An item has a $title by default, can have any additional attributes you specified Items should have, and can have zero to multiple images. Any custom attributes you created are accessed in the item template as $attributename . So while building an item template, you can pick and choose which attributes you will utilize by simply adding or omitting $attribute strings from the template.  The default item template looks as follows:

Code: Select all

<div class="catalog_item">
<p>{$title}</p>
<div class="item_images"><img name="item_image" id="item_image" src="{$image_1_url}" />
<div class="item_thumbnails">{section name=ind loop=$image_url_array}
<a href="javascript:repl('{$image_url_array[ind]}')"><img src="{$image_thumb_url_array[ind]}" /></a>
{/section}</div></div>
{section name=at loop=$attrlist}
<div class="item_attribute_name">{$attrlist[at].name}:</div>
<div class="item_attribute_val">{eval var=$attrlist[at].key}</div>
{/section}
{literal}
<__script__ type="text/javascript">
function repl(img)
   {
   document.item_image.src=img;
   }
</__script>
{/literal}
</div>

Taking out the image handling code for simplicity's sake, we get:

Code: Select all

<div class="catalog_item">
<p>{$title}</p>
{section name=at loop=$attrlist}
<div class="item_attribute_name">{$attrlist[at].name}:</div>
<div class="item_attribute_val">{eval var=$attrlist[at].key}</div>
{/section}
</div>

And really, we don't even need the $attrlist loop, as we can access our item attributes directly, so I'll simplify it to:

Code: Select all

<div class="catalog_item">
<p>{$title}</p>
{$myattribute1}<br>
{$myattribute2}
</div>

OKAY, that lays the groundwork. Now let's integrate this with Paypal.

Paypal Forms

Do use this, you have to use the non-encrypted paypal forms, so you can play around with the form variables. No biggie, just watch that someone doesn't change prices on you.  Here's a fairly typical Palpal form, straight out of their "buy now button" generator, to sell My Widget with some widget style choices:

Code: Select all

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="yourpaypalemail@yourdomain.com">
<input type="hidden" name="item_name" value="My Widget">
<input type="hidden" name="item_number" value="widget01">
<input type="hidden" name="amount" value="10.00">
<input type="hidden" name="no_shipping" value="2">
<input type="hidden" name="return" value="http://yourdomain.com/purchase_thanks.html">
<input type="hidden" name="no_note" value="1">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="lc" value="US">
<input type="hidden" name="bn" value="PP-BuyNowBF">
<table><tr><td><input type="hidden" name="on0" value="Style">Style</td>
<td><select name="os0"><option value="Plain">Plain<option value="Engraved">Engraved<option value="Full Bling Ahead">Full Bling Ahead</select>
</td></tr></table>
<input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but23.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>

I can't and won't teach you all the stuff about setting up Paypal, but suffice to say you can get in there, set your shipping/tax preferences, change how it behaves with regards to a single buy-now purchase or acting like a shopping cart, etc. Make your settings appropriately for what you intend to do. Significant reading and comprehension may be required.

Integrating Cataloger and Paypal

Ok, so now I want my items to come out of the database, and get displayed with valid Paypal "Add to Cart" buttons.  Remember that disclaimer I made in the first paragraph?

This is not a one-size-fits all solution, and I know that. It will only work for certain types of e-commerce sites.

It is particularly important if your items have options. If your items always have the same option set (always the same colors and sizes, for instance), you're gold.  If you have one item with one option set, and another with a different option set, it's no sweat. If options have to be customized on every item, you need a different solution.  That's because item options have to be embedded in the template. If Samuel decides to add more complex Item and Catalog attributes, so we can do an attribute with mutiple choices, have global content blocks included in an item description (as opposed to just a template), or similar, this limitation will be removed, but I've already bothered him with a bunch of questions that he was kind enough to answer, so I'm not going to ask.  :) 

Anyway, for example, let's say I sell widgets, with the standard widget style choices, and I also distribute Spacely Sprockets, in a standard range of colors. I could display this product line with two templates.  I decide to define items as having a few custom attributes that will be helpful to me... $amount, $item_number, and $sprocket_diameter.  The observant may notice that some of these variables match variables in my Paypal form.  They don't have to match, but it makes it easier to keep track of.  :) 

Now, when selling Widgets, I don't need a $sprocket_diameter, so I just don't fill that in when creating a Widget content item.  I then format my Widget item template to contain a Paypal form that is filled in with my item variables, and leave out the $sprocket_diameter I don't need:

Code: Select all

<div class="catalog_item">
<p>{$title}</p>
(some image display loops and javascript might go here)

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="yourpaypalemail@yourdomain.com">

<!-- *** here is where i substitute my attributes in *** -->
<input type="hidden" name="item_name" value="{$title}">       
<input type="hidden" name="item_number" value="{$item_number}">
<input type="hidden" name="amount" value="{$amount}">

<!-- *** the rest of the form remains unchanged, except I made the style options code more legible  *** -->
<input type="hidden" name="no_shipping" value="2">
<input type="hidden" name="return" value="http://yourdomain.com/purchase_thanks.html">
<input type="hidden" name="no_note" value="1">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="lc" value="US">
<input type="hidden" name="bn" value="PP-BuyNowBF">
<table>
<tr>
  <td><input type="hidden" name="on0" value="Style">Style</td>
  <td><select name="os0">
          <option value="Plain">Plain
          <option value="Engraved">Engraved
          <option value="Full Bling Ahead">Full Bling Ahead
          </select>
  </td>
</tr>
</table>
<input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but23.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>
</div>

I then save this as "Widget Item Template".

My Spacely Sprocket Template would be very similar, but I'm going to append my $sprocket_diameter to my item title to make my life easier. I might alternately pass this as a second option to Paypal, as Paypal will support up to two option sets when submitting an item, but I don't want to complicate the example too much. Here is my "Sprocket Item Template":

Code: Select all

<div class="catalog_item">
<p>{$title}</p>
(some image display loops and javascript might go here)

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="yourpaypalemail@yourdomain.com">

<!-- *** here is where i substitute my attributes in *** -->
<input type="hidden" name="item_name" value="{$title} - {$sprocket_diameter} Dia.">       
<input type="hidden" name="item_number" value="{$item_number}-{$sprocket_diameter}">
<input type="hidden" name="amount" value="{$amount}">

<!-- *** the rest of the form  *** -->
<input type="hidden" name="no_shipping" value="2">
<input type="hidden" name="return" value="http://yourdomain.com/purchase_thanks.html">
<input type="hidden" name="no_note" value="1">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="lc" value="US">
<input type="hidden" name="bn" value="PP-BuyNowBF">

<!-- *** my altered options, for selecting sprocket colors  *** -->
<table>
<tr>
  <td><input type="hidden" name="on0" value="Style">Color</td>
  <td><select name="os0">
          <option value="Supernova White">Supernova White
          <option value="Sun Orange">Sun Orange
          <option value="Dark Side of the Moon Black">Dark Side of the Moon Black
          <option value="Little Green Man">Little Green Man
          <option value="Mauve">Mauve
          </select>
  </td>
</tr>
</table>
<input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but23.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>
</div>

Whenever I create a Widget, use the widget template, and whenever I add a sprocket, I use the sprocket template.

Misc other Tips and Tricks

#1  See this page:  http://www.althaea.biz/index.php?page=e ... ugar-scrub , and check the options dropdown.
I had a huge options list of scent choices I had to maintain, and rather than maintain it in several different templates, I made the scent list a global content object, and included it in my template as so:

Code: Select all

<select name="os0" class="qty">
{global_content name='scentlist'}
</select>

#2  See this page:  http://www.althaea.biz/index.php?page=orange-spice  and note the additional items at the bottom of the page.
Each of these add-on items is just an additional paypal form hard-coded in the "Soaps" item template.  The top four add-on items are scent specific, so I utilized the $title attribute to customize the form for the proper scent. Here's a part of the 1/2oz Eau De Parfum paypal form:

Code: Select all

<input name="item_name" value="{$title} Eau de Parfum" type="hidden">
<input name="item_number" value="{$title}eaudeparfum" type="hidden">

#3  See this page:  http://www.althaea.biz/index.php?page=s ... -pack 
Paypal only supports two option choices per item. If you need more choices, you can use javascript to concatenate all your choices and store them in one field. View source to see how I did that.


Conclusion

I hope this helps some folks. I can attest that a viable Ecommerce site can be built using this technique, as http://althaea.biz is my wife's site and it supplies a good chunk of our income.

Shameless Plug : if you have skin issues, or just like giving yourself a luxurious treat, she makes great stuff.  :)  It's vegan safe, very good for your skin, and smells so much better than the commercial junk you get at the store.

Coming soon, my own website redone using Cataloger to sell photo prints, with integrated Thickbox, Social Bookmarking, random_GCB, and other goodies.  :)

[cyberman]

Great solution - many thanks !

[PatDeLux]

Super solution and great thanks for sharing it !

[dhtml12345]

Thanks a lot!

[mrk]

you rock!

[Pierre M.]

Thank your vaughnt for sharing this solution !-)

And know what you are doing everyone : Google for "Seller Punishment Policy" and "Terms of Servitude" if you want to sign with Paypal.

Pierre M.

[reidjazz]

I'm not sure from reading your solution if this is possible, but:

If you have very individual items, all of the same type, but each one having its own characteristics and you sell it, via PayPal, is there a way for your system to, once the item is sold, indicate on the site that that particular item is no longer available, almost like an inventory management system?

Thanks in advance!!

Todd

[vaughnt]

is there a way for your system to, once the item is sold, indicate on the site that that particular item is no longer available, almost like an inventory management system?

I can't think of any way for it to do this as presently set up, no.

[hippostarz]

This is a great explanation and a good first step.  Does anyone know how to do it seamlessly with no new windows?

[giggler]

Code: Select all

is there a way for your system to, once the item is sold, indicate on the site that that particular item is no longer available, almost like an inventory management system?

If someone can make a mod that uses paypl IPN, it can send data back to the site's database. So it can be done, but no one has done it yet in cmsms...
https://www.paypal.com/ipn

Resources:
http://www.freewebspace.net/forums/show ... ?t=2199767

http://www.19.5degs.com/paypal_ipn.php
http://www.19.5degs.com/element/601.php

[nuno]

http://www.vaughnsphotoart.com.

Well done and the site is excellent congratulations

[vaughnt]

Thanks, that is appreciated.

[replytomk3]

I am evaluating this method now. Several points:

1) In the examples, shipping is not specified on item, shopping cart, and checkout pages. However, Paypal allows you to set up very detailed shipping options (based on amount, for example) that will appear only once per the shopping cart (instead of included in every item)

2) The example is not showing the item description (Item Notes text is ignored). I am working on this now. Solved below.

3) In the template where

Code: Select all

<input type="hidden" name="amount" value="{$amount}">

$amount must be replaced with $price.

4) Top of the template is wrong. It has comments that are not properly commented out (in parentheses). It does not show item description. And it duplicates the item title on the page. Replace the top of the template with this:

Code: Select all

<div class="catalog_item">

<!-- *** (some image display loops and javascript might go here) *** -->

{$itemnotes}

5) And last but not least, the following are more things that I recommend you implement:

• target attribute _self to stay in same tab
  shipping saved in your paypal profile so it is added once for the order
  taxes for your state should be included (check laws), but out of state purchases don't
  description and duplicate title isssue as outlined above
  checkout page style. it would be helpful and less scary if the checkout page had your logo and colors on top
  tell paypal to accept credit card instead of forcing people to get a paypal account.

[vaughnt]

replytomk3 discovered that item notes were not showing up. It appears a variable has changed between the version of cataloger I used, and more recent versions. Also, there is now a standard for price, where before I had to add it as an item attribute. So, for folks finding this how-to, be aware that:

HOW-TO VAR      NEW VAR
{$notes}            {$itemnotes}
{$amount}          {$price}

Thank you to replytomk3 for bringing this to my attention.

[replytomk3]

One question because I am not sure that I am doing it right: How do I display the two images? Right now, I included this

Code: Select all

<img height="200" alt="" src="{$src_image_1_url}" />
<img height="200" alt="" src="{$src_image_2_url}" />

in my item template (below {$itemnotes} in my illustrated source above). Am I doing this right?

I think that I am bypassing the whole resizing deal. So how do I implement it correctly, what code I use, where, etc?