classAd 4.0 - user manual

Installation

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

  1. Edit configuration
    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 this for security reasons.
  2. Start admin_install.php in your browser
    Thereafter start the database installation script admin_install.php. After calling the installation script, check the displayed database parameters. After clicking "Install database", the installer will create all necessary tables for you. If errors occur during installation process, the script will inform you about that fact and display the native database error message.
    ! Attention: How to update from a previous ClassAd version, see below.
    ! Attention: After successful installation, please make sure that the files "admin_install.php" and "admin_update_*.php" are being deleted or set to non-executable (chmod 000). These steps are necessary to avoid unwanted database manipulations.
  3. Start admin.php in your browser
    After starting the administration, log in with the data entered in inc/config.inc.php. After that, think about your category structure, create free fields, if needed, and insert categories.
  4. To change layout, mail, and other parameters of your market before productive use, proof and edit the configuration file inc/config.inc.php. Besides that it is important, that URLs and pathes are changed to the requirements of your webserver.
  5. For further adaptions, change templates, language, and stylesheet-files. For more information view Customizing in documentation.

Especially on UNIX-based systems pay remember that the script needs read/write-access to /usergraphics and /cache directories.

Update

Distributed files overview

The distribution package of cts ClassAd should contain the following files:

File / Directory function
admin.php Login and Administrator's console
admin_addcategory.php Add new categories to the market (Administrator)
admin_dbmaintain.php Maintenance of database (Administrator)
admin_definefields.php Definition of free ad fields (Administrator)
admin_deleteoutdated.php Deleting outdated ads (Administrator)

admin_editcategory.php

Deleting and editing categories (Administrator)
admin_editmessage.php Managing, editing and deleting ads (Administrator)
admin_editmessagedetails.php Edit a single ad (Administrator)
admin_edituser.php Managing, editing and deleting users (Administrator)
admin_edituserdetails.php Editing of user data (Administrator)
admin_install.php Installation script
Attention: Has to be deleted after successful installation (chmod 000)
admin_update_*.php Update script(s)
Attention: Has/Have to be deleted after successful installation (chmod 000)
admin_logout.php Logout Administrator (Administrator)
admin_phpinfo.php Display PHP-Info (Administrator)
admin_showlog.php Display log entries (Administrator)
admin_statistics.php Display market statistics (Administrator)
contact.php General contact (form mailer)
contactad.php Allows users to get in contact with other users by e-mail
cyclicmain.php Database maintenance script
Attention: This script should be run as a cronjob (or on an other regulary base)
editmessageuser.php Edit as single ad by inserting user (User)
generalterms.php Display of general terms and conditions
imprint.php Display of imprint
index.php Main index / front page
lostpassword.php Send users their new passwords, if they have lost it
newad.php Inserting new ads by user
newuser.php Registering as a new user
releasesubmit.php Release an ad by e-mail code (Administrator w/o login)
releaseuser.php Activation / Release of users, registered using the optional-in procedure (Users w/o login)
rss.php Display of information about RSS-feed
rssfeed.php Generates the XML-RSS-feed
searchads.php Simple search for ads
searchextend.php Extended search for ads
showad.php Display of a single ad
tellad.php Tell-a-friend about an interesting ad
userlogin.php Login for users
userlogout.php Logout for users
usermymessages.php Users' ad overview (user)
usermysettings.php Edit of users' settings and profile data (user)
/inc Directory: Necessary modules to run ClassAd
/languages Directory: Language-packs for all available languages
/styles Directory: CSS-files
/emailtemplates Directory: Contains e-mail templates
/templates Directory: Contains HTML templates (subordinated by languages)
/graphics Directory: All graphics used by the script
/catlogos Directory: All graphics, which should be used as category logos
/usergraphics

Directory: All graphic files uploaded by users are stored into this directory. By uploading a picture, two files are generated: A thumbnail and a resized version.
! Attention: Never touch files contained in this directory manually. All maintenance is done by the script itself.
! Attention: ClassAd needs read/write-privileges to this directory

/doc Directory: Documentation and user manual
/cache Directory: Cache files
! Attention: ClassAd needs read/write-privileges to this directory

Setting up cronjob

