Index: openacs-4/packages/ecommerce/www/doc/ecommerce-setup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ecommerce/www/doc/ecommerce-setup.adp,v diff -u -r1.1 -r1.2 --- openacs-4/packages/ecommerce/www/doc/ecommerce-setup.adp 20 Apr 2001 20:51:14 -0000 1.1 +++ openacs-4/packages/ecommerce/www/doc/ecommerce-setup.adp 26 May 2002 04:36:50 -0000 1.2 @@ -1,297 +1,348 @@ - -Setup of the Ecommerce Module + - + + Setup of the Ecommerce Module + @signatory@ -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 -@ec_url@admin/ (must be accessed using HTTPS). +

@title@

+ + + + + + +
@context_bar@
+
-
    -
  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 -administring the ecommerce site parameters, and for those individuals adding products or services to your site. -

    -If you don't know what some of these -questions mean, read on. These should make sense after you've finished -reading this page. -

    -

      +

      This is intended to be a guide for the content administrators of + @package_name@. Content administrators are not assumed to have any + technical expertise (although HTML knowledge is necessary if you + want to edit product templates).

      -
    1. what units of currency and weight (e.g. USD and lbs) will be used -throughout the site +

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

      -
    2. whether you are selling products or services (items that are not -shipped) +
        +
      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!

        -
      2. how many products to display per page when the customer is -browsing (default 10) +

        You will need to answer the following questions for whomever + will be administring @package_name@ site parameters, and for + those individuals adding products or services to your + site.

        -
      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 +

        If you don't know what some of these questions mean, read on. + These should make sense after you've finished reading this + page.

        -
      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 +
          +

        1. What units of currency and weight (e.g. USD and lbs) will be used + throughout the site.

          2. -
        2. 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? +

        3. Whether you are selling hard goods that require + shipping and/or soft goods and services that are not being + shipped.

          4. -
        4. what percentage of the shipping charges should be refunded if a -customer returns their purchases +

        5. How many products to display per page when the customer is + browsing (default 10).

          6. -
        6. whether express shipping is available +

        7. 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.

          8. -
        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. Whether you want product relationships (e.g. "people who bought + product A also bought products B, C, and D") to be calculated and + displayed

          10. -
        10. 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) +

        11. 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):

          + +
            +

          1. Do you want them to know what classes they're + in?

            2. -
          2. 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.) +

          3. Can they request via the web site to be placed into + user classes, and

            4. -
          4. the number of days a user's shopping cart will stay valid before -it goes into the 'expired' state +

          5. 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. +
          +
          12. -
        12. whether to allow preorders for items that are not yet available +

        13. What percentage of the shipping charges should be refunded if a + customer returns their purchases.

          14. -
        14. the email address that will be used for all email sent from the -system to the customers +
        15. +

          Whether express shipping, and pickups at your location are available.

          +
          16. -
        16. 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 +

        17. 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).

          18. -
        18. 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 +

        19. 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).

          20. -
        +

      5. 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.).

        6. -

      6. Set up product categorization (@ec_url@admin/cat/): +

      7. The number of days a user's shopping cart will stay valid before + it goes into the 'expired' state.

        8. -

        +

      8. Whether to allow preorders for items that are not yet + available.

        9. -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. +

      9. The email address that will be used for all email sent from the + system to the customers.

        10. -

        +

      10. 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.

        11. -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. +

      11. 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.

        12. -

        +

      -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. +
    3. -

      +

      Set up product categorization (@package_url@admin/cat/):

      -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. +

      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.

      -
    4. Set up your shipping cost rules (@ec_url@admin/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. +

      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.

      +
      5. -
    5. Set up your sales tax rules (@ec_url@admin/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. +
    6. -

      +

      Set up your shipping cost rules (@package_url@admin/shipping-costs/). + @package_name@ 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.

      +

      Check out the Shipping Service + Contract if the + default @package_name@ shipping cost rules don't allow you to + specify the rules you want. With the Shipping Service Contract + installed you can select an implementation of the contract + that fills your needs and it will supersede the @package_name@ + shipping rules. (Including the express shipping and pickup at + location options.)

      -
    7. Decide if you want to add any custom product fields. First look -at the current fields available (@ec_url@admin/products/add) 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 @ec_url@admin/products/custom-fields. +
      8. -

      +

    8. -
    9. Create new product display templates -(@ec_url@admin/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). +

      Set up your sales tax rules (@package_url@admin/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 + @package_name@. 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.

      -

      +

      10. -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. +
    10. -

      +

      Decide if you want to add any custom product fields. First + look at the current fields available (@package_url@admin/products/add) 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 @package_url@admin/products/custom-fields.

      -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). +
      11. -

      +

    11. -
    12. Set up user classes (@ec_url@admin/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. +

      Create new product display templates (@package_url@admin/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 @package_name@ 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.

      -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!). +

      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).

      -

      +

      13. -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. +
    13. -

      +

      Set up user classes (@package_url@admin/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.

      -
    14. Enter your products into the database. This can be done using the -simple form at @ec_url@admin/products/add. +

      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.

      -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 @ec_url@admin/products/upload-utilities so that they can be uploaded in -bulk. +
      15. -

      +

    15. -
    16. After you've added a product, there are a variety of things you can -do to it, such as: -
        -
      • Add any number of professional reviews. -
      • Add "cross-selling links" so that the customer always sees a link - to another given product when they're viewing this product, or vice versa. -
      • Put the product on sale or create "special offers". -
      +

      Enter your products into the database. This can be done + using the simple form at @package_url@admin/products/add.

      -

      +

      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 @package_url@admin/products/upload-utilities so that they + can be uploaded in bulk.

      -
    17. Add product recommendations (<%= [ec_url] -%>admin/products/recommendations). 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. +
      18. -

      +

    18. +

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

      +
        +
      • Add any number of professional reviews.
        • -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. +
      • Add "cross-selling links" so that the customer always sees + a link to another given product when they're viewing this + product, or vice versa.
        • -

        +

      • Put the product on sale or create "special offers".
        • +
      +
      19. -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. +
    19. -

      +

      Add product recommendations (@package_url@dmin/products/recommendations). + 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.

      -
    20. Modify the email templates (@ec_url@admin/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. +

      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.

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

      +

    21. -
    22. The layout for all the pages in your site is created using ADP templates -which are stored in the directory packages/ecommerce/www/templates/ -(with the exception of product 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. +

      Modify the email templates (@package_url@admin/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.

    -

    +

    2. -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. +
  2. The layout for all the pages in your site is created using ADP templates + which are stored in the directory packages/ecommerce/www/templates/ + (with the exception of product 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.
    3. +
+

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 + @package_name@.