cts Classified Ads "ClassAd" Version 3.0

• Features
• Licence
• Requirements
• Files distributed
• Installation
• Updating Version 2.0
• Security and right management
• Free fields definition
• Category management
  
• Administration
• Configuration of e-mail messages
• Download
• Bugtracking & FAQs
• Contact

Version 1.0 of ClassAd implements the following features:

• Unlimited number of categories
• Unlimited number of ads
• Upload of pictures and management (Jpeg, Png-format)
• Automatic creation of thumbnails as preview pictures
• Secure web-based administration (delete, add and edit categories, delete articles, php info-display)
• Integrated management of outdated ads
• Well-designed user input forms with easy input-error detection
• Ad search (AND/OR-Combination)
• Integrated form mailer to keep the ad-writers e-mail address anonymous
• Integrated tell-a-friend-function
• Display of new ads since last visit
• Easy configuration and installation
• Design encapsulated in template files

Version 2.0 adds the following features to ClassAd:

• Listing of ads in a cateogory can be interrupted after a specified number of ads
• Multilingual support of ClassAd (included is English and German version)
• Administrators can now edit articles including picture change/delete and ad re-assign to a category
• E-mail texts are now encapsulated in special templates including parsing of variables
• Integrated 'View'-counter
• Listing of ads in a category can have an alternating background color for a better overview
• Installation and update script added/edited
• If configured, ads can now be stored for an unlimited period of time (to be more exact: 10 years)
• Logfile for special events (add / delete / edit ads, login, failed login, etc.)
• Outdated ads can now be deleted automatically
• Various small changes and bugfixing

Version 2.01 adds the following features:

• Improved upload function (advanced recognition of Jpeg pictures)
• Improved picture scaling with optional suppression of picture upsizing, if smaller than default

Version 3.0 adds the following features and changes:

• Integrated user management including the following functions:
  • Adding users to database with assignment of unique user names. Recorded are address data, passwords, ICQ-number, e-mail address and an initial language selection
  • User´s overview of ads including the possibility to change, delete and prolong ads
  • Selection of user´s favorite language and display of all user interface texts as selected
  • Change of user data by user himself and Administrator
  • Forgotten-Password function incl. generating a random temporary password
  • Blocking of user accounts by Administrator
  • User information for Admin and user (number of ads, views, contacts, tells etc.)
  • Login / Logout of users
• Integrated security and rights management
  • Right to submit ads to database
  • Right to submit ads directly into database or ads have to be checked by Administator first
  • Right to view ads or categories belonging to the closed user group
• User management and recognition is not necessarily based on cookies - that means it makes no difference if cookies are activated on client side
• Featured articles as eye-catchers on front page (assigned by Administrator)
• Multilevel category structure (for optional use)
  • unlimited number of categories with an unlimited number of sub categories
  • flexible display of category overview by number of column definition and sorting order
• Advanced search (incl. combinations of indate, ad title and text, zip-code and city, ad writer and picture availability) with different sorting orders
• Integration of ICQ in user and ad data, direct contact to ICQ users via ICQ-Webpager
• Definition of 10 globally used free fields
  • type definition for every single field (DropDown, listbox, textbox, textarea, option list or simple checkbox)
  • status definition (mandatory field, search field (not yet implemented))
  • text definitions (field name, description, standard text and initially selected element)
• Release of non-directly submitted ads by Administrator via e-mail with unique security code or via Administrator´s console
• Possiblity to filter user or ad lists by a keyword in the Administrator´s console
• Logfiles are now deletable (every log category individual)
• Database maintenance included (only MySQL 3.23 or higher), included are database backup and restore, database table check, database optimize (repair and re-index)
• Building time of pages can now be displayed
• Performance gain with caching and persistent database connections
• various smaller changes

Later versions will implement the following features:

• Support of Microsoft SQL Server® [Priority: middle - version 3.1] and Postgres-DB® [Priority: middle - version 3.1]
• Advanced user management with privilegue management (Restricted use of categories, limitation of ads per period, accounting) (Priority: middle - version 3.0 prof.)
• Multilingual user FAQ (Priority: low - version 3.1)
• Free field definitions for every single category

Are there any missing features, please contact us: support@how2pc.de or use our contact form. We need your support to create the best working classified ads application!

Estimated release of version 3.0 professional: June 2002
Estimated release of version 3.1: End of may 2002

This version of ClassAd is free for privat use and for use in teaching and science; if you use the script in a company´s intranet, on a commercial website or for commercial reasons, you have to register the script and buy a licence.

In any case you are not allowed to edit any copyright information and the program's name. Your are also not allowed to re-use even parts of the source code in your own scripts. If you do not follow these rules, it will be treated as a copyright violation.

