Products | Scripts | Services | Tutorials | Books | Links | Contact | Bulletin Board

The CITY Shop

Overview | Concept | Licensing | Demo/Download | Installation | Gallery | Last Updates | FAQ

Templates | Views | Engines | Libraries | Main Setup | Shop Setup | Database | Session | Shipping

Shop Setup

Most of the "ways" of your shop are defined in the ShopSetup.pm. All the basic settings, runtime options, database settings, and data queries are controlled here.

Performance questions

We agree that the file is big, and it's not getting any smaller as the shop evolves, but we chose to sacrifice speed for the advantage of simplicity. If you run ModPerl, that should not be an issue anymore, since the file is compiled only once, with the first click. On average machines, the standard click takes anywhere between 1 and 2 seconds, whereas on a ModPerl implementation, you can achieve about 5 clicks a second. The size of your database and the nature of the click might add some slack, but that is not anymore the issue of the setup file.

Basic working model

Once the module is loaded, the main script can and will invoke the object constructor, with the line:

my $S = new ShopSetup($T);

This will assign to the variable $S an hash containing all the system setup values. The library has some global variables, that get referenced in this hash.

Global variables

When you run ModPerl, it is good to keep as many variables as possible as global, if their value does not change in time. These are script messages, CSS styles, and other initialising values for shop modules. You can even make global the database definitions, if you feel like it. The reason I keep them lexical is that it makes debugging easier, you don't need to restart Apache everytime you change a thing in the setup file.

One funny thing that can happen to you, is when you change the data in a global variable, and suddenly nothing works anymore. This is a quite nasty bug to fix, since it does not happen at the first click, but rather when the offended code is being accessed next time. Check and test your customized code thoroughly.

$VERSION

This variable is here only for the fancy, since the shop does not check versions right now.

$CompanyAddress

This is the address that appears on the printable orders. You can redefine the system key -SHOP_ADDRESS if you need to display a different address depending on some logic that you might implement in your shop. An example to that, is when you have corporate customers and normal customers, which, after logging in, get to see a different view of the shop and the ordering process.

$BaseHTMLStyle

This is the style applied throughout the shop, that is, if you use the standard templates. You can include static embedded styles, if you want. Linked files will not work, since this is a script, not a html document, coming from the web root. Some browsers do not like it, when you try to give a path to a CSS file. It is also possible to extend the shop.cgi to use a different CSS value, depending on what action was taken. We chose to keep it simple. The variable is saved in the system key named -LAYOUT_BASE_HTML_STYLE, and is used in the main script only.

$ShopAdvertising

This variable holds an anonymous hash of links to partner sites, or plain advertising links. We only put there the "default", which will be displayed on the main page, but you can add your own as you wish. The correspondent system key, -SHOP_ADVERTISING, is currently being used only in the MainVIEW.pm , but you can define values and use them throughout the shop as you wish. We recommend keeping it at the VIEW level.

$CheckFormVars

Some form fields values need to be within a certain range, or of a certain type. This anonymous hash, saved in the -CHECK_FORM_VARS system key, holds the field names and the field types for the input data that needs to be checked. These are the generic fields of the shop navigation, but you can experiment with type-checking other form values as well. The CheckInputData() routine in the main script takes care of validating the input using these defining values.

%SearchExcludedKeywords

When performing a search in the database, you want to exclude some words that will be too obvious and do not improve search result quality. For example, words like: "and", "not", "a", and others will be ignored from the list of the keywords entered in the form search field. Every language has its own list of such words, therefore we implemented it as a hash, with a list of words for every language.

The system key -SEARCH_EXCLUDED_KEYWORDS holds only the list corresponding to the current language. This list is currently used in the ShopSearchLib.pm.

$MerchantData

This anonymous hash holds the basic settings for the payment gateway. Saved in the -MERCHANT_DATA system key, this hash is used in the ShopOrderLib.pm. It is needed if you use online credit card or check processing.

$Currencies

This anonymous hash holds the information for defining the currencies used in the shop. The keys explained:

-BASE_CURRENCY is the currency code for the currency considered to be the base for calculating all the prices. Once you set this up, you should not change it, unless you change all the prices in the product data table.

-DEFAULT_CURRENCY is what the shop displays by default, if the form parameter "curr" is not set. This means, you can change what currency you display, as you do with the language. Due to the sensitivity of the parameter, we do not comment much here about this feature.

