Frequently Asked Questions

The CITY Shop

Frequently Asked Questions

How do I...

...turn off the display of the debug info?
...set my email address, so I can receive the orders?
...change the address displayed on the order?
...access the saved orders, if my email gets lost?
...set up the shop to work with my merchant gateway, or disable it alltogether?
...disable the display of the secondary currency?
...change the currency to display my country's currency?
...modify the number of products displayed per page?
...handle the display of items in stock?
...change the admin user name and password?
...delete the demo data from the shop, and start fresh?
...deal with errors that appear when I add items to the cart?
...set the shop to just email me the orders, and not use the payment gateway for transactions?
...How do I change the second language to the language of my choice, or even add another language?
...configure the shop for CyberCash?
...configure the store to automatically load the right the correct shop, depending on the domain name?
...get the up-to-date values for the currencies in the shop?
...pay with PayPal, Qenta, or other "link me up, Scottie"- payment gateway?
...set up automatic discounts for certain users (i.e. resellers)?
...schedule jobs on Win32 platforms?
...enable the promotions entry field in the checkout?

I have problems...

1. ...using Authorizenet, Verisign, or other payment gateway that uses SSL to connect

Please note that there are a lot of VERY useful FAQ's around to help you set up your system. Here is for example:

http://www.xav.com/perl/faq/ActivePerl-faq.html

A very interesting document on system security on NT can be found at:

http://www.usenix.org/publications/library/proceedings/lisa-nt2000/full_papers/carvey/carvey.pdf

How do I turn off the display of the debug info?

In the ShopSetup.pm, locate the key named: "-SHOW_DEBUG_INFO" and set it to 0.

How do I set my email address, so I can receive the orders?

In the ShopSetup.pm, locate the key named: "-MAIL_SITE_ADMIN" and set it to point to your email address. Please make sure also that you set up the mail server properties correctly.

How do I change the address displayed on the order?

Locate in the ShopSetup the variable named "$CompanyAddress" and set it to show your company address. If you want that address to show on the orders sent by email to the customer, edit one or all of the following files:

Templates/eng/OrderMailAdmin.txt
Templates/eng/OrderMailHTMLUser.txt
Templates/eng/OrderMailUser.txt
Templates/eng/RegistrationMailUser.txt

How do I access the saved orders, if my email gets lost?

If you want to access the orders individually, the shop keeps a local copy of all the emails sent to the admin, and to the user. These are saved in the Logs/adminorders and Logs/orders directories. The save to single files is enabled by default, using the keys:

-SHOP_SAVE_ADMIN_ORDER_AS_FILE => 1,
-SHOP_SAVE_ORDER_AS_FILE       => 1,

How do I set up the shop to work with my merchant gateway, or disable it alltogether?

In the ShopSetup.pm, there are a couple of demo hashes with the name "$MerchantData". Uncomment the one corresponding to your gateway, and set up the correct merchant ID and password where required.

We provide a list of the available merchant gateways, and we have examples of installation on this page.

If you want to disable the merchant gateway, comment out the correspondent key in the ShopSetup.pm:

# -MERCHANT_DATA => $MerchantData,

How do I disable the display of the secondary currency?

In the ShopSetup.pm, locate the key named: "-SHOP_CURRENCY_SECONDARY" and set it on 0.

How do I change the currency to display my country's currency?
(example: Euro)

In the ShopSetup.pm, locate the hash named: "$Currencies". Set the -BASE_CURRENCY and the -DEFAULT_CURRENCY to EUR. Then, configure the hash under -DATA to display the correct exchange rates for the other currencies, using your currency as default:

'EUR' => ['EUR', 'Euro', '&euro;', '%.2f', 1, 0, 1],

All the rates are multiplicators for the base curency.

How do I modify the number of products displayed per page?

In the ShopSetup.pm locate the key named: "-SEARCH_HITS_PER_PAGE". Set it to a numeric value, of how many hits per page should be displayed. Practically, that could be changed to display a different number of hits depending of the category of products displayed, or something similar, but for the sake of keeping the shop simple, we consider that as being a customization option.

How do I handle the display of items in stock?

