Setup

of the Ecommerce Module by Eve Andersson of ArsDigita
This is intended to be a guide for the content administrators of the site. Content administrators are not assumed to have any technical expertise (although HTML knowledge is necessary if you want to edit product templates).

These are the basic steps needed to get your ecommerce system up and running. Most functions below can be performed using the ecommerce administration pages in /admin/ecommerce/ (must be accessed using HTTPS).

  1. First make sure that the technical setup has been taken care of. Although most of it can be done quickly, the process of setting up a merchant account to accept credit cards can take weeks, so don't procrastinate!

    You will need to answer the following questions for whomever will be editing the parameters/yourservername.ini file. If you don't know what some of these questions mean, read on. These should make sense after you've finished reading this page.

    1. what units of currency and weight (e.g. USD and lbs) will be used throughout the site
    2. how many products to display per page when the customer is browsing (default 10)
    3. whether to allow users to write public comments of the products and, if so, whether the comments need to be approved (by you) before they appear on the site
    4. whether you want product relationships (e.g. "people who bought product A also bought products B, C, and D") to be calculated and displayed
    5. regarding user classes (i.e., classes that you might place users in like "publisher" or "student" for purposes of giving discounts or different views of the site): (a) do you want them to know what classes they're in? (b) can they request via the web site to be placed into user classes, and (c) if so, do they automatically become a member of any user class they request to be a part of, or do their requests need to be approved by an administrator first?
    6. what percentage of the shipping charges should be refunded if a customer returns their purchases
    7. whether express shipping is available
    8. whether you want to save credit card data (if so, customers can reuse their credit card with one click; if not, the credit card number is deleted after the order has shipped)
    9. how large you want the automatically-generated thumbnail images of the products to be (you can specify either the width or the height, in pixels; the dimension you don't specify will vary based on the original image's size)
    10. what product stock messages you want to be able to choose from when adding/editing products (e.g. "Out of Stock", "Usually Ships Within 24 Hours", "Usually Ships Within 2-3 Days", etc.)
    11. the number of days a user's shopping cart will stay valid before it goes into the 'expired' state
    12. whether to allow preorders for items that are not yet available
    13. the email address that will be used for all email sent from the system to the customers
    14. whether people fulfilling the orders should be alerted if there's a problem reauthorizing a credit card for payment (which happens when orders are shipped) -- you'll want them to be alerted if they're in a position to do anything about the problem (e.g. abort the shipment); otherwise, there's no need to alert them because the problem will still be logged so that someone else can take care of it
    15. whether customers are allowed to purchase gift certificates for others and, if so, the minimum and maximum amounts of money that the gift certificates can be worth as well as the number of months until the gift certificates expire

  2. Set up product categorization (/admin/ecommerce/cat/):

    Product categories, subcategories and subsubcategories are optional, but if you intend to offer many products for sale, it is best to think about how they should be categorized before you enter any products into the database. The categorization is used when displaying the products and when the customer is searching for products.

    Here is an example to help you decide how you want to categorize your products. Say you are a publisher and you are selling a variety of books and periodicals. You may wish to divide your goods into two categories: books and periodicals. The subcategories of books will be: fiction, biography, history, science, and so on. The subcategories of periodicals will be: health & fitness, sports, news, beauty, and so on. If you want to go a level deeper, you can subdivide science, for instance, into physics, chemistry, biology, geology, and so on.

    Another example: say you sell CDs and nothing else. Then your categories can be: classical, rock, jazz, international, etc. You will probably not need to use subcategories.

    What if one of your products spans two categories? That's OK; you are allowed to put a product into as many categories (and subcategories and subsubcategories) as you like. So, if you're selling the Girl From Ipanema CD, you can put it into both the jazz and the international categories so that your customers can find it in both places.

  3. Set up your shipping cost rules (/admin/ecommerce/shipping-costs/). The ecommerce module is flexible regarding how you charge your customers for shipping. The Shipping Costs page in the admin section will lead you through it. Make sure you read the Shipping Cost Examples page if you don't already know how you want to set it up.

  4. Set up your sales tax rules (/admin/ecommerce/sales-tax/). If your company is located only in one or a few states, this will be easy. On the other hand, if you're a Fortune 500 company and you have nexus (i.e. have an office or factory or store) in many states, you might want to buy tax tables from www.salestax.com. A fair bit of programming would be needed to integrate this data with your ecommerce system. Also if you're not based in the USA, you may need to have some programming done to handle the tax for the regions in your country.

  5. Decide if you want to add any custom product fields. First look at the current fields available (/admin/ecommerce/products/add.tcl) to see if they meet your needs. The current fields are probably sufficient for many types of products. However, a bookseller may wish to add a custom field to store the ISBN, or someone who sells clothing from many manufacturers may wish to add a manufacturers field. Custom fields are added at /admin/ecommerce/products/custom-fields.tcl.

  6. Create new product display templates (/admin/ecommerce/templates/) (unless you're happy with the somewhat minimalist default template). The reason for having product display templates is that you might want to present different types of products in different ways (e.g., spring dresses get a yellow background page color; winter coats get a blue background page color).

    You can modify the default template that the ecommerce module comes with to incorporate your custom product fields, to exclude fields you don't use, or just change the way it looks to fit whatever design scheme you want to use. The template is written in AOLserver's ADP language, which is just HTML with Tcl variables (or commands) inside <% and %> tags. It is extremely easy. It you can write HTML, you can write ADP. If you can't, you can hire someone cheaply to do it for you.

    You can create as many additional templates as you like. You can associate templates with product categories so that every product in the "book" category is automatically assigned the "book" template by default, although you can always assign any template you want to any product you want (so if you have an unusual product, you can give it an unusual template).

  7. Set up user classes (/admin/ecommerce/user-classes/). User classes are groupings of the users, such as "student", "retired", "institution", "publisher", etc. They may get special prices, different views of the site, or different product recommendations.

    Depending on your settings in the ini file, users may or may not be able to see which user classes they're a member of (so be careful of what you call them!).

    If a user is a member of more than one class and there are special prices on the same product for both classes, the user will receive whichever price is lowest.

  8. Enter your products into the database. This can be done using the simple form at /admin/ecommerce/products/add.tcl.

    However, if you have many products already stored in another database, you will not want to enter them one by one. Instead, export them into a CSV file (or a series of CSV files), and manipulate them into the formats documented at /admin/ecommerce/products/upload-utilities.tcl so that they can be uploaded in bulk.

  9. After you've added a product, there are a variety of things you can do to it, such as:

  10. Add product recommendations (/admin/ecommerce/products/recommendations.tcl). If you have many products subdivided into a number of categories/subcategories/subsubcategories, it's good to include product recommendations in order to make the site more browsable and interesting.

    Recommendations are displayed when the customer is browsing the site, either on the home page (if a product is recommended at the top level), or when the customer is browsing categories, subcategories, or subsubcategories.

    You can also associate product recommendations with a user class. E.g., you might only want the book "Improving your GRE Scores" to only be recommended to Students.

  11. Modify the email templates (/admin/ecommerce/email-templates/), which are used when the system sends out automatic email to customers. There are seven predefined email templates for email sent out when a customer's order is authorized, when a customer's order ships, when a customer receives a gift certificate, etc.

    The current templates are functional but should probably be edited to reflect your company better.

  12. The layout for all the pages in your site is created using ADP templates which are stored in the directory /web/yourservername/templates/ecommerce/ (with the exception of product.tcl which, as discussed above, uses a different ADP templating system to allow for different templates for different products). If you are unhappy with the look of any of the pages in your site, there's a good chance that it can be changed simply by editing the corresponding ADP template.

That's it for setup! Of course, your customers won't be very happy until you can do things like order fulfillment, so it's time to read about operation of your ecommerce site.


eveander@arsdigita.com