-SECONDARY_CURRENCY If the shop is to display a secondary currency, this is what you set here.

-CURRENCY_FIELDS this is an array of field names corresponding with the next parameter

-DATA contains a hash of currencies and their description. It is important that you define ALWAYS the -EXCHANGE_RATE of 1 for the base currency, otherwise the shop with end up miscalculating orders.

Since this key needs a bit more explaining, here is a description of the fields:

  • -CURRENCY_SYMBOL is the same as the key name
  • -CURRENCY_SYMBOL_NUMERIC is its numeric ISO equivalent. Please use the following link to get more information about the correct codes: http://www.unece.org/cefact/rec/cocucod.htm
  • -TEXT_SYMBOL is the symbol used by the text display mode, used in the emails sent to the user and the shop manager
  • -HTML_SYMBOL is the HTML equivalent symbol for this currency
  • -NUMBER_FORMAT is a sprintf string that is used to format the currency.
  • -EXCHANGE_RATE is the multiplier used to convert the currency in report with the -BASE_CURRENCY
  • -SYMBOL_POSITION is a binary flag; when set, the currency symbol is placed in front of the number, otherwise it is placed behind the number
  • -SYMBOL_USE_SPACE is also a flag, that enables inserting a space between the currency symbol and the number
  • -SYMBOL_COMMIFY contains the character used for the 1000 separator. If you use here a dot, the shop will use a comma for the decimal separator. The Comma is the alternative default, but it needs to be specified.

 

 

 

The object construction

As said before, it all lies in a hash. It is simple and convenient. You can add keys to it as need arises, modify database and query data as you feel fit, and look good doing it. It might be not so easy on the memory usage, but it certainly makes development easy. Even on NT, consider that your site will have a constant load of 3 hits a second, every click takes 3 seconds or more, you will not use more than, say, 60 MB RAM, considering the absurd thought that you want to do that not using ModPerl, that is. This is being calculated considering that a process eats 5MB just because it's Microsoft; add to it your 1 MB of database read data, and variable space. Unless you are running a web server on a hardware built in the middle-ages, memory is not what hurts you, processor power is.

 

Setting up the shop language

Setting up the shop working language is important before defining any database queries, paths to libraries, or anything else that is language-dependent. The variable $LanguageField contains the corespondent value defined in the %LangMap. The form field for the language preference is "L".

As of the beta 2, the ShopSetup uses a mapper hash from the shop display language to the appropriate database field name extension that is used for the language:

my %LangMap = (
  'eng' => 'ENG',
  'ger' => 'GER',
  'fre' => 'ENG',
  'hun' => 'ENG',
  'ita' => 'ENG',
  'dut' => 'ENG',
);

That makes a building a flexible multi-language database very simple. Keep in mind that every database module in the manager has to have appropriate fields defined. For more information, look in each module's header. If you don't know Perl, maybe that is a thing that you should not mess with :)

 

Setting up the shop currency

Setting up the shop working currency is an optional step, that you can perform, to improve the integration level of shops selling in countries with dual/multiple currency. The shop will handle all using the base currency, but the customer will see the alternate currency. If all you want is to display the alternate currency, enable the key "-SHOP_CURRENCY_SECONDARY", and make sure you have the proper entry in the global hash $Currency. This hash also contains the exchange rates, calculated from the base ("-BASE_CURRENCY").

Describing the data tables

The database tables can come from different sources. For the time being, the shop uses a flat-file database, which is very convenient for small shops with up to 3000 items. Above that, if you want performance, you can implement SQL.

Every data file (table) has a hash assigned to it, that uses the following keys:

  • -TYPE - this has only one valid value now, "File"
  • -FILE_PATH - for the type "File", this is the path to the actual file
  • -FIELD_NAME - this contains a reference to the array of fields in the data record
  • -FIELD_KEY - points to the field that is the key of the table
  • -FIELD_TYPE - is a simple hash of correspondence between the fields and their type. An autoincrement key field needs to appear in here, with the value "auto". Multiple value fields, defined by the value "multiple", are usually separated by "::".

More about the definition of a data file can be found in the documentation of the DBLib.pm module.

All the data tables are referenced in the system key -DB.

 

$DataSource

To make some parts of the code easier to understand and have more control over some processes in the shop, we define "Data Sources" in the setup file. They are referred to by the system key -DATA_SOURCE.

A data source is nothing else but a pre-defined database query, for the most obvious queries made in the shop. You can get more information about the required keys in a query, in the documentation of the DBLib.pm module.

 

$DataQuery

Yeah, I know, the name is not appropriate. We put together all the information needed to create a select form field, or a menu, from the data source to the form field definition. This data will be processed in the FormLib.pm, through the method CreateFormField(). More about the structure of the hash you will find in the documentation of the FormLib.pm package. You can access the queries under the system key -DATA_QUERY.

 

$DatabaseMapToForm - Mapping table field names to form field names

It is a good practice to never directly refer your database table field names in the form fields. Whatever you get to change then in your code, or in your database definition, this hash of field names will help match to the right one. You can access the mappers through the system key -DB_MAP_TO_FORM, which is a reference to a hash of hashes, one for each data table.

$DatabaseMapToSession - Mapping table field names to session field names

As the one before, this hash maps field names to their session file counterparts. This is useful for the case when you want to save a datarecord to the session file.

For the both paragraphs above, we simplified the definition method of the assignments, defining a meta-mapper as follows:

-MAP_DB_KEY is a flag that enables the mapping of the table key field to a form field.

-MAP_CUSTOM describes the explicit field mappings, if the database field name is not the same with the form field name. All fields that are not defined here, will be mapped 1:1 with the database

-MAP_EXCLUDE is an array that lists the database fields that should not be mapped in any case.

 

The main system hash

After defining all the stuff listed above, we will map it to keys in the system hash. All the routines that are called in the shop pass a reference to this hash, under the variable $S. Some of this data is dynamically assigned, some of it is only read where needed.

We will list the more important keys of this hash (that are not too obvious by their name), what data they store, and where they are used. If you want more information about other keys you see, please ask us.

-FORM_TAG
-FORM_TAG_SECURE
-FORM_TAG_ONECLICK
-FORM_TAG_ONECLICK_SECURE
-MGR_FORM_TAG
-MGR_FORM_TAG_MULTIPART

these are the generic form tags used in the shop. They are defined in the WhatShop() routine in the main script, and are in the format: "<FORM METHOD="post" ACTION="shop.cgi">". If you want some fancier ones, with name, target, and other tag extras, you can build your own custom tags and use them where needed. The -FORM_TAG_ONE_CLICK adds a javascript that prevents the user from double-clicking the submit button.

-HTTP_BASE_LINK
-HTTP_SECURE_BASE_LINK
-HTTP_MANAGER_BASE_LINK

These are the base links to the shop and manager scripts, with the basic information needed to pass along shop, language, session, and eventually cart information. The format of the link is: "shop.cgi?&shop=city&L=eng&session=141207192&cart=234234".

The key is set in the same routine as the form tags, and completed with all the basic info in the routine WriteHeader(), also in the main script.

-SHOP_BASE_URL
-SHOP_SCRIPT_URL
-SHOP_MANAGER_URL

these keys store basic information about common locations to all the shops. The first one is not used anywhere yet, but can be prepended to any URL formed from the script, or even be used in re-calculating the image links on the page. The next two hold the script names for the shop and for the manager, like "/cgi-bin/store/store.cgi", with no parameters, and can be used to build links.

-COMMON_SCRIPT_METHOD

The default method for the shop is POST.

-SHOP_ENCRYPTION_SETUP

Here you define the encryption methods, by name. You can then in the shop use these together with the CryptLib.pm to encrypt/decrypt different data. We will give here as an example, how you could use it in your code:

  $Data = $Encrypted =  'Data to encrypt';  
  my $EncryptMethod = 'pgp';
my $EncryptSetup = $S->{-SHOP_ENCRYPTION_SETUP} || '';
if ($EncryptSetup && $EncryptSetup->{$EncryptMethod}) {
eval "use CryptLib;";
if (! $@) {
$Encrypted = CryptLib::encrypt($EncryptMethod,
$Data, $EncryptSetup->{$EncryptMethod}); }
}

-MAIL_ORDER_FROM_ADDRESS
-MAIL_ORDER_REPLY_TO_ADDRESS

These are the emails used for processing the order emailing to user. If missing, the next key will be used.

-MAIL_SITE_ADMIN

This is the email that is being used to send the order information to the shop admin. It is also used everywhere an admin email address is needed.

-MAIL_PROGRAM_PATH
-MAIL_PROGRAM_TYPE
-MAIL_SMTP_HOST