There are a couple keys in the ShopSetup.pm that are in charge of displaying items in stock:

-SHOP_USES_STOCK_DATABASE     => 1,
-SHOP_DISPLAYS_REAL_STOCK     => 1,
-SHOP_DISPLAYS_NEGATIVE_STOCK => 1,
-SHOP_HIDE_ITEMS_OUT_OF_STOCK => 0,

To disable the stock handling, set the first key on 0.
The next two keys control if the stock should be displayed in the product page and cart, and respectively hide the backordered amounts.

Setting the "-SHOP_HIDE_ITEMS_OUT_OF_STOCK" on 1, only hides the items that cannot be backordered (have the backorder flag checked out in the stock table). Note that enabling this option will slow down the shop a bit, since an extra table query is being made, every time when one or more product are displayed.

How do I change the admin user name and password?

The file named "manageruser.db" contains the user accounts that have access to the shop manager. By editing this file, you can modify the access to the admin interface. Currently the admin user is named "admin" and the password is as well, "admin". If you want to change either the name or the password, you can use a text editor to edit the file and then reupload it to the server. There are plans to implement an interface to this table in the manager itself, but for the time being, you will have to edit it by hand.

The structure of this file, as of the field names and their order in the file, are described in the ShopSetup.pm.

How do I delete the demo data from the shop, and start fresh?

The shop has a lot of data in the tables for testing purposes. If you want to delete all this demo data, here are the steps to do it:

Always keep a copy of the "city" shop demo. Create a copy of that directory, in the "shops", and name it by the name of your shop, so you always have a term of comparison to be able to debug the code.
delete all the files in the "Logs" directory, and the subdirectories.
delete the files "user.db", "usershipping.db", "userbilling.db", "usercreditcard.db", "paymentdata.db", "orders.db", "orderdata.db"
set the following files on 0 length (do not delete the file, just the contents): "options.db", "product.db", "discount.db", "promotions.db", "upsell.db".

How do I deal with errors that appear when I add items to the cart?

The shop uses templates for the display of different pages. Most of the views generate their own form tags, but you can have more than one on one page. When you modify a template, please be careful and do not remove the </FORM> tags that you may see. Basically, if you see something like:

<!--%%FormTag%%-->
<!--%%HiddenFields%%-->
...
<!--%%TextTopBar%%-->
...
</FORM>

If you use some html editor that auto-corrects code, it is likely that the end form tag will be removed, causing you all this trouble. Newer versions of the shop have instead:

<cityshop:FormTag/>
<cityshop:HiddenFields/>
...

<cityshop:EndFormTag/>

Which is unlikely to cause any conflicts with your html editor.

You should be aware that the view named "TextTopBar" does not put its own form tags. This particular view has the "Search" field in it, and therefore you have to surround it with form tags. We chose to do this from a variety of reasons, one of these being that we want people to see all the possibilities available within the shop.

If you feel uncomfortable with this format, you can modify the MenuVIEW.pm, which is associated with the "TextTopBar" in the ShopSetup.pm, to use its own form tags. Better yet, you can create your own "MenuCustomVIEW.pm" with the modifications, and update the ShopSetup.pm to use your module.

How do I set the shop to just email me the orders, and not
use the payment gateway for the credit card transactions?

Locate in the OrderFormVIEW.pm the following entry:

<input type="checkbox" name="SaveOrderOnFile">

And change it to be a hidden field, as follows:

<input type="hidden" name="SaveOrderOnFile" value=1>

This will ignore the payment gateways settings and just send you the email, and save the order on file.

How do I change the second language to the language of my choice, or even add another language?

We will use here as an example, the Italian as a second language. There are a couple changes you have to make:

In the ShopSetup.pm and ManagerSetup.pm:
search and replace all the fields that end with GER and use ITA. Use for the country the ISO 3166-1 three-letter country code found at: http://www.un.org/Depts/unsd/methods/m49.htm.

In the ShopSetup.pm:

my %LangMap = ('eng' => 'ENG',
               'ita' => 'ITA');

Make a copy of the "eng" folder in both the Templates and the Views directories, and name it "ita"

Translate all the hashes that contain messages, in the ShopFormatting.pm and ManagerFormatting.pm from the Views/ita

In the Views/MenuVIEW.pm, modify the layout creation routine to include a link as in the example:

my $LanguageLinkITA = $S->{-HTTP_LINK};
my $LanguageLinkGER = $S->{-HTTP_LINK};
$LanguageLinkITA =~ s/L=eng/L=ita/;
$LanguageLinkGER =~ s/L=eng/L=ger/;

you can then use something like:

<a href="$LanguageLinkITA">Italian</a> | 
<a href="$LanguageLinkGER">German</a>

and place it in the routine, where it should show up.
Alternatively, you could build a javascript jumpbox, with the same link targets.

If you add a language, make sure you have the fields with language content in all the table descriptions that contain such fields, i.e. product.db, options.db, categories.db,...

Also you will need to modify the manager views that display entry fields for the language content.

The current release does include a couple special views for that, see in the ShopSetup that you have:

 'LanguageSelectText' => 'MenuVIEW.pm',
 'LanguageSelectJumpbox'=> 'MenuVIEW.pm',

Then you have to make sure that your template includes the view (here is the excerpt from index.html):

<html>
<cityshop:views:...:MenuCat:SmallCart:MainPage:LanguageSelectJumpbox/>
...
<td width=162 bgcolor="#E0E0E0" valign=top height=392>
<cityshop:view:MenuCat/>
<p><cityshop:view:SmallCart/>
<p><cityshop:view:LanguageSelectJumpbox/>
...

How do I configure the shop for CyberCash?

To enable cybercash, you need to use in the ShopSetup something like:

$MerchantData = {
  -GATEWAY_NAME => 'CyberCash',
  -GATEWAY_CONFIG_FILE => '/usr/home/myuser/conf/merchant_conf',
  -GATEWAY_AVS_ENABLED => 1, # set on 0 to disable AVS
};

and make sure you point to the correct merchant configuration file. Of course, you need to uncomment the existing $MerchantData hash. For other merchant gateways, we have examples of installation on this page.

How do I configure the store to automatically load the right the correct shop, depending on the domain name?

You have to place in the domain mapper hash in the This.pm, a key like:

  -COMMON_DEFAULT_SHOP  => 'city',
  -DOMAIN_MAPS_TO_SHOP  => {
    'mydomain.com'    => 'myshop',
    'otherdomain.com' => 'othershop',
  },

How do I get the up-to-date values for the currencies in the shop?

There are a couple URL's that you can use to obtain this data as a free service:

European Central Bank (updated around 14:30 CET):
http://www.ecb.int/home/eurofxref.htm

Bank of Canada (updated around 12:00 EST):
http://www.bankofcanada.ca/fmd/exchange.htm

International Monetary Fund (updated around 12:00 EST):
http://www.imf.org/external/np/tre/sdr/drates/0701.txt

Federal Reserve Bank of New York:
mid rates, updated around 10:00 EST: http://www.ny.frb.org/pihome/statistics/forex10.shtml
buying rates, updated around 12:00 EST: http://www.ny.frb.org/pihome/statistics/forex12.shtml

The output of these pages can be parsed and used in the shop quite easily.

However, it is not wise to build that as a plugin in the shop, because the site you use might be down, not represent the daily exchange at your bank, and besides, the overhead of polling the site with every click would slow down the shop.

The alternative would be to build an import script, which will poll your values and update the ShopSetup.pm. Such a script would need to be cronned to run once a day, and keep your shop up to date.

A much better solution would be to generate a conversion table, which the shop would use to build its currency table, although that would mean loading yet another file, with every click, and thus the shop performance will be affected.

We chose not to include such a conversion mechanism, and even if we will provide soon some conversion scripts on our site, it will be up to you to implement it.

Please contact us if you need to implement such a solution, we will give you an estimate of the implementation costs.

How do I pay with PayPal, Qenta, or other "link me up, Scottie"- payment gateway?

You need to set a merchant hash in the ShopSetup.pm, as for the other formats, as in the examples:

Qenta