Please note that this program is written and tested very carefully. You are using this script on your own risk and we cannot be made responsible for any bugs or damage resulted from using it.

A simple one-site licence (one internet-domain, one intranet server) costs 65€ / 60 US-$. There are special rates for multi-site licences - feel free to contact us at support@how2pc.de. You can also send us your order online.

The following components are required to run ClassAd:

• PHP 4 with activated and working session management, working upload function
• MySQL database (database maintenance uses MySQL 3.23 or higher)
• activated Cookies (on clients to use administration)
• GD-Library installed (used to do the picture conversion and scaling) / GD-Version 2.0 is highly recommended for Windows systems because of its true color support (should be a part of newer PHP4 distributions)
• some minutes to install and configure

The following files should be part of your ClassAd distribution:

¹ Files responsible for design, layout and configuration

The Installation of ClassAd is very simple, so that you can (almost) call it 'out-of-the-box':

1.) First of all, edit the file inc/config.inc.php. When running the database installation, it is important to edit the database section (database host, database username, database password and the database name itself) and set a new Administrator´s name and password. Never leave name and password empty, because the login script will not accept them for security reasons.

2.) Thereafter start the database installation script installsql30.php - it will create all the necessary tables for you. If all entries are correctly entered in configuration file, the script will give back a success-message and ClassAd can be used.

3.) To check the installation, call index.php. You should see a message, that no categories could be found and should then enter the administration.

4.) When entering the Administrator´s console for the first time, please think of category management and definition of free fields. After that start to add new categories to the database.

5.) To configure layout and special functions like mail and directories - check and edit the file inc/config.inc.php.

6.) You can use a template to display commercial banners. To change these messages, edit the file templates/commercial.tpl.php.

Note: Please check, if ClassAd has Read-/Write-privilegues at the directory /usergraphics. Otherwise you will get the copy file error message, when submitting a new ad with an attached picture. On Unix-based web servers, please set the paramter $LY_GD_VERSION_2 in the configuration file inc/config.inc.php to false.

Before updating from a ClassAd 2.0 version to version 3.0, please ensure that all data is backed up - especially the file inc/config.inc.php and the stylesheet-directory /styles should be saved.

Attention: Regarding to the high number of new features in version 3.0, some web templates got changed completely. Please keep in mind, that old templates of version 1.0 or 2.0 could no longer be used or may behave in an incorrect way.

After a backup follow these steps:

1.) Depack the files from the distribution pack and copy them into your installation directory.

2.) Edit the configuration file inc/config.inc.php in the well-known manner. Please synchronize the "new" configuration with your old one and check especially check the database section and the newly added configuration keys.

3.) Then start the script updatesql30.php, which will do the necessary database and table changes to use the new version.

4.) Your ClassAd should now be ready to use. If there are any problems updating your installation, please feel free to get in Contact with us!

Update from 2.0 -> 2.01

To update from version 2.0 to 2.01 simply copy the files inc/baseclass.inc.php, newad.php and editmessage.php to your installation directory. And copy the line starting with $LY_ALLOW_UPSIZING=false; from the new inc/config.inc.php to your config.inc.php. The database and all data stored within it will remain the same.

Version 3.0 of ClassAd has several new features and options to handle users and their rights. Generally ClassAd has three different kind of rights:

• Right to submit an ad
• Right to submit an ad with or without Adminstrator´s check
• Right to access closed user group's categories and ads

Every registered and logged in user has the right to submit an ad has every registered and logged in user. Using the parameter $SEC_UNKNOWN_SUB in the configuration file inc/config.inc.php you can define, if unknown and not logged in users also should have the privilegue to do that. The user can submit ads to the classified ads system, if the above mentioned parameter is set to true.

To avoid any misuse of the ad submit function, a direct entry into the database can be prevented. The non-directly entered ad gets into a waiting status and remains there until it is released by an Administrator. This can be done via e-mail or Administrators console (edit ads). If an ad is released using the e-mail link, this process is secured by a code, only valid for this special ad.

The define which user has the right to do a direct submit, depends on whether the user belongs to a special user group (user profile) and the settings in the configuration file inc/config.inc.php. At the moment the following user groups are predefined in ClassAd 3.0:

• Registered user
  A registered user has sent his new user form
• Authenticated user
  Authenticated user data was checked by the Administrator and seem to be valid
• Commercial user
  Commercial users participate at the commercial service of ClassAd (Version 3.0 prof)
• Administrator
  The Administrator is a system manager
  Please note, that an user with Administrator privilegues has no right to log into Administrator's console. This is a restriction for security reasons.
  