These keys are replicating the mail settings from the This.pm. If you want to customize the mail parameters for every shop (unlikely), you can enter here the right values (see the This.pm file for more details.

-MAIL_LOG_PATH
-MAIL_LOG_FILE

Thes keys holds the error log path and file name.

-SHOP_PATH

This key holds the path for the shop libraries. It is built based on the shop definition in the This.pm.

-SHOP_IMAGE_PATH
-SHOP_IMAGE_URL

These two keys hold the path (used for image upload in the manager) and the URL to the images.

-SHOP_DATA_PATH

The value of this key is the directory (preferrably absolute path) to where the downloadable content should be copied, when you upload a data file. That directory will have to be aliased or reside below the web root, if you intend to offer download links after the sale. We will rather recommend to use a push mechanism instead, since that way you can customize the process on a per/user basis.

-SHOP_UPLOAD_PATH
-SHOP_UPLOAD_PATH_DATA

Every shop has an upload directory, where all the uploaded files land, before being redistributed by the script where they are supposed to go. In the case of images, the manager will move the uploaded images in the appropriate folder, and rename them to match the product ID. The "SHOP_UPLOAD_PATH_DATA" is for the downloadable content.

-SHOP_NO_IMAGE_NAME
-SHOP_HIDE_MISSING_IMAGES

For all the products that have no image, this is the default image displayed by the shop. it is meant more as a placeholder. We will extend in a future release the categories, to support a custom image, but for right now, there is only one placeholder. The second keys triggers displaying of a standard image as a placeholder for missing images. Since we want to extend the concept of customizing the "missing image" by categories and/or manufacturer, this is a temporary fix.

-SHOP_TEMPLATE_PATH
-SHOP_VIEW_PATH
-SHOP_SESSION_PATH
-SHOP_DATABASE_PATH
-SHOP_CART_PATH
-SHOP_PRODUCT_HTML_PATH

These are the paths to the main shop directories. Unless you want to share some among shops, you should use the defaults. You can alias the "-SHOP_PRODUCT_HTML_PATH" somewhere under the web root, if you want to offer static content. In that case, the files should have a refresh tag that will load the store with that page.

-SHOP_ADMIN_TEMPLATE_PATH

This is the path for the templates used for admin purposes. For example, the user might have selected a different language, but you want the admin mail to come out in english instead.

-SHOP_RESTRICT_ACCESS

If this flag is set on 1, the shop will check the table ipdata.db for IP address matches. If the client address is found in one of the ranges defined in the ipdata.db, the client is seeing the template AccessDenied.html. The table ipdata.db has the format:

start_IP_address|end_IP_address

and any IP within this range will be denied access.

-SHOP_WEB_ROOT_PATH

This path is used by the template processing. If the file is under this path, the image links are re-calculated if they are relative. For example, if you have an image defined as follows:

<img src="products/myimage.jpg">

it will be interpreted by the browser as:

<img src="/cgi-bin/store/products/myimage.jpg">

which of course is an invalid path. The script will calculate the path resulting from the page absolute path, and reformat the tag to display the correct image path.

-SHOP_HTML_PATH
-SHOP_USES_STATIC_PAGES

The first key is a hash of paths used for the static class pages. With that, we mean product pages, category pages, etc... If enabled for a certain class, every time when the shop receives a link with the key as parameter, this path will be check for the existence of a static file. This can be in the same format as a template, but can also be a static page, with a minimal set of custom tags.

This is where the second key comes in the action. If this flag is enabled, and the shop receives the parameter spage , this parameter value is used to retrieve the correspondent static page from the shop web root

-SHOP_VIEW_PATH

This is the path where the shop finds the views.

-SHOP_VIEW_LANGUAGE_PATH

This is the path for the language-specific folders. These folders are the 3 digit lowercase ISO names for the languages.

-SHOP_SESSION_PATH

This is the path for the user sessions. It has to be writable by the script.

-SHOP_DATABASE_PATH

This is the path for the flat-file database. It has to be writable by the script.

-SHOP_CART_PATH

This is the path for the user carts. It has to be writable by the script.

-SHOP_ERROR_LOG_PATH

This is the full path to the shop error log. The MainLib.pm has been extended to support logging of events, with the typical call:

 LogSystemError($S->{-SHOP_ERROR_LOG_PATH}, 
   'ShopOrderLib', '_AddOrderToDatabase', $ErrP);

As expected, the parameters will be saved in a pipe-delimited file.

-SHOP_SAVE_ORDER_AS_FILE
-SHOP_SAVE_ADMIN_ORDER_AS_FILE
-SHOP_ORDER_LOG_PATH
-SHOP_ADMIN_ORDER_LOG_PATH

Set on 1, the first keys enable the saving of every single order in one file. The last keys value are the directories that hold all the orders, as single files. The last one, is where the admin mails are saved, as a backup for when the email daemon fails.

-SHOP_SAVE_ORDER_TO_LOG
-SHOP_SAVE_ADMIN_ORDER_TO_LOG
-SHOP_COMMON_ORDER_FILE_NAME
-SHOP_COMMON_ADMIN_ORDER_FILE_NAME

If you want to save the orders in one common file, set on 1 the first keys. The last keys value will be the file name.

-SHOP_USES_POST_ORDER_PROCESSING

Set on 1, this key enables the post-processing of orders. After the order is placed, and before sending the email to the user and admin, we implemented the chance for you to customize some action that will be performed in relationship with the ordered item. The call is in the ShopOrderLib.pm, and the processing is done in the ShopProcessOrderItems.pm. If you want to use it, you can either add a field to the product table, named "RoutineName", as the code is written to query for that value, or even customize the ShopProcessOrderItems.pm routine, to support some other mechanism, or even a separate table. We did not implement anything with it yet, but with the first practical example, we will update this file with more details.

-SHOP_USES_DISCOUNT_DATABASE

Set on 1, this key enables the discount table to be checked and the discounts applied to products.

-SHOP_USES_UPSELL_DATABASE

Set on 1, this key enables upselling of items in the cart. A lot of people will not need upselling, since they have just a few items in the database, but if you are planning on a huge inventory, you will have a use for that.

-SHOP_USES_STOCK_DATABASE
-SHOP_DISPLAYS_REAL_STOCK
-SHOP_DISPLAYS_NEGATIVE_STOCK
-SHOP_HIDE_ITEMS_OUT_OF_STOCK

Set on 1, the first key enables the checking of stock availability in the ShopCartLib.pm, and update of the stock data in the ShopOrderLib.pm. The other keys are triggering the way stock is being displayed, and if the total of items backordered should be displayed or not. The last key triggers the hiding of the items that are out of stock and cannot be backordered.

-SHOP_USES_CREDIT_CARD_DATABASE
-SHOP_USES_BANK_ACCOUNT_DATABASE

If you disable either of these, the correspondent user information will not be saved on file.

-SHOP_USES_ONLINE_DELIVERY

If you disable this key, the order data that contains online delivery items will not be displayed

-SHOP_DISPLAYS_CATEGORY_DATA

If enabled, the extended category data will be displayed, when the shop receives the parameter "Category". This is basically happening for the category pages only.

-SHOP_HIDE_DISABLED_ITEMS

If some items are disabled in the database, they will not be displayed, should this flag be set.

-SHOP_MAIL_ORDER_TO_USER
-SHOP_MAIL_ORDER_TO_ADMIN

These two keys are flags that determine if the orders are being emailed to the site admin and/or the user.

-SHOP_ENABLE_USER_WHEN_ORDER_OK

Normally, you would not want to enable an user when they did not positively receive the order confirmation. The reason for that is, that the user email could be wrong, and they never got the order confirmation in the first place. If you enable this flag, the user will be enabled on the fly, when the order is placed, otherwise only when they click on the validation link that gets sent to them by email.

-SHOP_SEND_SECURE_LINKS_IN_EMAILS

When enabled, the validation emails sent to the user contain secure links, so the user logs in secure mode by default.

-SHOP_LOG_OUT_USER_AFTER_PLACING_ORDER

It does what it says, it logs out the user after successfully placing an order.

-SHOP_AUTO_REDIRECT_TO_SECURE_CHECKOUT

This is one of the most problematic tags. When enabled, any click on a link or a button that would bring up the order form, comes up in secure mode, if the secure mode is defined. It does not work on all servers, since some servers are configured to rewrite the http headers, thus messing up the redirect process.

-SHOP_AUTHENTICATE_BEFORE_CHECKOUT

We set this on 1 by default. It will not allow an unauthenticated user, to reach the order form. It is better so, but if you want to let them checkout without logging in, disable this flag.

-SHOP_AUTHENTICATE_BEFORE_CART_DISPLAY

This flag set, only the authenticated users can add items to the cart. Of course, they will not be able to checkout either.

-SHOP_AUTHENTICATE_BEFORE_PRICE_DISPLAY

This flag set, the shop will only display prices to authenticated users. The not authenticated users will also be unable to add products to the cart, or checkout.

-SHOP_PRODUCT_ASSOCIATED_TABLES

This is a hash of tables associated with the product table, by the item key. Of course, the table needs to be enabled and valid.

-SHOP_USERGROUP_PROMOTIONS

This hash is a mapper between the user group and the promotion applied by default. You can, for example, give a 10% discount on a certain class of items, to the people belonging to a distinct group.

-SHOP_USES_MULTIPLE_TAX
-SHOP_TAX_CATEGORIES

If the flag is enabled, the tax field in the states/countries tables will be considered a multiple field. The second key will contain an array of tax categories, which describes the structure of the multiple field.

-SHOP_RESET_SESSION_FIELDS_AT_LOGIN

This is an array of session records that will be resetted when the user logs in

-SHOP_RESET_SESSION_FIELDS_AT_LOGOUT

This is an array of session records that will be resetted when the user logs out

-SHOP_RESET_SESSION_FIELDS_AFTER_PLACING_ORDER

This is an array of session records that will be resetted when the user places the order

-SHOP_BUTTONS

This key holds a reference to an anonymous hash, that maps the buttons to standard templates. Some of the actions in the shop set internally these button values, so the right template will be loaded.

-SHOP_TEMPLATES

As the one before, this is a mapper hash, between the template names and the actual files used for it. That way, we do not handle file names as form field values, anywhere in the shop.

-SHOP_VIEWS

Every template has at least one "view" which loads, executes, and displays the result of a shop "view" library. These are packages located in a language-specific directory, please see the views documentation for more info.

-ACCOUNT_RELATED_FIELDS
-SEARCH_RELATED_FIELDS

These are the form field names that are used in an account/search process. The first have a place in the ShopUserData.lib and the AuthVIEW.pm. The second are used in the _FormatSearchLink() routine, in the ShopSearchLib.pm package, and will be built in the link used to browse through the search results, as well as saved in the session file. See the docs for the ShopSearchLib.pm for more info. All these fields are the fields that we validate before querying for their value.

-SEARCH_EXCLUDED_KEYWORDS

As we saw at the beginning of this file, we defined a hash of "non-keywords", which will be accessed through this key.

-NAVIGATION_RELATED_FIELDS

This key holds an array reference of field names. These are the fields used to build the navigation link through search results.

-SHOP_AUTH_FORM_FIELDS

This key holds an array reference of field names. These fields are used in the authentication process. If you customize your AuthLib.pm routine, you need to add to this array all the fields you add in your customization process.

-SHOP_ORDER_FORM_FIELDS
-SHOP_ORDER_FORM_FIELDS_REQUIRED

These key holds array references of field names. These are the fields used in the order process, that do not belong to specific areas. The second key holds the fields required for the order form.

-SHOP_ORDER_FORM_BILLING_FIELDS
-SHOP_ORDER_FORM_BILLING_FIELDS_REQUIRED
-SHOP_ORDER_FORM_SHIPPING_FIELDS
-SHOP_ORDER_FORM_SHIPPING_FIELDS_REQUIRED

These are the fields used for the billing and shipping fields of the user data.

-SHOP_PAYMENT_DATA_FIELDS
-SHOP_PAYMENT_DATA_FIELDS_REQUIRED

These are all possible fields used for the payment screen, and the fields that are required for that step.

-SHOP_PAYMENT_DATA_CC_FIELDS
-SHOP_PAYMENT_DATA_CC_FIELDS_REQUIRED
-SHOP_PAYMENT_DATA_CHECK_FIELDS
-SHOP_PAYMENT_DATA_CHECK_FIELDS_REQUIRED
-SHOP_PAYMENT_DATA_BANKACCT_FIELDS
-SHOP_PAYMENT_DATA_BANKACCT_FIELDS_REQUIRED
-SHOP_PAYMENT_DATA_ACCOUNT_FIELDS_REQUIRED

Depending on the payment method, there are certain fields, some of them required, that are listed under these keys. If you customize the payment process, add the new/changed fields in these arrays.

-SHOP_ORDER_MAIL_ADMIN_TEMPLATE
-SHOP_ORDER_MAIL_USER_TEMPLATE
-SHOP_ORDER_MAIL_REGISTRATION_TEMPLATE

These are the template file names that will be used to format the order and the order information that gets emailed to the shop admin or the user.

-CHECK_FORM_VARS

As described in the header, this key holds the reference to a hash of form field types, that are checked at the beginning of the main script.

-CART_LIFESPAN

This holds the lifetime of the cart, in days.

-CART_REUSE_ID_IF_EXPIRED

If a cart was deleted(expired) and the user claims to have it, setting this value on 1 allows the shop to use that cart id, basically creating a new file with the same name.

-CART_DATA
-CART_IS_EMPTY
-CART_WAS_READ
-CART_WAS_PROCESSED

The first key holds the data in the cart, after the cart was read, the others are just flags to point to the status of the cart/processing.

-CART_ITEM_FIELDS_SAVED_IN_ORDER_DATA

This key holds an array ref of the cart fields that will be saved in the table "orderdata".

-SHOP_DISPLAY_MODE_PRODUCT_LIST
-SHOP_DISPLAY_MODE_SEARCH_RESULTS

These are display modes used for the product list or the search results

-SHOP_DISPLAY_MODES

This is a hash of display modes, and their parameters. As the two listed above, there are many other product list display modes, and here is a list of the parameters:

-UPSELL_ITEMS is the number of items upsold in the footer of that view. If not set, or set on 0, no upsell items will be displayed in that display mode

-MAX_PER_PAGE is the number of items that will be displayed on a page. If more items were found, a page navigator will be displayed

-SORT_BY this is the meta-name of the field to sort the results. Valid values are:

  • pid - ProductID
  • cat - CategoryID
  • product - the product short description field (language specific)
  • man - ManufacturerID
  • mpid - ManufacturerPID
  • author - AuthorID
  • price - ProductPrice

These are defined in the following files:

  • ShopProductBuilder.pm
  • ShopDisplaySearchResults.pm
  • ShopDisplayProductList.pm

If you want to add more, let us know, we will be happy to do that for you, for the sake of keeping the standard shop consistent

 

-SEARCH_HITS_PER_PAGE
-SEARCH_MAX_HITS_DEFAULT

The first one defines how many products per page are displayed in the search result, the second limits the number of hits returned by the database query. These are functioning as defaults, if the specific display mode is not specified in the -SHOP_DISPLAY_MODES hash.

-SEARCH_SORT_BY

This is a symbolic name for what the shop is sorting the search results by default. For the time being, only the value "name" is valid, which means to sort by the product short description. We avoid to put here any field names, since later on, we will display also links to static html pages, where then the "name" will stand for the file title.

-SEARCH_IN_DB_FIELDS

These are the actual database field names, gathered in an array, that will be used to search for the keywords entered by the user.

-SHOP_DELIVERY_METHODS

This array holds all the delivery methods to be displayed in the manager for defining how the product is delivered. It is not really used in the shop, but might be in a later release, this is why we put it here instead of the ManagerSetup.pm.

-SHOP_SHIPPING_FROM_ZIP
-SHOP_SHIPPING_FROM_STATE
-SHOP_SHIPPING_FROM_COUNTRY

These values are used by the shipping routine to properly calculate shipping.

-SHOP_SHIPPING_METHODS
-SHOP_SHIPPING_METHOD_DEFAULT
-SHOP_ALLOWS_FREE_SHIPPING

The first key holds an array ref. of all the shipping methods allowed for the shop. Depending on what you customized in the shipping routine, you can add to this array the symbolic names. One name is here interesting, the "free" entry. If you have the second key set on "1", free shipping will be offered as an option. No, we did not implement anything like "free shipping for more than x items". It will be implemented on request. The -SHOP_SHIPPING_METHOD_DEFAULT holds the shipping method that should "stick" if the user does not define one.

-SHOP_CALCULATE_SHIPPING_BY_QUANTITY

If enabled, the shipping will be calculated by the number of items, instead of the weight. Do not enable, unless you know what you do.

-SHOP_PAYMENT_AUTOFILL_WITH_BILLING_DATA

When set on 1, this key triggers autofilling the credit card data fields with the data from the billing form fields.

-SHOP_PAYMENT_MODE
-SHOP_PAYMENT_MODE_DEFAULT
-SHOP_PAYMENT_CC_ACCEPTED

These keys define the available payment modes, the default mode, and the list of all the credit card types accepted by this shop. Whether you use an online merchant account or not, it is useful to define these fields in advance, so you can take the heat off the EPI modules.

-SHOP_FORMAT_AS_PRICE_FIELD

These are the fields in %$OX that are to be reformatted as a price before display in the order form or in the email sent to the user. Follow up the code in the ShopOrderLib.pm and OrderFormVIEW.pm if you want to understand how that works. Yes, you should look at the code, it will not bite you :)

