
------------------------
PgMarket Coding Rules...
------------------------

The multilingual support is obtained through
A - the locale/??/global.inc.php files
B - templates whose direectory path is language-dependent
    ( */templates/??/*.ihtml )
Without global.inc.php files (A), one copy of each template
would be needed for each language to be supported; this would lead
to replication (hence redundance and risk of inconsistence)
both of the PHP part (this is bad for the programmer)
and of the HTML graphical customization (this is bad for
the web developer in charge of the graphical part of the work).
Also "B" templates may be needed; in fact, otherwise, it would be
impossible to provide really different looks (and maybe different
sets of data) for different languages (and, hence, different countries
with different uses and rules) on some pages of the e-shop.
Furthermore, "B" templates are used when the major part of the
template content is text.

Any submitted data should be validated before processing it
and eventually storing it in the database.
Hence, for each data, a validation function has to be used
to check its consistence as much as possible.
Validation functions are placed in lib/pgmarket.inc.php
and are named "validate_this_stuff($this_stuff, &$errors, &$msg)" ;)
- $this_stuff contains the data to be validated;
- $errors->this_stuff is true (validation not passed) or false
  (validation passed);
- $msg->this_stuff contains (eventually) error messages related
  to validation of $this_stuff.
Error messages have to expressed parametrically, i.e. through
a PHP variable that is a string defined in locale/??/global.inc.php

Validation has to be performed fundamentally through the scripting language
rather than being implemented employing the DBMS features through
the PHP interface with it, in order to
- provide compatibility with more than one DBMS
- simpler and more powerful error handling

As an example, to add another descriptive field for products,
it is needed at least:
- at least an entry in application-??.inc.php may be needed to impose
  parameters like the maximum number of characters of the field,
  or its minimal / maximal value
- maybe you will want to add the parameter in advanced_search.php
  and, hence, also in dblib.inc.php (mysqllib.inc.php)
- something will need to be added to the global.inc.php files:
  labels, error messages...
- a validation function has to be added to pgmarket.inc.php
- the validation function has to be called in admin/products.php
  in correspondence of the "insert" and "update" cases of the "switch" construct
- maybe here and there you will need to change some queries, some templates
  to show the parameter value, and so on...
I hope I haven't forgot anything :)
I suggest you to add code in analogy to the existing code, especially
if you wish that I consider the option of accepting your addin
in the official releases.

The goal foresees compatibility with PostgreSQL >= 6.5
and MySQL >= 3.22; sometimes this target imposes to avoid
some useful advanced features of the mentioned DBMS and/or
their interfaces with PHP.
IMHO, it is important to support all them, as PostgreSQL
is a robust and rather full-featured Open Source DBMS,
while MySQL is a fast, very widely used, and GPLed DBMS;
furthermore, PostgreSQL 6.5 and MySQL 3.22 are still
widely used, hence it would not be so good to support only
newer versions.

The support of both DBMS is achieved using "abstract" PHP functions
to access the database; the implementation of such functions
is provided in lib/dblib.php
Obviously, PostgreSQL and MySQL will use different dblib.php files;
but, to switch from one DBMS to the other, it is sufficient
to use another dblib.inc.php, and maybe to apply some minor
changes to the code.

lib/cart.inc.php contains the code needed to handle the shop cart,
which is defined as an object, with its variables and methods
(following the object oriented paradigm).

lib/stdlib.inc.php provides functions that are more general purpose
and less pgmarket-related than the ones provided in pgmarket.inc.php

lib/treemenu.inc.php is taken from the PHP3 TreeMenu
((c)1999 Bjorge Dijkstra, email: bjorge@gmx.net)

lib/layersmenu-*.inc.php provide the Layers menu.

lib/wordlist.txt contains a list of words, it is used to generate
random passwords.

In tables where the primary key is a numerical ID, ID = 0 is used
to denote a null or not significant value.
Some examples: a product with brand_id = 0 has not a brand associated with,
or has an unknown brand; accordingly, in the "brands" table,
name = '' and description = '' correspond to id = 0.
Analogously, in the "iva" table, iva = 0 for id = 0,
and, in the "orders_states" table, id = 0 corresponds to
a non significant order state.
When a non mandatory input field is not filled,
the null / not significant value has to be considered;
hence the use of the 0 value is easier than the use of the 1 value,
even though with MySQL it is difficult to insert an id = 0
in auto_increment fields... (this is not difficult with PostgreSQL).
For this reason, it must not be possible (and the web interface
must not "propose") to edit/delete/update rows with id = 0
in tables involved by this argumentation.

For each entity ("products", as an example), a corresponding .php script
and at least one template (more likely, more than only one template)
are needed to handle the insert, edit, delete, and import actions.
Such actions have to performed only when rights are granted
and validation is passed by all the submitted data.

In the "products" table, "imagetype" may assume the following values:
"gif" --> gif; "jpg" --> jpeg; "png" --> png, "" --> no image.
"imagetype" is identical to the extension of the image file
in the "products" directory; the name of the image file is chosen
"cleaning up" the product ID through the function
string_cleanup() in lib/stdlib.inc.php
It is not necessary to store the image type for the thumbs,
as all thumbs are generated as jpeg files (*.jpg).
The "imagewidth", "imageheight", "thumbwidth", and "thumbheight" field names
should be rather self explanatory :) ; they are empty if no image
is associated to the product.
The scripts check the presence/absence of an image representing the product
searching for the corresponding file in the "products" directory,
and not checking for the above fields contents in the "products" table;
only the "imagetype" field is involved if the full size image
(and not the thumb) is needed.

The shop users' passwords are stored md5'ed in the database.
They are not exchanged by the server and the client as clear text,
as they are md5'ed on the client side through JavaScript.

In the "users" table, the "usertype" field is "pf" for persons
(Persona Fisica in Italian) and "az" for Companies (AZienda in Italian).

--
Marco Pratesi
http://www.telug.it
pratesi@telug.it

