tero.co.uk

Shopable - Settings

Shopable can be configured by changing the sytlesheet display.css and editing the variables in currency.html and at the top of the file settings.html. This manual describes those variables and the effects they have. It covers display, alternate currency, shop and payment (including formmail info), basket, language, and internal settings.

Display Settings
Shopable now uses a stylesheet to control everything. display.css has entries for the BODY tag (useful for changing the background colour throughout the shop); H3 is used for all page headers; all normal text appears within P or TD tags; TD.headers is for the column headers in the shopping basket; and TD.totals is for the totals in the shopping basket. loading.html contains the loading message.

Alternate Currency
The automatic currency convert is provided by Textor. Rates are usually updated daily, and it appears in the lower right corner of the shopping basket only. You can set the default currencies using the currencyname and currencyalt variables. These are 3 letter symbols like GBP, EUR or USD (the currency converter itself lists all the avaiable symbols). If you wish to remove the Textor currency converter completely, you will have to remove the lines at the bottom of basket.html

You can also have a fixed rate conversion that appears directly in the shopping basket. If you set the currencyrate variable, the converted total will appear below the total in the shopping basket (the label for the converted total is the currencyalt variable).

Shop and Payment Settings
These variables define information about who runs the shop, and the prefered payment method. Currently the only available payment types are mailto and formmail. They both send unencrypted email across the Internet containing the order details, the customer details, and the payment information, but mailto is less reliable (it depends on the user's email program). There is a FormMail.pl script included with Shopable (courtesy of Matt's Script Archive at www.scriptarchive.com), and help implementing it can be found at that website.

In brief, you just need to make FormMail.pl executable, and alter three variables inside FormMail.pl. Firstly, enter the correct mailer program in $mailprog (something like /usr/lib/sendmail for UNIX). Then place your own domain in the @referers variable (without the www). The @recipients variable specifies who can receive the emails. Newer formmail versions (and the one included here) are more restrictive with the @recipients to prevent formmail being used by spammers. To get by this, either use the included file payment_formmail1_nospam.html (instead of payment_formmail1.html) which sends the confirmation to you (and asks you to forward it the customer), or much less desirably (because it opens your FormMail up to exploitation by spammers), set the following to allow all recipients:
@recipients = &fill_recipients("[\\\w-.]+");

For proprietary secure implementations, set the payment type to other, and edit the page payment_other.html. There is also an array for the credit card you accept, a variable to determine if customers can pay be switch, whether or not to perform a preliminary credit card check (this only checks the number of digits and the correctness of the last digit), and the default langauge.

Basket Settings
These control the display of the shopping basket. Some are just column headings and the others are explained below, followed by an example. (Note that they have been changed to b_ to save space in settings.html.)

  • basket_addToTop: whether new items are added to the top of the basket or the bottom
  • basket_header_font: HTML tag that is placed before each column heading in the basket
  • basket_description_link: whether the item's description should link back to the order page from whence it was added
  • basket_numColumns: the number of columns (in addition to "Description", "Quantity", "Price", and "Total") to list in the shopping basket (see below for an example)
  • basket_numOptions: the total number of options to pass into Shopable from the order function (see below for an example)
  • basket_options_before: HTML tag appearing before unnamed options
  • basket_options_join: string which joins multiple unnamed options
  • basket_options_after: HTML tag appearing after unnamed options
  • basket_remove: column heading text for the removing column
  • basket_currency: the currency symbol to use
The basket_numColumns and basket_numOptions settings control how the options (the arguments to the order function after the description) are displayed in the basket. The basket_numColumns variable must match the number of elements in the basket_columns array from the language settings, and the basket_numOptions variable must match the number of options in the order functions on each order page. For example, suppose the order button had the following code:
order('t1', 'Tshirt', 'vneck', 'green', 'plain', 5)

and the columns and options variables were defined thusly:

s.basket_numColumns = 2; s.basket_numOptions = 3;

and the basket_namedOptions array in the language settings was defined like this:

t.basket_namedOptions = new Array ("Type", "Colour")

then the shopping basket would look like:
Description Type Colour Quantity Price Total
Tshirt (plain) vneck green 5.00 5.00

From the basket_numOptions variable, Shopable knows that the order function on each order page will pass in three options, and that the first two of these (from basket_numColumns) will be displayed as columns in the basket. Then Shopable uses the language settings (from basket_columns) to set the column headings as Type and Colour, and places the first two order options (vneck and green in these columns. The third option does not get a column of it's own, and so plain appears in parenthesis after the item description (Tshirt). As another example, if you set s.basket_numColumns = 3 and s.basket_numOptions = 5 then your order buttons should have 5 options, and your language settings should have three column headings, like t.basket_namedOptions = new Array ("Colour", "Size", "Model").

Note: If yours is a new shop, it may be advantageous to define three or four options even if you are only going to use one of them at the beginning, because then you can add new options later without having to change every single order button in your site. Also, the same column headings apply to every order button, so think carefully about the column names if you sell a wide variety of products.

Language Settings
A major addition to Shopable in version 2.4 is multiple languages. There are about 100 different strings which make up all the text displayed on the screen and in the emails. (Only the basket_namedOptions setting is not a string, it is an array, explained above. The basket_free setting is what to display when something costs nothing.) Customers can switch languages using the flags on the shopping basket page. At the bottom of each language section are the buttons. By using the format SRC=imagesrc.gif you can display an image instead of a button. (There are Dutch images included in the Shoapble download which you can use.) If you wish to remove some languages (for file size reasons), remove the code from settings.html. If you wish to use a language but not display it's flag, set the t.flag variable (which stores an image of the flag) to blank.

Internal Settings
The first part of the internal settings deals with how Shopable opens (whether in a frame or a new window - the default is a window). (See the order pages manual for more information.) The remaining settings are about cookies.

  • displayFrame: the frame where the basket is shown, it is mainFrame.shopable_view by default
  • orderFrame: the frame where order pages go, when the user clicks on an item in the basket. When Shopable appears in a new window, this should be mainFrame.opener (the frame that opened Shopable). If Shopable appears within a frame, this will probably be the same as displayFrame.
  • lastOrderPage: this determines the behaviour when a user presses the "Continue Shopping" button. When Shopable appears in a new window, this variable should be blank, so that the button just passes focus back to the order frame. However, in a frame situation, the "Continue Shopping" button will load (into the order frame) the last order page that was visited. If there was no last page (if for example the user hasn't ordered anything), it will load the lastOrderPage page into the order frame.
  • viewBasketAtStart: whether Shopable should show the basket straight away after loading. This would only be false if you use Shopable in a frame set, so that it is loaded when a user first visits your site.
  • saveShoppingBasket: determines whether the shopping basket contents should be saved to a cookie on the shopper's computer (so they are available if the shopper closes Shopable and comes back later).
  • saveCustomerDetails: for remembering the shopper's customer details (name, address, etc).
  • itemJoinChar: the character which the order function uses to combine items into a single string (this character must not appear in the item's properties, and must correspond to the order function).
  • cookieJoinChar: used to join the basket and customer details into a string for placing in a cookie, and also must not appear in any item's properties or the customer's details. (These two characters really ought to be escaped.)

Please note that some servers will also set cookies which could interfere with Shopable's cookie. If this happens, you might get an undefined item being added to your shopping basket whenever you first order something. To correct this, you must add a path to the cookie which is set. Go to the bottom of settings.html and find the setCookie function, and find the line below. Then add the relative path to the end as shown. 

var theCookie = "shopable=" + escape (theCookie) 
	      + "; expires=" + expireDate.toString() + "; path=/shopable/";