For maintenance of ClassAd the file cyclicmain.php should be executed at regular intervals. On Unix-system are normally cronjobs available to achieve this aim. On information, how to create a cronjob on your webspace, please ask your webspace provider.

! Attention: Normally changes at the maintenance script are necessary (i.E. state the shell to use, change paths etc.).

How large the time period between two maintenance runs is mainly depends on the usage of your market (e.g. the amount of newly created ads). Generally the time period should been between 1 hour and 1 day.

The following actions are triggered by the maintenance script:

Cronjobs are not available on webspace

If your webspace does not you give you the possibility to install a cronjob script, ClassAd has a build-in alternative. Set the parameter $CRONJOB to false in the configuration file inc/config.inc.php. This solution is fully working, but not recommended, because a random user gets the fully computing time for maintenance.

Technically the periodical execution is steered by the index-script. Within this, a random generator starts and every 1000th call (default) the maintenance is executed. The probability can be configured by the Administrator in configuration file - the $MAINTAIN_PROBABILITY parameter is set to 1:x (one time called in x calls). The higher the probabilty value, the infrequent called.

RSS-Feed

ClassAd offers a RSS-feed for external use, based on RSS-specification version 2.0. At the actual state of development this service is provided to all users without futher need of authentication.

The feed is callable at: http://<IHRE.DOMAIN>/rssfeed.php.

Using this standard call the latest ads, in a shortend version (max. 200 chars per ad), are returned. The amount of ads taken in account, can be configured in inc/config.inc.php - the regarding parameter is named RSS_MAX_COUNT.

In the configuration file all parameters beginning with RSS_* should be checked or set. This parameters define, which title and description the RSS-feed returns. Further on the RSS_TTL-parameter can be set, which defines the period of time (in minutes) in which a newsreader re-reads the feed to keep it up to date.

An RSS-feed created by ClassAd looks like this (XML-format):

<? xml version="1.0" ?>
< rss version =" 2.0 " >
	< channel > 
		< title > My little classified ads server </ title > 
		< link > http://www.xyz.com/classifieds/index.php </ link > 
		< description > The latest ads of www.xyz.de. Bla bla bla </ description > 
		< generator > cts classAd 4.00 - www.projects-and-software.de </ generator > 
		< ttl > 60 </ ttl >
		< item > 
			< title > This is the ad title </ title > 
			< link > http://www.xyz.com/classifieds/showad.php?adid=24 </ link > 
			< description > This is the ad text </ description > 
			< pubDate > Tue, 10 Oct 2006 22:47:51 +0200 </ pubDate > 
		</ item >
	</channel >
</rss>

Providing specialized RSS-feeds

One of the main reasons for using RSS, is the loose linking of websites. Let's assume that you run a market for all kinds of pets - another website deals with all information about cats. In this situation, both sides can profit of a your RSS-feed: The cat-website can integrate your latest ads and attract more users, your website gets more visitors too, because the details of each ad are stored in your market.

The example above shows one problem. The cat-website is not interested in ads regarding dogs or reptiles. To solve this problem, ClassAd provides a filter mechanism to get a specialized RSS-feed:

http://<IHRE.DOMAIN>/rssfeed.php?feed=category_latest&cat=17&count=10

This RSS-feed returns the 10 latest ads (see 'count' parameter) from the category with id 17. If you are using the structured category model, all ads contained in its sub-categories are returned to.

This means for our example above: Let's say that category #17 stores ads about cats and has the subcategories 'Persian cats', 'House cats' and so on. The subscriber (means: the cat-website) gets the 10 latest ads of all categories mentioned above, if he uses the specialized RSS-feed url.

RSS-Feed - general information

A large number of feed subscribers can lead to performance shortage, if these are not caching their calls.

For these reasons, it is 'good style' to adopt the following solution on subscriber side: The XML returned by your Feed should be stored to a textfile (or for bigger solutions into a database). After that, every call check the filedate - if its older than i.E. one hour, the call is directly redirected to your RSS-feed and the file is updated, otherwise the content of the file is returned. This is a very easy solution and you should propagate it to your RSS subscribers.

Later version of ClassAd will integrate a system to block subsequent uncached calls and will integrate a server cache.