• Debug-Administrator
  This is like the normal Administrator, but activates the ClassAds debug mode when logged on

This right management can and will be extended in further versions of ClassAd. Please note, that all rights given to an user are additive. That mens, a user can belong to more than one group and gets the rights of all groups he belongs to.

There are corresponding parameters for all user groups in the configuration file inc/config.inc.php:

Administrators and Debug Administrators always have the privilegue to submit an ad directly.

ClassAd Version 3.0 implements a system that gives you the possibility to define a closed user group. Every ad and every category can be defined to as a part of the closed system (i.e. for age restricted ads). This closed areas are integrated in the "open" classified ad system.

An assignment of an user to the closed user group can be done in the Administrator's console (edit user). When a new user is created, he is not member of the closed user group.

The following paramters can be found in the configuration file inc/config.inc.php to define the behavior of closed user groups:

To change ClassAd to your personal needs, you have the possibility to define up to ten free fields in version 3.0. These free fields are displayed everytime a new ad is entered, shown or edited. They behave exactly like the "normal" input fields in other forms.

Available field types arel:

To use a defined free field, the controlbox "Active" has to be activated.

If a field should be defined as mandatory, the column "Mand" has to be activated. A mandatory field is checked after a form is submitted - if the field is empty, an error sign is displayed and the form will not be processed.

The Option "Srch" (Search) is not yet implemented in version 3.0.

"Name of Field" is displayed in front of the created field, "Description" should give the user more information about the expected value. This is displayed below the field, i.e.

When using free field, please keep the following information in mind:

• The use of free fields can be activated or deactivated generally using the parameter $USE_FREE_FIELDS in the configuration file inc/config.inc.php
• Version 3.0 only has one free field definition for all categories. Version 3.0 prof. will be able to store a free field definition for every category in the database
• Every ad in the database stores the free field definition it is created with. That means, an ad will keep its values and definitions stored in the free fields, even if the global definition is changed. Benefits are that the database stays consistent and there is no chance of data loss. At the same time this ist the reason, why the definition of free fields should be done at installation already
  
  

Version 3.0 of ClassAd has a totally renewed category management with two different available modes:

• Structured category model
• Classic category model (flat model)

One should decide on which model should be used at the beginning of the installation, but best before creating categories. The following points characterize the different models:

• Classic category model / Flat model
  The flat model works with categories of equal rights. The categories are displayed one after each other incl. category logo, description and the ad counter. The sorting order can be changed in the configuration file inc/config.inc.php.

• Structured category model
  The structured category model works with categories subordinated to another category or the root in a multilevel way (category trees). The categories are displayed in a flexible way - sorting order and column amount can be changed to the personal needs in the configuration file inc/config.inc.php.
  Using the structured category model, every ad and category view gets a category history like:

Small ClassAd installations should work well with a flat category model, larger markets with a lot of different categories should use the structured model.

In the configuration file inc/config.inc.php are parameters to fine tune the behavior and layout:

The administration is almost self-explaining. To start the administration, call the script admin.php or use the link in the category overview (only in Debug-Mode).

If you are using the administration for the first time or if you have restarted your web-browser, you have to log in. For security reasons, it's highly recommended, that Admin name and password are changed before using the script on a website (see inc/config.inc.php for details!!)

After a successful login you should see the following options:

User edit / delete
Within this menu you can find all functions needed to manage your users:

• Filter user selection...
  If you are working with a large number of users, the selection of a user to edit may be wearisome. To simplify the selection you can filter all entries by a given filter key. The key searches in user id, -name, -real name and city.
• Edit user
  Select an user and submit the form. You should now get this user´s details. Changeable are user data, telecommunications, user rights and language settings - the user name cannot be changed
• Deactivate / activate user
  An user can be deactivated and is then no longer able to log in to ClassAd. All user data of the deactivated user is kept and can be reactivated. Deactivated users are displayed as *BLOCKED* in user selection
• Delete user
  Deletes a user and -data - his ads will remain in the database. Attention: This step is not reversible! Deleted user accounts cannot be reactivated!

Something you should know about users:

• User name are unique and cannot be changed
• The e-mail address entered by the user has to be unique (prevents multiple user entries of the same user)

Define free fields
More here.

Delete messages
Use this option to delete ads from your database. Select one or more ads that should be deleted and click on the submit button to start deleting. Important notice: If you delete a message, the assigned pictures will be deleted, too.

Edit ads
In some cases it is necessary to edit messages. In this case, first select an ad you want to edit and click on the submit button. By the way: '(pic)' behind the ad´s name means that this message has a picture attached.
Then you should see the message with all its data and the assigned picture. Change the data as intended and click the submit button to write the changes to the database.
If you like to change the attached picture, simply select another picture file from your hard disk and submit the form. The old picture is deleted and the new one attached to the ad.
To delete a picture, simply activate the 'Delete picture' option and click the button to submit.

Delete categories
Use this button to delete categories. Select one or more categories from the listbox and click the submit button to delete. If you also want to delete the messages assigned to this category, activate the option box.
Caution: Keep in mind that categories and ads are deleted irreversibly.

Create category
To add a new category to your database, you should use this button.
To create a new category you have to enter at least two values: the name and a description of the new category. These are the strings the user gets displayed when calling the category overview (index.php).
The third value you can enter is a category logo. This logo is also displayed in the category overview, if configured to do so (see config.inc.php for details). Simply enter a (graphic-) file name in the accompanying text field. Please remember that the script will search the graphics/ - Directory for this file.
If the complex category structure is activated you have to choose a mother category for your new created one. Your category will be subordinate to the selected mother category. To create a top-level category, choose 'root' as a mother category.
To assign the new category to a closed user group, check the accompanying box.

Edit category
Use this form, if you like to edit a category use this form. First select a category in the upper listbox you want to edit. As a second step, edit the text fields to change the values. Important notice: Only the fields you edit (and are not empty) will be updated in the database. Untouched fields will remain untouched in the database.
For more information have a look at the "Create category"-section.

Delete outdated messages
If you have ever entered a new message to ClassAd, you should have selected a 'duration' for your ad. This duration specifies how long your ad will stay active in the database.
This form shows you all the outdated ads in your database. Select them to delete or leave them untouched, if you want to keep an ad in the database for a longer time.
Caution: Please keep in mind that ClassAd has the possibility to delete outdated messages automatically (see inc/config.inc.php for further details).

Show log file
An important new feature of ClassAd version 2.0 is the possibility to log what happens, i.e. who adds messages, who logs on, which keywords were searched etc.
First select a log you want to display and then click on the submit button. After that you should see a list of logfile entries incl. time stamp and IP-addresses.
To delete a type of logfile, check the accompanying checkbox and submit the form.

Show PHP-Information
Get the PHP-environmental information

Logout
Please leave the administration with this button, because this is the only *really* safe way to do that.

Starting with version 2.0 of ClassAd, e-mail texts are stored in a subdirectory named /emailtemplate. There are five different kinds of templates:

The files have to be named as follows:

• response[.LanguageCode] (for contact e-mails)
• tellad[.LanguageCode] (for simple tell-a-friend-mails)
• telladcomplete[.LanguageCode] (for advanced tell-a-friend-mails)
• releasesubmit[.LanguageCode] (release of ads)
• lostpassword[.LanguageCode] (transmitting a new password)

The language code is one of the defined languages (see config.inc.php for details). It can be .GER for the German or .ENG for the English version. Please remember to write them in uppercase letters, because UNIX-based OSes will work case-sensitive on file names.

You can edit the mail texts with a simple mail editor (i.e. notepad on Windows-systems) and the following variables can be inserted into the text:

To download the script, please use the following links:

The following bugs and problems are known in ClassAd 3.0:

• Nothing yet

Version 2.0 - Fixed in current downloadable version (2.01):

• Updated and working database install and update script (Wrong text, partially incompatible SQL-Statements)
• Editing articles impossible ("No message selected!") - fixed with current downloadable version
• After submitting a new ad with a picture attachment only a blank page was shown. This can be solved by turning the property $LY_GD_VERSION2 to false (config.php.inc). Some webserver do not seem to run the newest version of GD-library.
• Various picture upload problems
• "set_time_limit could not be set in safe_mode" will now be suppressed
• correct link to ad in tell-a-friend mail
• problem of unrecognized jpg-files solved when uploading with Netscape- or Opera browsers. Jpg-files can now have the suffixes .jpg, .jpeg, .jpe
• As a new feature it is now possible to configurate (see inc/config.inc.php for details) that uploaded pictures, smaller than the pictures' default width, are not upsized, but remain at their original size

FAQ - all versions:

• While submitting a new ad with a picture attachment, you can get the following error: "Fatal error: imagecreatetruecolor(): requires GD 2.0 or later in classifieds/inc/baseclass.inc.php on line 866". To solve this problem simply edit inc/config.inc.php and set the parameter $LY_GD_VERSION_2 to false. This error occurs on Linux/Unix-systems with version GD 1.6x installed and is a result of different versions of GD-library on Windows and Unix systems.

To get in contact with us, you can send a snail mail or e-mail to the following address:

cts-projects&software
Forsthoevel-Muensterstr. 26
59387 Ascheberg-Herbern
Germany
Email: support@how2pc.de

Or use our contact form!