-SHOP_TAX_TABLE

This key IS OBSOLETE! We have already a table named "cities.db" that implements tax and handling fees!

-SHOP_CURRENCY
-SHOP_CURRENCY_SECONDARY
-SHOP_ALL_CURRENCIES

The first two keys hold the hashes defined in the beginning of this file, pertaining to multiple currencies. The last key refers to the entire currency configuration hash. If you want to disable the secondary currency, just comment out the -SHOP_CURRENCY_SECONDARY.

-SHOP_USE_COOKIES

This key will stay on 0 for a while... we do not like cookies, nobody does. We implemented some support for cookies when you use the CGI.pm module, and honestly we discourage their use, given the piss-poor security that they offer. Do you want to do it like a man, track the user's IP address to make sure it's the right one. Most of the cookie-specific stuff is relocated in the session file. It's safe there.

-SHOP_COOKIES

These are the specific records saved in the cookie, prepared so that the CGI.pm will have no work with it.

-SHOP_ASSOCIATE_LINKS
-SHOP_ASSOCIATE_TEXT
-SHOP_ASSOCIATE_NAME

If you want to offer some associate links, for some products, so that the user will leave your site and take his business elsewhere, we provide the glue for it here. The first key holds the mapper hash for every associate, and the links used for it; the second is the display text for that associate, then the third is used in the manager to display the name of the associate.

