Administration Manual
INDEX
1- Innovations compared to the previous version.
2- Introduction to the Cibertienda.
3- Maintaining and updating the database.
4- Construction of the shop.
5- Delivery expenses.
1.- Innovations compared to the previous version.
The 1.3 version of the CiberTienda is exactly the same as the 1.2 version except that:
The majority of these were of an internal nature, and were therefore clear to the user. But there were some important changes:
2.- Introduction to the CiberTienda.
The CiberTienda system will allow you to build your own shop in INTERNET with a wide range of possibilities thanks to its extensive configuration capacities.
With the CiberTienda system you will be able to create an electronic business that will satisfy all your needs. You will be able to organize your products any way you wish, use the information search capacities included, visualize products and add any additional information that you require. To do all this you will need to know the modification process and the possibilities offered by the use of the templates.
Of course, to get the best from this software you need to have some knowledge of the administration of the Operative System and of HTML language.
However, someone with no knowledge of the administration of Operative
Systems could perfectly well keep data up to date, update prices or edit
descriptions thanks to the data maintenance interface by means of a Web
application.
All the shops have a common skeleton which consists of:
informacion.cert@banesto.es. or:
https://www.banesto.es/banesto/certificacion/castella/a.htm
In an electronic transaction the most important part is what the client
sees, and so the most important part of the shop is the design of the templates
required for the introduction of data. Thanks to these templates you can
give your shop a business-like image, or if you prefer, a more informal
and relaxed design. It can be adapted to your client profile as often and
whenever you wish.
There is a detailed explanation of the structure of the shop in the installation instructions. However, before continuing it is useful to know the following:
Installation of the CiberTienda will automatically copy all the software files onto the corresponding preestablished directories. This installation program will request values for the configuration variables.
If this is the first time a shop has been installed the directory /bin will be created, which will contain the 17 cgi files, one of which is the database update file (different for each shop), and the /gif sudirectory which contains some images which are common to all the shops. If more than one shop is installed these files will be shared by them all with the exception of the update files, which are exclusive to each shop. Also, the shop is assigned a name which, in order to guarantee that this is unique will be: ShopName_Random where ShopName is the name assigned to the shop during installation and Random is a random hexadecimal number.
A subdirectory will be created for each shop /ShopName_Random
The structure of the directories is the following:
/ShopName_Random/templates
/descriptions
/carts
/shopping
/data
/gif
/log
/expenses
/pages
The content of each of the directories is now explained in detail:
/bin/ In addition to the cgi's,
this contains the configuration file for each shop.
ShopName_Random.conf: is the file where the configuration variables are stored. Each of these variables is given a value during installation. Most of their values can be changed through a Navigator, as will be explained later. The configuration variables are:
The following files are to be found in this directory:
transactions.count: is the transactions counter. When it reaches 10,000
it goes back to 1 again.
The following directories hang from this directory:
/templates/ Where the templates for the shop are stored (1.)
/descriptions/ Where the descriptions of the products are (2).
/carts/ and /carts/tmp/ Where the shopping carts are stored (3).
/shopping/ Where the carts which have resulted in purchases are stored (4).
/data/ Where the data for the products for which purchase attempts have been made is stored (5).
/gif/ Where the *.gif files are stored.
/expenses/ Where the files with the delivery expenses are written in case a personalized calculation of these should be required (6).
If payment is made in any other way the shopping carts are taken straight
to the /shopping/ directory.
The email message which is sent to the shop is only valid for information purposes. Its validity must be checked in the Transfers Updates menu of the database update program.
The subject of these messages is: method of payment: transaction no.
This allows the navigator to order them according to subject, and thus have them grouped according to method of payment: (card, check, transfer and COD) and within each method of payment, they are ordered from smallest to largest transaction number, which is usually equivalent to ordering them according to dates.
Its content is the following:
##THIS MESSAGE IS ONLY FOR INFORMATION PURPOSES. CHECK
ITS VALIDITY.##
##DATA FOR ORDER N:2153164 CARRIED OUT IN THE CIBERTIENDA##
##CLIENT DATA##
name = Pedro
surname = Perez Garcia
mail =
idnumber =
street = Paseo de la Castellana
number = 80
floor =
flat =
stair =
city = Madrid
state = Madrid
zip = 28014
area description = Europe 100
amount area = 100.00
country = Spain
company =
phone =
fax =
deliver = morning
##DATA OF PERSON RECIEVING THE ORDER##
name_deliver = Jorge
surname_deliver = García Pérez
street_deliver = Paseo de la Castellana
number_deliver = 66
floor_deliver=
flat_deliver=
stair_deliver=
city_deliver = Madrid
state_deliver = Madrid
zip_deliver = 28989
description deliver_area = Europe 100
amount deliver_area = 200
country_deliver = Spain/161ª
phone_deliver=
fax_deliver=
##DATA OF TRANSACTION TYPE##
pay= card
authorization code = 257297
total = 6200
bonus discount = 0
to_pay = 6200
usebonus = NO
##LIST OF PRODUCTS##
#Desc=Offer12, Ref=OFFERREFERENCE12, Qty.=1, Unit Price=3000,
Subtotal=3000
#Desc=Offer11, Ref=OFFERREFERENCE11, Qty.=1, Unit Price=3000,
Subtotal=3000
Total=6000
If the person receiving the order is not the client (if the DATA OF PERSON RECEIVING THE ORDER has been completed) the delivery expenses to be added are those shown in amount area_deliver. Otherwise they are those shown in amount area. The total which appears in the section DATA OF THE TYPE OF TRANSACTION includes delivery expenses. Where they are not shown is in the Total which appears at the end of the LIST OF PRODUCTS.
It is the shop administrator’s responsibility to check that the country where the purchased products are to be sent corresponds to the area selected for the delivery expenses, since the CiberTienda does not carry out this type of check.
authorization code only appears in payments by credit card. It is used for possible claims regarding the payment or to cancel a transaction.
bonus_discount is the equivalent in pesetas of the bonus points which the client has spent to pay for the order. It can only be discounted when the configuration variable BONUS is at a setting other than NO DISPONIBLE.
to pay is the total amount which is to be paid once the bonus discount has been discounted from the total of the DATA OF THE TYPE OF TRANSACTION.
usebonus only serves to inform as to whether bonus points have
been used to pay for the order. This cannot be done when the configuration
variable BONUS is set at NO DISPONIBLE
The functioning of the CiberTienda is based on files called cgi which create HTML pages in a dynamic manner, according to needs. In order to do this they open other files written in HTML language called templates which contain the basic structure of the page which must be shown at each moment. Links between the different pages are made between the cgi and not between the templates, since some parameters between the cgi are necessary for the CiberTienda to function correctly.
After the installation process some example templates are copied. It is best to begin with these to change the way the shop looks.
The templates contain special codes, with the format: %#code# which are used to: visualize database values in the template, include data generated by the cgi and/or send parameters to other cgi contained in the template code. The cgi which shows the template replaces these codes with their value.
Due to the transactions system used in the CiberTienda it is not possible to make direct reference to normal HTML pages outside the CiberTienda, as the server would lose count of the transaction being carried out and not be able to carry out correct accounting of the products stored in the shopping cart. For this reason a method has been implemented by means of which a particular HTML page may be called by a CGI created for this purpose. Each of the *.cgi files always opens the same templates with the exception of the target file which is prepared to open any file which you wish to add for additional information which has nothing to do with the CiberTienda. Of course, this page must have a return call by means of a direct link either to the CGI which produces the main page, or to any other CGI of the system as long as the necessary parameters are correctly passed on to it.
The call to this CGI has the following format:
<A HREF="%#BASECGI#target?name=[nam]&transaction=
%#transaction#&shop=%#shops#">
[Text and/or image]
</A>
Where [nam] must be substituted for the name of a template which will contain the Web page which we wish to visualize, and which must be found in the subdirectory /templates/ with the name [nam].htm.template. Should [nam] be for example help, the CGI would open the template with the name help.htm.templ and show it on screen. This template, as has already been mentioned, must have a link which enables return with a format like this:
<A HREF="%#BASECGI#principal?&trans=
%#transaction#&shop=%#shops#">
</A>
which makes it return to the shop’s front page. The return can be made to any page you wish as long as the appropriate parameters are passed on to the cgi. This allows us to have a series of, for example, help pages, which are necessary so that the shop’s clients can move around it with ease.
In the example that comes with the CiberTienda target is used from the front page to make calls to the help pages (help.htm.templ).
The final visual look of a CiberTienda is given by the HTML code written in the data presentation templates. For information on programming in HTML language you can access the Banesto Web:
http://www.banesto.es/banesto/manuhtml/castella/curso.htm
Installation required you to define two url: which together form the installation path, one up to and including /bin and the other up to and including /gif. In the configurational file, the name of these URL’S should be assigned to the BASECGI and BASGIF parameters, respectively. You will use %#BASECGI# when you want to call a cgi from a template and %#BASEGIF#when you want to visualize a gif within a template. In this second case, you will find that in the example shop that is installed, to show the gifs something along the lines of the following is written in the templates:
%#BASEGIF#migif.gif
You must use this way to add new gifs which are placed in the subdirectory
.../ShopName_Random/gif.
Access to the CiberTienda is made by means of a Navigator. The access address is:
http://www.my_computer.com/my_url/page_of_access.html
A first page will appear which will allow you to access the CiberTiendas. When the first CiberTienda is installed this page will be created. When further shops are installed you must add a link to this page, the same as the first one, for each of them, using this page as an entrance to a shopping mall. Each of these links is a call to the index.cgi file:
<a href="my_url_cgi/index?shop=ShopName_Random">ShopName</a>
index assigns each prospective client accessing the CiberTienda a transaction number which is calculated from a file called transactions.count. It then calls principal which reads the template: index.card.templ and shows the main page of the CiberTienda.
This template must have the links necessary to access the rest of the shop, as you will see later on in the section on constructing a shop. From this moment on the client moves at will through the various lists and product cards which are automatically generated by the CiberTienda. The products are organized according to sections, each section being one of the database fields.
When the user adds a product to the shopping cart from a product card, a unit of the product selected is added to the file XXXX.cart, of the shopping carts directory, where XXXX is the transaction number. If the same product has been selected previously the system will increase the quantity of this product in the shopping cart by one unit.
The number of product units in the cart can also be modified or a product can be eliminated if wished.
There is a limit to the total price of the products included in the cart. So if the figure 2,147,483,647 is exceeded, an overflow error message will appear and the operation will not be permitted.
After a client has placed all the products he wishes to purchase in
the shopping cart he only has to click on the buy button and a list of
the contents of the cart together with the total cost will appear as well
as a form that the client must fill in to be able to receive his purchase.
Once this form has been completed and the method of payment has been selected
the data will be checked and, if it is correct the transaction will be
accepted, and then sent to the email address previously assigned to the
configuration variable EMAIL_SHOP.
A DB engine must be installed in order for the shop to function. There is no need to know how to use or update this, since the CiberTienda included, for each shop that you have installed, a menu written in HTML language with which any necessary modification can easily be carried out through a Navigator. This menu is called menutienda.html and may be found in the same directory as the templates, that is, there is one for each shop.
http://dirección del servidor{:número de puerto}/my_url_gif/templates/menushop.html
This call can also be made as https is you have a certificate.
This page must make a call to managershop cgi. A known copy of this cgi must be made for each shop, for example: MSShopName_Random (if you have a certificate this call can by made by means of https) which is responsible for modifying the contents of the DB. It is not a cgi like the rest in that it does not open any template but produces HTML pages as an output. The CiberTienda administrator will therefore have to bear in mind that this cgi uses an image whose name is boton1.gif, and so an image with this name will have to be created if you do not want the CiberTienda logo to appear. It is highly advisable to limit access to these applications with user and code through your WebServer.
If access to these files is restricted at level of web server, before executing MSShopName_Random a user name and a password are requested. If these are correct the update menu of the shop they have access to will be shown. In any case, after making any modification to the database, it is advisable to exit the Navigator and start it up again if necessary.
The CiberTienda installs scripts to create a DB and various tables, amongst others a products table and another of areas in which different delivery expenses are charged. In this way, once installed it can be tested without it being necessary to introduce any register.
The update menu also makes it possible for you to update the database whilst the shop is functioning, or on the other hand, to block access to the shop to avoid new hits. This last option is advisable when a large number of products or delivery areas are going to be modified. In either case a check will always be made to see that the prices of the products in the shopping carts correspond to those which appear in the database. Should any problem arise, the client is informed and his cart is erased.
The Database tables
PRODUCTS TABLE
Field Type Size
SECTION varchar() 31
CATEGORY varchar() 5
BRAND varchar() 31
NAME varchar() Not Null 51
SLOGAN varchar() 71
DESCRIPTION varchar() 513
STOCK varchar() 10
PICTURE varchar() 21
GIFTS varchar() 10
GIVEBONUS varchar() 10
AUXFIELD varchar() 255
PRICE
numeric Not Null 9
default 0
REFERENCE varchar() Not Null
21
The products table is made up of the following fields:
%#description#
<br>
If this field is not completed and the command %#description# is in the template, nothing will appear on the page. You also have the option not to put the command %#description# in the template if you do not want the description of any product to appear.
IMPORTANT: this field does not permit characters which
are not letter or numbers to be introduced. Should this be done an error
message will be shown.
field type size
REFERENCE varchar() Not Null 61
PRICE
numeric not null 12.2
default 0
COMMENTS varchar()
61
IDX
int4
4
The areas table is made up of the following fields:
All the values of the attributes will always have to be written in upper or lower case, but you must bear in mind that the Database does not consider two chains of characters to be equal if one is written in upper case and the other in lower case. The fields which represent names of files must always be in lower case.
Note: In the compulsory fields values which
begin with blank spaces or which are null will not be accepted.
QUEUED TRANSACTIONS TABLE
field type size
DATE varchar() Not Null 12
TRANSCOUNT varchar() Not Null 10
AMOUNT numeric Not Null 12.2
PAYMETHOD varchar() Not Null 15
BONUS numeric Not Null 12.2
CODE varchar() 10
VERIFIED varchar() 10
All attempts to carry out transactions will be stored in this table. With the update program which we will speak about later this table is managed in such a way that all purchase attempts may be verified before being approved.
The bonus points which the client has used when making a purchase are stored in the BONUS field. If for any reason the purchase is not confirmed then the points will be returned to the client.
If payment is made by card the VERIFIED filed will show ‘YES’, because
the payment has been made.
STATS TABLE
field type size
DATE varchar() Not Null 10
HITS int4 4
PAY_TRIES int4 4
OK int4 4
KO int4 4
TOTAL int4 4
N_TAL int4 4
T_TAL numeric 12.2
N_TRA int4 4
T_TRA numeric 4
N_REE int4 4
T_REE numeric 12.2
BONUS numeric 12.2
All data corresponding to the statistics of the shop are stored in this
table, as well as the number of hits, the number of payments made with
each method of payment, the income from each, and even the equivalent in
pesetas of the total amount of bonus points spent by clients.
CARD TABLE
field type size
CODE varchar() 10
PASSWORD varchar() 10
BONUS numeric 12.2
DATE varchar() 10
NAME varchar() 60
SURNAME varchar() 60
BONUSTICKET numeric
12.2
This table contains all information referring to the clients’ bonus
cards. The information it contains is only relevant if the bonus points
are authorized in the BONUS_CONF configuration variable. How to use this
table for the administration of the CiberTienda is clear.
AMOUNT BONUS TABLE
field type size
ST_AM numeric not null 12.2
END_AM numeric not null 12.2
PORC varchar() not null 6
This table contains the ranges and the percentage of bonus points obtained when making a purchase. The information it contains is only relevant if the bonus points are authorized in the BONUS_CONF configuration variable. It may have two meanings depending on the value of this variable:
If BONUS_CONF =AMOUNT the bonus is calculated as the percentage of the total amount of the purchase indicated in the PORC field (not including delivery expenses).
If BONUS_CONF =ITEMS the bonus is calculated as a the percentage of the total amount of the products whose GIVEBONUS field have the value YES indicated in the PORC field.
All fields in this table must be completed, the ranges may not overlap,
and the porc field may only use the ‘.’ (dot) as a decimal separator.
ENQUEUED BONUS TABLE
field type size
TRANSACT varchar() Not Null 10
CODE varchar() Not Null 10
BONUS numeric not null 12.2
DATE varchar() Not Null 10
The bonus points pending to be given to clients are stored here until
the transaction has been successfully carried out. Once this has occurred
the BONUS is added to the bonus points there may be on the card table of
the client in question.
Functioning
The menutienda.html page (which is in the templates directory) is accessed from the Navigator in the following manner:
http://IPof thehostname/BASEGIF/ShopName_Random/templates/menutienda.html
where there is a link like this:
<a href="%#BASECGI#MSShopName_Random?menu=0&shop=
ShopName_Random">
Menu de Actualizaciones</font>
</a>
This links leads to another page in which various options appear. For this purpose it contains a form which makes it possible to choose one of the following options:
1.1 Stats list for all the months: All the registers in the
table are shown grouped according to months. It shows a table for each
month and a line for each day, giving all the methods of payment and the
total income from each one, as well as the equivalent in pesetas of the
bonus points spent by clients. There is also a button which when clicked
on shows the same statistics in charts: two pie charts with the number
of payments in each method and the amount of each them. The other is a
bar chart with the number of hits for each day.
1.2 Stats list for the month selected: in this case there is only one table with the previously mentioned information.
1.3 Stats list in intervals: it is possible to see a table
for each month within a chosen interval.
2.2 To cancel products: it requests a word to search for in the database. If it finds it, it shows the registers found. The search is carried out by name, slogan and reference fields in the case of products, and by reference and comments in the case of areas. If more than 1,000 registers are found a message will be shown saying that the search will have to be further restricted. ‘*’ and ‘?’ must not be used, the search will be carried out by finding coincidences in any position within the value of the field. If nothing is introduced all the products will be found. The registers found in the ITM groups (configuration value) are listed, and they appear linked to other ITM registers. After selecting the product or area desired, the option is executed. If the "all" button is clicked on all the registers which coincide with the search pattern will be deleted. A message is then shown to confirm that the operation has been carried out successfully.
2.3 To make modifications: it asks for a word to search for in the database. If it finds it, it shows all the registers found. The search is carried out in the same way as in the previous point and with the same characteristics. After selecting the product or area desired it leads to a similar page to the registration page and after introducing the appropriate values for the attributes and clicking on the OK button the option is carried out. A message is then shown to confirm that the operation has been carried out successfully.
2.4 Go to the home page of the shop. As in point 6.
2.5 Access to the Shop. As in point 7.
2.6 Main page: this is the access button for the main page of the update menu.
3.2 List of transactions on the selected day.
3.3 Select the transaction.
Likewise, if in the introduction boxes of any field an appropriate value is not introduced (or none in the case of compulsory fields) an error message will be shown.
In this way you can be sure that the CiberTienda database is
permanently updated and the values introduced in the fields are appropriate.
Limitations to the Database content
Before modifying or inserting new products or areas in the database you must bear in mind the following norms:
Massive loads to the Database
There is another way to maintain the database which is by using the psql postgres program directly. To make massive loads of both products and areas:
Creation and modification of Templates
Introduction
All the templates have the same file extension, '.templ' and although they are all in the same place so that they may be located with ease, (.../BASE_DIR of the configuration file that you gave in the installation of the shop/templates), they are divided into two large groups, the card and the lists. The first (XXX.card.templ) are usually for visualizing a single product or some other element in the shop, the second (XXX.list.templ) are the templates which will contain the database or shopping cart lists of data.
Each type of template usually contains a series of special codes which will interact with the database, and although these codes follow a common and homogeneous nomenclature, not all the codes are valid in all the templates. The special codes used are always preceded by the characters %#, plus a key word which may be a database field name or another special identification finished all by the characteres #.
At the end of many of the templates there are links to other sections of the shop, as well as the possibility to send email to the shop administrator. It is not advisable for the shop email address (EMAIL_SHOP) and this address to be the same because the first is where the CiberTienda sends the messages with the orders made and the second is the shop administrator’s address. It is the CiberTienda administrator’s responsibility to change the address which appears by defect (NameCiberTienda@cibertienda.org) for the appropriate address in each of the templates where this may be necessary.
One possible way of doing this is:
<a href="%#BASECGI#principal?trans=
%#transaction#&shop=%#shops#">menu</a>
|<a href="%#BASECGI#target?name=help
&trans=%#transaction#&shop=%#shops#">HELP</a>
|<a href="%#BASECGI#target?name=search&trans=
%#transaction#&shop=%#shops#">
search</a>
|<a href=mailto:NameCibertienda@cibertienda.org>
As well as reading, the cgi produce some HTML pages internally which are modifiable in part. Most of them obey messages in error situations. These will be discussed later on.
As has already been mentioned, clients may obtain bonus points for the purchases they make and then use these to obtain other products. This possibility is more complicated to manage than the shop without bonus points. There therefore follows a detailed explanation of each type of template and the special codes which may be used in them, separated into two sections: one for the administration of the shop without bonus points and the other with bonus points.
It is best to begin without using bonus points (the form of the shop
after installation) by setting the configuration variable BONUS_CONF=NO
DISPONIBLE.
Administration of the CiberTienda without bonus points.
(index.card.templ and stop.templ files)
When entering the shop the index file is executed. As well as assigning a transaction number and creating an initially empty cart, this file calls the principal file which opens the front page template (this has been explained earlier on). If the Shop is blocked, the stop.templ template is opened, which shows a message announcing its momentary block. It has a link which is used in order to try to access the Shop again. The Shop administrator may decide whether he wishes this link be to the main page of the Shop or to the entrance to the shopping mall according to whether the call is:
<A HREF="%#BASEGIF#index.html">Return to the entrance to the shopping mall
</A>
or
<A HREF="%#BASEGIF#index?shop=ShopName_Random">Return to main page </A>
The shop front page (index.card.templ) is responsible for welcoming prospective clients. We may and should use any kind of graphics, logos or other indicators to identify our service, brand or company, thus building a page from which access to all the products of the shop may be made.
For this purpose it is highly advisable to create a list on the front page of all the sections that our shop is going to have and link each of them with a call to the CGI which will be responsible for showing the product list for that particular section. The elements of this list may be both lines of text, graphics or even an image map. What is important is that the references (HREF) are carried out correctly. Each time you want a list of the sections to appear you must add a reference like the following one to the appropriate template for each section:
<A HREF="%#BASECGI#
listshop?table=products§ion=[sec]&begin=0&trans=
%#transaction#&shop=
%#shops#">
[Text and/or image]
</A>
The table parameter must be = products, which is the name of the database table which contains the products. The words inside square brackets indicate those variables which control the list which will be obtained when this link is clicked on. [sec] indicates the section which contains the products you wish to list, (if the name contains blank spaces they must be exchanged for ‘+’), whilst [Text and/or image] will be exchanged for what we wish to appear on the main screen to symbolize that particular section. The rest of the line must be written exactly as shown.
Another important feature of the shop is the capacity to search for a product by name, section, slogan or category. To include one of these search insets in the main template we will have to insert the following form in HTML code:
<form method="post" action="%#BASECGI#search">
<input type=hidden name="shop" value="
%#shops#">
<input type=hidden name="transaction" value="
%#transaction#">
<input type=hidden name="table" value="products">
<input type=hidden name="begin" value="0">
<input type=text name=texto size=16 maxlength=60>
<input type=submit value="Search">
</form>
Of course both the input type submit and the input type text may be changed in form or size within the HTML norms without affecting your front page as long as the latter’s name parameter, the former’s maxlength=60 and the same written order of the input types are respected. The rest of the input types as well as the definition of the form are fixed and may not vary even in order.
Searches are carried out in the following fields: name, slogan, section and category, which means that it is advisable that these should all be completed in the database.
In principle searches from here are intended to be made independently from the section in which the required product is, but the tag %#sect_list# may be added after the text. This will be exchanged automatically for a pull-down menu where the required section may be chosen. In this way the search will be carried out within the chosen section.
Should nothing be entered as a search pattern the client will be shown a list with the first products found on the database in no order. As many as the ITM variable which is found in the configuration file indicates are shown. As has already been mentioned, as well as the ITM products listed various links to see the next products in ITM groups will appear.
Should there be more than 1,000 products corresponding to the search pattern introduced, a message will be shown (see the show.messages.templ template) which may be changed. This will make it obligatory to further restrict the search.
It is also possible to include direct references to particular products from the main page by introducing a reference (HRED) to the product presentation CGI. The drawback of this is that we must know some of the product data exactly. This is especially useful when we wish to show a client a product as soon as he enters the shop, whether because it is a special offer, a new product or some other kind of clearance sale. To include one of these references the call is constructed as follows:
<A
HREF="%#BASECGI#productshop?table=products&reference=[ref]&trans=
%#transaction#&shop=
%#shops#">
[Text and/or image]
</A>
Where products indicates the name of the database table where the product is to be found and [ref] is its reference number.
As has already been indicated, due to the transactions system used in the CiberTienda it is not possible to make direct references to some normal HTML pages, since the server would lose count of the transaction being carried out and not be able to keep correct accounts of what is stored in the shopping cart.
For this reason if you wish to make a call to a particular HTML page the target cgi must be used. This page must of course have a return call by means of a direct link either to the CGI which produces the main page, or to any of the system’s cgi as long as they pass through the necessary parameters correctly.
The call to this CGI will have the following format:
<A HREF="%#BASECGI#target?name=[nam]&transaction=
%#transaction#&shop=
%#shops#">
[Text and/or image]
</A>
Where [nam] indicates the name of a template which will contain the Web page we wish to visualize. For example, if [nam] is help the CGI will open the template with the name help.htm.templ and will show it on the screen. This template, as has already been mentioned, must have a link making it possible to return with a format similar to the following:
<A HREF="%#BASECGI#principal?trans=
%#transaction#&shop=
%#shops#">
[Text and/or image]</A>
which returns to the front page of the shop.
But this template serves not only to welcome prospective clients but may also be returned to from many parts of the CiberTienda. So a link may be added here in order to see the cart:
<A HREF="%#BASECGI#watchcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#&where=index">
See the cart
</A>
With regards to the construction of the front page these are the only
special codes which may be used. The rest of the elements put on the page
are to decorate it and give it the look we want it to have.
Sections lists templates
(products.list.templ file, only template)
This template is shown by the listshop.cgi file which is accessed by means of a call such as the following:
<a href="%#BASECGI#listshop?table=products
§ion=[sec]&begin=0&trans=
%#transaction#&shop=
%#shops#">
[text or image]</a>
Once the call to listshop has been made this CGI reads a template of listings by sections and interprets the commands found in it to produce an exit page with a list for the section selected. Remember that if the name of the section has blank spaces they would have to be exchanged for ‘+’.
To locate this list within the template more special codes are used, this time of a slightly more complex nature. In this case it is a question of indicating where and with what form the data on the list is going to be printed. For this we use the special command %#listbegsect# and %#listendsect# to delimit what will be listed data taken from the database. The HTML code and the names of the fields we wish to visualize will be introduced between these two tags preceded by %# (e.g. %#slogan#, %#price#, %#reference#, ...) and finished by the characters #. All the %#tags indicate to the CGI that what immediately follows is the name of a field in the database product table and so the CGI substitutes it for its value when it reads the template. The two tags: %#listbegsect# and %#listendsect# must each be on a line and alone.
The format has the following style:
%#listbegsect#?
<FONT size=5>
<A HREF="%#BASECGI#productshop?tabla=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#">
<B>
%#name#</B>
</A>
</FONT>
<BR>
%#slogan#
<P>
%#listendsect#
The registers order according to the desired database field by just changing the tag %#listbegsect# for %#listbegsect#?order=field_desired and as many as the LPS variable indicates come out. Also, a number of links will appear in order to see the next products in LPS groups. Since there is only one table and there may be a number of different sections in it, it is possible to make a reference to the section field from outside the listbegsect – listendsect block to identify on the page itself the section that is being visualized. In this way we can automatically put a title before the list that indicates the name of the section as in:
<H1>
%#section#</H1>
or with the following HTML sentence:
<IMG SRC="%#BASEGIF#%#section#.gif" >
which would visualize a GIF graphic with the same name as the section.
In this kind of template it is also possible to make reference to the searcher as we explained for the front page template:
<form method="post" action="%#BASECGI#search">
<input type=hidden name="shop" value="
%#shops#">
<input type=hidden name="transaction" value="
%#transaction#">
<input type=hidden name="table" value="products" >
<input type=hidden name="begin" value="0">
<input type=text name=texto size=17 maxlength=60>
<input type=hidden name="section" value="
%#section#">
<input type=submit value="Search">
</form>
Here, the search is intended to be carried out within the section you are in. That is what the %#section# is there for, which is automatically exchanged for the name of the section you are in.
As many products as the ITM variable which is in the configuration file indicates are shown. As has already been mentioned, as well as the ITM products listed a number of links will appear to see the next products in ITM groups.
Should there be more than 1,000 products corresponding to the search pattern introduced, a message (see the show.messages.templ template) will be shown which may be changed. This will make it obligatory to further restrict the search.
The explanation made for the previous template regarding direct references to specific products and the target CGI to access normal HTML pages is perfectly valid and applicable for this type of template.
A link may also be added to this template in order to see the cart:
<A HREF="%#BASECGI#watchcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#&where=listshop
§ion=%#section#&begin=0">
See the cart
</A>
This call is not exactly the same as in the case of the front page template, since it is now inside a section, and both its name and the start of the list must be passed on as parameters.
Just as in the case of the front page template these are the only special
codes which may be used. The rest of the elements which are put onto the
page are to decorate it and give it the look we want it to have.
Search templates
(search.list.templ and search.htm.templ files)
The search.htm.templ template shows the target file for which the call has already been explained:
<a href="%#BASECGI#target?name=search&trans=
%#transaction#&shop=
%#shops#">
search</a>
This template shows a page on which there is a box in which the client will introduce one or a number of words for which he wants to search in the database. The clients may also choose the section and the fields in which they wish to carry out the search.
In the example this call is made from the bottom part of a number of
templates such as:
index:card.templ, products.list.templ, or products.card.templ
When the client starts a search by means of the corresponding box, the search CGI finds all the products which comply with the specified features and then shows them in the form of a list using the orders given in search.list.templ. This search, as has already been indicated, is made according to fields: section, category, name, slogan, auxfield, description, price, brand, picture, reference or by all simultaneously. If it is desired to look for by the price it will have to introduce a numerical value.
The search.htm.templ template exists for this purpose. The search.list.templ template is shown to give the result of a search, by the search cgi.
The search.htm.templ template is opened by target for which the call has been seen previously. Basically it consists of a form like the one for products.list.templ, which also contains some boxes with which we may choose the fields in which the search will be carried out.
<form method="post" action="%#BASECGI#search">
<input type=hidden name="shop" value="
%#shops#">
<input type=hidden name="transaction" value="
%#transaction#">
<input type=hidden name="table" value="products" >
<input type=hidden name ="begin" value="0">
<input type=text name=texto size=17 maxlength=60>
%#sect_list#
. . . . .
<input type=checkbox name="category" value="category">Category
. . . (as many of these as the fields which you wish it to be possible choose).
<input type=submit value="Search">
</form>
The way this template is made, the most convenient thing is to change the way it looks and eliminate from it the fields for which you do not wish it to be possible to search. It also includes a function in Javascript which makes it possible to mark and unmark all the boxes of the search fields.
If nothing is put in the search box a list of the LPS first products will be shown by means of the search.list.templ template. Also a number of links will appear in order to see the next products in LPS groups. This result may be ordered according to the field desired as in the case of the sections lists.
Since, when all is said and done we are dealing with a list of products, this template is extremely similar to the sections lists template which we have just looked at. All the commands seen are valid for the search template, in the same format and in the same parts of the template. But here the link in order to see the cart must be done in a different way since we are not inside any section:
<A HREF="%#BASECGI#watchcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#&where=index">
See the cart
</A>
It may also be included inside a search box within the search template
so that should the desired results not be obtained, the client may repeat
it without having to return to the previous screen.
Product card templates
(products.card.templ file, only template)
This template shows the productshop cgi for which the call is made as follows:
<A HREF="%#BASECGI#productshop?table=products&reference=
%#reference#&trans=%#transaction#&shop=%#shops#">
[Text and/or image]
</A>
In a similar way to the lists, all products of the same database table will have a common template which will define the way in which they will be visualized.
In this case, due to the fact that only one product will be shown on the page, there are no listbegproduct – listendproduct blocks, although the rest of the tags preceded by %# are equivalent, that is we may use the database field names preceded by %# and finished by # to present the information we wish on the screen. For example we might have an HTML code like this:
%#listbegproduct#
<font size=5 color=#002299><B<<I>
%#name#</I></B></font>
<br>
<font size=4><b>
%#slogan#</b></font>
<br>
%#description#
<font size=4><B>Price:
%#price# Pts. </B></font><br>
<IMG SRC="%#BASEGIF#
%#picture#" width=226 height=253
alt="Foto of
%#name#"></font>
%#listendproduct#
Where each of the fields will be exchanged for its database value. All the database fields may be used and, if necessary, they may be repeated in different places in the template. The description field which has been used in the example has a special treatment. In fact, description contains the name of the text file of the description of the product, but as it is located by the CGI, instead of putting the name of the file, what it does is to open that text file and empty its contents onto the page. If it is not a file name then the contents of this database field are shown. As we can see %#description# appears in a separate line with no text in front or behind. This is not by chance, since due to the special condition of this field and the contents which it empties onto the page, it must be on a line of its own.
As can be seen, some parts of the shop connect up to the next and the same thing occurs with the sales system and the shopping cart, which are usually connected up from these product file templates. It is logical that this should be the case, as the client of the shop will buy final products just after seeing them.
There are three calls to the purchase system cgi which may be used from the product card templates. These are the cigis for visualization of the shopping cart, adding to the cart and making a purchase.
To use these options the following code must be introduced in the chosen place on the template:
See the cart:
<A HREF="%#BASECGI#watchcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#&where=donde>
See the cart
</A>
Where donde represents the name of the cgi which opens the template from which the call to watchcart was made:
From index.card.templ: donde must be exchanged for index.
From products.list.templ: donde must be exchanged for listshop.
From products.card.templ: donde must be exchanged for productsop.
In this way the page from which it was accessed will never be lost for the purpose of later return links.
Add to the basket:
<A HREF="%#BASECGI#addcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#">
Añadir
</A>
To make the purchase:
<A HREF="%#BASECGI#buyshop?trans=
%#transaction#&shop=%#shops#">
buy</A>
The call to buyshop may be made in secure mode if, on going from the test stage to the production stage, the way of making the call is exchanged for:
<A HREF="https://%#HOSTNAME#%#BASECGI#buyshop?trans=
%#transaction#&shop=
%#shops#">
buy</A>
Where %#HOSTNAME# is a special tag which productshop.cgi will exchange for the IP address of the host in which we have installed the CiberTienda.
Within this template there are other http:// absolute references. There references are for continuing in insecure protocol as they are calls to previous pages of the shop.
In order for the purchase to be made, some product must have previously
been placed in the shopping cart. If not, the product which is being seen
may not be bought. If the cart is empty, buyshop will show the shopping.card.templ
template with an empty shopping cart message added by the cgi.
Shopping cart templates
(cart.list templ file, only file)
A special feature of this template is that instead of being shown by only one cgi, it is shown by the watchcart, addcart, delcart, and modifcart files which serve to see the shopping cart, introduce a product, delete and modify the contents of the shopping cart:
See the cart:
<A HREF="%#BASECGI#watchcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#&where=donde
§ion=%#section#
&begin=0">
See the cart
</A>
or
<A HREF="%#BASECGI#watchcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#&where=donde">
See the cart
</A>
According to whether the call is made from the sections lists template or from another template in which it may be made.
Where donde represents the name of the cgi which opens the template from which the call to watchcart.cgi was made:
From products.list.templ: donde must be exchanged for listshop.
From products.list.templ: donde must be exchanged for productshop.
From any other template, donde must be exchanged for index.
In this way one returns to the page from which access was made.
Add to the cart:
<A HREF="%#BASECGI#addcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#">
Añadir
</A>
Delete the cart:
<A HREF="%#BASECGI#delcart?trans=table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#">
buy
</A>
Modify the cart:
<A HREF="%#BASECGI#modifcart?table=products&reference=
%#reference#&trans=
%#transaction#&shop=
%#shops#">modify the cart</A>
Visualization of the contents of the shopping cart is carried out by following the format of the shopping cart template. Whilst the contents of the cart may be seen from the main page, the sections lists page and the product card page, introduction of a new product in the cart may only be carried out from the product card page. Modification of the number of units of the products in the cart may be done by putting a link to modifcart as has already been explained, in the desired place in the CiberTienda. It is best to do this in the template we are dealing with, although it may be done in any other.
The principal tag of this template, as in the case of the sections lists template, is the %#listbegcart# and %#listendcart# tag which visualizes a list with all the products the client has been putting on the shopping list. This list must be composed of tags which will be exchanged for the name of the article, the number of times that article has been placed in the cart, its unit price and a subtotal which is calculated by multiplying the number of units by the unit price, as well as any of the Database fields. Also, at the end of the list we can make a general total appear which is the sum of the subtotals. Note that the tag which indicates the total must always come after the product list as otherwise the calculation will not be made correctly.
This is an example of how to construct a table in which all the products stored in the shopping cart appear:
<table>
%#listbegcart#
<tr>
<td width=225>
%#name#</td>
<td width=70 align=right>
%#ammount#</td>
<td width=92 align=right>
%#price#</td>
<td width=70 align=right>
%#subtotal#</td>
%#listendcart#
</table>
%#total#
As well as the %# tags followed by any field of the database products table and finished in #, the %#subtotal# tag may be introduced and lower down we would introduce the %#total# tag in order to visualize a sum of the subtotals.
Apart from this list a number of calls may be introduced which work on the contents of the cart. There are four cgi which may be called from this template: the first serves to return to the page which took us to see the contents of the cart, the second is responsible for emptying shopping from the cart, the third is to modify the contents of the cart or to delete individual products, and the fourth is to carry out the purchase.
<A HREF="%#where#">Return</A>
<A HREF="%#BASECGI#delcart?table=products&reference=
%#reference#&trans=%#transaction#&shop=#shops#">Delete the cart</A>
<A HREF="%#BASECGI#modifcart?table=products&reference=
%#reference#&trans=%#transaction#&shop=%#shops#">modify the
cart</A>
%#transaction#&shop=%#shops#">buy</a>
But when you go from the development phase to the production phase, if you wish the buyshop.cgi file to be executed in secure mode, (see installation manual) the call must be:
<A HREF="https://%#HOSTNAME#%#BASECGI#buyshop?trans=
%#transaction#&shop=%#shops#">
buy </a>
Where %#HOSTNAME# is a special tag which the cgi will exchange for the IP address of the machine in which we have installed the CiberTienda (parameter of the file of configuration).
Within this template there are other absolute http:// references. These references are for continuing with insecure protocol in the previous pages.
The fact that the template we are dealing with may be called from a
number of places means that return is not to a specific page, but to the
page from which the call was made, and so there must always be a %#where#
tag
in the template. If not, the link mechanism between the sections of the
shop which calls the cgi which show this template will fail.
Modification of the cart templates
(cart.modif.templ file, only template)
This template is shown by the modifcart.cgi file for which the call has already been explained:
<A HREF="%#BASECGI#modifcart?table=products&reference=
%#reference#&trans=%#transaction#&shop=
%#shops#">modify the cart</A>
Basically, it consists of a form which shows the contents of the shopping cart. But when it shows the units, it does so in a box with the form:
<input type="text" name="ammount" value="%#ammount#" align=left size=2
maxlength=2>
In this way the number of the same articles that may be placed in the cart is limited. The size and maxlength parameters may be changed at will, but the modifcart.cgi file limits the maximum number of units to four digits. If the number of digits is not limited in the template and more than four are introduced, the change will be ignored.
This template also contains the %#listbegcart# and %#listendcart# tags between which %# followed by the name of any Database field may be put and finished in #.
As in any form, if the "Modify" button is clicked on the amounts contained
in the cart will change. Clicking on this button produces a new call to
modifcart, but this time the template shown is cart.list.templ.
Order and purchase templates
(shopping.card.templ file, only template)
This template is shown by the cgi buyshop, the call for which was explained in the section on the product card template.
<A HREF="%#BASECGI#buyshop?trans=
%#transaction#&shop=
%#shops#">
buy
</A>
But when you move on from the test phase to the production phase, if you wish the buyshop.cgi file to be executed in secure mode, the call must be:
<a href="https://%#HOSTNAME#%#BASECGI#buyshop?trans=
%#transaction#&shop=
%#shops#">
buy
</a>
Where %#HOSTNAME# is a special tag which will be exchanged for the IP address of the machine in which we have installed the CiberTienda (parameter of the file of configuration), as long as the link to buyshop is located in products.card.templ or/and in cart.list.templ.
This template has the same format as that of the shopping cart although it has in addition the design of a form for entering data, so that the client of the shop may specify the necessary data for the payment of the products bought and the place to which they will be sent.
Due to this, the %#total# tag may be inserted as well as other new ones such as %#list#, a tag from which the list of products that they wish to purchase is shown. The fields shown are fixed: name, amount, price and subtotal. Other closely related tags are %#areas# and %#areadeliver# which are exchanged for pull-down lists which show the reference field of the areas table of the database. The value which is accepted in the menu which is put instead of %#areas# is taken into account for delivery expenses if the person paying is the person receiving the goods. If the person receiving the goods is different to the person paying, then the delivery expenses will correspond to the area chosen in the menu which appears instead of %#areadeliver#.
It is compulsory to respect the format of this template as any change in the names of the entry boxes of the form might result in erroneous functioning of the purchase system.
As most possible methods of payment are taken into account in this template it will not be necessary to add anything new. But should you wish to delete any method of payment (if all methods of payment are deleted the system will not function), what you have to do is to comment this out in the payment system template. To do this you will have to put: <! - - at the beginning of the first line which you wish to comment out and --- > at the end of the last line that you want to comment out. Take care not to put any comments inside others as this will result in incorrect functioning. If you want one of the options to be payment by default you must only put CHECKED in this option when the selection button shows:
<INPUT TYPE="radio" NAME="pay" VALUE="talon" CHECKED>
But if you only have one method of payment authorized, then you will have to tag it as a default option.
If you have a number of methods of payment authorized only one of them
may appear as CHECKED.
Only two calls are made from this template:
If all the fields marked with an asterisk (*), which are compulsory, are not filled in, databuy.cgi will generate a page warning that the information is incomplete. Also, if an attempt is made to pay for the same cart twice a page is generated with the message: non existing cart.
In the call to databuy the same type of protocol used as for the call to buyshop is maintained. That is: if this call is produced by means of secure protocol (https) databuy.cgi will be executed in secure mode.
Again, this call must not be changed since otherwise the purchase service
would not function. This absolute reference (http://) is for going from
secure protocol to insecure protocol if this is being used, in order to
return to previous pages of the CiberTienda.
Transaction check templates
(pay.templ, pay.1.templ, pay.2.templ and pay.3.templ files)
The file which shows the pay.1.templ, pay.2.templ and pay.3.templ templates is databuy, which receives the data introduced when the order and purchase template (shopping.card.templ) is shown. These simple files make it possible to give a format to the sending out of data which is produced after checking that the data introduced in the purchase form is correct.
The pay.templ file is used to confirm an order if the payment is made by credit card. The databuy cgi is used to show the amount payable and the reference number which identifies the transaction. When ‘send’ is clicked on pay is executed, and parameters such as name of shop where the purchase is made, reference of the transaction (a number with which the purchase is identified) and cost of the purchase made, are passed on to it. The call is made as follows:
<form name = "pago"
method = "post"
action="%#BASECGI#pay">
In this call the same type of protocol as used for the call to buyshop.cgi is maintained. That is to say: if the call is made by means of secure (https) protocol, pay.cgi will be executed in secure mode.
The pay cgi carries out checks on cost, which it receives as a parameter (which corresponds to that of the data and carts files, as well as to the prices registered in the Database), moves the carts whilst the payment process is being carried out, and finally serves as a link with the payment module used, that is, with the Virtual TPV of the chosen Financial Institution, by means of the call to the enlace_con_tpv(....) function. Basically, this function is responsible for reading the configuration file of the chosen TPV called conf.tpv. Certain parameters in this file are compulsory and serve for any TPV and others are specific to the Banesto TPV.
In this case it is personalized for the Banesto TPV. The following are details of all the compulsory parameters:
MODE =cgi.
URL ="http://hostname/cgi-tpv/totalizacion"
BASEPARAMETERS =shopname= commerce_name, reference=reference,
totalprice=coste, currency=currency
1.- The chosen TPV needs first the cost with the name amount_transaction, then the commerce with the shop name, and finally the reference with the name transaction. The BASEPARAMETERS parameter of the conf.tpv file would have the following form:
BASEPARAMETERS = totalprice=amount_transaction, shopname=tienda, reference=transaction, currency=currency
2.- The TPV chosen needs first the reference with the name refe_compra, the commerce with the name shop_name. The BASEPARAMETERS parameter of the conf.tpv file would have the following form:
BASEPARAMETERS = reference=refe_compra, shopname=shop_name
The following parameters are specific to the Banesto TPV and optional, that is to say, if they are not specified in the configuration file conf.tpv it will still be possible to make a complete link. It is not strictly necessary to provide the .cgi with these parameters.
These or others may appear, to connect to other TPVs these paramaters may be changed and other/s which other TPVs need may be put (by reprogramming the enlace_con_tpv() function of the pay cgi).
PRODUCT = cod_articulo, description, cantidad, precio_unitario,
precio
SUBTOTAL = subtotal
EXPENSESDELIVER = expenses_deliver
EMAIL =e_mail
CARDHOLDER =titular_tarjeta
LIMITOK = 15000
URLRESULT = http://www.cibertienda.org/BASEGIF
*PRODUCT. If we specify this parameter in the conf.tpv file, the description of the order we have made will be sent to totalizacion.
*SUBTOTAL. If this parameter is specified in the configuration file, this same file will be sent to totalizacion with the name subtotal=amount corresponding to the purchase not including delivery expenses.
*EXPENSES_DELIVER. If it is specified in the conf.tpv file this
parameter will be passed on to totalizacion with the name expenses_deliver=amount
corresponding to delivery expenses for our purchase.
The three previous parameters are used for SET transactions in Banesto.
*EMAIL. If this parameter appears in the configuration file totalizacion will be given the e-mail of the client who has made the purchase.
*CARDHOLDER. If this parameter appears in the configuration file the card holder must be passed on when connecting to totalizacion.
*LIMITOK or LIMITKO. The first parameter indicates the established limit, which the total sum of the amount of the authorized transactions made by a card on the same day may not exceed. The second has the same meaning but for transactions which are refused.
*URLRESULT. If this parameter appears in the conf.tpv file, the url where the executable exec_result will generate the pages with the result of the transaction must be specified in it. This parameter is compulsory if version 3 of the Banesto TPV is used, and if this is specified the cookie as an account code for operating with bonus points will also be specified.
You will obtain more information about the Banesto TPV in its download package.
The value of all parameters specified for the Banesto TPV is taken from
the carts and/or data files, except URLRESULT, the value for which is indicated
in the configuration file.
Once this file has been read the pay cgi will contact the corresponding
TPV defined in the conf.tpv file.
Depending on whether it is a cgi or an executable the program with which we wish to link will be called up as follows:
Both if the transaction is accepted by the Authorization Center and if it is not, the result cgi must be called and given the appropriate parameters. For this purpose a cgi may be made which serves as a bridge between the chosen TPV and the result cgi. If you decide to make a CGI as a bridge, the format of the call may have the following form:
Print("Location:%s?commerce_name=%s&reference=%&result=%s&date=%s&code=%PATH_LOCATION, commerce, reference, resultado, date, code, rest);
Where:
If the transaction is not authorized or an error occurs, result will call show.messages.templ explaining the reasons, and from there it will be possible to return to the beginning of the shop by means of a call to index, which will generate a new transaction number.
The database update operations are carried out in this cgi. The operations will be stored in the queued_transactions table as verified.
As well as using a cgi it is possible to choose the option of using an executable, called in this case exec_result. This executable of the shop will be responsible for communicating the result of the transaction so that the order may be carried out.
This executable will receive as the only parameter a line with the following format:
Example:
"COMMERCE=name_of_the_shop:RESULT=KO:REFERENCE=123456:AMOUNT=3100:COD
TRANSACTION REFUSED FOR VARIOUS
REASONS:CURRENCY=ESP:SESSION_DATE=991212:
REST=ccc=12345678:"
Examples:
Trans_no_procesadas.log
-----------------------------------------------------------------------
Failure in commerce:tests at 18:05:38
Date991202 in transaction:09c
Reason: Incorrect number of parameters
-----------------------------------------------------------------------
-----------------------------------------------------------------------
Failure in commerce: demo_78965432 at 18:43:26
Date 991202 in transaction:66666666
Reason: Error on opening data file
-----------------------------------------------------------------------
Error_resultado.log
COMMERCE=demo_19576198:RESULT=OK:REFERENCE=206548:AMOUNT= 350:MONEDA=ESP:DATE_SESION=991293:REST=ccc=12345678:
It is not possible to try to pay for a cart again because pay.cgi will generate a page with the message ‘non existing cart’.
If another method of payment is used, in principle, the result will be satisfactory if all the compulsory fields have been completed. Then, databuy.cgi first reads pay.1.templ, which contains the heading of the HTML page as well as the tags necessary for the buyer’s data to appear, and then pay.2.templ which contains the data of the recipient and is only shown if the recipient of the order is different to the buyer.
Important: These templates may not be modified except to improve the way the page shown looks. Especially pay.templ.
Note: The databuy file may show error pages without having
to open any template. This is when an attempt is made to pay for the same
cart twice, when the cart does not exist, or when an error occurs on opening
a file such as the template file (shopping.card.templ), the shopping cart
file or the data file. In these cases a page is shown warning that an error
has occurred. An image called button1.gif is shown on these pages. It is
the CiberTienda administrator’s responsibility to create a graphic
with this name if he does not wish the CiberTienda logo to appear.
Error templates
(error.templ and show.messages.templ templates)
There are two kinds of error which may occur while navigating in the CiberTienda:
The first is caused by poor functioning of the shop, basically due to the fact that a template cannot be opened (in this case it is advisable to check that it exists and has the appropriate permits), or because the parameters sent are not the right ones or are in another order (check the calls to that cgi).
The second kind of error occurs when the user does not complete all the compulsory fields of a form, if too many products are obtained after making a search, etc.
When an error of the first kind occurs, all the cgi type files may open the error.templ template to make it known. This template shows an HTML page which contains a link to the principal file.
This template also contains a series of special tags, like:
<a href=http://%#HOSTNAME#%#BASECGI#principal?trans=%#transaction#&
shop=%#shops# >
<img border=0 src="%#BASEGIF#%#shops#/gif/button1.gif></a>
%#message#
Where %#transaction# will be exchanged for the transaction number, %#shops# for the name of the shop, and %#message# for the error message.
The %#HOSTNAME# parameter will be exchanged for the IP address of the machine in which the CiberTienda is installed. The call to principal.cgi is made in absolute mode in order to have the first pages of the shop in secure or insecure mode (See Installation Manual for going from development to production) depending on whether the protocol used is https or http respectively.
In this template, the only thing that may be modified is the look of both the background and the image. The latter may even be eliminated. Under no circumstances should the call to principal be changed, nor the order of the parameters passed on to it.
In the case of more important errors such as, for example, having lost the name of the shop, this template may not be opened, and a page created dynamically is shown. As no template is used to do this, the way this page looks may not be modified and what is shown is a link to the entrance to the shopping mall:
"Parameters incorrect"
When the second kind of error occurs, all cgi type files may open the show.messages.templ template which contains all the messages which may be shown to the client, and which are configurable as wished. This template is rather special, because unlike the rest, not all of it is shown, but only the part corresponding to the error which it wishes to show.
All messages are contained between tags of the <BEGIN_X> and <END_X> type, where X may be one or a number of digits. When modifying this template try not to eliminate any of these tags because either the message is not shown or the file is shown up to the end. Also the %#field1#, %#field2#, %#field3#, %#field4#, %#list#, %#transaction# and %#shops# tags may be used, the meaning of which depends on the message being shown. These tags must be the only thing in the lines in which they appear. Then the possible messages are listed and the tags there might be are commented.
2.1. If the password introduced does not correspond to that of the account. %#field 1# is the account introduced. %#field2# is the password introduced.
2.2.When not all the products in the cart may be purchased with bonus points. The products which may not be accepted are in %#list#. Obviously, this message may only appear when BONUS_CHANGE=ONLYGIFTS.
2.3.When BONUS_CHANGE=NO DISPONIBLE, and an attempt has been made to pay with bonus points.
2.5. When the client wishes to make the purchase with bonus points and does not have an account. %#field1# is the account that the client has specified.
%#field1# The directory where the cgi are to be found.
%#field2# Name of the shop
%#field3# transaction
%#field4# Refusal code
%#field1# Directory where the cgi are to be found.
%#field3# transaction
%#field4# Refusal code
Help templates
(help.htm.templ files)
This is the template which comes with the example shop. It is shown by the target file which, as has already been mentioned, serves to show HTML pages which may not have anything to do with the shop. The ayuda.htm.templ template is used to show information about the CiberTienda and its use. The call to these templates is made as follows from any template or templates you wish except those which have already been mentioned as ones which must not be modified:
<a href="%#BASECGI#target?name =help&trans=
%#transaction#&shop=%#shops#">
At the end of these templates there are links for returning to the desired CiberTienda sections.
You may add as many templates of this type as you need without affecting
the functioning of the CiberTienda as long as the previously mentioned
requirements are fulfilled.
Administration of the CiberTienda with bonus points.
If BONUS_CONF=AMOUNT the points obtained are calculated by looking at what range of the AMOUNT_BONUS table the total (not including delivery expenses) for the products in the cart whose GIVEBONUS field = YES is in.
When a user receives bonus points, an account code for storing them is calculated cryptographically and a cookie is sent. If it is accepted, the next time a purchase is made from the same computer, the cookie for accessing the bonus account will be detected and the bonus points may be spent. It is also necessary for the user to introduce his password, without which it is not possible to spend the bonus points.
If the bonus points option of the shop is enabled this means that another two cgi type files are used: createcode and changecode. There may be links to these files from any pages you wish, but you must bear in mind that if the calls are not made by means of secure protocol the data introduced will not be encrypted in any way. It is advisable that on all pages these links be put together with the other links at the end of each page in the form of a menu.
These calls must have the format:
<a href="https://%#HOSTNAME#%#BASECGI#target?name =changecode&trans=
%#transaction#
&shop=%#shops#
">Change to account</a>
<a href="https://%#HOSTNAME#%#BASECGI#target?name =createcode&trans=%#transaction#
&shop=%#shops#">Account request</a>
Of course these calls may be made by means of insecure protocol, with the exceptions that have just been mentioned.
If bonus points have been used and it has been decided to stop using then, then HTML comments will have to be used to avoid these calls being made, or if not delete them from the templates if you think you are not going to enable this option again.
Calls like these may be included in any template, but it is advisable that they should appear in the following:
index.card.templ
products.list.templ
products.card.templ
search.htm.templ
search.list.templ
help.htm.templ
and in any additional pages created for the shop, with the name xxxx.htm.templ the call for which must be made by means of the call to target as has already been indicated.
As well as the specific bonus templates, if the bonus points are enabled,
there are some tags which, placed in the usual templates, are exchanged
for sections of templates or subtemplates and/or values related to the
administration of bonus points.
Order and purchase templates
(shopping.card.templ file)
The only tag which may be added to this template is %#cookiemsg. It is only interpreted if BONUS_CONF ¹ NO DISPONIBLE. This may therefore be in the template without any action being taken.
If the bonus is activated, two different situations may occur as a result of this tag, depending on whether a cookie is detected or not:
%#cookiename: it is exchanged for the name of the card holder.
Transaction check templates
showaccount.templ interprets the tags.
%#card# = card number.
%#pas_card# = password of the card that has been requested.
showaccount.templ shows the data for the card to which the bonus points obtained are added. It interprets the following tags:
%#card_id# = card number.
%#card_name# = name of the card holder.
%#card_surname# surname of the card holder.
%#bonus# = the bonus points associated with the card to which the points obtained are added. It interprets the following tags:
%#card_pas# = password of the card.
After connecting with the corresponding transactions Authorization Center the result cgi must be called up. If the transaction is authorized, then the pay.3.templ template is shown if no bonus points have been spent. But if they have been spent, then
pay.3.usebonus.templ is shown which recognizes the following tags:
%#used_bonus# = are the bonus points which have been spent to pay for the purchase.
%#old_bonus# = are the bonus points possessed before making the purchase.
%#to_pay# = what is paid in money after discounting the bonus points. Bear in mind that delivery expenses may not be paid with bonus points.
%#card_name# = name of the card holder.
%#card_surname# = surname of card holder.
%#bonus_v# = value of the bonus in pesetas.
%#account# = card number.
%#code_transaction# is exchanged for the authorization code which
is always given in the case of payments with credit card and which is needed
for possible claims.
Bonus account request templates
(createcode.htm.templ and account.templ files)
The createcode.htm.templ template is shown by the target cgi, the call for which has been seen previously:
<a href="https://%#HOSTNAME#%#BASECGI#target?name =createcode&trans=
%#transaction#&shop=
%#shops#">Account request<a/>
This template shows a form which may not be modified except in the way it looks:
<form ACTION="%#BASECGI#createcode" METHOD=POST>
Name <input type=text name=nombre size=20 maxlength=60>
Surname <input type=text name=surname size=20 maxlength=60>
<input type=hidden name=trans value=%#transaction#>
<input type=hidden name=shop value=%#shops#>
<input type=submit value="Send data"></td>
</form>
Nor may the sizes of the cells of text be modified.
After sending the form, the createcode.cgi file calculates cryptographically a new card and a password associated to it. And it shows them by means of the account.templ template, which has these tags:
%#shops#
%#transaction#
%#code# = is the number of the new card.
%#password# = of the new card.
Also, this template contains links to the other sections of the shop.
Change to bonus account templates
(changecode.htm.templ file, only template).
This template is shown by the target cgi. Basically, it consists of a form in which the data requested must be introduced: name, surname, account, password, and the new password twice. In principle, the purpose of this is to change the password of the clients’ accounts, so the boxes corresponding to this account will always have to be completed. It recognizes these tags:
%#shops is exchanged for ShopName_Random.
%#transaction# is exchanged for the transaction number assigned to each prospective client when they access the shop.
%#cookie# is exchanged for the client’s account code. If his tag is left, the box on the form corresponding to the account will be completed automatically.
%#name# is exchanged for the name of the client. If this tag is left, the box on the form corresponding to the account will be completed automatically.
%#surname# is exchanged for the surname of the client. If this tag is left, the box on the form corresponding to the account will be completed automatically.
%#bonus# which is the bonus points associated with the client’s
account.
But if they are used they must be exactly as in the example template:
<form ACTION="%#BASECGI#changecode" METHOD=POST>
<table border=0 width80%>
<tr>
<td width=50% align=right>
<font size=2 color="black"><b>Account: </b></font></td>
<td><input type=text name=account size=8 maxlength=8 value=
"%#cookie#">
</td>
<td><input type=text name=name size=20 maxlength=60 value=
"%#name#">
</td>
<td><input type=text name=surname size=20 maxlength=60 value=
"%#surname#">
</td>
<tr>
</table>
In other words, they must be placed between double inverted commas and be the only thing on that line. The only thing it is advisable to change is the way the template looks, but not the form. The sizes of the boxes of text may not be changed. Also, if the content of any of the boxes corresponding to the name or surname is changed, then the data of the owner will be modified. If they are left blank, they will remain so in the database CARDS table.
Even if the password is not going to be changed, the box must always be completed and, then, a new password introduced twice (which may be the same as the original one).
After clicking on the send data button, all necessary checks are made,
and whatever the result may be, it is shown by means of the show.messages.templ
template
messages.
Since this way of calculating them may not be the most be convenient for the administrators of some businesses, it is possible to create a program which calculates them and places them in a file in the /expenses/ directory with the name transaction_number.expenses. In this way the databuy cgi will call this function to calculate the expenses and will add them to the total to be paid for the purchase. If this file (transaction_number.expenses) does not exist, the delivery expenses are calculated in the usual way. If the file exists, the expenses are added up and the file is deleted.
To create a program which calculates delivery expenses you must bear in mind the following:
{
char name [100]
char reference [100]
char table [50]
int units;
long int precio;
};
It is possible that a client may wish to return a purchase or part of a purchase. In this case there are a number of things to bear in mind:
If the transaction has not been verified in the QUEUED_TRANSACTIONS table, the only thing you have to do is to click on the DELETE button of the corresponding update menu.
Also, the points that he would have obtained as a result of the purchase must be subtracted. If he does not have sufficient points, the equivalent in pesetas will have to be subtracted from the total amount to be returned.
In any case, afterwards you will have to update the corresponding tables. To do this you will have to learn to use the sqlplus program: