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.
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)
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.
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").
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 :
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.
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.
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 :
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.
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)
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.
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).
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.
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 :
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%>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 :
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">
<input name="strSearch" size="20">
<input type="submit" name="submitSearch" value="GO">
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 :
3.8. New Products
To display a list of all the latest products added to the store, use the showNewProd() function :
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 :
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:
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.
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.
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 18.104.22.168
Aug. 24, 2006
July 26, 2006
July 20, 2006
July 14, 2006
June 28, 2006
June 16, 2006 - v22.214.171.124
June 2, 2006 - v126.96.36.199
May 31, 2006 - v188.8.131.52
April 19, 2006 - V184.108.40.206
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 v220.127.116.11
December 20, 2005
December 18, 2005
December 16, 2005
December 12, 2005
December 3, 2005 V18.104.22.168
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