CandyPress Store
 
Copyright 2005 Shopping Tree, Inc DBA CandyPress.Com

Caution: The following assumes installation from zip files only. If you install using the CandyPress FTP installer then follow the instruction provided with that tool.

Contents

  1. Introduction
  2. Installation and Setup
  3. Customizing your Store
  4. General Notes
  5. Upgrading from previous versions
  6. Acknowledgements
  7. Change History

1. Introduction (TOP)

CandyPress Store is part of an eCommerce solution based on popular Microsoft technologies. It is designed to run on an IIS web server that is ASP and VBScript enabled. In addition, the software is designed to work with SQL Server or MS Access databases. Unless indicated otherwise the instructions apply to both the store front-end and back-end installations.


2. Installation and Setup (TOP)

2.1. License

Before Unzipping and Installing this product, be sure to read the License Agreement (included with this software) carefully. By using the software, you also accept and agree to the License Agreement. If you don't have a copy of the License Agreement, you can contact us for a copy.

2.2. Unzip the software

Note: The store back-end should be unzipped over a previous installation of the store front-end.

Unzip the software to a folder on your computer's hard drive. The unzipped folders and files will have a structure similar to this :

2.3. Upload files to your web server

Upload, copy or FTP the entire folder to your web server, including ALL the folders and files inside it. Do not change the file and folder structure. You would typically place the folder in your web server's root directory, but it can also be copied to any sub-directory under the web server's root directory. The file store1.mdb in folder cpdata should have read/write permissions.

Store Front-End Install
Once uploaded, start the on web site configuration by opening your browser and in the address bar enter the URL to the upload location followed by /installer/000_welcome.asp and press enter. Follow the on screen instructions.

Store Administration (back-end) Install
Once uploaded, start the on web site configuration by opening your browser an in the address bar enter the URL to the upload location followed by /admin_installer/000_welcome.asp and press enter. This will set the on web site configuration. Follow the on screen instructions.

2.4. MS Access Only

The folder CPData contains the database file store1.mdb. The folder and file must have read and write permissions on the server. If you don't know how to change file permissions on your web server ask your web hosting company for assistance. Once you have done that, you should take some extra steps to ensure that the database is protected :

2.5. SQL Server Only (Administration Only)

You will need to create a blank (empty) database for your store using whatever means you have at your disposal for doing this (you may have to contact your web host). Next, run Admin_Installer/makeSQL.asp to create the tables and load the existing Access database data to the SQL Server. Change the config/config.asp connection string to use the SQL database and change the type of database in use, see below.

2.6. Modify Configuration File

The configuration file is called config.asp and is located in the Config folder. This file holds some of the most important settings required to run the store. Before proceeding to the next step, it's important that you make the necessary changes to this file. Open the file with a good text based editor (e.g. Notepad). Don't use MS Word or something similar because it may insert a lot of 'junk' characters into the file. The settings below are the most important and must be set properly in order to continue :

2.7. Test Your Database