$MerchantData = {
  -GATEWAY_NAME    => 'Qenta',
  -GATEWAY_HOST    => 'https://www.qenta.at/cgi-bin/paysite/qtill.cgi',
  -MERCHANT_ID     => 'xxxxxxxx-M_',
  -EXTERNAL_METHOD => 1,
 };

Please contact us if you need to implement a different gateway, we will give you an estimate of the implementation costs.

PayPal

Here is how I set this up for now (ShopSetup.pm):

Remote Method:

-SHOP_PAYMENT_MODE => [qw(PayPal PayAtDelivery)], 
-SHOP_PAYMENT_REMOTE_METHODS => [qw(PayPal)], 
-SHOP_PAYMENT_MODE_DEFAULT => 'PayPal',

This method processes the order BEFORE the user pays with PayPal. The order will be marked as "B" for "Billed", and the site manager will have to hand-mark the order as processed, once the paypal payment arrives.

Note that the default PayPal method, which is when you do NOT use the -SHOP_PAYMENT_REMOTE_METHODS key, has a major flaw: The customer HAS TO CLICK on the continue link, from the payment screen, in order for the payment to be finalized, and the order to be processed. Also there is another nasty thing that happens when you use the default method: the PayPal payment information in the log does not contain an order number, since there is no order number at that point.
We are working at "decrypting" the documentation for the IPN (Instant Pay Notification) from PayPal, and will attempt to use that this weekend, and eventually to post another service pack with the updated PayPal configuration.
There is a major problem with PayPal and their IPN, which is, they do not return the fields that we need, i.e. shop, L, TransactionID, session, cart, Totals; the only fields you get back from them are the ones prescribed by PayPal, and that really, really sucks....

How do I set up automatic discounts for certain users (i.e. resellers)?

Look in the ShopSetup for the following key:

  -SHOP_USERGROUP_PROMOTIONS => {
    reseller => 'PROMRESELL', 
  },

The key "reseller" is a user group, its value refers to the key of the promotion that is active by default for the user group in question. Make sure you have the key in the ShopSetup:

 -SHOP_USER_GROUPS => [qw(normal associate reseller partner)],

Of course, you have to assign those users you want to be in that group, using the manager interface to the user table.

To activate the promotion, you have to do the following:

Set up the discounts for the specific group. The discounts have to be set on "disabled", in order for the promotion to see them.
define in the shop manager a promotion with the ID:"'PROMRESELL" and assign the desired discounts
assign that user to the group 'reseller' in the manager interface

How do I schedule jobs on Win32 platforms?

The UNIX cron utility doesn't exist on Win32 platforms.

For Windows NT, a scheduling tool called AT is available. Unlike the UNIX cron utility, AT doesn't store its schedule in a flat file, but is configured using command-line arguments. Note the AT command seems to be very picky about syntax. Here is one example:

 at 23:37 /interactive /every:M,T,W,Th,F,S,Su cmd /c "c:\perl\bin\perl.exe c:\test.pl"

This windows tip, and other useful Perl FAQ's can be found at http://www.xav.com/perl/faq/ActivePerl-faq.html

How do I enable the promotions entry field in the checkout?

The Promotions are operational in the standard shop, but you need to edit some code.

Edit the file OrderFormVIEW about line 361 and remove the HTML comment signs . The functionality of promotions is available already in the standard shop, there is no other change needed.

I have problems using Authorizenet, Verisign, or other payment gateway that uses SSL to connect

Your version of SSL layer modules is old, not in sync, or not installed at all.

Some packages use Net::SSLeay to submit the data to the gateway url. This is specified in the package header, along with the URL where it connects. You will need the following software installed:

Net::SSLeay v1.15
OpenSSL v0.9.6c

Please check the Net::SSLeay web page for the correct version required:

http://symlabs.com/Net_SSLeay/

For the people that cannot make use of the Net::SSLeay (NT folks), there is an alternative submission method using LWP::UserAgent and Crypt::SSLeay. If you are using the ActiveState Perl, you can use the package manager to install both of the above.

To install either modules from CPAN, you will have to ask your ISP to do it. This operation requires root or Administrator access, since you are installing software in the common Perl distribution.

The CITY Shop