-SHOP_ADVERTISING

Advertising is important. You might want to show some links on the main page, some on the order page, whatever suits your fancy. We described in the beginning of this file how this key works.

-SHOP_APPLY_DISCOUNT_TO_OPTIONS

We try to accomodate everybody. if your product options are affected by the discount applied, set this on 1. This is a global value.

-MERCHANT_DATA

This key points to the merchant configuration hash, described in the beginning. If you do not use an online merchant, or you don't use it for a certain period of time, you can disable it by commenting it out.

-LAYOUT_USE_HTML_STYLES
-LAYOUT_BASE_HTML_STYLE

If the first one is set, the shop will assign to the template, if the tag <cityshop:HTMLStyle/> was found, the value of the -LAYOUT_BASE_HTML_STYLE

-PAGE_JAVASCRIPT_HEADER

If this has any valid value, its value will be displayed by the tag <cityshop:JavaScriptHeader/>.

-DB

This points to a hash of table names, that point to the actual table descriptions. They are NOT THE SAME AS THE TABLE NAMES!!!. For example, the order table is described as follows:

 'order' => $DBOrders,

and the table is actually named 'orders.db'. The reason we do that, is that we want to be able to rename the tables as we wish, without affecting the shop code. In the shop we can use the 'order' as the descriptor for the order table, all over the script, and we can redefine the real name in the ShopSetup at any time.

PLEASE, PLEASE, read this again and understand the difference!

-DB_MAP_TO_FORM

This holds the hash of mappers between the table field names and the form field names. Please see the description of $DatabaseMapToForm, earlier in this file.

-DB_MAP_TO_SESSION

This holds the hash of mappers between the table field names and the session field names. Please see the description of $DatabaseMapToSession, earlier in this file.

-DB_LANGUAGES

This holds the array of database language field suffixes displayed in the manager.

-DB_LANGUAGES_REQUIRED

This holds the array of required fields, by the database language field suffixes. It is used in the manager.

-DB_DEFAULT_LANGUAGE

This is also used in the manager and needs a bit of explaining. If some of the language fields are missing, and they are not in the list of required fields, their value will be auto-filled with the value of this suffixed field.

-DATA_SOURCE

This holds the data sources, as described previously in this file.

-DATA_QUERY

This holds the data queries, as described previously in this file.

-HIDE_INVALID_TAGS

if set, no error message regarding invalid shop tags will be displayed.

-SHOW_DEBUG_INFO

This key enables the display of the form variables and the environment settings, at the bottom of each page.

-AUTH_SETUP

This holds the hash describing the authentication module. See more about that in the description of the authentication process.