At this point, you should have all the scripts copied to your web server, and the sample Access database should be in a read/write folder (or if you're using SQL Server, you created a blank database). Now we need to ensure that your connection string and database permissions are correct so that you're able to connect to your database, and read and write to it. This is done using some utilities available from the Admin area of your store. IMPORTANT : You'll need to pass all the tests below before you can proceed with the installation as the rest of the installation procedure requires that you are able to read and write from your database.

2.10. Store Configuration

You should now be able to connect to the database and write to it. Most of the store's configuration settings are held in the database and are updated with an online utility. It is therefore important that you can successfully read and write to your database before you continue (see previous paragraph). Click on the Store Configuration link and review each setting carefully. Detailed help is available online for each of the settings. At a minimum, you must change the two settings indicated below before you can start testing your store.

http://www.mydomain.com/candypress/scripts/

http://www.mydomain.com/candypress/scripts/
https://www.mydomain.com/candypress/scripts/

2.11. Text Configuration

Some of the messages and text in your store can be modified to more closely match your specific requirements. For more details, click on the Text Configuration link, where you will find detailed instructions on how to make these modifications. You can leave the default values if you simply want to test the store (just remember to update them before you go live), or if you are happy with the default settings.

2.12. Test your store

At this point (provided that you have successfully completed the steps above) you can start to test your store. You should be able to browse the products in the store, add items to the shopping cart, create an account and complete an order. Depending on the specific gateway that you will be using for payment, you will have to take additional steps to configure your store to work with the gateway of your choice (see further down). You may also want to re-visit the Store Configuration utility to review all the settings to ensure that they are set to whatever values is appropriate for your store.

2.13. Other Permissions

If you want to use the file upload utility provided with this product, you will have to ensure that the anonymous web user account has read and write permissions on the Product Images directory, and the Download Files directory. In the meantime you will be able to upload images and other files using any good FTP software, or your regular web authoring software (e.g. "FrontPage").

2.14. Affiliates

If you want to allow Affiliates to signup themselves, there is a special link that must be placed in _INCtemplate_.asp. See the Links section in this document for more information. There is also an example inside _INCtemplate_.asp but it is enclosed in HTML comments. You can simply remove the comments which will result in the link being displayed.

2.15. Adjusting Session Timout

If during testing, you feel that the session times out too quickly, you can modify the "session.timeout" value in your store's global.asa file. Locate the global.asa file on your web server and insert the line session.Timeout=nn (where nn is the timeout value in minutes, increase or decrease to suit your needs). This line should be placed in the Session_OnStart code block. For example :

sub Session_OnStart
session.Timeout=60
end sub

2.16. Payment Gateways

This software comes with built-in support for various payment methods and gateways.

Offline Payments - These payment methods refer to payments that will be manually finalized after the order has been placed. For example, Mail-In, Fax-In, Call-In, COD, etc. If necessary, You should make sure that the customer is aware of where and how they need to send payment. This information could go into a separate web page on your site and/or the Terms and Conditions and/or the confirmation email. After payment has been finalized, you will then manually update the order status.

Offline Credit Cards - Normally you would only offer this as a payment method if you have a merchant account. If you select this as a payment method for your store, the customer will be asked to enter their Credit Card details during the checkout process, and this information will then be stored along with the rest of the order in your database. Your next step (after receiving the order) would then be to process the credit card payment using the tools provided by the company with whom you have your merchant account, or you can use the built-in Authorize.Net interface if you have an account with them. After successfully processing the credit card payment, you can then go ahead and update the Order's Status and complete the transaction. If you will be using this payment method, be sure to also enter the type of Credit Cards (e.g. Visa, MasterCard, etc.) you can accept into your store's configuration settings. NB : If you are using offline credit cards, you should delete the card number from the order after it has been processed to ensure maximum security.

Authorize.Net AIM - With the AIM payment method, the customer will be instructed to enter their credit card details on a form on your web site. The form values are then posted to Authorize.Net "silently", meaning the customer doesn't see any interaction with Authorize.Net. To setup, you will need to enter your Authorize.Net login ID, Currency Code and Transaction Key into your store's configuration settings (these are obtained from Authorize.Net). See Authorize.Net for more details.

Authorize.Net SIM (Front-End) - If used on the front-end, the customer will be redirected to Authorize.Net during the checkout process where they will fill in a form to complete the payment. Their payment info is stored directly on Authorize.Net's servers. To setup, you will need to enter your Authorize.Net login ID, Currency Code and Transaction Key into your store's configuration settings (these are obtained from Authorize.Net). You will also have to enter the full URL to your store's 60_PayReturn.asp file (e.g. "http://www.mysite.com/store/scripts/50_PayReturn.asp") in your Authorize.Net account as a valid receipt URL. See Authorize.Net for more details.

Authorize.Net SIM (Back-End) - If you accept 'Offline Credit Card' payments, and you have an Authorize.Net account, you can use the integrated back-end credit card authorization tool. With 'Offline Credit Card' payments, the customer enters their credit card info on your site, and it is stored in your database. You must then authorize these transactions manually. The Authorize.Net back-end interface makes this process much simpler by allowing you to simply click on a link in the Administration area which will pre-fill the authorization form, saving you from typing everything in manually. Setup is the same as the front-end (above). See Authorize.Net for more details.

PayPal - Setting up your store to accept PayPal payments is a simple matter of entering your Primary PayPal Email Address (sometimes refered to as the Member ID) into your store's configuration settings. You will also need to select the Currency for your store. No further setup is required from within your PayPal account. Your customer will supply PayPal with all the necessary payment details (such as their credit card info, etc.) during the checkout process, and PayPal will then notify you via email if the payment has been successful (or you can check your PayPal account online). This means that you don't have to store the customer's payment details in your store's database. Note that the customer will be required to create an account with PayPal (if they don't have one already) when they pay for their order. Fortunately, PayPal is by far the most popular 3rd Party payment processor so the chances are very good that your customers will already have a PayPal account. See PayPal.Com for more details.

PayPal IPN - (Requires Microsoft XML Parser to be installed on the server) If you use PayPal IPN (Instant Payment Notification), the order status and product inventory is automatically updated whenever PayPal processes a valid payment for your store. In addition, an email is automatically sent from your store to your customer to notify them of the status change. To use PayPal IPN, you must setup your store as described above for regular PayPal payments. Then, you must take the additional step of "activating" PayPal IPN.

  1. Log on to your PayPal account.
  2. Navigate to "Profile" -> "Instant Payment Notification Preferences".
  3. Switch IPN on.
  4. Enter the URL of the script that will be processing IPN payments for your store. The PayPal IPN script is located at "scripts/60_PayXPayPal.asp". You will have to enter the FULL path to this script into your PayPal IPN URL (e.g."http://www.mysite.com/store/scripts/60_PayXPayPal.asp").

See PayPal.Com for more details.

2CheckOut.Com - 2CheckOut.Com is in many ways similar to PayPal, except that the customer is not required to create an account with them when they pay for their orders. The customer would (like PayPal) supply 2CheckOut.Com with all their payment details, so there is no need to store that information in your store's database. To use 2CheckOut.Com, you would need to enter your 2CheckOut.Com account number into your store's configuration settings. In addition to this, you should also enter a 'return URL' into your 2CheckOut.Com account setup. This is to allow 2CheckOut.Com to redirect your customer back to your web site after the payment has been concluded by 2CheckOut.Com.

  1. Log on to your 2CheckOut.Com account.
  2. Navigate to "Shopping Cart" -> "Cart Details".
  3. Set "Return to a routine on your site after credit card processed:" to "Yes".
  4. Enter the full path to the "/scripts/60_PayReturn.asp" page in the "Return URL" text box (e.g. http://www.myStore/scripts/60_PayReturn.asp).
  5. Put your 2CheckOut.Com account in "demo" mode and enter a few test orders to see that everything works as it should.

See 2CheckOut.Com for more details.

2CheckOut.Com Auto Update - You can automatically update an order's status and inventory on return from 2CheckOut.Com. When the customer pays via 2CheckOut.Com, they will be presented with a confirmation screen, with a button that they must click to return to your web site. When they click this button, several bits of information is passed back to your web site that allows the software to determine if the order was successful, and do the necessary updates automatically. To use this feature, you will have to follow these steps :

  1. 1. Log on to your 2CheckOut.Com account.
  2. Navigate to "Shopping Cart" -> "Cart Details".
  3. Set "Return to a routine on your site after credit card processed:" to "Yes".
  4. Enter the full path to the "/scripts/60_PayX2CheckOut.asp" page in the "Return URL" text box (e.g. http://www.myStore/scripts/60_PayX2CheckOut.asp).
  5. Navigate to "Account Details" -> "Return".
  6. At the bottom of the page, enter your "Secret Word".
  7. Go to your store's Admin section and enter the exact same "Secret Word" there (this word is case sensitive).
  8. Put your 2CheckOut.Com account in "demo" mode and enter a few test orders to see that everything works as it should.

See 2CheckOut.Com for more details.

Custom Payments - If you want to use a payment gateway not provided as standard with the software, you can write your own gateway routine using the "_INCpayOut_.asp" and "INCpayIn_.asp" files located in the "UserMods" directory. Some ASP and HTML knowledge is required. The FAQ section in our support forum has several working examples for some popular gateways.

2.17. Troubleshooting

If you are experiencing difficulty installing and running the software, please visit the FAQ and support section on our web site where a lot of questions are already answered. Some of the most common causes for errors are :


3. Customizing your Store (TOP)

3.1. Overview

If you want to change the look and design of the store, you will need to make some changes to the files in the UserMods folder. Depending on the amount of customization you want to do, it's not that difficult. CSS is used extensively for the purpose of changing colors, fonts, and so forth. The most important files are :

NOTE : To ensure that you will be able to upgrade the software later on, you shouldn't make any changes to the files in the Scripts or Admin folders. If you do, be sure to document these changes so that you can re-apply them after doing an upgrade.

3.2. /UserMods/*.gif

There are several image files that can be modified with a graphic (or image) editor to more closely resemble the color scheme and theme of your web site. Do not change the name of the file, just it's contents. Also, we strongly advise you to stick to the original image dimensions (i.e. width and height).

3.3. /UserMods/*.asp

As mentioned earlier, there are several ASP files within the UserMods folder that can be modified to change the look of your store. You should use a good text editor, or ASP aware software like Visual Interdev to make these changes. The golden rule is to make a small amount of changes, then thoroughly TEST those changes before making more changes. This way it will be a lot easier to pin-point where you went wrong. Even if you are not skilled in ASP or HTML, you can always experiment. Just keep a copy of the original file(s) so you can restore if you need to.

3.4. Links

The most important thing to remember about links is that you must ALWAYS specify the full URL to the target page, not a relative path. The easiest way to do that is to use the urlNonSSL variable as shown below. This will ensure that links operate properly when switching to and from SSL sessions.

Standard links included in _INCtemplate_.asp . These links should always be present in _INCtemplate_.asp to ensure that the customer can browse and use your store properly :

<ahref="<%=urlNonSSL%>default.asp">Home</a><br><ahref="<%=urlNonSSL%>prodList.asp">All Categories</a>
<ahref="<%=urlNonSSL%>contactUs.asp">Contact Us</a><br><ahref="<%=urlNonSSL%>05_Gateway.asp?action=logon">Account</a><br><ahref="<%=urlNonSSL%>cart.asp">Cart</a>
<ahref="<%=urlNonSSL%>05_Gateway.asp?action=checkout">Checkout</a>
<ahref="<%=urlNonSSL%>prodList.asp?special=Y">Specials</a>
<ahref="<%=urlNonSSL%>prodSearch.asp">Advanced Search</a>

Products and Categories example links. These examples show how you can put a hard-coded link to a specific product or category in _INCtemplate_.asp if you wish :

<ahref="<%=urlNonSSL%>prodList.asp?idCategory=5">Sauce Category</a>
<ahref="<%=urlNonSSL%>prodView.asp?idProduct=5">Mayonnaise - 500g</a>

Affiliate signup link. If you want to allow affiliates to sign themselves up, use the following link in _INCtemplate_.asp :

<ahref="<%=urlNonSSL%>05_Gateway.asp?action=logonaff">Affiliates</a>

3.5. Search

To add a search box, use the example code below. The default version of _INCtemplate_.asp already has a search box.

<formaction="<%=urlNonSSL%>prodList.asp" method="post" id="search" name="search">
<b>Search</b><br>
<input name="strSearch" size="20">
<input type="submit" name="submitSearch" value="GO">
</form>

3.6. Cart Quantity and Total

You can display the current cart quantity and total by using the code shown below. The default version of _INCtemplate_.asp already has this built-in.

Quantity : <%=cartQty(idOrder)%>
Total : <%=moneyS(cartTotal(idOrder,0))%>

3.7. Featured Categories

You can easily display the Featured Categories of the store by using the showFeaturedCat() function. The code below serves as reference :

<%=showFeaturedCat()%>

3.8. New Products

To display a list of all the latest products added to the store, use the showNewProd() function :

<%=showNewProd(5)%>

The parameter signifies the number of products you want to display. In the above example the function will display the most recent 5 products added to the database.

3.9. Top Sellers

To display a list of the best selling products in the store, use the showTopSell() function :

<%= showTopSell(5)%>

The parameter signifies the number of products you want to display. In the above example the function will display the top 5 best selling products.

3.10 Custom Pages

To display a list of defined extra pages in the store, use the showExtraPages() function:

<%= showExtraPages()%>

A custom page may also be displayed using the link <%=NonSSLUrl%>openExtra.asp?Extra=x where 'n' is the id of the custom page.

3.11. ASP Variables and Functions

Users who want to enhance the functionality of their pages with ASP and VBScript can also make use of several predefined variables and functions (see the default version of _INCtemplate_.asp for examples on proper usage). Some of the variables and functions at your disposal are :


4. General Notes (TOP)

4.1. Product Images

Product Images can be uploaded with the Upload Utility provided with this software, FTP or any other web authoring package you have. Note that you may create a product on the database without any images. Each product can have two images. A small "thumbnail" version of the product image, and a regular sized version of the product image. The product maintenance functions provide for the entry of both these files. The thumbnail version is displayed in the product list pages, while the regular sized version is displayed when the customer looks at the product detail. You should stick to ".gif" or ".jpg" files for these images because those are the most widely supported image file formats.

4.2. Software Downloads

The downloadable software products that you intend to sell through your store can be uploaded with the Upload Utility or any good FTP software. The product maintenance functions provide for the entry of the filename of the downloadable product as part of the product record. When a customer orders a downloadable product, they will be able to download the product by logging on to their Account and clicking on the order. This system gets rid of the problematic email system employed by so many other Shopping Cart packages. The system automatically checks to see if the order has been paid, before allowing the download.

4.3. Security 

Security of your data is important. Since most stores run on shared web hosting accounts, your web host is responible for the most important task - namely securing the web server itself. The vast majoirty of hackers will gain access to your web site via FTP, or via an unpatched operating system exploit. That is why it is important to make sure that your web host has a good reputation for security, since they are responsible for securing the FTP servers and applying patches. However, there are some things YOU should do to minimize the risk to your web site :


5. Upgrading from previous versions (TOP)

5.1. Install CP 3.x from 2.x - CandyPress 3.x utilizes a different methodology to maintain such things as database structure, menus,  etc. Therefore, it is recommended that you install CP 3.x into a new folder or rename your existing CP installation and create a new folder of the same name as your prior installation. Follow the steps for a new installation Installation and Setup .

5.2 Install CP 3.5 from 3.3/4 - The installation of the source is simply a copy of the storefront files and admin files, minus the database, over the top of your existing installation. However, there have been changes made to the database which will require your attention.

  1. The Menu table now uses text strings to chain the menu system together and the existing Menu table will no longer work. We have provided a utility.
  2. There are new store parameter values added to storeAdmin
  3. The Products table has additional support fields, wholesaleprice, MSRP, MAP, Brand, Freight, EstimatedShip, and Refurbished.

Once the copy of the source files is complete run /admin_installer/upgrade.asp  to update the above areas.

5.3. Upgrade Database 2.5 to 3.X - Move your existing store data and configuration parameters to the CandyPress 3.x database format by using the upgrade.asp page found in the Admin_Installer folder. Upgrade.asp will move all your data to the new CandyPress 3.x database format.

5.4. Upgrade Database 3.3 to 3.4.x.x prior to running the installer you must move your existing database into the CPData folder or change the connection string (CPConfig/config.asp) to point to the 3.3 database. Make sure that you have a backup at all times.

5.5. That's it! You're done. If necessary, re-apply any changes you may have made to the scripts and storefront template.

5.6. Test your store - Make sure that you are still able to write to the database and send emails, etc. Enter a few orders to ensure that everything is working as expected.

5.7. Backup - your prior installation and archive.


6. Acknowledgements (TOP)

1. MD5 Digest Routine was written by http://www.frez.co.uk.


2. RC4 Routine was written by Mike Shaffer and can be found at http://www.4GuysFromRolla.com.


3. Parts of database structure, SQL logic and SQL command tool based on Comersus Cart .


 7. Change History

September 25, 2006 version 3.5.2.14

Aug. 24, 2006

July 26, 2006

July 20, 2006

July 14, 2006

June 28, 2006

June 16, 2006 - v3.5.2.12

June 2, 2006 - v3.5.2.11

May 31, 2006 - v3.5.2.10

April 19, 2006 - V3.5.2.9

April 18, 2006

April 14, 2006

April 5, 2006

March 7, 2006

February 21, 2006

February 20, 2006

February 9, 2006

January 29, 2006

January 24, 2006

January 20, 2006

January 13, 2006

January 11, 2006

January 10, 2006

January 7, 2006

January 4, 2006

January 2, 2006 v3.4.1.13

December 20, 2005

December 18, 2005

December 16, 2005

December 12, 2005

December 3, 2005  V3.4.1.12

November 20, 2005 

November 17, 2005

November 13, 2005

November 10, 2005

November 1, 2005

October 29, 2005

October 28, 2005

October 27 2005 v3.3.1

October 24 2005 v3.3.1

October 17, 2005 v3.3.1

 

October 16, 2005 v 3.3.1